filedist 0.30.0 → 0.33.0

package/README.md

@@ -5,7 +5,7 @@ Publish folders as npm packages or git repositories and extract them in any work
 ## How it works
 
 - **Publisher**: a project that has folders to share. Running `init` prepares its `package.json` so those folders are included when the package is published.
-- **Consumer**: any project that installs that package and runs `extract` to download the files locally. A `.filedist` marker file is written alongside the managed files to track ownership and enable safe updates.
+- **Consumer**: any project that installs that package and runs `install` to download the files locally. A `.filedist` marker file is written alongside the managed files to track ownership and enable safe updates.
 
 ## Extraction patterns
 
@@ -13,75 +13,73 @@ There are three ways to extract data with `filedist`. Choose the one that fits y
 
 ### Pattern 1 — Ad-hoc CLI extraction
 
-Use `npx filedist extract` directly from the command line whenever you need to pull files from a package without any prior setup.
+Use `npx filedist install` directly from the command line whenever you need to pull files from a package without any prior setup.
 
 ```sh
-npx filedist extract --packages my-shared-assets@^2.0.0 --output ./data
+npx filedist install my-shared-assets@^2.0.0 --output ./data
 
 # or use a git repository as the source
-npx filedist extract --packages git:github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs
+npx filedist install git:github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs
 ```
 
 Package specs support optional source prefixes. Use `git:` for git repositories and `npm:` when you want to make the npm source explicit. When no prefix is present, filedist treats the spec as npm. Git specs accept full repository URLs and host/path shorthands such as `git:github.com/org/repo.git@ref`.
 
-#### Auto-save to `.filedistrc.yml`
+#### Auto-save to `.filedist.yml`
 
-Whenever `--packages` is used, filedist automatically creates or updates a `.filedistrc.yml` file in the current directory with the packages and selectors from that run. This means subsequent updates can be done with a single command — no flags needed:
+Whenever a package argument is supplied, filedist automatically creates or updates a `.filedist.yml` file in the current directory with the package and selectors from that run. This means subsequent updates can be done with a single command — no flags needed:
 
 ```sh
-# First run: extract and save to .filedistrc.yml automatically
-npx filedist extract --packages my-shared-assets@^2.0.0 --output ./data
+# First run: extract and save to .filedist.yml automatically
+npx filedist install my-shared-assets@^2.0.0 --output ./data
 
-# .filedistrc.yml is now created:
+# .filedist.yml is now created:
 # sets:
 #   - package: my-shared-assets@^2.0.0
 #     output:
 #       path: ./data
 
-# Future bumps: just run extract (reads .filedistrc.yml)
-npx filedist extract
+# Future bumps: just run install (reads .filedist.yml)
+npx filedist install
 
 # Or bump to a newer version
-npx filedist extract --packages my-shared-assets@^3.0.0 --output ./data
-# .filedistrc.yml is updated in place (same entry, new version)
+npx filedist install my-shared-assets@^3.0.0 --output ./data
+# .filedist.yml is updated in place (same entry, new version)
 ```
 
-If the entry already exists in `.filedistrc.yml` with identical content, the file is left unchanged. Use `--no-save` to run a one-off extraction without reading or updating `.filedistrc.yml`:
+If the entry already exists in `.filedist.yml` with identical content, the file is left unchanged. Use `--no-save` to run a one-off extraction without reading or updating `.filedist.yml`:
 
 ```sh
-npx filedist extract --packages my-shared-assets@^2.0.0 --output ./tmp --no-save
+npx filedist install my-shared-assets@^2.0.0 --output ./tmp --no-save
 ```
 
 ### Pattern 2 — Data packages with embedded configuration
 
-Create a dedicated npm package whose `package.json` declares an `filedist` config block. That config encodes the extraction sources, output directories, filtering rules, and any combination of upstream packages. Consumers install the data package and run its bundled script — they don't need to know the internals.
+Create a dedicated npm package with a `.filedist-package.yml` file that encodes the extraction sources, output directories, filtering rules, and any combination of upstream packages. Consumers install the data package and run its bundled script — they don't need to know the internals.
 
-**Publisher** — add an `filedist` block to the data package's `package.json`:
+**Publisher** — create a `.filedist-package.yml` in the data package root:
 
-```json
-{
-  "name": "my-org-configs",
-  "version": "1.0.0",
-  "filedist": {
-    "sets": [
-      {
-        "package": "base-datasets@^3.0.0",
-        "selector": { "files": ["datasets/**"] },
-        "output": { "path": "./data/base" }
-      },
-      {
-        "package": "org-configs@^1.2.0",
-        "selector": { "contentRegexes": ["env: production"] },
-        "output": { "path": "./configs" }
-      },
-      {
-        "package": "git:github.com/flaviostutz/xdrs-core@1.3.0",
-        "selector": { "files": ["docs/**"] },
-        "output": { "path": "./xdrs" }
-      }
-    ]
-  }
-}
+```yaml
+sets:
+  - package: base-datasets@^3.0.0
+    selector:
+      files:
+        - datasets/**
+    output:
+      path: ./data/base
+
+  - package: org-configs@^1.2.0
+    selector:
+      contentRegexes:
+        - env: production
+    output:
+      path: ./configs
+
+  - package: git:github.com/flaviostutz/xdrs-core@1.3.0
+    selector:
+      files:
+        - docs/**
+    output:
+      path: ./xdrs
 ```
 
 Run `pnpm dlx filedist init` in that package and then `npm publish` to release it.
@@ -98,76 +96,43 @@ No knowledge of the upstream packages or transformation rules is required.
 
 ### Pattern 3 — Config file mode
 
-Add an `filedist` configuration directly to a project's own `package.json` (or a `.filedistrc` file) and then run `filedist extract` without `--packages`. The CLI automatically loads the configuration and runs every entry, reusing the same runner logic as data packages.
+Add a `.filedist.yml` file to your project and run `filedist install` without a package argument. The CLI automatically loads the configuration and runs every entry, reusing the same runner logic as data packages.
 
-**Consumer** — declare the config inline in `package.json`:
-
-```json
-{
-  "name": "my-project",
-  "filedist": {
-    "defaultPresets": ["prod"],
-    "sets": [
-      {
-        "package": "base-datasets@^3.0.0",
-        "selector": { "files": ["datasets/**"] },
-        "output": { "path": "./data" }
-      },
-      {
-        "package": "git:github.com/flaviostutz/xdrs-core@1.3.0",
-        "selector": { "files": ["docs/**"] },
-        "output": { "path": "./xdrs" }
-      }
-    ]
-  }
-}
-```
+**Consumer** — create a `.filedist.yml` in the project root:
 
-Or write a standalone `.filedistrc` (JSON object at the top level):
+```yaml
+defaultPresets:
+  - prod
+sets:
+  - package: base-datasets@^3.0.0
+    selector:
+      files:
+        - datasets/**
+    output:
+      path: ./data
 
-```json
-{
-  "sets": [
-    {
-      "package": "base-datasets@^3.0.0",
-      "selector": { "files": ["datasets/**"] },
-      "output": { "path": "./data" }
-    },
-    {
-      "package": "git:file:///absolute/path/to/local-repo@v2.0.0",
-      "selector": { "files": ["conf/**"] },
-      "output": { "path": "./local-conf" }
-    }
-  ]
-}
+  - package: git:github.com/flaviostutz/xdrs-core@1.3.0
+    selector:
+      files:
+        - docs/**
+    output:
+      path: ./xdrs
 ```
 
-For a local Windows path, use the same `file://` form with a drive letter, for example `git:file:///C:/work/local-repo@v2.0.0`.
+For a local git repository, use the `file://` form with an absolute path, for example `git:file:///absolute/path/to/local-repo@v2.0.0`. On Windows use a drive letter: `git:file:///C:/work/local-repo@v2.0.0`.
 
-Then run any command without `--packages`:
+Then run any command without a package argument:
 
 ```sh
-npx filedist           # same as 'npx filedist extract'
-npx filedist extract   # reads config, extracts all entries or only defaultPresets when defined
+npx filedist           # same as 'npx filedist install'
+npx filedist install   # reads .filedist.yml, extracts all entries or only defaultPresets when defined
 npx filedist check     # checks the same effective set selection
-npx filedist purge     # purges the same effective set selection
 ```
 
-Config is resolved using [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig). Sources searched in order from the current directory:
-
-| Source | Key / format | Notes |
-|---|---|---|
-| `.filedistrc.local.yml` | YAML object with `"sets"` array | Local-only override; checked first; not searched in parent dirs |
-| `package.json` | `"filedist"` key — object with `"sets"` array | |
-| `.filedistrc` | JSON or YAML object with `"sets"` array | |
-| `.filedistrc.json` | JSON object with `"sets"` array | |
-| `.filedistrc.yaml` / `.filedistrc.yml` | YAML object with `"sets"` array | |
-| `filedist.config.js` | CommonJS module exporting object with `sets` array | |
-
-When `.filedistrc.local.yml` is present in the current directory it takes full priority over all other config sources. This is useful when you are developing a package that already ships its own filedist config (e.g. in `package.json`) but you need to run extra extractions locally — for example to pull other packages into your workspace — without those entries being part of the published package config.
+filedist reads only `.filedist.yml` from the current working directory. No parent-directory traversal is performed.
 
 All runner flags (`--dry-run`, `--silent`, `--verbose`, `--gitignore=false`, `--managed=false`, `--presets`, `--output`) work as usual.
-When `filedist.defaultPresets` is defined, `extract`, `check`, and `purge` behave as if `--presets <tags>` had been passed automatically. Passing `--presets` explicitly overrides that configured default for the current invocation.
+When `filedist.defaultPresets` is defined, `install` and `check` behave as if `--presets <tags>` had been passed automatically. Passing `--presets` explicitly overrides that configured default for the current invocation.
 Use `--all` to ignore `defaultPresets` for one run and process every configured entry.
 
 Config-file mode can mix npm packages and git repositories in the same `sets` array. Use the `git:` prefix for git entries.
@@ -186,11 +151,9 @@ In the project whose folders you want to share:
 # share specific folders by glob pattern (required)
 pnpm dlx filedist init --files "docs/**,data/**,configs/**"
 
-# also bundle an additional package so consumers get data from both sources
-pnpm dlx filedist init --files "docs/**" --packages shared-configs@^1.0.0
-
-# share multiple upstream sources, including git
-pnpm dlx filedist init --files "docs/**" --packages "shared-configs@^1.0.0,git:github.com/flaviostutz/xdrs-core@1.3.0"
+# to also bundle upstream packages, add them manually to .filedist-package.yml after init
+pnpm dlx filedist init --files "docs/**"
+# then edit .filedist-package.yml and add entries for shared-configs@^1.0.0, git sources, etc.
 
 ```
 
@@ -204,46 +167,45 @@ npm publish
 
 ```sh
 # npm package examples
-npx filedist extract --packages my-shared-assets --output ./data
-npx filedist extract --packages my-shared-assets@^2.0.0 --output ./data
-npx filedist extract --packages "my-shared-assets@^2.0.0,another-pkg@1.x" --output ./data
-npx filedist extract --packages my-shared-assets --files "**/*.md" --output ./docs
-npx filedist extract --packages my-shared-assets --content-regex "env: production" --output ./configs
-npx filedist extract --packages my-shared-assets --output ./data --force
-npx filedist extract --packages my-shared-assets --output ./data --gitignore=false
-npx filedist extract --packages my-shared-assets --output ./data --managed=false
-npx filedist extract --packages my-shared-assets --output ./data --dry-run
-npx filedist extract --packages my-shared-assets@latest --output ./data --upgrade
+npx filedist install my-shared-assets --output ./data
+npx filedist install my-shared-assets@^2.0.0 --output ./data
+npx filedist install my-shared-assets --files "**/*.md" --output ./docs
+npx filedist install my-shared-assets --content-regex "env: production" --output ./configs
+npx filedist install my-shared-assets --output ./data --force
+npx filedist install my-shared-assets --output ./data --gitignore=false
+npx filedist install my-shared-assets --output ./data --managed=false
+npx filedist install my-shared-assets --output ./data --dry-run
+npx filedist install my-shared-assets@latest --output ./data --upgrade
 
 # git source examples
-npx filedist extract --packages https://github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs
-npx filedist extract --packages https://github.com/flaviostutz/xdrs-core@main --output ./xdrs
-npx filedist extract --packages "https://github.com/org/repo-a@v1.0.0,file:///tmp/repo-b@main" --output ./git-data
-npx filedist extract --packages https://github.com/flaviostutz/xdrs-core@1.3.0 --files "docs/**/*.md" --output ./docs
-npx filedist extract --packages https://github.com/flaviostutz/xdrs-core@1.3.0 --content-regex "Decision Outcome" --output ./filtered-docs
-npx filedist extract --packages https://github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs --force
-npx filedist extract --packages https://github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs --gitignore=false
-npx filedist extract --packages https://github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs --managed=false
-npx filedist extract --packages https://github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs --dry-run
-npx filedist extract --packages https://github.com/flaviostutz/xdrs-core@main --output ./xdrs --upgrade
+npx filedist install git:github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs
+npx filedist install git:github.com/flaviostutz/xdrs-core@main --output ./xdrs
+npx filedist install git:github.com/flaviostutz/xdrs-core@1.3.0 --files "docs/**/*.md" --output ./docs
+npx filedist install git:github.com/flaviostutz/xdrs-core@1.3.0 --content-regex "Decision Outcome" --output ./filtered-docs
+npx filedist install git:github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs --force
+npx filedist install git:github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs --gitignore=false
+npx filedist install git:github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs --managed=false
+npx filedist install git:github.com/flaviostutz/xdrs-core@1.3.0 --output ./xdrs --dry-run
+npx filedist install git:github.com/flaviostutz/xdrs-core@main --output ./xdrs --upgrade
+# For multiple packages at once, use a config file (.filedistrc) and run: npx filedist install
 ```
 
-`extract` logs every file change as it happens:
+`install` logs every file change as it happens:
 
 ```
-A	data/users-dataset/user1.json
-M	data/configs/app.config.json
-D	data/old-file.json
+  + data/users-dataset/user1.json (M,I)
+  ~ data/configs/app.config.json (M,I)
+  - data/old-file.json
 ```
 
 If the published package includes its own bin script (normally when it's prepared using "init") you can also call it directly so it extracts data that is inside the package itself:
 
 ```sh
-npx my-shared-assets extract --output ./data
+npx my-shared-assets install --output ./data
 npx my-shared-assets check  --output ./data
 ```
 
-When the data package defines multiple `filedist` entries in its `package.json`, you can limit which entries are processed using the `--presets` option. Only entries whose `presets` list includes at least one of the requested presets will be extracted; entries with no presets are skipped when a preset filter is active.
+When the data package defines multiple entries in its `.filedist-package.yml`, you can limit which entries are processed using the `--presets` option. Only entries whose `presets` list includes at least one of the requested presets will be extracted; entries with no presets are skipped when a preset filter is active.
 
 ```sh
 # run only entries tagged with "prod"
@@ -253,17 +215,21 @@ npx my-shared-assets --presets prod
 npx my-shared-assets --presets prod,staging
 ```
 
-To use presets, add a `presets` array to each `filedist` entry in the data package's `package.json`:
+To use presets, add a `presets` array to each entry in the data package's `.filedist-package.yml`:
 
-```json
-{
-  "filedist": {
-    "sets": [
-      { "package": "my-shared-assets", "output": { "path": "./data" }, "presets": ["prod"] },
-      { "package": "my-dev-assets",    "output": { "path": "./dev-data" }, "presets": ["dev", "staging"] }
-    ]
-  }
-}
+```yaml
+sets:
+  - package: my-shared-assets
+    output:
+      path: ./data
+    presets:
+      - prod
+  - package: my-dev-assets
+    output:
+      path: ./dev-data
+    presets:
+      - dev
+      - staging
 ```
 
 Check the /examples folder to see this in action
@@ -323,8 +289,8 @@ Top-level config fields:
 
 | Option | Type | Default | Description |
 |---|---|---|---|
-| `defaultPresets` | `string[]` | none | CLI-only fallback for config-file mode. `extract`, `check`, and `purge` behave as if `--presets <tags>` had been passed when the flag is omitted. |
-| `postExtractCmd` | `string[]` | none | Command argv run after a successful non-dry-run `extract`. The first array item is the executable and the remaining items are its arguments. Full extract argv is appended. |
+| `defaultPresets` | `string[]` | none | CLI-only fallback for config-file mode. `install` and `check` behave as if `--presets <tags>` had been passed when the flag is omitted. |
+| `postExtractCmd` | `string[]` | none | Command argv run after a successful non-dry-run `install`. The first array item is the executable and the remaining items are its arguments. Full install argv is appended. |
 
 #### SymlinkConfig
 
@@ -347,57 +313,50 @@ After extraction, for each config the runner finds workspace files matching `fil
 
 Example with multiple options:
 
-```json
-{
-  "filedist": {
-    "sets": [
-      {
-        "package": "my-shared-assets@^2.0.0",
-        "selector": {
-          "files": ["docs/**", "configs/*.json"],
-          "upgrade": true
-        },
-        "output": {
-          "path": "./data",
-          "gitignore": true,
-          "symlinks": [
-            { "source": "**\/skills\/**", "target": ".github/skills" }
-          ],
-          "contentReplacements": [
-            { "files": "docs/**\/*.md", "match": "<!-- version: .* -->", "replace": "<!-- version: 2.0.0 -->" }
-          ]
-        },
-        "presets": ["prod"]
-      },
-      {
-        "package": "git:github.com/flaviostutz/xdrs-core@1.3.0",
-        "selector": {
-          "files": ["docs/**"],
-          "upgrade": true
-        },
-        "output": {
-          "path": "./xdrs",
-          "gitignore": false
-        },
-        "presets": ["prod"]
-      }
-    ]
-  }
-}
+```yaml
+sets:
+  - package: my-shared-assets@^2.0.0
+    selector:
+      files:
+        - docs/**
+        - configs/*.json
+      upgrade: true
+    output:
+      path: ./data
+      gitignore: true
+      symlinks:
+        - source: "**/skills/**"
+          target: .github/skills
+      contentReplacements:
+        - files: docs/**/*.md
+          match: "<!-- version: .* -->"
+          replace: "<!-- version: 2.0.0 -->"
+    presets:
+      - prod
+
+  - package: git:github.com/flaviostutz/xdrs-core@1.3.0
+    selector:
+      files:
+        - docs/**
+      upgrade: true
+    output:
+      path: ./xdrs
+      gitignore: false
+    presets:
+      - prod
 ```
 
 ### 3. Check files are in sync
 
-Verifies that every file in the output directory matches what is currently in the published package. When the target package itself declares `filedist.sets`, check recurses into those transitive dependencies — reporting drift at every level of the hierarchy without downloading anything new beyond what is already installed. Use `selector.presets` on an entry to restrict which of the target's sets are checked.
+Verifies that every file in the output directory matches what was installed. `check` reads exclusively from `.filedist.lock` — it does **not** read your `.filedist.yml` configuration and does **not** require `--packages`. The lockfile must exist (run `filedist install` first).
 
 ```sh
-npx filedist check --packages my-shared-assets --output ./data
+npx filedist check
 # exit 0 = in sync, exit 1 = drift or error
-
-# check multiple packages
-npx filedist check --packages "my-shared-assets,another-pkg" --output ./data
 ```
 
+`check` uses the pinned package versions recorded in `.filedist.lock` so results are fully reproducible without any network access beyond what is already cached.
+
 The check command reports differences per package:
 
 ```
@@ -407,6 +366,24 @@ The check command reports differences per package:
     + extra:    data/old-file.json
 ```
 
+#### Offline / local-only check
+
+By default `check` compares local files against the package versions pinned in `.filedist.lock` to also detect *extra* files — files that exist in the package source but were never extracted. If you want a fast, fully offline check that skips all network and install steps, use `--local-only`:
+
+```sh
+npx filedist check --local-only
+```
+
+In this mode filedist reads the `.filedist` marker file for each output directory and verifies:
+
+1. **File checksums** — every non-mutable file listed in the marker is hashed and compared against the checksum recorded at extraction time.
+
+Extra-file detection (files in the source that were never extracted) is skipped because no package source is available. Use `--local-only` when:
+
+- Running in a **CI environment** where the package registry is unavailable or you want to avoid install latency.
+- Checking **air-gapped** or **offline** environments.
+- You only care that previously extracted files have not been **locally tampered with**, and are not concerned about new files added to the upstream package since the last extract.
+
 ### 4. List managed files
 
 ```sh
@@ -425,26 +402,45 @@ another-pkg@1.0.0
   data/other-file.txt
 ```
 
-### 5. Purge managed files
+### 5. Remove a package set
 
-Remove all files previously extracted by one or more packages without touching any other files in the output directory. No network access or package installation is required — only the local `.filedist` marker state is used. When the target package itself declares `filedist.sets`, purge recurses into those transitive dependencies and removes their managed files too, mirroring what extract originally created.
+Remove one or more set entries from your config file and delete their managed files from disk. `remove` reads your `.filedist.yml` config — **not** `.filedist.lock`. It deletes the matching entries from the config file, then runs a full install with the remaining entries so the lockfile is updated and orphaned files are deleted. This is equivalent to manually deleting the sets from your config and running `filedist install`.
 
 ```sh
-# remove all files managed by a package
-npx filedist purge --packages my-shared-assets --output ./data
+# remove all entries for a package (version is ignored during matching)
+npx filedist remove my-shared-assets
+
+# remove only the entry pointing to a specific output directory
+npx filedist remove my-shared-assets --output ./data
+
+# remove every set entry from the config (clears all managed files)
+npx filedist remove --all
+
+# preview changes without modifying config or disk
+npx filedist remove my-shared-assets --dry-run
+```
 
-# purge multiple packages at once
-npx filedist purge --packages "my-shared-assets,another-pkg" --output ./data
+After the config is updated, `remove` calls `install` internally (without `--frozen-lockfile`) so:
+- The lockfile is rewritten with the remaining sets.
+- Files that were managed by the removed package are deleted from disk.
+- Files managed by other packages are left untouched.
 
-# preview what would be deleted without removing anything
-npx filedist purge --packages my-shared-assets --output ./data --dry-run
+### 6. Update to latest versions
+
+Bumps all packages to their latest available versions, updates `.filedist.lock`, and re-extracts the files.
+
+```sh
+npx filedist update
+
+# preview what would change without writing anything
+npx filedist update --dry-run
 ```
 
-After a purge, the corresponding entries are removed from the `.filedist` marker file and any empty directories are cleaned up. `.gitignore` sections written by `extract` are also removed.
+`update` reads the current `sets` recorded in `.filedist.lock` (falling back to your config file if no lockfile exists), forces a fresh install of every package, and writes the new resolved versions back to `.filedist.lock`.
 
 ## Hierarchical package resolution
 
-`extract`, `check`, and `purge` are all hierarchy-aware: when a target package or git repository carries its own `filedist.sets` block in its `package.json` or `.filedistrc*`, the command automatically recurses into those transitive dependencies.
+`extract` and `check` are all hierarchy-aware: when a target package or git repository carries its own `.filedist-package.yml`, the command automatically recurses into those transitive dependencies.
 
 This lets you build layered data package chains:
 
@@ -456,7 +452,7 @@ consumer project
             └─ raw-assets     (leaf package)
 ```
 
-Running `npx filedist extract --packages my-org-configs --output ./data` will extract files from every package in the chain, not just `my-org-configs` itself.
+Running `npx filedist install my-org-configs --output ./data` will extract files from every package in the chain, not just `my-org-configs` itself.
 
 When the source is git, filedist clones repositories into `.filedist-tmp` inside the working directory, adds that folder to `.gitignore` if needed, resolves nested config from the cloned repository, and removes `.filedist-tmp` when the command ends.
 
@@ -464,9 +460,9 @@ When the source is git, filedist clones repositories into `.filedist-tmp` inside
 
 Each level's `output.path` is resolved relative to the caller's own `output.path`. A package at depth 1 with `output.path: "./configs"` and a transitive dependency with `output.path: "./shared"` will land at `./configs/shared`.
 
-### Caller overrides (extract only)
+### Caller overrides (install only)
 
-When `extract` recurses, the caller's `output` flags are inherited by every transitive dependency, with caller-defined values always winning:
+When `install` recurses, the caller's `output` flags are inherited by every transitive dependency, with caller-defined values always winning:
 
 | Caller sets | Effect on transitive entries |
 |---|---|
@@ -483,21 +479,17 @@ Settings that are undefined on the caller are left as-is so the transitive packa
 
 Set `selector.presets` on an entry to control which sets inside the target package are recursed into. Only sets whose `presets` tag overlaps with the filter are processed; sets with no `presets` are skipped when a filter is active.
 
-```json
-{
-  "filedist": {
-    "sets": [
-      {
-        "package": "my-org-configs@^2.0.0",
-        "output": { "path": "./data" },
-        "selector": { "presets": ["prod"] }
-      }
-    ]
-  }
-}
+```yaml
+sets:
+  - package: my-org-configs@^2.0.0
+    output:
+      path: ./data
+    selector:
+      presets:
+        - prod
 ```
 
-The same filtering is applied during `check` and `purge` so they stay in sync with what `extract` originally wrote.
+The same filtering is applied during `check` so they stay in sync with what `extract` originally wrote.
 
 ### Circular dependency detection
 
@@ -507,14 +499,15 @@ If a package chain references itself (directly or transitively), the command sto
 
 ```
 Usage:
-  npx filedist [init|extract|check|list|purge] [options]
+  npx filedist [init|install|check|list|remove|update] [options]
 
 Commands:
   init      Set up publishing configuration in a package
-  extract   Extract files from a published package into a local directory
-  check     Verify local files are in sync with the published package
+  install   Extract files from a published package into a local directory (alias: extract)
+  check     Verify local files are in sync with the lockfile (reads .filedist.lock)
   list      List all files managed by filedist in an output directory
-  purge     Remove all managed files previously extracted by given packages
+  remove    Remove a package set from config and delete its managed files (reads .filedist.yml)
+  update    Bump packages to latest versions, update lockfile, and re-extract
 
 Global options:
   --help, -h       Show help
@@ -523,20 +516,13 @@ Global options:
 Init options:
   --files <patterns>       Comma-separated glob patterns of files to publish
                            e.g. "docs/**,data/**,configs/*.json"
-  --packages <specs>       Comma-separated additional package specs to bundle as data sources.
-                           Each spec is "name" or "name@version", e.g.
-                           "shared-configs@^1.0.0,base-templates@2.x".
-                           Added to `dependencies` so consumers pull data from all of them.
   --output, -o <dir>       Directory to scaffold into (default: current directory)
 
-Extract options:
-  --packages <specs>       Comma-separated package specs.
-                           When omitted, filedist searches for a configuration file
-                           (package.json "filedist" key, .filedistrc, etc.) and runs all
-                           entries defined there.
-                           Each spec is `name`, `name@version`, `npm:name@version`, or
-                           `git:github.com/org/repo.git@ref`, e.g.
-                           "my-pkg@^1.0.0,git:github.com/org/repo.git@main"
+Install options:
+  [<package>]              Package spec to add/install (positional; omit to use config file).
+                           When provided, the entry is saved to .filedist.yml automatically.
+                           Spec formats: name, name@version, npm:name@version, or
+                           git:github.com/org/repo.git@ref
   --output, -o <dir>       Output directory (default: current directory)
   --force                  Overwrite existing files or files owned by a different package
   --mutable                Skip files that already exist; mark extracted files as mutable (check ignores
@@ -551,22 +537,29 @@ Extract options:
   --upgrade                Reinstall the package even if already present
   --silent                 Print only the final result line, suppressing per-file output
   --verbose, -v            Print detailed progress information for each step
-  --no-save                Skip loading and updating the local .filedistrc.yml config file.
-                           By default, when --packages is provided the run is saved to
-                           .filedistrc.yml so future `filedist extract` calls (without
-                           --packages) reuse the same config automatically.
+  --no-save                Skip loading and updating the local .filedist.yml config file.
+                           By default, when a positional package is provided the entry is saved to
+                           .filedist.yml so future `filedist install` calls reuse the same config.
+  --frozen-lockfile        Use .filedist.lock exclusively; fail if the lock file does not
+                           exist. Does not update the lock file.
 
 Check options:
-  --packages <specs>       Same format as extract.
-                           When omitted, reads from a configuration file (see Pattern 3).
-  --output, -o <dir>       Output directory to check (default: current directory)
-
-Purge options:
-  --packages <specs>       Comma-separated package names whose managed files should be removed.
-                           When omitted, reads from a configuration file (see Pattern 3).
-  --output, -o <dir>       Output directory to purge from (default: current directory)
-  --dry-run                Simulate purge without removing any files
+  (no extra options — reads exclusively from .filedist.lock)
+  --local-only             Skip package install; verify only file checksums from .filedist markers
+  --verbose, -v            Print detailed progress information
+
+Update options:
+  --dry-run                Preview changes without writing any files
+  --verbose, -v            Print detailed progress information
+
+Remove options:
+  <package>                Package name to remove (version/ref is ignored during matching)
+  --output, -o <dir>       Only remove entries whose output.path equals this value
+  --all                    Remove every set entry from the config
+  --dry-run                Preview changes without modifying config or disk
+  --config <file>          Path to a config file (overrides default .filedist.yml)
   --silent                 Suppress per-file output
+  --verbose, -v            Print detailed progress information
 
 List options:
   --output, -o <dir>       Output directory to inspect (default: current directory)
@@ -577,8 +570,9 @@ List options:
 `filedist` also exports a programmatic API:
 
 ```typescript
-import { actionExtract, actionCheck, actionList, actionPurge } from 'filedist';
+import { actionInstall, actionCheck, actionList, actionRemove, actionUpdate } from 'filedist';
 import type { FiledistExtractEntry, ProgressEvent } from 'filedist';
+import path from 'node:path';
 
 const entries: FiledistExtractEntry[] = [
   { package: 'my-shared-assets@^2.0.0', output: { path: './data' } },
@@ -586,35 +580,58 @@ const entries: FiledistExtractEntry[] = [
 const cwd = process.cwd();
 
 // extract files
-const result = await actionExtract({ entries, cwd });
+const result = await actionInstall({ entries, cwd });
 console.log(result.added, result.modified, result.deleted);
 
 // dry-run: preview changes without writing files
-const dryResult = await actionExtract({ entries: entries.map(e => ({ ...e, output: { ...e.output, dryRun: true } })), cwd });
+const dryResult = await actionInstall({ entries: entries.map(e => ({ ...e, output: { ...e.output, dryRun: true } })), cwd });
 console.log('Would add', dryResult.added, 'files');
 
 // track progress file-by-file
-await actionExtract({
+await actionInstall({
   entries,
   cwd,
   onProgress: (event: ProgressEvent) => {
-    if (event.type === 'file-added')    console.log('A', event.file);
-    if (event.type === 'file-modified') console.log('M', event.file);
-    if (event.type === 'file-deleted')  console.log('D', event.file);
+    if (event.type === 'file-added')    console.log('+', event.file);
+    if (event.type === 'file-modified') console.log('~', event.file);
+    if (event.type === 'file-deleted')  console.log('-', event.file);
   },
 });
 
-// check sync status
-const summary = await actionCheck({ entries, cwd });
-const hasDrift = summary.missing.length > 0 || summary.modified.length > 0 || summary.extra.length > 0;
+// use frozen lockfile (reads .filedist.lock, fails if missing, does not update it)
+const frozenResult = await actionInstall({ entries, cwd, frozenLockfile: true });
+console.log(frozenResult.added, frozenResult.modified);
+
+// check sync status (reads .filedist.lock; pass entries:[] to let lockfile drive)
+const lockfilePath = '.filedist.lock';
+const summary = await actionCheck({ entries: [], cwd, lockfilePath, frozenLockfile: true });
+const hasDrift = summary.missing.length > 0 || summary.conflict.length > 0 || summary.extra.length > 0;
 if (hasDrift) {
   console.log('Missing:', summary.missing);
-  console.log('Modified:', summary.modified);
+  console.log('Conflict:', summary.conflict);
   console.log('Extra:', summary.extra);
 }
 
-// remove all managed files (no network required)
-await actionPurge({ entries, config: null, cwd });
+// remove a specific package set from config and delete its managed files
+const removeResult = await actionRemove({
+  cwd,
+  packageSpec: 'my-shared-assets',
+  configFilePath: path.join(cwd, '.filedist.yml'),
+  lockfilePath: path.join(cwd, '.filedist.lock'),
+});
+console.log('Removed entries:', removeResult.removedEntries, 'deleted files:', removeResult.install.deleted);
+
+// remove all sets from config (clears all managed files)
+await actionRemove({
+  cwd,
+  all: true,
+  configFilePath: path.join(cwd, '.filedist.yml'),
+  lockfilePath: path.join(cwd, '.filedist.lock'),
+});
+
+// update all packages to latest versions
+const updateResult = await actionUpdate({ cwd });
+console.log('Updated:', updateResult.added, 'added,', updateResult.modified, 'modified,', updateResult.deleted, 'deleted');
 
 // list all files managed by filedist in an output directory
 const managed = await actionList({ entries, config: null, cwd });
@@ -635,11 +652,59 @@ type ProgressEvent =
 
 ### `postExtractCmd`
 
-Set `postExtractCmd` at the top level of your config to run a command after a successful non-dry-run `extract`.
+Set `postExtractCmd` at the top level of your config to run a command after a successful non-dry-run `install`.
 Use an argv array such as `["node", "scripts/post-extract.js"]`; shell strings are rejected so common quoting mistakes fail clearly.
 
 See the root [README.md](../README.md) for the full documentation.
 
+## Lock file
+
+Each `install` run writes a `.filedist.lock` file in the working directory that records:
+
+- **`packages`** — the exact resolved version for every package in the dependency graph
+- **`sets`** — the full entry definitions (package specs, selectors, output paths) that were used for this install
+- **`managed_files`** — the list of all files managed after the install
+
+```json
+{
+  "lockfileVersion": 1,
+  "packages": {
+    "my-shared-assets": { "source": "npm", "spec": "my-shared-assets", "resolvedVersion": "2.3.1" },
+    "git:github.com/org/repo.git@main": { "source": "git", "spec": "git:github.com/org/repo.git@main", "resolvedVersion": "abc123def456" }
+  },
+  "sets": [
+    { "package": "my-shared-assets@^2.0.0", "output": { "path": "./data" } }
+  ],
+  "managed_files": ["data/user1.json", "data/configs/app.config.json"]
+}
+```
+
+This file makes installs **reproducible** — even if a newer version of a package is published between runs, repeating `install` will fetch exactly the versions that were used the first time.
+
+`check` reads **exclusively from `.filedist.lock`** (using the `sets` stored there) and does not read your `.filedist.yml` configuration. This ensures it always operates on the same entry definitions that were used during install, regardless of any local config changes.
+
+When `--frozen-lockfile` is passed to `install`, it also validates that the current managed files match the list stored in the lockfile, failing if they differ.
+
+### `--frozen-lockfile`
+
+Pass `--frozen-lockfile` to enforce that the lock file is used as-is without any resolution or update:
+
+```sh
+# use exactly the versions from .filedist.lock, fail if it does not exist
+npx filedist install --frozen-lockfile
+```
+
+Behaviour:
+- Reads `.filedist.lock` and pins every package to its recorded version.
+- Fails immediately if `.filedist.lock` does not exist.
+- Does **not** write or update `.filedist.lock`.
+
+### Commit `.filedist.lock`
+
+Commit `.filedist.lock` alongside `.filedist.yml` so that everyone on the team and all CI jobs install identical file versions.
+
+---
+
 ## Managed file tracking
 
 Extracted files are set read-only (`444`) and tracked in a `.filedist` marker file in each output directory. On subsequent extractions:
@@ -659,7 +724,7 @@ Multiple packages can coexist in the same output directory; each owns its own fi
 | Folder / file | Purpose |
 |---|---|
 | `src/cli/` | CLI entry-points: argument parsing, help text, config loading, per-command handlers |
-| `src/package/` | Package-level orchestration: config resolution, fileset iteration, purge and init coordination |
+| `src/package/` | Package-level orchestration: config resolution, fileset iteration, and init coordination |
 | `src/fileset/` | File-level extraction, diff, check, and sync logic |
 | `src/types.ts` | Shared TypeScript types |
 | `src/utils.ts` | Low-level utilities: package install, glob/hash helpers, package manager detection |