### Custom Capabilities: Explicit Installation and Usage

Source: https://github.com/lavamoat/lavamoat/wiki/Configuration-Brainstorm

Example showing explicit installation of capabilities, including custom ones, and their transparent usage with specific global assignments.

```js
// install explicitly, use mostly transparently
// need to know what's available from docs
// could point to a custom one only and compose everything else in there
{
  "capabilities": [
    "@lavamoat/powers/reasonable-process",
    "@lavamoat/powers/defineProperty-global",
    "./customcaps/mycapability.js"
  ],
  "resources": {
    "some>package": {
      "globals": {
        "customthing": true,
        "process": true
      }
    },
    "other>package": {
      "globals": {
        "process": ['reasonable-process options', 'go here']
      }
    }
  }
}
```

--------------------------------

### Configure setup script in package.json

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/allow-scripts/README.md

Add a setup script to your package.json to automate dependency installation and script permission management.

```json
{
  "scripts": {
    "setup": "yarn install && yarn allow-scripts && ..."
  }
}
```

--------------------------------

### Install @lavamoat/vog

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/vog/README.md

Install the package using npm. This is the initial setup step before using its utilities.

```bash
npm install @lavamoat/vog
```

--------------------------------

### Start the Fixture

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/node/test/unit/fixture/dynamic/README.md

Run this command to start the dynamic fixture. This is primarily for creating snapshots.

```bash
npm run start
```

--------------------------------

### Install @lavamoat/allow-scripts globally

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/allow-scripts/README.md

Install the package globally to perform initial project setup.

```sh
npm i -g @lavamoat/allow-scripts
```

--------------------------------

### Run setup command

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/allow-scripts/README.md

Execute the setup command to configure the project to ignore lifecycle scripts.

```sh
allow-scripts setup
```

--------------------------------

### Install node-gyp-build

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/node/test/unit/fixture/native/node_modules/node-gyp-build/README.md

Install node-gyp-build using npm. This is the first step to integrating it into your native module project.

```bash
npm install node-gyp-build
```

--------------------------------

### Supported Allow-List Policy Example

Source: https://github.com/lavamoat/lavamoat/blob/main/docs/policy.md

This example demonstrates the correct way to configure policies by explicitly allowing only the desired properties, ensuring fine-grained access control.

```json
  "globals": {
    "a.c": true,
    "a.d": true
  }
```

--------------------------------

### Run lavamoat-node

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/__bin-fix__/README.md

Use this command to run the `lavamoat` executable for the LavaMoat node environment. No specific setup is required beyond installing the package.

```sh
lavamoat-node <args..>
```

--------------------------------

### Example JavaScript for Browserify

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/browserify/README.md

This is an example JavaScript file that demonstrates typical module requires for a Browserify build.

```javascript
const foo = require('./foo.js');
const gamma = require('gamma');

const elem = document.getElementById('result');
const x = foo(100);
elem.textContent = x;
```

--------------------------------

### Run the hardening wizard

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/harden/README.md

Starts the interactive wizard to assess and apply hardening settings to the project.

```sh
harden wizard
```

--------------------------------

### Run lavamoat2

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/__bin-fix__/README.md

Use this command to run the `lavamoat` executable for the @lavamoat/node package. No specific setup is required beyond installing the package.

```sh
lavamoat2 <args..>
```

--------------------------------

### Install Dependencies with npm ci

Source: https://github.com/lavamoat/lavamoat/blob/main/AGENTS.md

Install all project dependencies using `npm ci` for a clean and reproducible environment. This command can take several minutes and should not be interrupted.

```bash
# Install dependencies - takes 6 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
npm ci --foreground-scripts
```

--------------------------------

### Configure npm install script

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/node/test/unit/fixture/native/node_modules/node-gyp-build/README.md

Add node-gyp-build as an npm install script in your project's package.json. This ensures it runs automatically during installation.

```json
{
  ... 
  "scripts": {
    "install": "node-gyp-build"
  }
}
```

--------------------------------

### Execute local allow-scripts

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/allow-scripts/README.md

Run the local installation using yarn or npx.

```sh
yarn allow-scripts setup
npx --no-install allow-scripts setup
```

--------------------------------

### Example allowlist configuration

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/allow-scripts/README.md

The structure of the allowScripts object within package.json.

```json
{
  "lavamoat": {
    "allowScripts": {
      "keccak#3.0.4": false,
      "rezeplayer>core-js#3.49.0": false
    }
  }
}
```

--------------------------------

### Install LavaMoat with npm or yarn

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/lavamoat-node/README.md

Use either npm or yarn to install the lavamoat package. Ensure allow-scripts is set up before installation.

```bash
npm i lavamoat
```

```bash
yarn add lavamoat
```

--------------------------------

### Validate allow-scripts Setup

Source: https://github.com/lavamoat/lavamoat/blob/main/AGENTS.md

Set up a test project to validate the `allow-scripts` CLI functionality. This involves initializing an npm project, running the setup command, and inspecting the generated `package.json` and `.npmrc` files.

```bash
# Create test project to validate allow-scripts
cd /tmp && mkdir test-project && cd test-project && npm init -y
node /path/to/LavaMoat/packages/allow-scripts/src/cli.js setup
cat package.json  # Should show @lavamoat/preinstall-always-fail dependency
cat .npmrc        # Should show ignore-scripts=true
```

--------------------------------

### Good Commit Message Summary Examples

Source: https://github.com/lavamoat/lavamoat/blob/main/CONTRIBUTING.md

Examples of well-formatted commit message summaries.

```text
feat!(core): added default behavior

fix: semicolons no longer breaking everything

chore(webpack): upgrade to browserify v5
```

--------------------------------

### Update Prebuilt Native Modules with npm

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/node/test/unit/fixture/static-native/README.md

Navigate to the `node_modules/hello_world` directory and run this command to rebuild all native modules in `node_modules/hello_world/prebuilds`. You may be prompted to install `prebuildify`.

```bash
cd node_modules/hello_world
npm run build
```

--------------------------------

### Install git-safe-dependencies

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/git-safe-dependencies/README.md

Install the package as a development dependency using npm.

```sh
npm install --save-dev @lavamoat/git-safe-dependencies
```

--------------------------------

### Install Laverna as a Dev Dependency

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/laverna/README.md

Install Laverna using npm as a development dependency. This is the recommended installation method.

```shell
npm install @lavamoat/laverna -D
```

--------------------------------

### Install the Yarn plugin

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/yarn-plugin-allow-scripts/README.md

Use this command to import the plugin directly from the LavaMoat repository.

```sh
yarn plugin import https://raw.githubusercontent.com/LavaMoat/LavaMoat/main/packages/yarn-plugin-allow-scripts/bundles/@yarnpkg/plugin-allow-scripts.js
```

--------------------------------

### Install LavaMoat Browserify with npm

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/browserify/README.md

Install the lavamoat-browserify package as a development dependency using npm.

```bash
npm i -D browserify lavamoat-browserify
```

--------------------------------

### Install LavaMoat Browserify with Yarn

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/browserify/README.md

Install the lavamoat-browserify package as a development dependency using Yarn.

```bash
yarn add -D browserify lavamoat-browserify
```

--------------------------------

### Install @lavamoat/preinstall-always-fail

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/preinstall-always-fail/README.md

Add this package to your project using either Yarn or npm to enable its functionality.

```bash
yarn add @lavamoat/preinstall-always-fail
```

```bash
npm i @lavamoat/preinstall-always-fail
```

--------------------------------

### Publishing a New Package with Laverna

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/laverna/README.md

When publishing a package in a new workspace, use the --newPkg flag to specify the package name. This example assumes the package is named 'foo'.

```shell
npm exec laverna -- --newPkg=foo
```

--------------------------------

### Custom Capabilities: Direct Mapping

Source: https://github.com/lavamoat/lavamoat/wiki/Configuration-Brainstorm

Example of defining custom capabilities directly within the configuration, mapping specific capabilities to package globals.

```js
// too much preconfiguraation for basic ones
{
  "capabilities": {
    "ownName1": ['@lavamoat/powers/reasonable-process', {opions}]
  },
  "resources": {
    "some>package": {
      "globals": {
        "process": ["ownName1"]
      }
    }
  }
}
```

--------------------------------

### Unsupported Deny-List Policy Example

Source: https://github.com/lavamoat/lavamoat/blob/main/docs/policy.md

This example shows an unsupported method of denying access to specific properties by first allowing the parent property. This approach will not work as intended.

```json
  "globals": {
    "a": true,
    "a.b": false
  }
```

--------------------------------

### Install @lavamoat/node

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/node/README.md

Install the @lavamoat/node package using npm. Requires Node.js v20.19.0 or newer.

```sh
npm install @lavamoat/node
```

--------------------------------

### Shim Example: Promise.withResolvers

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/webpack/README.md

An example of a shim script that could be used to polyfill functionality on intrinsics.

```javascript
// resolvers-shim.js
  Promise.withResolvers = ...

```

--------------------------------

### Create JSON Fixture with snapshot-fs

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/node/test/unit/json-fixture/README.md

Use this command to create a Compact JSON snapshot of a directory. Ensure `snapshot-fs` is installed and the target directory exists.

```sh
npx snapshot-fs project.json --dir project
```

--------------------------------

### Install @lavamoat/allow-scripts locally

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/allow-scripts/README.md

Add the package as a development dependency to your project.

```sh
npm i -D @lavamoat/allow-scripts
yarn add -D @lavamoat/allow-scripts
pnpm add -D @lavamoat/allow-scripts
```

--------------------------------

### Run application with @lavamoat/node

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/node/README.md

Execute your application using the `exec lavamoat` command to run it with the generated policy. Manual policy overrides may be necessary if the application fails to start.

```sh
npx exec lavamoat <your-app-entrypoint>
```

--------------------------------

### Laverna Dry Run Example

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/laverna/README.md

Use the --dryRun flag to see what Laverna would do without actually publishing packages. This is useful for testing.

```shell
npm exec laverna -- --dryRun
```

--------------------------------

### Complex Allow-List Policy Example

Source: https://github.com/lavamoat/lavamoat/blob/main/docs/policy.md

This example illustrates a more complex allow-list configuration, showing how to allow specific nested properties while denying others, by defining access at the deepest required level.

```json
  "globals": {
    "a": true,
    "a.b": false,
    "a.b.c":true
  }
```

--------------------------------

### Install LavaMoat Browserify Globally with npm

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/browserify/README.md

Install the lavamoat-browserify package globally using npm, ignoring scripts.

```bash
npm i --ignore-scripts -g browserify lavamoat-browserify
```

--------------------------------

### LavaMoat Generated Policy Example

Source: https://github.com/lavamoat/lavamoat/blob/main/docs/policy.md

This is an example of a LavaMoat policy file generated for a specific dependency tree. It defines granular access controls for packages and globals.

```json
{
  "resources": {
    "some-package": {
      "globals": {
        "Buffer.from": true
      },
      "packages": {
        "some-package>entropoetry": true
      }
    },
    "some-package>entropoetry": {
      "builtin": {
        "assert": true,
        "buffer.Buffer": true,
        "zlib": true
      },
      "globals": {
        "console": true,
        "process.exitCode": "write",
      },
      "packages": {
        "some-package>entropoetry>bn.js": true
      }
    },
    "some-package>entropoetry>bn.js": {
      "builtin": {
        "buffer.Buffer": true
      },
      "globals": {
        "Buffer": true
      }
    }
  }
}
```

--------------------------------

### Troubleshoot Native Fixture Test Failures

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/node/test/unit/fixture/native/README.md

If tests consuming this fixture fail on certain architectures, navigate to the module and run this build command. This installs prebuildify, creates prebuild binaries, and runs tests. Do not run this command in CI.

```bash
npm run build
```

--------------------------------

### Run App with Default Policy Location

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/lavamoat-node/README.md

Execute your application using LavaMoat with policies automatically detected in the default `./lavamoat/node/` directory. This is the simplest way to start enforcing policies.

```bash
lavamoat index.js
```

--------------------------------

### Tofu Configuration Example

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/tofu/README.md

This JSON configuration indicates read access to the 'location' object. Be aware that read access to a global object implies write access to its properties.

```json
{
  "location": "read"
}
```

--------------------------------

### Custom Capabilities: Capability Alias

Source: https://github.com/lavamoat/lavamoat/wiki/Configuration-Brainstorm

Example using a capability alias for 'reasonable-process' within the configuration.

```js
// too much guessing
{
  "capabilities": [
    "@lavamoat/powers"
  ],
  "resources": {
    "some>package": {
      "globals": {
        "process": ["reasonable-process"]
      }
    }
  }
}
```

--------------------------------

### Verify Node.js and npm Versions

Source: https://github.com/lavamoat/lavamoat/blob/main/AGENTS.md

Check if your Node.js and npm versions meet the project requirements before proceeding with setup.

```bash
# Verify Node.js version (requirement: ^20.19.0 || ^22.5.1 || ^24.0.0)
node --version
```

```bash
# Verify npm version (requirement: >=7.0.0)
npm --version
```

--------------------------------

### Browserify API Usage with LavaMoat Options

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/browserify/README.md

Programmatically create a browserify bundle with LavaMoat using the API. This example configures policy paths and enables debug policy generation.

```javascript
const browserify = require('browserify')
const fs = require('fs')

const lavamoatOpts = {
  policy: '../../policy.json',
  override: '../../policy-override.json',
  writeAutoPolicyDebug: true,
  prunePolicy: true,
}

const bundler = browserify(['./index.js'], {
  plugin: [['lavamoat-browserify', lavamoatOpts]],
})

bundler.bundle().pipe(fs.createWriteStream('./bundle.js'))
```

--------------------------------

### Install LavaMoat React Native Lockdown

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/react-native-lockdown/README.md

Install the package using npm or yarn.

```shell
npm i @lavamoat/react-native-lockdown
```

```shell
yarn add @lavamoat/react-native-lockdown
```

--------------------------------

### LavaMoat 'run --help' Output

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/node/test/e2e/snapshots/cli-run.spec.js.md

Displays the help information for the 'lavamoat run' command. Use this to understand available options and arguments for running applications with LavaMoat.

```text
lavamoat run <entrypoint>\n      \nRun a Node.js application safely\n      \nPositionals:\n  entrypoint  Path to the application entry point; relative to --project-root\n                                                                       [string] [required]\n      \nBehavior Options:\n  -b, --bin        Resolve entrypoint as a bin script                  [boolean]\n      --prod-only  Exclude development dependencies                    [boolean]\n      --verbose    Enable verbose logging                              [boolean]\n      --quiet      Disable all logging                                 [boolean]\n      --scuttle    Enable scuttling of globalThis                      [boolean]\n      \nPath Options:\n  -p, --policy                Filepath to a policy file\n                                     [string] [default: "lavamoat/node/policy.json"]\n  -o, --policy-override       Filepath to a policy override file\n                              [string] [default: "lavamoat/node/policy-override.json"]\n      --project-root, --root  Path to application root directory\n                                               [string] [default: (current directory)]\n      \nOptions:\n            --help     Show help                                             [boolean]\n            --version  Show version number                                   [boolean]
```

--------------------------------

### Global Commit Message Example

Source: https://github.com/lavamoat/lavamoat/blob/main/CONTRIBUTING.md

Example of a commit message that affects all projects, omitting the scope.

```text
chore: update keywords in package.json files
```

--------------------------------

### Build, Test, and Lint Commands

Source: https://github.com/lavamoat/lavamoat/blob/main/AGENTS.md

Execute build, test, and linting processes for the entire project. These operations may take several minutes and should not be cancelled.

```bash
# Build all packages - takes 2 seconds after setup
npm run build
```

```bash
# Run complete test suite - takes 6 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
npm test
```

```bash
# Run linting - takes 20 seconds
npm run lint
```

```bash
# Clean and rebuild everything - takes 10 seconds
npm run rebuild
```

--------------------------------

### Scoped Commit Message Example

Source: https://github.com/lavamoat/lavamoat/blob/main/CONTRIBUTING.md

Example of a commit message with a scope, indicating the affected package or directory.

```text
chore(webpack): frobnicate the widget
```

--------------------------------

### Commit Message Tag Examples

Source: https://github.com/lavamoat/lavamoat/blob/main/CONTRIBUTING.md

Examples of valid tags for commit messages, indicating the type of change.

```text
fix - for a bug fix.
feat - either for a backwards-compatible enhancement or for a rule change that adds reported problems.
fix! - for a backwards-incompatible bug fix.
feat! - for a backwards-incompatible enhancement or feature.
docs - changes to documentation only.
chore - for changes that aren't user-facing.
```

--------------------------------

### Wizard CLI options

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/harden/README.md

Displays the available command-line options for the wizard command.

```text
Options:
  -p, --package-manager <pm>  Package manager to harden (npm, yarn, pnpm)
  -d, --decisions-snapshot <file>  Path to decisions snapshot file (JSON) to pre-fill wizard
  -s, --save-decisions  Save decisions snapshot to ./decisions-snapshot.json at end of run
```

--------------------------------

### Run Browserify with Existing Policy Files

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/browserify/README.md

Execute browserify with the lavamoat-browserify plugin, automatically searching for policy files in `./lavamoat/browserify/`.

```bash
$ browserify index.js --plugin [ lavamoat-browserify ]
```

--------------------------------

### Multi-Scope Commit Message Example

Source: https://github.com/lavamoat/lavamoat/blob/main/CONTRIBUTING.md

Example of a commit message affecting multiple packages, with scopes separated by commas.

```text
fix(core,node): fix a bug in lavamoat-core and lavamoat-node
```

--------------------------------

### applyMigrations - first run allowConfig after migrations

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/allow-scripts/test/snapshots/config.spec.js.md

Shows the allowConfig object after the initial run of applyMigrations. All packages are marked with a false allowlist status as they are newly added.

```json
{
  'pkgA#1.1.0': false,
  'pkgB#1.1.0': false,
  'pkgC#1.0.0': false,
  'pkgD#1.0.0': false,
}
```

--------------------------------

### List configuration information

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/allow-scripts/README.md

Print debug information used by allow-scripts.

```sh
allow-scripts list
```

--------------------------------

### Run Test Preparation

Source: https://github.com/lavamoat/lavamoat/blob/main/AGENTS.md

Execute test preparation commands separately if needed. This ensures your test environment is correctly set up before running tests.

```bash
npm run test:prep
```

--------------------------------

### Defaults CLI options

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/harden/README.md

Displays the available command-line options for the defaults command.

```text
Options:
  -p, --package-manager <pm>  Package manager to harden (npm, yarn, pnpm)
  -l, --level <level>         Hardening level: baseline, moderate, strict  [default: moderate]
  -d, --decisions-snapshot <file>  Path to decisions snapshot file (JSON) to apply regardless of level set
  -s, --save-decisions  Save decisions snapshot to ./decisions-snapshot.json at end of run (useful as a template to edit and re-use)
```

--------------------------------

### Decisions snapshot format

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/harden/README.md

Example JSON structure for a decisions snapshot file.

```json
{
  "n_engines": true,
  "n_scripts": "n_allowscripts",
  "n_git": true,
  "n_strictgit": false,
  "n_filterenv": true
}
```

--------------------------------

### applyMigrations - first run return value

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/allow-scripts/test/snapshots/config.spec.js.md

Illustrates the return value of applyMigrations when run for the first time. It indicates changes made and logs the addition of lifecycle entries for packages.

```json
{
  "changed": true,
  "logs": [
    'Adding lifecycle pkgA#1.1.0',
    'Adding lifecycle pkgB#1.1.0',
    'Adding lifecycle pkgC#1.0.0',
    'Adding lifecycle pkgD#1.0.0',
  ]
}
```

--------------------------------

### Build the plugin

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/yarn-plugin-allow-scripts/README.md

Execute this command to compile the plugin after modifying the source code.

```sh
npm run build
```

--------------------------------

### Programmatic Usage Example

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/git-safe-dependencies/README.md

Import the git-safe-dependencies module for programmatic use. A more granular API is planned for future development.

```js
const gitSafeDependencies = require('@lavamoat/git-safe-dependencies')
```

--------------------------------

### Test @lavamoat/node CLI Functionality

Source: https://github.com/lavamoat/lavamoat/blob/main/AGENTS.md

Verify the help output for the `@lavamoat/node` CLI tool. This ensures the CLI is correctly installed and accessible.

```bash
# Test @lavamoat/node CLI functionality
node packages/node/src/cli.js --help
```

--------------------------------

### Check configuration

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/harden/README.md

Commands to verify the current configuration against a hardening level.

```sh
harden check
```

```sh
harden check --level moderate
harden check -p yarn -l strict
```

--------------------------------

### TypeScript Configuration for @lavamoat/vog

Source: https://github.com/lavamoat/lavamoat/blob/main/packages/vog/README.md

Example tsconfig.json settings required for projects using @lavamoat/vog, emphasizing ESM-only and type stripping features.

```json
{
  "compilerOptions": {
    "rewriteRelativeImportExtensions": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true
  }
}
```