@_linked/cli 1.46.2 → 1.47.0

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # Changelog
 
+## 1.47.0
+
+### Minor Changes
+
+- [#265](https://github.com/linked-fw/cli/pull/265) [`2185964`](https://github.com/linked-fw/cli/commit/2185964a8ddbe910812ff0b1bf6dbae76ec82e47) Thanks [@flyon](https://github.com/flyon)! - `linked localize` now builds on npm workspaces. A checkout in `packages-local/` is a workspace
+  member through the app's `"packages-local/*"` glob, so npm links it and dedupes everything below
+  it; nothing is installed inside a checkout, pruned or symlinked by hand any more. A lock-at-rest
+  hook keeps the committed `package-lock.json` clean while checkouts are linked, git hooks stop a
+  leaked lockfile from being committed, and a drift report says when the linked tree is not what
+  the app declares. The full guide is `docs/localize.md`.
+
+  **To adopt it**
+
+  1. Update `@_linked/cli`.
+  2. Run `npx linked localize <pkg>` once. Its first run sets the app up and prints what changed:
+     `"packages-local/*"` in `workspaces`, `postinstall` and `dependencies` scripts that run the
+     lock-at-rest hook, `packages-local/` and `.packages-local.parked/` in `.gitignore`, and the
+     matching `package-lock.json`. Commit exactly those three files (`package.json`,
+     `package-lock.json`, `.gitignore`); `git status` shows nothing else. An app that already has the
+     earlier unguarded hook command is upgraded in place.
+  3. Remove `linked localize --ensure` from `pre*` scripts and `--relink` from `postinstall` (the
+     set-up replaces it).
+  4. Migrating checkouts made by the old localize: delete `local-packages.json` and each checkout's
+     own `node_modules`, then take them all in with one `npx linked localize <names…> --adopt`. See
+     "Migrating from the old localize" in `docs/localize.md`.
+
+  The hook scripts run through a guard that does nothing where the cli is not installed, so
+  `npm ci --omit=dev` (Docker, production) is unaffected. `npm ci` itself refuses while checkouts are
+  present; use `npm install` then.
+
+  **Commands and flags**
+
+  - **Changed:** `linked delocalize [names…]` (no names: every checkout) now parks checkouts in
+    `.packages-local.parked/` and reinstalls the registry copies itself;
+    `linked localize <name>` or the new `linked localize --parked` takes them back. `--purge`
+    deletes instead, and refuses unless the work is saved elsewhere: uncommitted changes, commits no
+    remote has (on any branch or a detached `HEAD`), a stash, a checkout without `.git` or any
+    failing git call all refuse; `--force` overrides.
+  - **New:** `--subdir` clones a monorepo whole into `packages-local/.repos/` and links the package
+    inside it.
+  - **New:** `linked localize --list --check` prints only the drift and exits 1 when there is any,
+    for CI.
+  - **Removed:** `--reinstall`, `--no-prune` and `localize --force`, with pruning and the Vite dedupe
+    localize used to derive. `--dir` accepts only `packages-local` (exit 2 otherwise).
+  - **Deprecated:** `--relink` and `--ensure` do nothing and exit 0, so existing scripts keep
+    installing. Remove them.
+  - `local-packages.json` is no longer read; the record is the directories in `packages-local/`.
+  - Every command acts on the app root: the nearest directory whose `package.json` has `workspaces`,
+    climbing further only through ancestors whose globs match it. They work from inside a member, and
+    a git worktree nested in the app stays its own app.
+
+  **Exit codes.** 1: `--list --check` found drift. 2: bad command line. 6: any guard refusal,
+  including a refused `--purge` (was 5) and an `overrides` key naming a localized package (npm
+  refuses those with `EOVERRIDE`; localize names the key and changes nothing). 7: `npm install` at
+  the app root failed. 3 (unusable record file) and 8 (manifests changed during the run) are retired
+  and not reused.
+
+  **Git hooks.** localize writes `pre-commit` (refuses a staged `package.json` or
+  `package-lock.json` that lists a checkout, and refuses when git cannot show what is staged) and
+  `post-merge`/`post-checkout` (`npm install` when the dependency manifests changed; nothing in a
+  work tree without checkouts). They work for an app below the git top level and in linked
+  worktrees (which share them; localize says so). Under `core.hooksPath` (husky) nothing is written:
+  localize prints the one line to add to each hook, which refuses wherever in the file it sits. A
+  hook file you wrote is left alone. A clone that has checkouts but no hooks gets a one-line notice
+  from lock-at-rest naming the command that writes them.
+
+  **Lock-at-rest.** After every install it restores the committed (or deliberately staged)
+  `package-lock.json`. While `package.json` differs from `HEAD` it leaves the lockfile alone and
+  warns that it must not be committed: change dependencies with `linked delocalize` first.
+
+  **Drift.** Reported by `--list`, by lock-at-rest after an install that changed the tree, and
+  before `start`, `script`, `call` and `build-all`: a range a checkout misses, a second copy of a
+  localized package, a nested copy of `@_linked/core`, `@_linked/react` or `@_linked/server-utils`,
+  and a checkout npm installed that is gone. It only reports, except under `--list --check`.
+
+  **`build-all`** builds the cli's own dependencies (a localized `@_linked/core`) first, then the
+  cli alone, then the rest; a localized cli builds with its own `npm run build`.
+
+  **Windows (written for it, not yet run there).** `npm`, `npx` and `.bin` shims start through one
+  helper (`node npm-cli.js` when npm started the cli, else the `.cmd` through `cmd.exe` with every
+  argument quoted), in the commands and in the `post-merge`/`post-checkout` hook. `--subdir` links
+  are junctions; files are imported by `file:` URL; POSIX-only shell use (`cd <dir> &&` chains,
+  `/dev/tty`, single-quoted strings, `chmod` in the cli's own build) is gone; edited
+  `package.json`, `.gitignore`, `.npmrc` and source files keep CRLF. README "Windows" lists what is
+  left.
+
+  **Removed deep imports** (reachable before through the `@_linked/cli/*` subpath exports; no known
+  consumer):
+
+  - `vite-config`: `localizedDedupe`;
+  - `utils/createPackageLocation`: `ensureRelinkPostinstall`, `ensureRelinkHooks`, `RELINK_COMMAND`;
+  - `installed-packages`: `readInstalledPkgSync`;
+  - `lifecycle`: `BuildToolOrder.buildToolFirst` (the type now has `pre` and `start`);
+  - `commands/localize`: `pruneOptions`;
+  - `localize/index`: `relink`, `pruneProvided`, `shouldPrune`, `providedPackages`, `ensure`,
+    `reinstall`, `checkOneCopy`, `readManifest`, `writeManifest`, `manifestPath`,
+    `MANIFEST_FILENAME`, `SCHEMA_VERSION`, `DEFAULT_DIR`, `EXIT_BAD_FILE`, `EXIT_MANIFEST_DIRTY`, and
+    the types `Manifest`, `ManifestEntry`, `PruneOptions`, `PruneScope`, `Provided`, `ProvidedSkip`
+    (`satisfies` stays, now drift's range check);
+  - `localize/localize`: `forEachName`, `installLinkAndRecord`, `guardForeignLink`, `declaredRange`,
+    `assertManifestsUntouched`, and the types `OneName`, `OneResult`;
+  - `localize/fsops`: `linkTarget`, `writeLink`, `scanLinks`, `MANIFEST_FILES`,
+    `snapshotManifests`, `diffManifests`, `isGitCheckout`;
+  - `localize/errors`: `EXIT_BAD_FILE`, `EXIT_MANIFEST_DIRTY`;
+  - whole modules: `localized-dedupe`, `utils/relinkHooks`, `localize/prune`, `localize/ensure`,
+    `localize/relink`, `localize/provided`, `localize/manifest`, `localize/one-copy-hook`.
+
 ## 1.46.2
 
 ### Patch Changes

package/README.md

@@ -13,7 +13,7 @@ npm install --save-dev @_linked/cli
 One executable ships in this package: `linked`. (`lnk`, `lincd` and `lincd-cli` were dropped in
 [#40](https://github.com/linked-fw/cli/pull/40).)
 
-In a project that has `@_linked/cli` installed — any linked app, including Create Now — run it as
+In a project that has `@_linked/cli` installed — any linked app — run it as
 `npx linked <command>`. Everywhere else, name the package: `npx @_linked/cli <command>`.
 A bare `npx linked` outside such a project does **not** reach this CLI: npm resolves it to the
 unrelated `linked` package on the registry, which has no binary, and fails with
@@ -77,9 +77,11 @@ linked create-package @_linked/foo --remote <git-url> [--push] # the same, with
 - `packages/foo` — a workspace member: added to the app's `dependencies` (and `packages/*` to its
   `workspaces` if missing), installed at the app root.
 - `packages-local/_linked-foo` — the name `linked localize` uses. `git init` and a first commit,
-  `origin` and `repository.url` from `--remote`, pushed with `--push`; then installed, built,
-  linked and recorded by `linked localize --adopt`. It is not added to the app's `dependencies`
-  until it is published. `--remote` or `--push` imply this location.
+  `origin` and `repository.url` from `--remote`, pushed with `--push`; then handed to
+  `linked localize --adopt`, which sets the app up for checkouts if needed (`packages-local/*` in
+  `workspaces`, the lock-at-rest hook, `.gitignore` and the matching lockfile; commit those), installs at the app root so npm
+  links it as a workspace member, and builds it. It is not added to the app's `dependencies` until
+  it is published. `--remote` or `--push` imply this location.
 
 Any of the three flags skips the question. With none of them and no terminal, it exits 1 and says
 which flag to pass. An existing target folder is refused. Outside an app nothing changes: the
@@ -261,42 +263,41 @@ linked app-doctor                 # in an app: check optimizeDeps.include and Re
 
 ### Developing a dependency from a git checkout
 
-`linked localize` clones an npm dependency, installs inside the checkout, builds it with
-`linked build` and symlinks it into `node_modules` — **without** touching `package.json` or
-`package-lock.json`, so the manifest still describes the released dependency and CI is unaffected.
-Full guide: [docs/localize.md](docs/localize.md).
+`linked localize` clones an npm dependency into `packages-local/`, which the app lists in its
+`workspaces` (`"packages-local/*"`), so npm links and dedupes the checkout like any workspace
+member. A hook the app's `postinstall` and `dependencies` scripts run (`hooks/lock-at-rest.cjs`
+in this package, called through a guard that does nothing where the cli is not installed) puts the
+committed `package-lock.json` back after every install, so the working tree stays clean and CI, which has no checkouts,
+installs from the registry as always. Full guide: [docs/localize.md](docs/localize.md).
 
 ```bash
-linked localize @_linked/rdfs     # clone, install, build, symlink into node_modules
-linked localize                   # report what is localized (same as --list)
-linked localize --list --check    # exit 1 when something recorded is not actually linked
-linked localize --relink          # recreate the recorded symlinks — run this from postinstall
-linked localize @_linked/rdfs --adopt  # link a checkout already in packages-local/_linked-rdfs, no clone
-linked localize --reinstall @_linked/rdfs  # npm install inside the checkout, then prune it
-linked localize --ensure          # remove checkouts' own copies of what the app provides; exit 0 (no names)
-linked delocalize @_linked/rdfs   # unlink and forget, keeping the checkout
-linked delocalize --purge         # undo everything and delete the checkouts
+linked localize @_linked/rdfs          # clone, npm install at the app root, build
+linked localize @_linked/rdfs --adopt  # the same for a checkout already in packages-local/_linked-rdfs
+linked localize                        # checkouts, parked checkouts and drift (same as --list)
+linked localize --list --check         # print only the drift; exit 1 when there is any
+linked delocalize @_linked/rdfs        # park it in .packages-local.parked/, back to the registry copy
+linked localize --parked               # take every parked checkout back
+linked delocalize @_linked/rdfs --purge  # delete it instead (exit 6 on unsaved work on any branch, a stash, or git failing)
 ```
 
-Checkouts go in `packages-local/` under the npm name with the scope flattened:
-`@_linked/rdfs` → `packages-local/_linked-rdfs`. `--list` also flags a directory there that
-`local-packages.json` does not record (`UNRECORDED`).
-
-**One copy of each package the app provides.** A checkout's own install leaves its own copies of
-what it depends on, and Node loads those instead of the app's. One rule says what the app provides:
-the localized packages, plus every runtime dependency (`dependencies`, `peerDependencies`,
-`optionalDependencies`) a localized checkout declares that the app has at a version satisfying
-every localized range, plus `react` and `react-dom`. After every install in a checkout and on every
-`--relink`, each checkout's own copies of its siblings, of react/react-dom and of its own runtime
-dependencies in that set are removed — unless a range that loads the copy misses the app's version,
-or removing it would change what its own dependencies resolve to (kept copies are summarised per
-checkout; `--list` says why). `linked start`, `script`, `call` and `build-all` re-check first (tens
-of milliseconds; one line on stderr when it removes something), and `createViteConfig` derives
-Vite's `resolve.dedupe` from the same rule. `--no-prune` at localize/adopt is recorded
-(`"prune": false`) and leaves that checkout's `node_modules` as npm left them from then on.
-
-Localize used to be the separate `@_linked/localize` package (binary `linked-localize`), which is
-being retired; `linked localize` replaces it.
+The first `linked localize` in an app sets it up — `"packages-local/*"` in `workspaces`, the
+lock-at-rest hook in `postinstall` and `dependencies`, `packages-local/` and
+`.packages-local.parked/` in `.gitignore`, and the matching lockfile (made before anything is
+cloned) — so `git status` then shows exactly `package.json`, `package-lock.json` and `.gitignore`
+to commit ([details](docs/localize.md#set-up)). Run it anywhere in the app: it acts on the topmost
+directory whose `package.json` has `workspaces`. It also writes git hooks into the clone:
+`pre-commit` refuses a manifest that names a checkout, and `post-merge`/`post-checkout` run
+`npm install` when dependencies changed. They work for an app below the git top level; under
+`core.hooksPath` (husky) localize writes nothing and prints the line to add to each hook. Use
+`npm install`, not `npm ci`, while checkouts are present.
+
+**Drift.** npm links a checkout whatever its version. `--list` and the check before `linked start`,
+`script`, `call` and `build-all` report a range a checkout misses, a second copy of a localized
+package, a nested copy of `@_linked/core`/`react`/`server-utils`, and a checkout that is gone.
+
+`--relink` and `--ensure` are deprecated no-ops that exit 0; `local-packages.json` is no longer
+read. Localize used to be the separate `@_linked/localize` package (binary `linked-localize`),
+which is being retired; `linked localize` replaces it.
 
 ### Registry / dev utilities
 
@@ -362,6 +363,17 @@ npm run build
 
 Dual ESM + CJS build via `tsconfig-to-dual-package`. Sources in `src/`, output in `lib/esm/` and `lib/cjs/`.
 
+### Windows
+
+The cli is written to run on Windows but nobody runs it there yet, so treat it as untested. It
+starts `npm`, `npx` and `node_modules/.bin` shims through one helper (`src/utils/spawn.ts`: npm's
+own `npm-cli.js` when npm started the cli, else the `.cmd` through `cmd.exe` with quoted
+arguments), links directories with junctions, imports files by `file:` URL and keeps CRLF in the
+files it edits. Known limits: commands given as one string (`linked all <cmd>`, a `--build`) run
+in `cmd.exe` as written, so they must not use POSIX shell syntax; and this package's own
+`test:template` script sets an environment variable the POSIX way.
+For `linked localize`, see [docs/localize.md](docs/localize.md#windows).
+
 ### Templates
 
 Templates live in `defaults/`:

package/hooks/drift.cjs

@@ -0,0 +1,169 @@
+// Drift -- what npm is silent about once checkouts are workspace members.
+//
+// npm links the app's dependency on a localized package to its checkout by name, whatever the
+// version; when one checkout misses another's range it nests a registry copy that stays after the
+// range is reverted; and `npm ci` exits 0 with a dangling link when a checkout directory is gone.
+// Each of those loads code nobody meant to load, so this reports them:
+//
+// - `second-copy`: another copy of a localized package, besides its checkout;
+// - `singleton-copy`: a nested copy of a package the app must load once;
+// - `range-miss`: a declared range a checkout's version does not satisfy;
+// - `missing-dir`: npm installed a checkout that is no longer there.
+//
+// It reads npm's hidden lockfile (`node_modules/.package-lock.json`): the committed
+// `package-lock.json` is restored to the registry one after every install (lock-at-rest.cjs) and
+// does not describe the linked tree. Ranges come from the live manifests, because the hidden
+// lockfile lags an edit until the next install. It only reports; nothing here fails a command.
+//
+// The one implementation: lock-at-rest.cjs requires it after an install, and the cli's
+// src/localize/drift.ts loads it (and its range check) for `linked localize --list` and the check
+// before `linked start`.
+// Plain, unbuilt CommonJS with Node built-ins only; `semver` is used when it can be required from
+// here (the cli depends on it), and without it no range is checked.
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+const {
+  LOCAL_DIR,
+  readJson,
+  trackedGlobs,
+  expandGlobs,
+  localMembers,
+} = require('./manifests.cjs');
+
+let semver = null;
+try {
+  semver = require('semver');
+} catch {
+  semver = null;
+}
+
+// One copy each, app-wide, localized or not: they hold registries of classes (or React's
+// context), so a second copy splits the app in two.
+const SINGLETONS = Object.freeze([
+  '@_linked/core',
+  '@_linked/react',
+  '@_linked/server-utils',
+]);
+
+const DEP_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'peerDependencies',
+  'optionalDependencies',
+];
+
+// What an app without `workspaces` is read with: the layout linked apps use.
+const DEFAULT_GLOBS = ['packages/*'];
+
+/**
+ * Does `version` satisfy `range`? null means "cannot tell" -- a dist-tag, `file:`, `npm:`,
+ * `workspace:`, a git URL, a version that is not one, or no `semver` to ask -- and drift then
+ * reports nothing: npm links the checkout for such a range anyway. npm's own `semver` decides, so
+ * prereleases follow npm's rule.
+ */
+function satisfies(version, range) {
+  if (!semver || typeof version !== 'string' || typeof range !== 'string')
+    return null;
+  if (semver.valid(version) === null) return null;
+  if (semver.validRange(range) === null) return null;
+  return semver.satisfies(version, range);
+}
+
+/** Every drift in the installed tree, in a stable order. No install yet means none. */
+function driftProblems(appRoot) {
+  const lock = readJson(
+    path.join(appRoot, 'node_modules', '.package-lock.json'),
+  );
+  const packages =
+    lock && typeof lock.packages === 'object' && lock.packages !== null
+      ? lock.packages
+      : null;
+  if (!packages) return [];
+
+  const members = localMembers(appRoot);
+  const byName = new Map(members.map((m) => [m.name, m]));
+  const problems = [];
+
+  const memberKey = new RegExp(`^${LOCAL_DIR}/[^/]+$`);
+  const keys = Object.keys(packages).sort();
+  for (const key of keys) {
+    if (
+      memberKey.test(key) &&
+      !fs.existsSync(path.join(appRoot, key, 'package.json'))
+    )
+      problems.push({kind: 'missing-dir', dir: key});
+  }
+
+  for (const key of keys) {
+    const m = key.match(/(?:^|\/)node_modules\/((?:@[^/]+\/)?[^/]+)$/);
+    if (!m) continue;
+    const name = m[1];
+    const entry = packages[key] || {};
+    const version = typeof entry.version === 'string' ? entry.version : '';
+    const member = byName.get(name);
+    if (member) {
+      // The checkout itself, reached through a link, is the one copy.
+      if (entry.link === true && entry.resolved === member.dir) continue;
+      problems.push({kind: 'second-copy', name, version, at: key});
+    } else if (SINGLETONS.includes(name) && key !== `node_modules/${name}`) {
+      problems.push({kind: 'singleton-copy', name, version, at: key});
+    }
+  }
+
+  for (const importer of importers(appRoot, members)) {
+    const pkg = readJson(path.join(appRoot, importer, 'package.json'));
+    if (!pkg) continue;
+    for (const field of DEP_FIELDS) {
+      const declared = pkg[field];
+      if (!declared || typeof declared !== 'object') continue;
+      for (const [name, range] of Object.entries(declared)) {
+        const member = byName.get(name);
+        if (!member || typeof range !== 'string') continue;
+        // null -- a tag, `file:`, `workspace:` -- is not a miss: npm links the checkout anyway.
+        if (satisfies(member.version, range) !== false) continue;
+        problems.push({
+          kind: 'range-miss',
+          name,
+          version: member.version,
+          dir: member.dir,
+          range,
+          field,
+          importer: importer === '.' ? '<root>' : importer,
+        });
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * The app, its tracked members (every `workspaces` glob but the checkouts') and its checkouts:
+ * everything whose ranges npm resolves.
+ */
+function importers(appRoot, members) {
+  const tracked = expandGlobs(
+    appRoot,
+    trackedGlobs(appRoot, DEFAULT_GLOBS),
+  ).filter((dir) => dir !== LOCAL_DIR && !dir.startsWith(`${LOCAL_DIR}/`));
+  return ['.', ...tracked, ...members.map((m) => m.dir)];
+}
+
+/** One line, for `--list`, the check before `start` and friends, and lock-at-rest. */
+function describeDrift(d) {
+  switch (d.kind) {
+    case 'second-copy':
+      return `second copy of localized ${d.name}@${d.version} at ${d.at}`;
+    case 'singleton-copy':
+      return `nested copy of ${d.name}@${d.version} at ${d.at} — the app should load one`;
+    case 'range-miss':
+      return `${d.name}@${d.version} (${d.dir}) does not satisfy ${d.field} "${d.range}" of ${d.importer}`;
+    case 'missing-dir':
+      return `${d.dir} is installed but its checkout is gone — run npm install`;
+    default:
+      return `unknown drift ${JSON.stringify(d)}`;
+  }
+}
+
+module.exports = {driftProblems, describeDrift, satisfies};

package/hooks/git-hook.cjs

@@ -0,0 +1,170 @@
+// The git hooks `linked localize` writes into a clone (src/localize/git-hooks.ts) all hand over to
+//   node node_modules/@_linked/cli/hooks/git-hook.cjs <hook> [git's arguments]
+// from the app directory, which may sit below the git top level. Plain, unbuilt CommonJS with Node
+// built-ins only, like lock-at-rest.cjs: a fresh cli checkout without lib/ must still run it.
+//
+// - pre-commit: refuse a staged package.json or package-lock.json that lists a checkout
+//   ("packages-local/<dir>"); the glob "packages-local/*" itself is the committed setup. When git
+//   cannot show what is staged, it refuses too: a guard that cannot look does not let things by.
+// - post-merge, post-checkout: `npm install` when the dependency manifests changed, so the
+//   checkouts are linked again on top of the new lockfile. Nothing at all when this work tree has
+//   no checkouts (hooks are shared by every worktree of a repository). Never fails the git command.
+'use strict';
+const {execFileSync, spawnSync} = require('child_process');
+
+const {LEAK, localMembers, manifestPathspecs} = require('./manifests.cjs');
+const {npmCommand} = require('./platform.cjs');
+
+const MANIFESTS = ['package.json', 'package-lock.json'];
+const NO_COMMIT = /^0+$/;
+
+// An app's lockfile is often over a megabyte, execFileSync's default buffer.
+const MAX_BUFFER = 256 * 1024 * 1024;
+
+// The app directory: the hook shim starts this from there, and npm and every pathspec below are
+// relative to it.
+const root = process.cwd();
+
+function git(...args) {
+  return execFileSync('git', args, {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: MAX_BUFFER,
+  });
+}
+
+const errorText = (e) =>
+  String((e && e.stderr) || (e && e.message) || e).trim();
+const BYPASS = '  (git commit --no-verify skips this check.)\n';
+
+function preCommit() {
+  let staged;
+  try {
+    // Added, copied, modified, renamed -- not deleted: a staged deletion lists no checkout.
+    staged = git(
+      'diff',
+      '--cached',
+      '--name-only',
+      '--diff-filter=d',
+      '--relative',
+    ).split('\n');
+  } catch (e) {
+    process.stderr.write(
+      `pre-commit: refusing: cannot list the staged files: ${errorText(e)}\n${BYPASS}`,
+    );
+    return 1;
+  }
+  let refused = 0;
+  for (const file of MANIFESTS) {
+    if (!staged.includes(file)) continue;
+    let content;
+    try {
+      content = git('show', `:./${file}`);
+    } catch (e) {
+      process.stderr.write(
+        `pre-commit: refusing ${file}: cannot read the staged copy: ${errorText(e)}\n${BYPASS}`,
+      );
+      refused = 1;
+      continue;
+    }
+    if (!LEAK.test(content)) continue;
+    process.stderr.write(
+      `pre-commit: refusing ${file}: it references packages-local/ (written while packages were localized).\n`,
+    );
+    refused = 1;
+  }
+  if (refused) {
+    process.stderr.write(
+      '  To change dependencies: npx linked delocalize, npm install <dep>, commit, then npx linked localize --parked.\n',
+    );
+  }
+  return refused;
+}
+
+/** `npm install` when the dependency manifests differ between two commits. Always 0. */
+function installIfChanged(oldRev, newRev) {
+  if (!oldRev || !newRev || oldRev === newRev) return 0;
+  if (NO_COMMIT.test(oldRev)) return 0; // a fresh clone: the developer runs npm ci
+  if (!localMembers(root).length) return 0; // no checkouts here: npm ci / npm install as usual
+  // `git diff --quiet` exits 1 when there are differences; anything else is "cannot tell".
+  const files = [...manifestPathspecs(root), 'package-lock.json'];
+  const diff = spawnSync(
+    'git',
+    ['diff', '--quiet', oldRev, newRev, '--', ...files],
+    {cwd: root, stdio: 'ignore'},
+  );
+  if (diff.status !== 1) return 0;
+
+  process.stderr.write(
+    `[git hook] dependency manifests changed (${oldRev.slice(0, 9)}..${newRev.slice(0, 9)}): npm install\n`,
+  );
+  const start = Date.now();
+  const npm = npmCommand(['install', '--no-audit', '--no-fund']);
+  const r = spawnSync(npm.command, npm.args, {
+    cwd: root,
+    stdio: 'inherit',
+    env: npmEnv(),
+    shell: npm.shell,
+  });
+  if (r.status !== 0) {
+    process.stderr.write('[git hook] npm install FAILED - run it by hand\n');
+    return 0;
+  }
+  process.stderr.write(
+    `[git hook] npm install done in ${Math.round((Date.now() - start) / 1000)}s\n`,
+  );
+  return 0;
+}
+
+// git exports the variables that locate this repository to its hooks; npm would hand them to every
+// checkout's lifecycle scripts, and a `git` there would act on the app's repository, not its own.
+function npmEnv() {
+  const env = {...process.env};
+  for (const key of [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+    'GIT_PREFIX',
+    'GIT_OBJECT_DIRECTORY',
+    'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  ])
+    delete env[key];
+  return env;
+}
+
+function revParse(rev) {
+  try {
+    return git('rev-parse', '--verify', '--quiet', rev).trim();
+  } catch {
+    return '';
+  }
+}
+
+function main(argv) {
+  const [hook, ...args] = argv;
+  switch (hook) {
+    case 'pre-commit':
+      return preCommit();
+    case 'post-merge':
+      return installIfChanged(revParse('ORIG_HEAD'), revParse('HEAD'));
+    case 'post-checkout':
+      // $3 is 1 for a branch checkout and 0 for a file checkout -- lock-at-rest's own restore of
+      // package-lock.json is one, and must not start another install.
+      if (args[2] !== '1') return 0;
+      return installIfChanged(args[0], args[1]);
+    default:
+      return 0;
+  }
+}
+
+let code = 0;
+try {
+  code = main(process.argv.slice(2));
+} catch (e) {
+  process.stderr.write(
+    `[git hook] skipped: ${e && e.message ? e.message : e}\n`,
+  );
+}
+process.exit(code);

package/hooks/hook-shim.cjs

@@ -0,0 +1,63 @@
+// The `sh` that a git hook written by `linked localize` runs: it hands over to git-hook.cjs in the
+// installed cli. src/localize/git-hooks.ts writes it into hook files; lock-at-rest.cjs prints it
+// for a hook file that is not ours. One copy, so the two never drift apart.
+// Plain, unbuilt CommonJS with Node built-ins only, like the other files in hooks/.
+'use strict';
+
+// What marks a hook file `linked localize` wrote.
+const HOOK_MARKER = '# managed by linked localize';
+// The script every hand-over runs, relative to the app: in our hook files and in the line a
+// developer adds to their own.
+const HOOK_SCRIPT = 'node_modules/@_linked/cli/hooks/git-hook.cjs';
+
+/** `s` as one single-quoted `sh` word: survives spaces, `$`, quotes and backticks. */
+function shQuote(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * The commands that run git-hook.cjs for `hook` from the app at `prefix` (relative to the git top
+ * level, `/`-terminated or empty). Each is one `sh` command, so they can be lines of a file or
+ * `; `-joined in a subshell.
+ */
+function hookCommands(hook, prefix) {
+  const dir = prefix
+    ? `dir="$(git rev-parse --show-toplevel)"/${shQuote(prefix.replace(/\/$/, ''))}`
+    : 'dir="$(git rev-parse --show-toplevel)"';
+  return [
+    dir,
+    `script="$dir/${HOOK_SCRIPT}"`,
+    '{ [ -f "$script" ] && command -v node >/dev/null 2>&1; } || exit 0',
+    // git starts a hook at the top level. With GIT_DIR set, git takes the
+    // current directory for the top level unless GIT_WORK_TREE says otherwise,
+    // and a relative path is relative to here: both stop holding after the cd.
+    '[ -z "${GIT_DIR-}" ] || [ -n "${GIT_WORK_TREE-}" ] || export GIT_WORK_TREE="$PWD"',
+    // Git for Windows' sh: an absolute path may also be `C:/...` or `C:\...`.
+    'for v in GIT_DIR GIT_INDEX_FILE GIT_WORK_TREE; do eval "p=\\${$v-}"; case "$p" in ""|/*|[A-Za-z]:*) ;; *) export "$v=$PWD/$p" ;; esac; done',
+    'cd "$dir" || exit 0',
+    `exec node "$script" ${hook} "$@"`,
+  ];
+}
+
+/**
+ * The same hand-over as one `sh` line, in a subshell, for a hook file another tool or person owns.
+ * A subshell's failure does not stop a plain `#!/bin/sh` script, so `|| exit $?` passes it on:
+ * a refusing pre-commit refuses wherever in the file the line sits. post-merge and post-checkout
+ * always exit 0, so the rest of their file still runs.
+ */
+function hookLine(hook, prefix) {
+  return `(${hookCommands(hook, prefix).join('; ')}) || exit $?`;
+}
+
+/** Does this hook file run ours: written by localize, or holding the line added by hand? */
+function runsOurHook(text) {
+  return text.includes(HOOK_MARKER) || text.includes(HOOK_SCRIPT);
+}
+
+module.exports = {
+  HOOK_MARKER,
+  HOOK_SCRIPT,
+  hookCommands,
+  hookLine,
+  runsOurHook,
+};