@dzhechkov/harness-core 0.8.32 → 0.8.34

package/dist/packed-install-smoke.js

@@ -0,0 +1,172 @@
+/**
+ * Packed-install smoke — feature `publish-sibling-drift-gate`, ADR-001 (Decision 2).
+ *
+ * `dz release`'s existing smoke gate boots a package's bin straight from the WORKSPACE — its
+ * sibling `workspace:*` deps resolve via pnpm's workspace links, never through a real install.
+ * That makes the whole class of "published tarball missing an export" incidents invisible by
+ * construction (Alternative Б1, rejected). This module plans and judges the alternative
+ * (Б2, accepted): pack every package in the batch, `npm install` the resulting tarballs together
+ * into a CLEAN directory — siblings OUTSIDE the batch resolve from the registry, exactly like a
+ * fresh user's install — then boot every bin with `--version` and require exit 0 AND non-empty
+ * stdout (the "publisher output is not a receipt" lesson: a bin that boots but prints nothing has
+ * not proven it works).
+ *
+ * Pure by construction (NFR-2): `planPackedInstallSmoke` only builds command STRINGS from
+ * injected package/bin facts and paths — it never spawns anything. `judgePackedInstallSmoke`
+ * only classifies injected execution records. The CLI (`cmdPublish`, `cmdRelease`) is the single
+ * executor, sharing this same plan/judge pair so both doors apply the identical rule.
+ *
+ * @packageDocumentation
+ */
+import { join } from 'node:path';
+const DEFAULT_PACK_TIMEOUT_MS = 60_000;
+const DEFAULT_INSTALL_TIMEOUT_MS = 180_000;
+const DEFAULT_VERSION_TIMEOUT_MS = 30_000;
+/** Mirror npm's own tarball naming: `@scope/name@1.2.3` -> `scope-name-1.2.3.tgz`. */
+export function packedTarballName(name, version) {
+    return `${name.replace(/^@/, '').replace(/\//g, '-')}-${version}.tgz`;
+}
+export function planPackedInstallSmoke(opts) {
+    const packTimeoutMs = opts.packTimeoutMs ?? DEFAULT_PACK_TIMEOUT_MS;
+    const installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
+    const versionTimeoutMs = opts.versionTimeoutMs ?? DEFAULT_VERSION_TIMEOUT_MS;
+    const steps = [];
+    const tarballs = [];
+    for (const pkg of opts.packages) {
+        const tgz = join(opts.packDir, packedTarballName(pkg.name, pkg.version));
+        tarballs.push(tgz);
+        if (opts.skipPack === true)
+            continue; // AM-1: already packed by the caller — see skipPack's doc
+        steps.push({
+            id: `pack:${pkg.name}`,
+            kind: 'pack',
+            cmd: `npm pack ${JSON.stringify(pkg.dir)} --pack-destination ${JSON.stringify(opts.packDir)}`,
+            cwd: pkg.dir,
+            timeoutMs: packTimeoutMs,
+            pkg: pkg.name,
+        });
+    }
+    if (tarballs.length > 0) {
+        steps.push({
+            id: 'install',
+            kind: 'install',
+            cmd: `npm install ${tarballs.map((t) => JSON.stringify(t)).join(' ')} --no-audit --no-fund`,
+            cwd: opts.installDir,
+            timeoutMs: installTimeoutMs,
+        });
+    }
+    for (const bin of opts.bins) {
+        const absBinPath = join(opts.installDir, 'node_modules', bin.pkg, bin.relPath);
+        // AM-8: a manifest can declare a `bin` whose target file does not exist (never built, moved,
+        // typo'd) — the OLD `cli.ts` bin-collection step silently DROPPED such a bin before this
+        // amendment, which read as "n/a: nothing to smoke" (or even skipped the whole gate when it
+        // was the batch's only bin). `test -f` is a dedicated, portable existence probe RUN AFTER THE
+        // REAL INSTALL — pass/fail here is judged into a specific, honest message
+        // ("declared bin missing after packed install") instead of being folded into whatever
+        // `node <bin> --version` happens to print for a missing file (a generic MODULE_NOT_FOUND).
+        steps.push({
+            id: `bin-exists:${bin.pkg}:${bin.binName}`,
+            kind: 'bin-exists',
+            cmd: `test -f ${JSON.stringify(absBinPath)}`,
+            cwd: opts.installDir,
+            timeoutMs: versionTimeoutMs,
+            pkg: bin.pkg,
+            binName: bin.binName,
+        });
+        steps.push({
+            id: `bin:${bin.pkg}:${bin.binName}`,
+            kind: 'bin-version',
+            cmd: `node ${JSON.stringify(absBinPath)} --version`,
+            cwd: opts.installDir,
+            timeoutMs: versionTimeoutMs,
+            pkg: bin.pkg,
+            binName: bin.binName,
+        });
+    }
+    return { steps, tarballs };
+}
+/**
+ * First 3 lines (FR-3), EXCEPT when they are pure source context. MEASURED 2026-09-13 reproducing
+ * the exact incident this gate targets — a bin whose `import` names a missing export — Node
+ * prints the location, the offending source line and a caret BEFORE the actual
+ * `SyntaxError: … does not provide an export named …` message (identically for a plain uncaught
+ * `throw`: file:line / code / `^` / blank / `Error: …`). A literal first-3-lines slice therefore
+ * shows three lines of code and caret marks and never the reason — useless for the incident it
+ * exists to surface. When stderr contains a line that LOOKS like an error header
+ * (`SomethingError: …` or bare `Error: …`), the snippet starts there instead.
+ */
+function firstLines(text, n) {
+    const lines = text.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+    if (lines.length === 0)
+        return '(no output)';
+    const errorHeaderAt = lines.findIndex((l) => /^[A-Za-z][A-Za-z0-9_]*Error:|^Error\b/.test(l));
+    const start = errorHeaderAt >= 0 ? errorHeaderAt : 0;
+    return lines.slice(start, start + n).join(' | ');
+}
+const NO_EXECUTION_RECORD = '(no execution record — under-executed plan)';
+function stepOk(exec) {
+    return exec !== undefined && exec.timedOut !== true && exec.exitCode === 0;
+}
+function stepDetail(exec) {
+    if (exec === undefined)
+        return NO_EXECUTION_RECORD;
+    if (exec.timedOut === true)
+        return 'timed out';
+    return firstLines(exec.stderr || exec.stdout, 3);
+}
+/**
+ * Classify a plan's executions. `plan` may be the `{ steps }` half of {@link PackedInstallPlan}.
+ * A missing execution for a planned step is a FAILURE (an under-executed plan cannot pass) —
+ * never treated as "nothing to judge, so it passed".
+ */
+export function judgePackedInstallSmoke(plan, executions) {
+    const byId = new Map(executions.map((e) => [e.stepId, e]));
+    let packOk = true;
+    let failureDetail;
+    for (const step of plan.steps.filter((s) => s.kind === 'pack')) {
+        const exec = byId.get(step.id);
+        if (!stepOk(exec)) {
+            packOk = false;
+            failureDetail ??= stepDetail(exec);
+        }
+    }
+    let installOk = true;
+    const installStep = plan.steps.find((s) => s.kind === 'install');
+    if (installStep !== undefined) {
+        const exec = byId.get(installStep.id);
+        if (!stepOk(exec)) {
+            installOk = false;
+            failureDetail ??= stepDetail(exec);
+        }
+    }
+    const bins = plan.steps
+        .filter((s) => s.kind === 'bin-version')
+        .map((step) => {
+        const exec = byId.get(step.id);
+        if (!packOk || !installOk) {
+            // Pack/install already failed for the whole batch — the generic pack/install detail is
+            // more informative than a bin-specific message about a step that never had a chance to run.
+            return { pkg: step.pkg, binName: step.binName, ok: false, stdout: '', detail: stepDetail(exec) };
+        }
+        // AM-8: a declared bin missing from the REAL post-install tree is its own failure class —
+        // checked and reported BEFORE the generic stdout rule below, whose message ("empty stdout")
+        // would otherwise misdescribe a file that was never there to boot at all.
+        const existsStep = plan.steps.find((s) => s.kind === 'bin-exists' && s.pkg === step.pkg && s.binName === step.binName);
+        if (existsStep !== undefined && !stepOk(byId.get(existsStep.id))) {
+            return { pkg: step.pkg, binName: step.binName, ok: false, stdout: '', detail: 'declared bin missing after packed install' };
+        }
+        // FR-3 / lesson "publisher output is not a receipt": exit 0 alone is not enough — the
+        // version output must be non-empty, or a bin that silently no-ops would read as healthy.
+        const ok = stepOk(exec) && (exec?.stdout ?? '').trim() !== '';
+        return {
+            pkg: step.pkg,
+            binName: step.binName,
+            ok,
+            stdout: exec?.stdout ?? '',
+            ...(ok ? {} : { detail: exec !== undefined && stepOk(exec) ? '(exit 0 but empty stdout)' : stepDetail(exec) }),
+        };
+    });
+    const ok = packOk && installOk && bins.every((b) => b.ok);
+    return { ok, packOk, installOk, ...(failureDetail !== undefined ? { failureDetail } : {}), bins };
+}
+//# sourceMappingURL=packed-install-smoke.js.map

package/dist/packed-install-smoke.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packed-install-smoke.js","sourceRoot":"","sources":["../src/packed-install-smoke.ts"],"names":[],"mappings":"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"}

package/dist/publish-sibling-drift.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Sibling-drift gate — feature `publish-sibling-drift-gate`, ADR-001 (Decision 1).
+ *
+ * `rewriteWorkspaceSpecs` (publish.ts) pins a sibling `workspace:^`/`workspace:~`/`workspace:*`
+ * dependency to the EXACT version currently on disk. That version may be published on the
+ * registry carrying an OLDER build than the workspace — the sibling changed without a version
+ * bump. The pinned range then resolves at install time to a package that does not match the
+ * workspace's current behavior, and a fresh `npm install` reproduces whatever regressed.
+ *
+ * Detection (ADR-001, Decision 1, alternative А3 — accepted): hash every file under the
+ * published tarball's `dist/**` plus its `package.json` (with `version`/`gitHead`/`_*` fields
+ * stripped, since those legitimately differ between the registry copy and the workspace copy),
+ * and compare against the same hash of the workspace copy. Any difference is drift. A published
+ * `dist/index.js` missing an export the workspace's `dist/index.js` declares is surfaced as a
+ * SECOND, more readable signal (`missingExports`) — the exact shape of the 2026-09-13 incident
+ * ("does not provide an export named …") — but the hash comparison is the load-bearing check:
+ * it also catches behavior changes that keep every export name intact.
+ *
+ * Network access is NOT this module's concern (NFR-2: pure, no network, fixture-testable):
+ * `fetchPublished` is injected. The CLI implementation packs the sibling from the registry via
+ * `npm pack <name>@<version>` into a temp dir; tests inject a local directory. A fetch that
+ * returns `null` (offline, 404, timeout) is reported as `'unavailable'` — never silently treated
+ * as `'same'` (the "a gate that infers a pass from silence breaks on the next failure path"
+ * lesson): the caller decides whether `'unavailable'` blocks or is overridden.
+ *
+ * @packageDocumentation
+ */
+export type SiblingDriftStatus = 'same' | 'drift' | 'unavailable';
+/**
+ * AM-6 (feature publish-gate-audit-durable): which mechanism produced BOTH sides' file inventory
+ * for this comparison — named on every result, never left implicit. `'npm-pack'`: the caller
+ * injected {@link DetectSiblingDriftOptions.localInventory} (the CLI's `npm pack --dry-run --json`
+ * via {@link parseNpmPackInventory}); the workspace side is exactly what npm will ship, and the
+ * published side is hashed by a FULL recursive walk of the already-unpacked tarball (AM-1 — the
+ * two sides must be symmetric: "every file npm put there" on one side, "every file npm will put
+ * there" on the other). `'readdir-approximation'`: no provider was injected — BOTH sides fall back
+ * to the pre-existing `dist`/`files`/`bin` walk ({@link shippedInventoryDirs}), which stays
+ * symmetric by construction (same function, same rules, both sides) but can miss a file
+ * `.npmignore` excludes or include one npm would never ship.
+ */
+export type InventorySource = 'npm-pack' | 'pnpm-pack' | 'readdir-approximation';
+export interface SiblingDriftResult {
+    readonly name: string;
+    readonly version: string;
+    readonly status: SiblingDriftStatus;
+    /** Relative paths (dist/** or package.json) whose hash differs, or is present on only one side. */
+    readonly changedFiles: readonly string[];
+    /** Export names the workspace's dist/index.js declares that the published one lacks (А2, secondary signal). */
+    readonly missingExports: readonly string[];
+    /** Present only when status === 'unavailable'. */
+    readonly reason?: string;
+    /**
+     * AM-6: named per-result (not merely per-call) because `detectSiblingDrift` short-circuits to
+     * `'unavailable'` before ever reaching the hashing step for some entries — those still carry the
+     * source that WOULD have been used, so a reader never has to guess.
+     */
+    readonly inventorySource: InventorySource;
+}
+export interface FetchedPublished {
+    /** Directory holding the extracted published tarball (contains dist/, package.json). */
+    readonly dir: string;
+}
+/** Fetch the published build of `name@version`. `null` = unavailable (network/404/timeout). */
+export type FetchPublished = (name: string, version: string) => FetchedPublished | null;
+export interface DetectSiblingDriftOptions {
+    readonly dependencies: Record<string, string> | undefined;
+    /** pnpm rewrites `workspace:` in peerDependencies too (mirrors findUnpublishedWorkspaceFloors). */
+    readonly peerDependencies?: Record<string, string> | undefined;
+    /** AM-3: ships and pins exactly like `dependencies` — checked the same way. */
+    readonly optionalDependencies?: Record<string, string> | undefined;
+    /** name -> version on DISK, for every package in the workspace. */
+    readonly workspaceVersions: ReadonlyMap<string, string>;
+    /** name -> absolute package dir on disk, for every package in the workspace. */
+    readonly workspaceDirs: ReadonlyMap<string, string>;
+    /** Names being published in THIS batch — they publish fresh, so drift cannot be measured against them. */
+    readonly batch: ReadonlySet<string>;
+    readonly fetchPublished: FetchPublished;
+    /**
+     * FR-3 (feature publish-gate-audit-durable): the LOCAL (workspace) package's shipped-file
+     * inventory, asked from npm instead of approximated by walking `dist`/`files`/`bin` by hand —
+     * `.npmignore` and nested ignore rules make the hand-rolled walk wrong in both directions (a file
+     * npm will never ship can still be read off disk, producing a false drift). No production default
+     * lives in THIS module — core stays pure (never spawns `npm`, per the core-boundary import
+     * ratchet). The CLI runs `npm pack --dry-run --json` and hands the stdout to
+     * {@link parseNpmPackInventory}, then passes the resulting closure here; a caller that injects
+     * nothing (`undefined`) makes `detectSiblingDrift` fall back to the named
+     * `'readdir-approximation'` {@link InventorySource} on BOTH sides (AM-1) — never a silent "no
+     * drift".
+     */
+    readonly localInventory?: LocalInventory;
+    /** Label for the injected provider's source (default `'npm-pack'`); the CLI passes `'pnpm-pack'` for a packed tree. */
+    readonly localInventorySource?: InventorySource;
+}
+/** The exact set of relative paths `npm pack` will ship for a package — no `.npmignore` guessing. */
+export interface PackInventory {
+    readonly paths: readonly string[];
+}
+/** `npm pack --dry-run --json` could not be run or answered in a shape this code cannot use. */
+export interface PackInventoryUnavailable {
+    readonly unavailable: string;
+}
+/**
+ * Lead fix after the fix-round's live dry-run (2026-09-14 01:02): the workspace side PACKED BY THE
+ * LIVE TRANSPORT (`pnpm pack`) and unpacked into `packedDir`. pnpm synthesises a LICENSE from the
+ * workspace root into the tarball of a package whose own tree has none; `npm pack --dry-run --json`
+ * never lists that file, so a `paths` inventory read every such sibling as "LICENSE only in the
+ * published copy" — 2 false drifts (harness-presets, scout) on a tree unchanged since publication.
+ * A packed tree is hashed by the SAME full walk as the published side, symmetric by construction.
+ */
+export interface PackedTree {
+    readonly packedDir: string;
+}
+export type LocalInventoryResult = PackInventory | PackedTree | PackInventoryUnavailable;
+/** Ask what npm would ship for the package rooted at `dir`. Injected in tests (no subprocess). */
+export type LocalInventory = (dir: string) => LocalInventoryResult;
+/**
+ * C-1/AM-4: `npm pack --dry-run --json` is a real subprocess call — the CLI caches its result per
+ * absolute directory for the lifetime of ONE `dz publish` run (not per package being checked), so
+ * a run that checks the same sibling from more than one dependent package packs it only once. Core
+ * itself never runs the subprocess or owns the cache (core-boundary import ratchet) — this parser
+ * is the pure half only.
+ *
+ * Parses `npm pack --dry-run --json`'s stdout (an array with one element; `files[]` holds
+ * `{path,size,mode}` per shipped path, plus `integrity`/`shasum`/`entryCount`) into the exact set of
+ * relative paths npm intends to ship, honouring `.npmignore`/`files`/default-ignore exactly the way
+ * a real `npm publish` would. A failure to run, parse, or make sense of the shape — including a
+ * malformed individual `files[]` element (AM-5: a corrupt entry is a reason to say the WHOLE
+ * inventory is untrustworthy, never a file to silently drop) — is `{ unavailable: reason }`: an
+ * input this gate cannot read is a reason to say so, never a silent "nothing to compare".
+ */
+export declare function parseNpmPackInventory(stdout: string): LocalInventoryResult;
+/**
+ * For every `workspace:`-declared dependency of a package that is NOT part of `batch` (i.e. will
+ * be pinned to whatever is already on the registry, not published fresh in this run), compare the
+ * build that will be pinned against the workspace copy. Pure: all IO (fetch, fs) is either
+ * injected or scoped to reading local dist/package.json files — no network call is made here.
+ */
+export declare function detectSiblingDrift(opts: DetectSiblingDriftOptions): SiblingDriftResult[];
+//# sourceMappingURL=publish-sibling-drift.d.ts.map

package/dist/publish-sibling-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-sibling-drift.d.ts","sourceRoot":"","sources":["../src/publish-sibling-drift.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAMH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,WAAW,GAAG,uBAAuB,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,+GAA+G;IAC/G,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED,MAAM,WAAW,gBAAgB;IAC/B,wFAAwF;IACxF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,+FAA+F;AAC/F,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,gBAAgB,GAAG,IAAI,CAAC;AAExF,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1D,mGAAmG;IACnG,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC/D,+EAA+E;IAC/E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACnE,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxD,gFAAgF;IAChF,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,0GAA0G;IAC1G,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,uHAAuH;IACvH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,eAAe,CAAC;CACjD;AAoBD,qGAAqG;AACrG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,gGAAgG;AAChG,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,UAAU,GAAG,wBAAwB,CAAC;AAEzF,kGAAkG;AAClG,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,oBAAoB,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CA0B1E;AAgKD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,kBAAkB,EAAE,CA6IxF"}