@haystackeditor/cli 0.25.1 → 0.26.0

package/dist/commands/capture-brief.js

@@ -1,42 +1,37 @@
 /** CAPTURE-V1 rule 7b in `haystack pre-verify`: the routes a change touches (the brief's blast-radius files and the changed
  * files, joined through the route manifest's source entries) with their share of captured sessions over the window, the union
- * over all of them, freshness and drops; sessions on routes no manifest names are unmapped, never zero. The application is the
- * one `.haystack/capture.json` names (rule 8b, written by `haystack init`); a checkout without it has no capture and the brief
- * is exactly as before. A capture read that fails is reported in the block and never fails the command. */
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+ * over all of them, freshness and drops; sessions on routes no manifest names are unmapped, never zero. One section per app
+ * whose `.haystack/capture.json` (rule 8b, written by `haystack init` in the app's directory, apps/web in a monorepo) records it,
+ * found as init finds them (app-config.ts); a checkout without one has no capture and the brief is exactly as before. A capture
+ * read that fails is reported in its section and never fails the command. */
+import { join, posix } from 'node:path';
 import chalk from 'chalk';
+import { CAPTURE_CONFIG_PATH, captureConfigDirs, readCaptureConfig } from '../capture/app-config.js';
 import { classifyHttpError } from '../utils/haystack-api.js';
 import { gatewayFetch } from './case-batch.js';
 import { CAPTURE_APPLICATION_ID, CAPTURE_WINDOW_PATH, captureChangedRoutes, } from './capture-contract.js';
-/** Rule 8b: the application identity init commits (key, repository id, application id, adapter). */
-export const CAPTURE_IDENTITY_FILE = '.haystack/capture.json';
-/** The checkout's application id, null without the identity file, or why the file cannot be read. */
-function captureApplication(gitRoot) {
-    const path = join(gitRoot, CAPTURE_IDENTITY_FILE);
-    if (!existsSync(path))
-        return null;
-    let value;
+/** An app's application id from its record, or why the record cannot give one. */
+function captureApplication(gitRoot, app) {
+    const file = posix.join(app, CAPTURE_CONFIG_PATH);
+    let config;
     try {
-        value = JSON.parse(readFileSync(path, 'utf8'));
+        config = readCaptureConfig(join(gitRoot, app));
     }
     catch (error) {
-        return { unreadable: `${CAPTURE_IDENTITY_FILE} is not JSON (${error instanceof Error ? error.message : String(error)})` };
-    }
-    const applicationId = value?.applicationId;
-    if (typeof applicationId !== 'string' || !CAPTURE_APPLICATION_ID.test(applicationId)) {
-        return { unreadable: `${CAPTURE_IDENTITY_FILE} names no valid applicationId` };
+        return { unreadable: `${file}: ${error instanceof Error ? error.message : String(error)}` };
     }
-    return { applicationId };
+    if (config === null)
+        return { unreadable: `${file} is gone` };
+    if (config.app !== app)
+        return { unreadable: `${file} records the app ${config.app}, not its own directory; run \`haystack init --app ${app}\`` };
+    if (!CAPTURE_APPLICATION_ID.test(config.applicationId))
+        return { unreadable: `${file} names no valid applicationId` };
+    return { applicationId: config.applicationId };
 }
-/** The pre-verify capture block, or null for a checkout with no capture identity. `files`: the brief's function files and the
- * changed files. */
-export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
-    const application = captureApplication(gitRoot);
-    if (application === null)
-        return null;
+async function readApp(gitRoot, app, repository, token, files, now) {
+    const application = captureApplication(gitRoot, app);
     if ('unreadable' in application)
-        return { applicationId: null, state: 'unavailable', reason: application.unreadable };
+        return { app, applicationId: null, state: 'unavailable', reason: application.unreadable };
     const { applicationId } = application;
     try {
         const response = await gatewayFetch(`${CAPTURE_WINDOW_PATH}?repository=${encodeURIComponent(repository)}&app=${encodeURIComponent(applicationId)}`, token);
@@ -46,18 +41,32 @@ export async function readPreVerifyCapture(gitRoot, repository, token, files, no
         if (answer.version !== 'capture-v1' || answer.applicationId !== applicationId)
             throw new Error('the capture window answer names another application');
         if (answer.window === null)
-            return { applicationId, state: 'no-data' };
-        return { applicationId, state: 'ready', window: captureChangedRoutes(answer.window, files, now) };
+            return { app, applicationId, state: 'no-data' };
+        return { app, applicationId, state: 'ready', window: captureChangedRoutes(answer.window, files, now) };
     }
     catch (error) {
-        return { applicationId, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) };
+        return { app, applicationId, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) };
     }
 }
+/** The pre-verify capture sections, one per app with a record, or null for a checkout with none. `files`: the brief's function
+ * files and the changed files. */
+export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
+    let apps;
+    try {
+        apps = captureConfigDirs(gitRoot, []);
+    }
+    catch (error) {
+        return [{ app: '.', applicationId: null, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) }];
+    }
+    if (apps.length === 0)
+        return null;
+    return Promise.all(apps.map(app => readApp(gitRoot, app, repository, token, files, now)));
+}
 const percent = (share) => share === null ? 'n/a' : `${(share * 100).toFixed(1)}%`;
 const plain = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f]/gu, ' '); // eslint-disable-line no-control-regex
-/** The block as a coding agent reads it, after the brief. */
+/** One app's block as a coding agent reads it, after the brief. */
 export function formatCapture(capture) {
-    const lines = [chalk.bold('What real users do where your change is (captured sessions)')];
+    const lines = [chalk.bold(`What real users do where your change is (captured sessions of ${capture.app === '.' ? 'the app at the repository root' : plain(capture.app)})`)];
     if (capture.state === 'unavailable') {
         lines.push(`  Captured sessions could not be read${capture.applicationId ? ` for ${plain(capture.applicationId)}` : ''}: ${plain(capture.reason)}`);
         return lines.join('\n');

package/dist/commands/feedback.js

@@ -0,0 +1,66 @@
+/**
+ * haystack feedback <message...>
+ *
+ * Tells the Haystack team something, in a sentence: a verify that went wrong,
+ * an output that confused you, a missing option. Meant for coding agents as
+ * much as for people: when Haystack gets in the way, say so here and keep
+ * going. The message lands in the team's Slack at once, with the CLI version,
+ * the platform and the repository (when run inside a GitHub checkout).
+ *
+ * `-` as the whole message reads it from stdin.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { withSchema } from '../schema.js';
+import { resolveAuthContext } from '../utils/auth.js';
+import { parseRemoteUrl } from '../utils/git.js';
+import { haystackJson } from '../utils/haystack-api.js';
+export const FEEDBACK_MAX_CHARS = 4000;
+function cliVersion() {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+}
+/** The checkout's GitHub repository, or null outside one (feedback never needs a repository). */
+function currentRepository() {
+    try {
+        const remote = parseRemoteUrl();
+        return `${remote.owner}/${remote.repo}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function buildFeedbackRequest(message, options, repository) {
+    const text = message.trim();
+    if (!text)
+        throw new Error('Say what happened: haystack feedback "<message>" (or - to read it from stdin)');
+    if (text.length > FEEDBACK_MAX_CHARS) {
+        throw new Error(`Feedback is ${text.length} characters; keep it under ${FEEDBACK_MAX_CHARS}`);
+    }
+    return {
+        message: text,
+        context: {
+            cliVersion: cliVersion(),
+            platform: `${process.platform}-${process.arch} node ${process.versions.node}`,
+            repository,
+            runId: options.run ?? null,
+        },
+    };
+}
+export async function feedbackCommand(words, options) {
+    const message = words.length === 1 && words[0] === '-' ? readFileSync(0, 'utf8') : words.join(' ');
+    const request = buildFeedbackRequest(message, options, currentRepository());
+    const { token } = await resolveAuthContext({ preferredLogin: options.account });
+    await haystackJson('/api/cli/feedback', token, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(request),
+    });
+    if (options.json) {
+        process.stdout.write(JSON.stringify(withSchema('feedback', { status: 'sent' }), null, 2) + '\n');
+        return;
+    }
+    console.log(chalk.green('Sent to the Haystack team.'));
+}

package/dist/commands/init-telemetry.js

@@ -20,8 +20,8 @@
  *   - the report (8e). InitTelemetryReport, plus the person's steps beside it: the ingest token (init never mints, prints,
  *     stores or reads one), production's environment, the start command, the deploy and the off switches (13c).
  */
-import { spawnSync } from 'node:child_process';
-import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -31,8 +31,10 @@ import { gatewayFetch } from './case-batch.js';
 import { CAPTURE_EVIDENCE_FRESH_HOURS, CAPTURE_STATUS_PATH, } from './capture-contract.js';
 import { captureAnswers, planCapture } from './init-capture.js';
 import { discoverApps } from '../capture/adapters/index.js';
+import { CAPTURE_CONFIG_PATH, recordedApps } from '../capture/app-config.js';
 import { loadBabel } from '../capture/js-ast.js';
 import { lineDiff } from './init.js';
+import { lockfileDrift, mergePnpmLockfile } from './lockfile-pin.js';
 import { readTelemetryServerStatus } from './telemetry-token.js';
 import { readFacts } from './verify-onboarding.js';
 /** Lane D1: with the user's yes, init checks browser capture's registration with Haystack around the writes. */
@@ -214,15 +216,20 @@ function planDependency(gitRoot, appDir, pkg, after, need) {
     const spec = `${CLI_PACKAGE}@${version}`;
     const dev = field === 'devDependencies';
     const workspaceRoot = isFile(join(appDir, 'pnpm-workspace.yaml')) ? ['--workspace-root'] : [];
+    // Each package manager's add, as it changes no lockfile entry but the CLI's own (lockfile-pin.ts): npm with its tree
+    // nested under the CLI (hoisting would replace packages the app already locks), pnpm through the merge.
     const argv = manager === null ? null : {
         pnpm: ['pnpm', 'add', '--save-exact', dev ? '--save-dev' : '--save-prod', ...workspaceRoot, spec],
-        npm: ['npm', 'install', '--save-exact', dev ? '--save-dev' : '--save-prod', spec],
+        npm: ['npm', 'install', '--save-exact', dev ? '--save-dev' : '--save-prod', '--install-strategy=nested', spec],
         yarn: ['yarn', 'add', '--exact', ...(dev ? ['--dev'] : []), spec],
         bun: ['bun', 'add', '--exact', ...(dev ? ['--dev'] : []), spec],
     }[manager.name];
     const action = promoting ? `Moved from devDependencies to dependencies at ${version}` : `Pinned to ${version}`;
+    const lockfileNote = manager?.name === 'pnpm'
+        ? `, keeping every other entry of pnpm's lockfile as it was (pnpm's own add re-resolves packages the CLI shares with the app; init adds only the CLI's entries, then \`pnpm install --frozen-lockfile\`)`
+        : `, which adds only the CLI's entries to ${manager?.name}'s lockfile`;
     const reason = argv
-        ? `${why} ${action} with \`${argv.join(' ')}\` in ${inside(gitRoot, appDir)}, which updates ${manager?.name}'s lockfile too.`
+        ? `${why} ${action} with \`${argv.join(' ')}\` in ${inside(gitRoot, appDir)}${lockfileNote}.`
         : `${why} ${action}: a newer release never reaches your build unless you change it.`;
     // The package manager's own word is not taken for it: the manifest must say what the integration needs.
     const check = () => {
@@ -235,7 +242,39 @@ function planDependency(gitRoot, appDir, pkg, after, need) {
         return null;
     };
     const touches = manager === null ? [] : LOCKFILES.map(([lockfile]) => join(manager.root, lockfile));
-    return { kind: 'change', change: change(gitRoot, pkg.path, reason, after, content, argv ? { argv, cwd: appDir, touches, check } : undefined) };
+    const exec = manager === null || argv === null ? undefined : () => pin(manager, appDir, argv);
+    return { kind: 'change', change: change(gitRoot, pkg.path, reason, after, content, argv ? { argv, cwd: appDir, touches, check, exec } : undefined) };
+}
+/** The lockfile a package manager writes, in a format lockfile-pin.ts reads (bun's binary lockb aside). */
+function textLockfile(manager) {
+    const name = { pnpm: 'pnpm-lock.yaml', npm: 'package-lock.json', yarn: 'yarn.lock', bun: 'bun.lock' }[manager.name];
+    const path = join(manager.root, name);
+    return isFile(path) ? { path, format: manager.name } : null;
+}
+/** Runs the add, so that the lockfile gains the CLI's entries and nothing else moves (rule 13); throws (init then restores
+ * every file) when the package manager moved anything else. */
+function pin(manager, appDir, argv) {
+    const run = (command) => { execFileSync(command[0], command.slice(1), { cwd: appDir, stdio: ['ignore', 2, 2] }); };
+    const lockfile = textLockfile(manager);
+    const before = lockfile ? readFileSync(lockfile.path, 'utf8') : null;
+    const importer = posix.normalize(relative(manager.root, appDir).split(sep).join('/')) || '.';
+    if (manager.name === 'pnpm' && lockfile && before !== null) {
+        // pnpm resolves the CLI, init keeps the rest as it was, and the install takes exactly that lockfile (proving it).
+        run([...argv, '--lockfile-only']);
+        writeFileSync(lockfile.path, mergePnpmLockfile(before, readFileSync(lockfile.path, 'utf8'), importer, CLI_PACKAGE));
+        run(['pnpm', 'install', '--frozen-lockfile']);
+    }
+    else {
+        run(argv);
+    }
+    if (!lockfile || before === null)
+        return;
+    const moved = lockfileDrift(lockfile.format, before, readFileSync(lockfile.path, 'utf8'), importer, CLI_PACKAGE);
+    if (moved.length > 0) {
+        throw new Error(`\`${argv.join(' ')}\` also changed ${moved.length} lockfile ${moved.length === 1 ? 'entry' : 'entries'} the CLI does not own`
+            + ` (${moved.slice(0, 5).join(', ')}${moved.length > 5 ? ', …' : ''}), so init put every file back. Add ${CLI_PACKAGE} at its exact version`
+            + ` to ${inside(manager.root, appDir) || '.'} yourself, keeping the lockfile's other entries, then run \`haystack init\` again`);
+    }
 }
 function isNode(value) {
     return !!value && typeof value === 'object' && typeof value.type === 'string' && typeof value.start === 'number';
@@ -819,13 +858,18 @@ export async function planTelemetry(gitRoot, repository, options) {
         // One rule for which directories are apps (capture/adapters/index.ts): a web framework an adapter claims, or a package
         // with a start script.
         await loadBabel();
-        const apps = await discoverApps(gitRoot);
+        // The user's earlier answer first: the one app a .haystack/capture.json records (with its origins and consent, which
+        // captureAnswers reads from it). Several records are as ambiguous as several apps.
+        const discovered = await discoverApps(gitRoot);
+        const recorded = recordedApps(gitRoot, discovered);
+        const apps = recorded.length > 0 ? recorded : discovered;
         if (apps.length !== 1) {
             // Rule 8(a): init never picks among several apps, and never guesses one where it found none.
             const ask = apps.length === 0
                 ? 'init found no app here (no web framework it recognizes and no package with a start script). If the repository has one that serves production, run '
                     + '`haystack init` again with `--app <its directory>`.'
-                : `Ask your user which of these apps serves production: ${apps.join(', ')}; then run \`haystack init\` again with \`--app <that directory>\`.`;
+                : `Ask your user which of these apps serves production: ${apps.join(', ')}${recorded.length > 0 ? ` (each has a ${CAPTURE_CONFIG_PATH})` : ''};`
+                    + ' then run `haystack init` again with `--app <that directory>`.';
             const questions = [ask, ...captureQuestions(options.origins, options.consent)];
             // A notice too, so a preview (which reports no telemetry yet) already says what to ask.
             notices.push(`Telemetry waits for your user's answers: ${questions.join(' ')}`);
@@ -834,6 +878,8 @@ export async function planTelemetry(gitRoot, repository, options) {
                 captureRegistration: null };
         }
         appDir = realpathSync(join(gitRoot, apps[0]));
+        if (recorded.length > 0)
+            notices.push(`Telemetry: the app is ${apps[0]}, as its ${CAPTURE_CONFIG_PATH} records (\`--app\` picks another).`);
     }
     const app = inside(gitRoot, appDir);
     const changes = [];

package/dist/commands/init.js

@@ -54,9 +54,11 @@ export const AGENT_NOTE = [
     '- Fix each bug it reports that your change caused, then run `haystack verify` again.',
     '- If it says onboarding needs an answer, ask the user that question and file their choice with',
     '  `haystack verify answer <question-id> <choice>`.',
-    '- Read its short report. `--json` prints the full result, often hundreds of kilobytes, for scripts;',
+    '- Read its short report. `--json` prints the same report as data; `--raw` prints the crawl\'s whole record (large), for scripts;',
     '  `haystack verify --help` explains the output and exit codes.',
     '- If `haystack` is not installed, run each command as `npx -y @haystackeditor/cli@latest <command>`.',
+    '- If Haystack fails, confuses you or gets in your way, say so in a sentence with',
+    '  `haystack feedback "<what happened>"` and keep going: the Haystack team sees it at once.',
     NOTE_END,
 ].join('\n');
 const EXIT_CODES = { planned: 2, 'login-required': 4, 'app-required': 5 };
@@ -310,7 +312,10 @@ function applyChange(gitRoot, planned) {
     if (planned.run) {
         const before = existsSync(planned.target) ? readFileSync(planned.target, 'utf8') : '';
         // Its output goes to stderr: in --json mode stdout carries only the one document.
-        execFileSync(planned.run.argv[0], planned.run.argv.slice(1), { cwd: planned.run.cwd, stdio: ['ignore', 2, 2] });
+        if (planned.run.exec)
+            planned.run.exec();
+        else
+            execFileSync(planned.run.argv[0], planned.run.argv.slice(1), { cwd: planned.run.cwd, stdio: ['ignore', 2, 2] });
         const failed = planned.run.check?.() ?? null;
         if (failed !== null)
             throw new Error(`\`${planned.run.argv.join(' ')}\` ran, but ${failed}.`);

package/dist/commands/lockfile-pin.js

@@ -0,0 +1,307 @@
+/**
+ * Adding one dependency to an app's lockfile without moving anything else (rule 13: init must never change what a build
+ * resolves beyond what it adds). Measured on real lockfiles (Rallly's pnpm workspace, and scratch workspaces whose app
+ * locks older versions of packages the CLI also uses):
+ *   - yarn 1, yarn 4 and bun add only the new descriptors and entries; nothing else moves.
+ *   - npm hoists the new tree and replaces hoisted packages the app already locks (ws, yaml, zod moved to the CLI's
+ *     versions); with `--install-strategy=nested` it places the new tree under the dependency and moves nothing.
+ *   - pnpm re-resolves the dependencies of every package the new tree shares with the old one to the newest version in the
+ *     graph (47 entries in Rallly, from @smithy/* to express), and no flag stops it. So init lets pnpm resolve the new
+ *     dependency (`--lockfile-only`), keeps every entry the lockfile had, adds the entries only the new dependency
+ *     reaches (mergePnpmLockfile), and installs exactly that (`pnpm install --frozen-lockfile`, which also proves it).
+ * lockfileDrift checks the result for every format init can read, so a package manager that moves anything else fails the
+ * change (and init restores every file).
+ */
+function unquote(text) {
+    if (text.startsWith('\'') && text.endsWith('\''))
+        return text.slice(1, -1).replace(/''/g, '\'');
+    if (text.startsWith('"') && text.endsWith('"'))
+        return JSON.parse(text);
+    return text;
+}
+/** An entry's key line (`  'name@1.0.0(peer@2)':`, `  name@1.0.0: {}`) as its name. */
+function keyOf(line) {
+    return unquote(line.trim().replace(/: \{\}$/, '').replace(/:$/, ''));
+}
+const ENTRY_SECTIONS = new Set(['importers', 'packages', 'snapshots']);
+/** pnpm-lock.yaml as its top-level sections, the importers, packages and snapshots split into entries kept as written. */
+function parseLock(text) {
+    const sections = [];
+    for (const line of text.replace(/\n$/, '').split('\n')) {
+        if (/^\S/.test(line))
+            sections.push({ header: line, entries: null, raw: [] });
+        else if (sections.length === 0)
+            throw new Error('pnpm-lock.yaml does not start with a section');
+        else
+            sections[sections.length - 1].raw.push(line);
+    }
+    for (const section of sections) {
+        if (!ENTRY_SECTIONS.has(section.header.replace(/:$/, '')))
+            continue;
+        const entries = [];
+        for (const line of section.raw) {
+            if (/^ {2}\S/.test(line))
+                entries.push({ name: keyOf(line), lines: [line] });
+            else if (line.trim() !== '') {
+                if (entries.length === 0)
+                    throw new Error(`pnpm-lock.yaml's ${section.header} has a line outside any entry`);
+                entries[entries.length - 1].lines.push(line);
+            }
+        }
+        section.entries = entries;
+    }
+    return sections;
+}
+function formatLock(sections) {
+    const blocks = sections.map(section => {
+        if (section.entries === null)
+            return [section.header, ...section.raw].join('\n');
+        return [section.header, '', section.entries.map(entry => entry.lines.join('\n')).join('\n\n'), ''].join('\n');
+    });
+    return `${blocks.join('\n').replace(/\n+$/, '')}\n`;
+}
+function section(sections, name) {
+    const found = sections.find(item => item.header === `${name}:`);
+    if (!found?.entries)
+        throw new Error(`pnpm-lock.yaml has no ${name} section`);
+    return found.entries;
+}
+/** A snapshot's edges: `dependencies` (required) and `optionalDependencies`, as snapshot keys. */
+function edges(entry) {
+    const out = [];
+    let field = null;
+    for (const line of entry.lines.slice(1)) {
+        const header = /^ {4}(\w+):$/.exec(line);
+        if (header) {
+            field = header[1];
+            continue;
+        }
+        if (/^ {4}\S/.test(line)) {
+            field = null;
+            continue;
+        }
+        const dependency = /^ {6}(.+?): (.+)$/.exec(line);
+        if (!dependency || (field !== 'dependencies' && field !== 'optionalDependencies'))
+            continue;
+        const name = unquote(dependency[1]);
+        const version = unquote(dependency[2]);
+        if (version.startsWith('link:'))
+            continue;
+        // An alias resolves to another package: its value is that package's own key.
+        const key = /^(@[^/@]+\/)?[^@(]+@/.test(version) && !/^\d/.test(version) ? version : `${name}@${version}`;
+        out.push({ key, optional: field === 'optionalDependencies' });
+    }
+    return out;
+}
+/** The snapshot key's package (`name@1.0.0(peer@2)` → `name@1.0.0`). */
+function packageKey(key) {
+    const at = key.indexOf('@', 1);
+    const peers = key.indexOf('(', at);
+    return peers === -1 ? key : key.slice(0, peers);
+}
+/** An importer's dependencies by field (`dependencies:`, `devDependencies:`, …), each entry's lines as written. */
+function importerFields(entry) {
+    const fields = [];
+    for (const line of entry.lines.slice(1)) {
+        const header = /^ {4}(\w+):$/.exec(line);
+        if (header) {
+            fields.push({ field: header[1], dependencies: [] });
+            continue;
+        }
+        const current = fields[fields.length - 1];
+        if (!current)
+            throw new Error(`pnpm-lock.yaml's importer ${entry.name} has a line outside any field`);
+        if (/^ {6}\S/.test(line))
+            current.dependencies.push({ field: current.field, name: keyOf(line.slice(4)), lines: [line] });
+        else if (current.dependencies.length > 0)
+            current.dependencies[current.dependencies.length - 1].lines.push(line);
+        else
+            throw new Error(`pnpm-lock.yaml's importer ${entry.name} has an unexpected ${current.field} line`);
+    }
+    return fields;
+}
+const byName = (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+function versionOf(dependency) {
+    const line = dependency.lines.find(item => /^ {8}version: /.test(item));
+    if (!line)
+        throw new Error(`pnpm-lock.yaml lists ${dependency.name} with no version`);
+    return unquote(line.trim().slice('version: '.length));
+}
+/** Every snapshot key reachable from `roots` (required edges first: `required` holds those reached without an optional edge). */
+function reach(snapshots, roots) {
+    const all = new Set();
+    const required = new Set();
+    const queue = roots.map(root => ({ ...root }));
+    while (queue.length > 0) {
+        const { key, optional } = queue.shift();
+        if (optional ? all.has(key) : required.has(key))
+            continue;
+        const entry = snapshots.get(key);
+        if (!entry)
+            throw new Error(`pnpm-lock.yaml references ${key}, which it does not list`);
+        all.add(key);
+        if (!optional)
+            required.add(key);
+        for (const edge of edges(entry))
+            queue.push({ key: edge.key, optional: optional || edge.optional });
+    }
+    return { all, required };
+}
+function withOptional(entry, optional) {
+    const body = entry.lines.slice(1).filter(line => line !== '    optional: true');
+    const key = entry.lines[0].replace(/: \{\}$/, ':');
+    if (optional)
+        return { name: entry.name, lines: [key, ...body, '    optional: true'] };
+    return { name: entry.name, lines: body.length === 0 ? [`${key.replace(/:$/, '')}: {}`] : [key, ...body] };
+}
+/**
+ * The lockfile `before` plus exactly what pnpm's own resolution (`after`, from `pnpm add --lockfile-only`) adds for
+ * `dependency` in `importer`: its importer entry, the snapshots and packages only it reaches, and the optional flag
+ * removed from snapshots it now requires; an earlier version of it and what only that reached go. Everything else stays as
+ * `before` had it, so shared packages keep their resolutions (each one satisfies its own ranges already).
+ */
+export function mergePnpmLockfile(before, after, importer, dependency) {
+    const old = parseLock(before);
+    const resolved = parseLock(after);
+    if (formatLock(old) !== before)
+        throw new Error('init cannot rewrite this pnpm-lock.yaml exactly as pnpm wrote it');
+    for (const lock of [old, resolved]) {
+        if (lock[0]?.header !== 'lockfileVersion: \'9.0\'')
+            throw new Error(`init merges pnpm lockfile version 9.0, and this one is ${lock[0]?.header ?? 'empty'}`);
+    }
+    const header = (lock) => lock.filter(item => item.entries === null).map(item => [item.header, ...item.raw].join('\n')).join('\n');
+    if (header(old) !== header(resolved))
+        throw new Error('pnpm changed the lockfile\'s settings while adding the dependency');
+    const oldImporter = section(old, 'importers').find(entry => entry.name === importer);
+    const newImporter = section(resolved, 'importers').find(entry => entry.name === importer);
+    if (!oldImporter || !newImporter)
+        throw new Error(`pnpm-lock.yaml has no importer ${importer}`);
+    const added = importerFields(newImporter).flatMap(item => item.dependencies).find(item => item.name === dependency);
+    if (!added)
+        throw new Error(`pnpm did not add ${dependency} to ${importer}`);
+    const earlier = importerFields(oldImporter).flatMap(item => item.dependencies).find(item => item.name === dependency) ?? null;
+    // The importer: as before, with the dependency in the field pnpm put it in (fields in pnpm's order).
+    const oldFields = importerFields(oldImporter);
+    const order = importerFields(newImporter).map(item => item.field);
+    const fields = [...new Set([...order, ...oldFields.map(item => item.field)])].map(field => {
+        const kept = (oldFields.find(item => item.field === field)?.dependencies ?? []).filter(item => item.name !== dependency);
+        return { field, dependencies: field === added.field ? [...kept, added].sort(byName) : kept };
+    }).filter(item => item.dependencies.length > 0);
+    const importerEntry = { name: importer, lines: [oldImporter.lines[0].replace(/: \{\}$/, ':'), ...fields.flatMap(item => [`    ${item.field}:`, ...item.dependencies.flatMap(dep => dep.lines)])] };
+    // The graph: before's snapshots, then pnpm's for keys before did not have.
+    const oldSnapshots = new Map(section(old, 'snapshots').map(entry => [entry.name, entry]));
+    const newSnapshots = new Map(section(resolved, 'snapshots').map(entry => [entry.name, entry]));
+    const merged = new Map(oldSnapshots);
+    const root = `${dependency}@${versionOf(added)}`;
+    // Walk the new dependency's tree through the merged graph, taking pnpm's entries only where before had none.
+    const queue = [root];
+    const seen = new Set();
+    while (queue.length > 0) {
+        const key = queue.shift();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (!merged.has(key)) {
+            const entry = newSnapshots.get(key);
+            if (!entry)
+                throw new Error(`pnpm's resolution references ${key}, which it does not list`);
+            merged.set(key, entry);
+        }
+        for (const edge of edges(merged.get(key)))
+            queue.push(edge.key);
+    }
+    const fieldOf = { dependencies: false, devDependencies: false, optionalDependencies: true };
+    const ours = reach(merged, [{ key: root, optional: fieldOf[added.field] ?? false }]);
+    for (const key of ours.all) {
+        const entry = merged.get(key);
+        const optional = !ours.required.has(key) && (oldSnapshots.has(key) ? entry.lines.includes('    optional: true') : true);
+        merged.set(key, withOptional(entry, optional));
+    }
+    // An earlier version of the dependency: what only it reached goes, as pnpm would prune it.
+    if (earlier && `${dependency}@${versionOf(earlier)}` !== root) {
+        const importers = section(old, 'importers').map(entry => (entry.name === importer ? importerEntry : entry));
+        const roots = importers.flatMap(entry => importerFields(entry).flatMap(item => item.dependencies
+            .map(dep => ({ dep, version: versionOf(dep) })).filter(({ version }) => !version.startsWith('link:'))
+            .map(({ dep, version }) => ({ key: /^(@[^/@]+\/)?[^@(]+@/.test(version) && !/^\d/.test(version) ? version : `${dep.name}@${version}`,
+            optional: fieldOf[dep.field] ?? false }))));
+        const live = reach(merged, roots).all;
+        for (const key of reach(oldSnapshots, [{ key: `${dependency}@${versionOf(earlier)}`, optional: false }]).all)
+            if (!live.has(key))
+                merged.delete(key);
+    }
+    // Packages: before's, less those only the earlier version's snapshots used, plus pnpm's for the new ones.
+    const used = new Set([...merged.keys()].map(packageKey));
+    const dropped = new Set([...oldSnapshots.keys()].filter(key => !merged.has(key)).map(packageKey).filter(name => !used.has(name)));
+    const oldPackages = section(old, 'packages');
+    const listed = new Set(oldPackages.map(entry => entry.name));
+    const newPackages = new Map(section(resolved, 'packages').map(entry => [entry.name, entry]));
+    const packages = oldPackages.filter(entry => !dropped.has(entry.name));
+    for (const name of used) {
+        if (listed.has(name))
+            continue;
+        const entry = newPackages.get(name);
+        if (!entry)
+            throw new Error(`pnpm's resolution lists no package ${name}`);
+        packages.push(entry);
+    }
+    return formatLock(old.map(item => {
+        if (item.header === 'importers:')
+            return { ...item, entries: section(old, 'importers').map(entry => (entry.name === importer ? importerEntry : entry)) };
+        if (item.header === 'packages:')
+            return { ...item, entries: packages.sort(byName) };
+        if (item.header === 'snapshots:')
+            return { ...item, entries: [...merged.values()].sort(byName) };
+        return item;
+    }));
+}
+/** Entries as keys and their content, per format; the importer's own entry under IMPORTER. */
+const IMPORTER = '\u0000importer';
+function entriesOf(format, text, importer) {
+    const out = new Map();
+    if (format === 'pnpm') {
+        for (const item of parseLock(text)) {
+            if (item.entries === null) {
+                out.set(`header ${item.header}`, item.raw.join('\n'));
+                continue;
+            }
+            for (const entry of item.entries) {
+                const name = item.header === 'importers:' && entry.name === importer ? IMPORTER : `${item.header} ${entry.name}`;
+                // The optional flag is the dependency's to clear (it now requires the package): compared without it.
+                out.set(name, entry.lines.filter(line => line !== '    optional: true').join('\n').replace(/: \{\}$/, ':'));
+            }
+        }
+    }
+    else if (format === 'npm') {
+        const packages = JSON.parse(text).packages ?? {};
+        for (const [key, value] of Object.entries(packages))
+            out.set(key === (importer === '.' ? '' : importer) ? IMPORTER : key, JSON.stringify(value));
+    }
+    else if (format === 'yarn') {
+        for (const block of text.split(/\n\s*\n/)) {
+            const lines = block.split('\n').filter(line => line.trim() !== '' && !line.startsWith('#'));
+            if (lines.length === 0 || /^\s/.test(lines[0]))
+                continue;
+            for (const descriptor of lines[0].replace(/:$/, '').split(/,\s*/)) {
+                const name = unquote(descriptor);
+                out.set(/@workspace:/.test(name) && name.endsWith(`@workspace:${importer}`) ? IMPORTER : name, lines.slice(1).join('\n'));
+            }
+        }
+    }
+    else {
+        const parsed = JSON.parse(text.replace(/,(\s*[}\]])/g, '$1'));
+        for (const [key, value] of Object.entries(parsed.workspaces ?? {}))
+            out.set(key === (importer === '.' ? '' : importer) ? IMPORTER : `workspace ${key}`, JSON.stringify(value));
+        for (const [key, value] of Object.entries(parsed.packages ?? {}))
+            out.set(`package ${key}`, JSON.stringify(value));
+    }
+    return out;
+}
+/** The entries both lockfiles list whose content adding `dependency` to `importer` changed, other than the importer's own
+ * and the dependency's own: what that must never touch. (An entry only an earlier version of the dependency used may go;
+ * a moved resolution always shows in the entries that reference it.) */
+export function lockfileDrift(format, before, after, importer, dependency) {
+    const a = entriesOf(format, before, importer);
+    const b = entriesOf(format, after, importer);
+    return [...a.entries()].filter(([key, value]) => key !== IMPORTER && !key.includes(dependency) && b.has(key) && b.get(key) !== value)
+        .map(([key]) => key);
+}