@williamthorsen/nmr 0.48.0 → 0.49.0

package/dist/esm/remote-session.js

@@ -0,0 +1,151 @@
+import { Writable } from 'node:stream';
+import { quoteForShell } from "./helpers/quoteForShell.js";
+import { isObject } from "./helpers/type-guards.js";
+import { runHostSession, } from "./remote-host-session.js";
+export function composeSessionScript(options) {
+    const { checkoutDir, params } = options;
+    const source = `(${runHostSession.toString()})(JSON.parse(process.argv[1]));`;
+    return `cd ${checkoutDir} && exec node -e ${quoteForShell(source)} ${quoteForShell(JSON.stringify(params))}`;
+}
+export function createSessionDemultiplexer(options) {
+    const { marker, onMalformedRecord, onRecord, stderr } = options;
+    const prefix = `${marker} `;
+    const prefixBytes = Buffer.from(prefix);
+    let pending = Buffer.alloc(0);
+    let output = '';
+    let hasStarted = false;
+    const stream = new Writable({
+        write(chunk, _encoding, callback) {
+            pending = pending.length === 0 ? chunk : Buffer.concat([pending, chunk]);
+            readSessionLines();
+            if (hasStarted) {
+                forwardRunOutput();
+            }
+            callback();
+        },
+    });
+    return {
+        flush() {
+            if (!hasStarted || pending.length === 0) {
+                return;
+            }
+            stderr.write(pending);
+            pending = Buffer.alloc(0);
+        },
+        hasStarted: () => hasStarted,
+        readOutput: () => (hasStarted ? output : output + pending.toString('utf8')),
+        stream,
+    };
+    function readSessionLines() {
+        let newlineIndex = pending.indexOf(NEWLINE);
+        while (!hasStarted && newlineIndex !== -1) {
+            const line = pending.subarray(0, newlineIndex).toString('utf8');
+            pending = pending.subarray(newlineIndex + 1);
+            const record = line.startsWith(prefix) ? parseRecord(line.slice(prefix.length)) : undefined;
+            if (record === undefined) {
+                output += `${line}\n`;
+            }
+            else {
+                onRecord(record);
+                hasStarted = record.kind === 'run';
+            }
+            newlineIndex = pending.indexOf(NEWLINE);
+        }
+    }
+    function forwardRunOutput() {
+        let segmentStart = 0;
+        let searchFrom = 0;
+        let markerIndex = pending.indexOf(prefixBytes, searchFrom);
+        while (markerIndex !== -1) {
+            const newlineIndex = pending.indexOf(NEWLINE, markerIndex);
+            if (newlineIndex === -1) {
+                writeRange(segmentStart, markerIndex);
+                pending = pending.subarray(markerIndex);
+                return;
+            }
+            const kind = readPassesRecord(pending.subarray(markerIndex + prefixBytes.length, newlineIndex).toString('utf8'));
+            if (kind !== 'other') {
+                writeRange(segmentStart, markerIndex);
+                segmentStart = newlineIndex + 1;
+            }
+            searchFrom = newlineIndex + 1;
+            markerIndex = pending.indexOf(prefixBytes, searchFrom);
+        }
+        const holdFrom = findPartialPrefix(searchFrom);
+        writeRange(segmentStart, holdFrom);
+        pending = pending.subarray(holdFrom);
+    }
+    function findPartialPrefix(from) {
+        for (let index = Math.max(from, pending.length - prefixBytes.length + 1); index < pending.length; index++) {
+            if (prefixBytes.subarray(0, pending.length - index).equals(pending.subarray(index))) {
+                return index;
+            }
+        }
+        return pending.length;
+    }
+    function readPassesRecord(json) {
+        let value;
+        try {
+            value = JSON.parse(json);
+        }
+        catch {
+            return 'other';
+        }
+        if (!isObject(value) || value['kind'] !== 'passes') {
+            return 'other';
+        }
+        const entries = value['entries'];
+        if (!Array.isArray(entries)) {
+            onMalformedRecord?.();
+            return 'malformed';
+        }
+        onRecord({ kind: 'passes', entries });
+        return 'passes';
+    }
+    function writeRange(start, end) {
+        if (end > start) {
+            stderr.write(pending.subarray(start, end));
+        }
+    }
+}
+export function formatDelegationWaitingLine(holder, host) {
+    if (holder === undefined) {
+        return `nmr: waiting for another delegation's checkout on ${host}`;
+    }
+    return `nmr: waiting for ${holder.command} in ${holder.dir} (pid ${holder.pid}) to finish on ${host}`;
+}
+const NEWLINE = 0x0a;
+function isDelegationHolder(value) {
+    return (isObject(value) &&
+        typeof value['command'] === 'string' &&
+        typeof value['dir'] === 'string' &&
+        typeof value['pid'] === 'number');
+}
+function isSessionRecord(value) {
+    if (!isObject(value))
+        return false;
+    switch (value['kind']) {
+        case 'failed':
+            return (typeof value['exitCode'] === 'number' &&
+                typeof value['output'] === 'string' &&
+                (value['phase'] === 'check out' || value['phase'] === 'install'));
+        case 'locked':
+        case 'run':
+            return true;
+        case 'passes':
+            return Array.isArray(value['entries']);
+        case 'waiting':
+            return value['holder'] === undefined || isDelegationHolder(value['holder']);
+        default:
+            return false;
+    }
+}
+function parseRecord(json) {
+    try {
+        const value = JSON.parse(json);
+        return isSessionRecord(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/esm/remote-snapshot.d.ts

@@ -0,0 +1,21 @@
+/** A commit that records the working tree, or why one could not be made. */
+export type SnapshotResult = {
+    ok: true;
+    sha: string;
+    toplevel: string;
+    treeId: string;
+} | {
+    ok: false;
+    isUnsupported: boolean;
+    reason: string;
+};
+/**
+ * Builds a commit whose tree is the working tree as it is on disk: tracked changes, staged or not, and untracked
+ * files that git does not ignore. The commit is built in a temporary index, so the repository's index, refs, and
+ * stash are untouched; the only write is to the object database.
+ *
+ * The identity and date are fixed, so that the same tree on the same `HEAD` always yields the same commit and a
+ * repeated push transfers nothing. A submodule, or a nested repository that `git add` would record as one, is
+ * refused: Its content is in a repository that the snapshot does not include.
+ */
+export declare function createSnapshot(cwd: string, env: NodeJS.ProcessEnv): SnapshotResult;

package/dist/esm/remote-snapshot.js

@@ -0,0 +1,80 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { GIT_OUTPUT_LIMIT } from '@williamthorsen/nmr-core';
+export function createSnapshot(cwd, env) {
+    const toplevelResult = runGit(['rev-parse', '--show-toplevel'], cwd, env);
+    if (!toplevelResult.ok) {
+        return { ok: false, isUnsupported: true, reason: `not a git repository: ${toplevelResult.error}` };
+    }
+    const toplevel = toplevelResult.stdout.trim();
+    if (fs.existsSync(path.join(toplevel, '.gitmodules'))) {
+        return { ok: false, isUnsupported: true, reason: 'the repository declares submodules' };
+    }
+    const indexPathResult = runGit(['rev-parse', '--git-path', 'index'], toplevel, env);
+    if (!indexPathResult.ok) {
+        return { ok: false, isUnsupported: false, reason: indexPathResult.error };
+    }
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'nmr-snapshot-'));
+    try {
+        const tempIndex = path.join(tempDir, 'index');
+        const indexPath = path.resolve(toplevel, indexPathResult.stdout.trim());
+        if (fs.existsSync(indexPath)) {
+            copyIndex(indexPath, tempIndex);
+        }
+        const indexEnv = { ...env, GIT_INDEX_FILE: tempIndex };
+        const addResult = runGit(['add', '--all'], toplevel, indexEnv);
+        if (!addResult.ok) {
+            return { ok: false, isUnsupported: false, reason: addResult.error };
+        }
+        const stageResult = runGit(['ls-files', '--stage', '-z'], toplevel, indexEnv);
+        if (!stageResult.ok) {
+            return { ok: false, isUnsupported: false, reason: stageResult.error };
+        }
+        if (stageResult.stdout.split('\0').some((entry) => entry.startsWith('160000 '))) {
+            return { ok: false, isUnsupported: true, reason: 'the working tree contains a submodule or a nested repository' };
+        }
+        const treeResult = runGit(['write-tree'], toplevel, indexEnv);
+        if (!treeResult.ok) {
+            return { ok: false, isUnsupported: false, reason: treeResult.error };
+        }
+        const headResult = runGit(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], toplevel, env);
+        const parentArgs = headResult.ok ? ['-p', headResult.stdout.trim()] : [];
+        const treeId = treeResult.stdout.trim();
+        const commitResult = runGit(['commit-tree', treeId, ...parentArgs, '-m', 'nmr delegate snapshot'], toplevel, {
+            ...env,
+            ...SNAPSHOT_IDENTITY_ENV,
+        });
+        if (!commitResult.ok) {
+            return { ok: false, isUnsupported: false, reason: commitResult.error };
+        }
+        return { ok: true, sha: commitResult.stdout.trim(), toplevel, treeId };
+    }
+    finally {
+        fs.rmSync(tempDir, { force: true, recursive: true });
+    }
+}
+const SNAPSHOT_IDENTITY_ENV = {
+    GIT_AUTHOR_DATE: '@0 +0000',
+    GIT_AUTHOR_EMAIL: 'nmr@localhost',
+    GIT_AUTHOR_NAME: 'nmr delegate',
+    GIT_COMMITTER_DATE: '@0 +0000',
+    GIT_COMMITTER_EMAIL: 'nmr@localhost',
+    GIT_COMMITTER_NAME: 'nmr delegate',
+};
+function copyIndex(source, destination) {
+    fs.copyFileSync(source, destination);
+    const { atime, mtime } = fs.statSync(source);
+    fs.utimesSync(destination, atime, mtime);
+}
+function runGit(args, cwd, env) {
+    const result = spawnSync('git', args, { cwd, encoding: 'utf8', env, maxBuffer: GIT_OUTPUT_LIMIT });
+    if (result.error !== undefined) {
+        return { ok: false, error: result.error.message };
+    }
+    if (result.status !== 0) {
+        return { ok: false, error: result.stderr.trim() || `git ${args[0] ?? ''} exited ${result.status ?? 'abnormally'}` };
+    }
+    return { ok: true, stdout: result.stdout };
+}

package/dist/esm/replay-assembly.d.ts

@@ -1,4 +1,4 @@
-import { type ReplayLine } from './check-cache.js';
+import { type ReplayLine } from './check-cache-entries.js';
 import { type Step } from './steps.js';
 /**
  * Assembles what a composite's skip replays: the excerpts recorded by its constituents, in the order in which
@@ -14,7 +14,7 @@ import { type Step } from './steps.js';
  *
  * An entry is admissible when the run that certified it is this one and the tree that it describes is this one.
  * The witness is what a run stamps on an excerpt that it records and on one that it recalls and replays; the
- * tree hash bounds an identity carried by a process out of the run that issued it.
+ * tree id bounds an identity carried by a process out of the run that issued it.
  */
 export declare function assembleReplay(options: {
     anchorDir: string;

package/dist/esm/replay-assembly.js

@@ -1,4 +1,4 @@
-import { readCheckCacheEntry } from "./check-cache.js";
+import { readCheckCacheEntry } from "./check-cache-entries.js";
 import { readNmrStep } from "./steps.js";
 import { getWorkspacePackageDirs } from "./workspace.js";
 export async function assembleReplay(options) {

package/dist/esm/run-chain.d.ts

@@ -0,0 +1,21 @@
+import { type OutputStyle } from '@williamthorsen/nmr-core';
+import type { TreeSnapshot } from './check-cache.js';
+import type { Invocation, PhaseResult, RunPlan } from './invocation.js';
+import type { ScriptRegistry } from './resolve-scripts.js';
+import { type ResolvedScript } from './resolver.js';
+/**
+ * Assembles the chain that a resolved script runs at this scope, the hooks wrapped around it included, and the key
+ * under which a pass by that chain is recorded. Settles a no-op override and an argument that no step can take.
+ */
+export declare function assembleChain(options: {
+    invocation: Invocation;
+    registry: ScriptRegistry;
+    resolvedScript: ResolvedScript;
+    snapshot: TreeSnapshot | undefined;
+}): PhaseResult<Pick<RunPlan, 'commandString' | 'key' | 'ownSteps' | 'steps'>>;
+/**
+ * Returns the line announcing that a `package.json` script is standing in for a built-in, or `undefined` under
+ * `quiet` or when none is due. Only a script replacing a name that the registry already defines is worth
+ * announcing; an ordinary tier-3 entry that happens to resolve is not standing in for anything.
+ */
+export declare function formatOverrideNotice(resolvedScript: ResolvedScript, registry: ScriptRegistry, command: string, anchorDir: string, quiet: boolean, style: OutputStyle): string | undefined;

package/dist/esm/run-chain.js

@@ -0,0 +1,108 @@
+import path from 'node:path';
+import { formatGlyphLine, reportError } from '@williamthorsen/nmr-core';
+import { resolveCacheKey } from "./check-cache-gate.js";
+import { reportNmrCrossing } from "./crossing-diagnostics.js";
+import { NMR_GLYPHS } from "./glyphs.js";
+import { isHookName } from "./helpers/hook-name.js";
+import { quoteForShell } from "./helpers/quoteForShell.js";
+import { wrapWithHooks } from "./hooks.js";
+import { reportVerdict } from "./presentation.js";
+import { applyDevBinToSteps } from "./resolver.js";
+import { dropRecursiveSteps, renderChain } from "./steps.js";
+export function assembleChain(options) {
+    const { invocation, registry, resolvedScript, snapshot } = options;
+    const { anchorDir, command, context, env, parsedArgs, stderr, stdout, styles } = invocation;
+    const { isEmptiedByWorkspace, steps: runnableSteps } = readRunnableSteps(resolvedScript, context.workspacePackageDirs);
+    const resolvedCommand = renderChain(runnableSteps);
+    const noOpReason = findNoOpReason(resolvedCommand, isEmptiedByWorkspace);
+    if (noOpReason !== undefined && !parsedArgs.shouldPrintLog) {
+        reportVerdict({ command, scope: invocation.scope, outcome: 'no-op', reason: noOpReason }, stdout, invocation.format, styles.stdout);
+        return { settled: true, result: { exitCode: 0 } };
+    }
+    const substitutedSteps = applyDevBinToSteps(runnableSteps, context.config.devBin, context.monorepoRoot);
+    const substitutedCommand = renderChain(substitutedSteps);
+    const bindResult = bindPassthrough(substitutedSteps, parsedArgs.passthrough, command);
+    if (!bindResult.ok) {
+        reportError(bindResult.error, stderr);
+        return { settled: true, result: { exitCode: 1 } };
+    }
+    const mainSteps = bindResult.steps;
+    const isHookInvocation = isHookName(command);
+    const fullSteps = isHookInvocation
+        ? mainSteps
+        : wrapWithHooks(command, mainSteps, registry, anchorDir, parsedArgs.isWorkspaceRoot);
+    const fullCommand = renderChain(fullSteps);
+    reportNmrCrossing({
+        config: context.config,
+        isReading: parsedArgs.shouldPrintLog,
+        isWorkspaceRoot: parsedArgs.isWorkspaceRoot,
+        monorepoRoot: context.monorepoRoot,
+        registry,
+        resolvedScript,
+        shouldUseRoot: invocation.shouldUseRoot,
+        stderr,
+        style: styles.stderr,
+    });
+    const key = resolveCacheKey({
+        anchorDir,
+        command,
+        commandString: fullCommand,
+        env,
+        monorepoRoot: context.monorepoRoot,
+        snapshot,
+        stderr,
+        substitution: substitutedCommand === resolvedCommand ? undefined : substitutedCommand,
+    });
+    return { settled: false, value: { commandString: fullCommand, key, ownSteps: mainSteps, steps: fullSteps } };
+}
+export function formatOverrideNotice(resolvedScript, registry, command, anchorDir, quiet, style) {
+    const registryEntry = Object.hasOwn(registry, command) ? registry[command] : undefined;
+    if (quiet || resolvedScript.origin.tier !== 'package' || registryEntry === undefined) {
+        return undefined;
+    }
+    const notice = `${path.basename(anchorDir)}: Using override script: ${renderChain(resolvedScript.steps)}`;
+    return `${formatGlyphLine(NMR_GLYPHS, style, 'package', notice)}\n`;
+}
+function acceptsArguments(step) {
+    return step.kind === 'opaque' || step.shouldDeclineArguments !== true;
+}
+function bindPassthrough(steps, passthrough, command) {
+    if (passthrough.length === 0) {
+        return { ok: true, steps };
+    }
+    if (!steps.some(acceptsArguments)) {
+        return { ok: false, error: formatUnroutableArgumentsError(command) };
+    }
+    const boundSteps = steps.map((step) => {
+        if (!acceptsArguments(step)) {
+            return step;
+        }
+        return step.kind === 'structural'
+            ? { ...step, argv: [...step.argv, ...passthrough] }
+            : { kind: 'opaque', command: `${step.command} ${passthrough.map(quoteForShell).join(' ')}` };
+    });
+    return { ok: true, steps: boundSteps };
+}
+function findNoOpReason(resolvedCommand, isEmptiedByWorkspace) {
+    if (isEmptiedByWorkspace) {
+        return 'empty-workspace';
+    }
+    if (resolvedCommand === '') {
+        return 'empty-override';
+    }
+    if (resolvedCommand === ':') {
+        return 'noop-override';
+    }
+    return undefined;
+}
+function formatUnroutableArgumentsError(command) {
+    return (`\`${command}\` does not take trailing arguments: every step of its chain declines them. ` +
+        'Running it unnarrowed is not what the arguments asked for, so nothing ran.');
+}
+function readRunnableSteps(resolvedScript, workspacePackageDirs) {
+    if (workspacePackageDirs.length > 0) {
+        return { isEmptiedByWorkspace: false, steps: resolvedScript.steps };
+    }
+    const steps = dropRecursiveSteps(resolvedScript.steps);
+    return { isEmptiedByWorkspace: steps.length === 0 && resolvedScript.steps.length > 0, steps };
+}

package/dist/esm/runCli.d.ts

@@ -1,9 +1,5 @@
 import type { Writable } from 'node:stream';
-/**
- * Marks a run made on a delegating caller's behalf, in which a command that the registry does not define, and a
- * `--log` with nothing to show, exit 0 rather than failing.
- */
-export declare const RUN_IF_PRESENT_ENV_VAR = "NMR_RUN_IF_PRESENT";
+import { type RunCliResult } from './invocation.js';
 /** @internal */
 export interface RunCliOptions {
     /** Post-slice CLI arguments (equivalent to `process.argv.slice(2)`). */
@@ -17,10 +13,6 @@ export interface RunCliOptions {
     /** Stream for errors, warnings, and debug notes. */
     stderr: Writable;
 }
-/** @internal */
-export interface RunCliResult {
-    exitCode: number;
-}
 /**
  * Executes the nmr CLI flow in-process and returns the resulting exit code.
  * Does not hold global state, does not read `process.*` globals, and never calls `process.exit`.