pm-ops 2026.10.16 → 2026.10.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -313,8 +313,8 @@ Git never clones `.git/config`, so every fleet package has to run `pm merge inst
313
313
  npm `prepare` script or concurrent agents conflict on tracker files. This package is the one
314
314
  canonical implementation.
315
315
 
316
- Consumers copy [`templates/prepare-merge-driver.ts`](templates/prepare-merge-driver.ts) unchanged to
317
- `scripts/prepare-merge-driver.ts` and set `"prepare": "node scripts/prepare-merge-driver.ts"`. The
316
+ Consumers copy the frozen v1 [`templates/prepare-merge-driver.ts`](templates/prepare-merge-driver.ts)
317
+ unchanged **once** to `scripts/prepare-merge-driver.ts` and set `"prepare": "node scripts/prepare-merge-driver.ts"`. The
318
318
  template skips `npm pack` and `npm publish` before resolving the installer, with one notice,
319
319
  so artifact creation preserves clone-local Git configuration. `npm install`, `npm ci`,
320
320
  and direct invocation still register drivers. The template imports **nothing** from pm-ops. pm-ops is a devDependency, so a checkout installed with
@@ -329,8 +329,35 @@ Dynamic `import()` is forbidden by the fleet lint gate. Instead the template res
329
329
  - **an unreadable or malformed lookup path**: fails with the original installer resolution error, because a failed presence probe cannot establish absence. The probe retains Node's global lookup paths (including `NODE_PATH`), matching the installer resolution above rather than treating an absent local package as proof of absence everywhere
330
330
  - **pm-ops installed**: runs `runPrepareMergeDriver` (below) and propagates its exit status
331
331
 
332
+ The template is a frozen dependency-free bootstrap; driver installation behavior lives in the
333
+ package, behind `pm-ops/merge-driver/prepare`. Its recorded SHA-256 in `launcher-check.ts` is
334
+ locked by a test. Editing it requires an explicit launcher version decision and retaining the
335
+ previous hash. Routine pm-ops updates must change package behavior rather than these copied bytes.
336
+
337
+ Consumer tests should use the exported assertion instead of byte-comparing their copy with the
338
+ installed template:
339
+
340
+ ```ts
341
+ import { assertCanonicalLauncher } from "pm-ops/launcher-check";
342
+
343
+ // Inside the consumer's existing test:
344
+ assertCanonicalLauncher("scripts/prepare-merge-driver.ts");
345
+ ```
346
+
347
+ `assertCanonicalLauncher(filePath)` returns normally for the frozen template and every previously
348
+ released template revision, and throws for edited/unrecognized content or unreadable files.
349
+ The allowlist is append-only. Existing copies pass after an automatic dependency bump without
350
+ being recopied; acceptance does not upgrade their historical behavior. Copy the frozen template
351
+ once to adopt the current bootstrap. Thereafter dependency updates bring package behavior updates
352
+ without consumer launcher edits. New consumers should always copy the frozen template.
353
+
354
+ Historical SHA-256 provenance is recorded with release tags and template commits in
355
+ `launcher-check.ts`; `test/fixtures/launchers/` contains the five distinct released byte sequences
356
+ through v2026.10.16. These text fixtures are assertion inputs, never executable launchers.
357
+
332
358
  Fixture tests in `test/merge-driver-launcher.test.ts` execute the shipped template against each of
333
- those consumer layouts with a stub `pm` on PATH.
359
+ those consumer layouts with a stub `pm` on PATH. `test/pack-prepare.test.ts` also exercises real
360
+ npm install/ci, omit-dev, broken installs and actual Git driver registration in disposable repos.
334
361
 
335
362
  `runPrepareMergeDriver` (also exported from `pm-ops/merge-driver`) resolves the real `pm` launcher on the supplied PATH/platform, then:
336
363
 
package/dist/index.js CHANGED
@@ -2082,7 +2082,7 @@ function renderDocstringsMarkdown(result) {
2082
2082
  const defineExtension = (module) => module;
2083
2083
  export default defineExtension({
2084
2084
  name: "pm-ops",
2085
- version: "2026.10.16",
2085
+ version: "2026.10.17",
2086
2086
  activate(api) {
2087
2087
  if (typeof api.registerRenderer === "function") {
2088
2088
  // Derived from OPS_COMMAND_PATHS rather than restated. A literal copy is
@@ -0,0 +1,10 @@
1
+ /** SHA-256 of the frozen v1 template; changing it requires a versioned decision. */
2
+ export declare const FROZEN_LAUNCHER_SHA256 = "b7f41184dc4c401be8ca80a1c2817e23df5f35df825a141d305bc64e2d3c595a";
3
+ /**
4
+ * Assert that a consumer file is the frozen launcher or a previously released copy.
5
+ * Throws for changed content and propagates read errors. Copy the frozen template
6
+ * once for current behavior; future pm-ops bumps need no consumer launcher edits.
7
+ * @param filePath - Path to the consumer's copied prepare launcher.
8
+ */
9
+ export declare function assertCanonicalLauncher(filePath: string): void;
10
+ //# sourceMappingURL=launcher-check.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"launcher-check.d.ts","sourceRoot":"","sources":["../launcher-check.ts"],"names":[],"mappings":"AAQA,oFAAoF;AACpF,eAAO,MAAM,sBAAsB,qEAAqE,CAAC;AAYzG;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAM9D"}
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Recognize canonical copied launchers without coupling consumers to package updates.
3
+ * Historical hashes are append-only: accepting a copy does not upgrade its behavior.
4
+ * @packageDocumentation
5
+ */
6
+ import { createHash } from "node:crypto";
7
+ import { readFileSync } from "node:fs";
8
+ /** SHA-256 of the frozen v1 template; changing it requires a versioned decision. */
9
+ export const FROZEN_LAUNCHER_SHA256 = "b7f41184dc4c401be8ca80a1c2817e23df5f35df825a141d305bc64e2d3c595a";
10
+ /** Released template revisions, verified from release tags and template history. */
11
+ const canonicalHashes = new Set([
12
+ FROZEN_LAUNCHER_SHA256,
13
+ "7e2b16378a5c05f83ad56bea577c78e2d09eaeca00f688579801552ae1d1b98a", // v2026.09.23, 963a6c4
14
+ "e248546626d7f3753a0c032795f05e36083b8dc130ac7e41f69f0d0faff0836f", // v2026.09.26, f87c17c
15
+ "56b9a31db495ab91cc8b77d05c102f832ccc9dd327232846d569805db6ace6b7", // v2026.09.28, 5278964
16
+ "2cc2d52bf51cd594f944f16bc5fde7d028276cfe59b89abd8c288e5208de88bc", // v2026.10.04, b97fd99
17
+ "e5673aef66825b37dc8cda95d6d8320960c118db914aba509001c0b16e9c7d8a", // v2026.10.12, 3fca1f2
18
+ ]);
19
+ /**
20
+ * Assert that a consumer file is the frozen launcher or a previously released copy.
21
+ * Throws for changed content and propagates read errors. Copy the frozen template
22
+ * once for current behavior; future pm-ops bumps need no consumer launcher edits.
23
+ * @param filePath - Path to the consumer's copied prepare launcher.
24
+ */
25
+ export function assertCanonicalLauncher(filePath) {
26
+ const digest = createHash("sha256").update(readFileSync(filePath)).digest("hex");
27
+ if (!canonicalHashes.has(digest)) {
28
+ throw new Error("Unrecognized pm-ops prepare launcher (SHA-256 " + digest +
29
+ "). Copy pm-ops/templates/prepare-merge-driver.ts unchanged.");
30
+ }
31
+ }
32
+ //# sourceMappingURL=launcher-check.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"launcher-check.js","sourceRoot":"","sources":["../launcher-check.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,oFAAoF;AACpF,MAAM,CAAC,MAAM,sBAAsB,GAAG,kEAAkE,CAAC;AAEzG,oFAAoF;AACpF,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAC;IACnD,sBAAsB;IACtB,kEAAkE,EAAE,uBAAuB;IAC3F,kEAAkE,EAAE,uBAAuB;IAC3F,kEAAkE,EAAE,uBAAuB;IAC3F,kEAAkE,EAAE,uBAAuB;IAC3F,kEAAkE,EAAE,uBAAuB;CAC5F,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjF,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,gDAAgD,GAAG,MAAM;YACvE,6DAA6D,CAAC,CAAC;IACnE,CAAC;AACH,CAAC"}
package/manifest.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pm-ops",
3
- "version": "2026.10.16",
3
+ "version": "2026.10.17",
4
4
  "description": "Multi-repo fleet operations for pm-cli",
5
5
  "author": "@unbraind",
6
6
  "entry": "./dist/index.js",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pm-ops",
3
- "version": "2026.10.16",
3
+ "version": "2026.10.17",
4
4
  "description": "Multi-repo fleet operations for pm-cli",
5
5
  "repository": {
6
6
  "type": "git",
@@ -42,6 +42,10 @@
42
42
  "types": "./dist/merge-driver-prepare.d.ts",
43
43
  "default": "./dist/merge-driver-prepare.js"
44
44
  },
45
+ "./launcher-check": {
46
+ "types": "./dist/launcher-check.d.ts",
47
+ "default": "./dist/launcher-check.js"
48
+ },
45
49
  "./lifecycle-policy": {
46
50
  "types": "./dist/lifecycle-policy.d.ts",
47
51
  "default": "./dist/lifecycle-policy.js"
@@ -1,70 +1,37 @@
1
1
  /**
2
- * npm `prepare` hook that registers pm's field-aware Git merge drivers.
3
- *
4
- * Git never clones `.git/config`, so every clone must register the drivers
5
- * `.gitattributes` declares. The installer lives in the devDependency pm-ops,
6
- * which an `npm install --omit=dev` checkout does not have. This launcher
7
- * therefore imports nothing from pm-ops: it resolves the installer entry from
8
- * the package root and runs it in a child process. Only a missing pm-ops package skips, with one
9
- * notice; any other resolution failure (for example a pm-ops too old to export
10
- * the entry, or a `pm-ops` directory whose package.json is gone) and any
11
- * installer failure fail the install.
12
- * Artifact-time prepare (`npm pack` or `npm publish`) instead exits with one
13
- * notice before resolving pm-ops, preserving the packing clone's Git config.
14
- *
15
- * Canonical copy: `pm-ops/templates/prepare-merge-driver.ts`. Copy it
16
- * unchanged to `scripts/prepare-merge-driver.ts`.
2
+ * Frozen v1 bootstrap: copy unchanged once; behavior lives in pm-ops.
3
+ * Keep dependency-free absence checks here so omit-dev installs can succeed.
4
+ * Changes require a new launcher version and retention of this hash.
17
5
  */
18
-
19
6
  import { spawnSync } from "node:child_process";
20
7
  import { lstatSync } from "node:fs";
21
8
  import { createRequire } from "node:module";
22
9
  import { join } from "node:path";
23
10
 
24
- // npm also runs prepare while creating artifacts. Git configuration belongs
25
- // to clone installation, so artifact creation must stop before resolution or
26
- // spawning the installer. Keep the install/ci broken-package checks intact.
27
11
  if (process.env.npm_command === "pack" || process.env.npm_command === "publish") {
28
12
  console.error(`npm ${process.env.npm_command}: skipping merge-driver install during artifact creation`);
29
13
  } else {
30
- // npm runs `prepare` from the package root, so pm-ops is resolved from there.
31
14
  const resolver = createRequire(join(process.cwd(), "package.json"));
32
15
  let installer: string | undefined;
33
16
  try {
34
17
  installer = resolver.resolve("pm-ops/merge-driver/prepare");
35
18
  } catch (error) {
36
- // Only an absent pm-ops package may skip. Probing its package.json tells that
37
- // apart from an installed pm-ops that cannot serve the entry (exports without
38
- // it, no exports map, a missing file): those resolve or fail differently, and
39
- // the original error is rethrown. A probe that finds no package.json is not
40
- // yet proof of absence: a broken install can leave `node_modules/pm-ops` (a
41
- // directory or a dangling link) with no package.json in any ancestor Node
42
- // searches. Such an entry also counts as present. Keep Node's global paths
43
- // too: the installer resolution above can use them, so an absent local
44
- // package alone cannot prove absence. An unreadable or malformed lookup path
45
- // leaves presence uncertain and must fail closed with the original error.
46
- // Node returns null paths only for built-in modules; pm-ops/package.json is
47
- // a package specifier.
48
- let packagePresent = true;
19
+ if ((error as NodeJS.ErrnoException).code !== "MODULE_NOT_FOUND") throw error;
20
+ // Metadata also detects self-references; physical entries include broken links.
21
+ let present = true;
49
22
  try {
50
23
  resolver.resolve("pm-ops/package.json");
51
24
  } catch (probe) {
52
- packagePresent =
53
- !(probe instanceof Error && "code" in probe && probe.code === "MODULE_NOT_FOUND") ||
54
- resolver.resolve.paths("pm-ops/package.json")!.some(
55
- (directory) => {
56
- try {
57
- return lstatSync(join(directory, "pm-ops"), { throwIfNoEntry: false }) !== undefined;
58
- } catch {
59
- // throwIfNoEntry:false only suppresses ENOENT, not EACCES, EPERM,
60
- // ENOTDIR, or ELOOP. Do not replace the installer diagnostic or
61
- // treat an inconclusive presence check as an omit-dev install.
62
- return true;
63
- }
64
- },
65
- );
25
+ present = (probe as NodeJS.ErrnoException).code !== "MODULE_NOT_FOUND" ||
26
+ resolver.resolve.paths("pm-ops/package.json")!.some((directory) => {
27
+ try {
28
+ return lstatSync(join(directory, "pm-ops"), { throwIfNoEntry: false }) !== undefined;
29
+ } catch {
30
+ return true;
31
+ }
32
+ });
66
33
  }
67
- if (packagePresent) throw error;
34
+ if (present) throw error;
68
35
  }
69
36
  if (installer === undefined) {
70
37
  console.error("pm-ops is not installed (omit-dev install); skipping merge-driver install");