@ekanos/cli 0.1.5 → 0.1.7

package/dist/commands/upgrade.js

@@ -0,0 +1,546 @@
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { resolveAuthEnvironment } from '../auth/session.js';
+import { cliVersion } from '../compatibility.js';
+import { networkError, preconditionError, validationError } from '../errors.js';
+import { EXIT_CODES } from '../exit-codes.js';
+import { readInstalledPackageManifest } from '../harness-scaffold.js';
+import { detectPackageManager, installExactArgs, lockfileName, } from '../package-manager.js';
+import { loadProject } from '../project.js';
+import { classifyPath, writeFileNoFollow } from '../safe-fs.js';
+import { renderTemplate, toDisplayName } from '../templates.js';
+import { TOOLCHAIN_PACKAGES, } from '../toolchain.js';
+import { resolveToolchainTarget } from '../toolchain-resolve.js';
+import { collectAllFindings } from '../validate-findings.js';
+import { AGENT_CONTEXT_FILES, DOCS_GROUNDING_FILES, copyBundledSkillTrees, } from './init.js';
+import { promptYesNo } from './publish.js';
+export async function runUpgrade(ctx, args, deps = {}) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const loaded = loadProject(args.dir);
+    const pm = detectPackageManager(loaded.projectDir);
+    // Captured BEFORE anything installs: the templates the project's CURRENT
+    // (pre-upgrade) local `@ekanos/cli` ships, which is what actually
+    // generated the agent-context files on disk — not necessarily this
+    // process's own bundled templates, since `upgrade` is a machine-level verb
+    // that never delegates and is routinely invoked via a DIFFERENT (global)
+    // install. See `regenerateAgentContextFiles`.
+    const oldAgentTemplates = captureAgentTemplates(loaded.projectDir);
+    const current = readCurrentToolchain(loaded.projectDir);
+    const session = resolveSessionQuietly(ctx, args);
+    const resolveTarget = (_a = deps.resolveTarget) !== null && _a !== void 0 ? _a : resolveToolchainTarget;
+    const resolution = await resolveTarget({
+        host: session === null || session === void 0 ? void 0 : session.host,
+        session: session === null || session === void 0 ? void 0 : session.session,
+    });
+    if (resolution.status === 'unavailable') {
+        throw networkError('Could not resolve a toolchain target from the Fusion host or the ' +
+            'npm registry.', 'Check connectivity and retry. If this deployment has no ' +
+            '"/api/partner/toolchain" route yet, the npm registry is the ' +
+            'fallback and a failure there means npm itself is unreachable.');
+    }
+    if (resolution.status === 'incoherent') {
+        throw preconditionError(`The resolved toolchain versions do not form an installable set: ` +
+            resolution.detail, 'Retry in a moment — this is almost always a multi-package publish ' +
+            'still in flight, and it self-resolves once every package finishes ' +
+            'publishing.');
+    }
+    const target = resolution.target;
+    const deltas = computeDeltas(current, target);
+    if (args.check) {
+        return ctx.succeed(Object.assign({ source: resolution.source, current,
+            target,
+            deltas }, (resolution.source === 'host'
+            ? { minimum: resolution.minimum, notes: resolution.notes }
+            : {})), checkSummary(resolution.source, deltas));
+    }
+    const changedKeys = Object.keys(deltas).filter((key) => deltas[key].changed);
+    if (changedKeys.length === 0) {
+        return ctx.succeed({ source: resolution.source, current, target, deltas }, `upgrade: already at the target toolchain (source: ${resolution.source}).`);
+    }
+    const isHuman = !ctx.jsonMode;
+    const stdinIsTTY = (_b = args.stdinIsTTY) !== null && _b !== void 0 ? _b : process.stdin.isTTY === true;
+    const canPrompt = isHuman && stdinIsTTY;
+    if (!args.yes) {
+        if (!canPrompt) {
+            throw validationError('Refusing to modify the project non-interactively without --yes.', 'Pass "ekanos upgrade --yes" to proceed, or "ekanos upgrade --check" ' +
+                'to preview the target with no changes.');
+        }
+        ctx.log(planSummary(resolution.source, deltas));
+        const confirm = (_c = args.confirm) !== null && _c !== void 0 ? _c : promptYesNo;
+        const confirmed = await confirm('Upgrade now? [y/N]');
+        if (!confirmed) {
+            throw validationError('Upgrade was not confirmed.', 'Re-run "ekanos upgrade --yes" to proceed non-interactively, or ' +
+                '"ekanos upgrade --check" to preview with no changes. Nothing was ' +
+                'modified.');
+        }
+    }
+    const packageJsonPath = path.join(loaded.projectDir, 'package.json');
+    const manifest = readManifest(packageJsonPath);
+    const specs = buildInstallSpecs(manifest, target, changedKeys);
+    if (specs.length === 0) {
+        return ctx.succeed({ source: resolution.source, current, target, deltas }, 'upgrade: none of the changed packages are direct dependencies of ' +
+            'this project — nothing to install directly. Their versions follow ' +
+            'from whichever direct dependency pins them.');
+    }
+    const snapshot = snapshotProject(loaded.projectDir, pm);
+    try {
+        const runInstall = (_d = deps.runInstall) !== null && _d !== void 0 ? _d : defaultRunInstall;
+        for (const group of [
+            specs.filter((s) => !s.dev),
+            specs.filter((s) => s.dev),
+        ]) {
+            if (group.length === 0)
+                continue;
+            const argv = installExactArgs(pm, group.map((s) => `${s.name}@${s.version}`), group[0].dev);
+            ctx.log(`Running "${pm.bin} ${argv.join(' ')}" in ${loaded.projectDir}…`);
+            const result = await runInstall(argv, pm.bin, loaded.projectDir);
+            if (result.code !== 0) {
+                return await failAndRollback(ctx, snapshot, pm, loaded.projectDir, runInstall, {
+                    step: 'install',
+                    exitCode: EXIT_CODES.PRECONDITION_FAILED,
+                    message: `"${pm.bin} ${argv.join(' ')}" exited with code ${result.code}.`,
+                    output: result.output,
+                });
+            }
+        }
+        if (!args.noVerify) {
+            const runValidateStep = (_e = deps.runValidateStep) !== null && _e !== void 0 ? _e : defaultRunValidateStep;
+            const validateResult = await runValidateStep(loaded.projectDir);
+            if (!validateResult.ok) {
+                return await failAndRollback(ctx, snapshot, pm, loaded.projectDir, runInstall, {
+                    step: 'validate',
+                    exitCode: EXIT_CODES.VALIDATION,
+                    message: 'The upgraded toolchain fails "ekanos validate" against this ' +
+                        "project's own integration definition.",
+                    output: JSON.stringify((_f = validateResult.findings) !== null && _f !== void 0 ? _f : [], null, 2),
+                });
+            }
+            const runTestStep = (_g = deps.runTestStep) !== null && _g !== void 0 ? _g : defaultRunTestStep;
+            const testResult = await runTestStep(loaded.projectDir, pm);
+            if (testResult.code !== 0) {
+                return await failAndRollback(ctx, snapshot, pm, loaded.projectDir, runInstall, {
+                    step: 'test',
+                    exitCode: testResult.code,
+                    message: `The project's test script exited with code ${testResult.code} on the upgraded toolchain.`,
+                    output: testResult.output,
+                });
+            }
+        }
+    }
+    finally {
+        snapshot.dispose();
+    }
+    const newTemplatesDir = path.join(loaded.projectDir, 'node_modules', '@ekanos', 'cli', 'templates');
+    const regenerated = regenerateAgentContextFiles({
+        projectDir: loaded.projectDir,
+        slug: loaded.primary.slug,
+        oldTemplates: oldAgentTemplates,
+        newTemplatesDir,
+    });
+    // The regenerated AGENTS.md and skills may now REFERENCE artifacts this
+    // project predates (docs/api-notes.md, .mcp.json, bundled skill trees) —
+    // instructions pointing at files that don't exist are exactly the stale-docs
+    // failure the docs-grounding feature closes, so create what's missing.
+    // Create-if-missing ONLY: these files are partner/agent-authored after the
+    // scaffold and are never regenerated.
+    const scaffolded = scaffoldMissingDocsArtifacts({
+        projectDir: loaded.projectDir,
+        slug: loaded.primary.slug,
+        newTemplatesDir,
+    });
+    // `specs` only ever covers DIRECT dependencies (see `buildInstallSpecs`) —
+    // a changed key with no spec is transitive and was never actually
+    // installed here, so the report (and the human summary) must say so
+    // explicitly rather than implying every changed key was upgraded. This
+    // matters most for exactly the scenario this PR's own delegation feature
+    // targets: a globally-installed `ekanos` with no local `@ekanos/cli`
+    // devDependency, where `cli` changes in `deltas` but the running global
+    // binary itself is untouched by this command.
+    const installedKeys = specs.map((spec) => spec.key);
+    const skippedKeys = changedKeys.filter((key) => !installedKeys.includes(key));
+    return ctx.succeed({
+        source: resolution.source,
+        current,
+        target,
+        deltas,
+        installed: installedKeys,
+        skippedTransitive: skippedKeys,
+        regenerated,
+        scaffolded,
+    }, successSummary(installedKeys, skippedKeys, deltas, regenerated, scaffolded));
+}
+/**
+ * Best-effort host/session resolution — NEVER throws. `upgrade` must work for
+ * a partner who has never logged in at all (pure npm-registry flow), so the
+ * throwing `resolveAuthEnvironment`/`requireSession` machinery is unusable
+ * here; this mirrors the tolerant lookup `update-notice.ts` uses.
+ */
+function resolveSessionQuietly(ctx, args) {
+    try {
+        const env = resolveAuthEnvironment(ctx, args.host, args.env, {
+            projectDir: args.dir,
+        });
+        const session = env.store.read(env.host);
+        return session ? { host: env.host, session } : null;
+    }
+    catch (_a) {
+        return null;
+    }
+}
+function readCurrentToolchain(projectDir) {
+    var _a;
+    const result = {};
+    for (const [key, pkg] of Object.entries(TOOLCHAIN_PACKAGES)) {
+        const installed = readInstalledPackageManifest(projectDir, pkg);
+        result[key] = (_a = installed === null || installed === void 0 ? void 0 : installed.version) !== null && _a !== void 0 ? _a : (key === 'cli' ? cliVersion() : null);
+    }
+    return result;
+}
+function computeDeltas(current, target) {
+    const keys = Object.keys(TOOLCHAIN_PACKAGES);
+    const result = {};
+    for (const key of keys) {
+        result[key] = {
+            current: current[key],
+            target: target[key],
+            changed: current[key] !== target[key],
+        };
+    }
+    return result;
+}
+/**
+ * Only packages the project depends on DIRECTLY are installed explicitly —
+ * `@ekanos/integration-schema` and often `@ekanos/harness` are transitive
+ * (pulled in by `@ekanos/sdk`), and forcing an exact transitive version would
+ * need a package-manager-specific override mechanism this CLI does not
+ * manage. Their versions follow from whichever direct dependency pins them,
+ * which is exactly what the coherent target guarantees is already correct.
+ */
+function buildInstallSpecs(manifest, target, changedKeys) {
+    var _a, _b;
+    const deps = ((_a = manifest.dependencies) !== null && _a !== void 0 ? _a : {});
+    const devDeps = ((_b = manifest.devDependencies) !== null && _b !== void 0 ? _b : {});
+    const specs = [];
+    for (const key of changedKeys) {
+        const pkg = TOOLCHAIN_PACKAGES[key];
+        if (pkg in deps) {
+            specs.push({ key, name: pkg, version: target[key], dev: false });
+        }
+        else if (pkg in devDeps) {
+            specs.push({ key, name: pkg, version: target[key], dev: true });
+        }
+    }
+    return specs;
+}
+function readManifest(packageJsonPath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    }
+    catch (error) {
+        throw preconditionError(`Could not read ${packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`, 'Ensure the project has a valid package.json, then re-run "ekanos upgrade".');
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw preconditionError(`${packageJsonPath} does not contain a JSON object.`, 'Fix package.json, then re-run "ekanos upgrade".');
+    }
+    return parsed;
+}
+/**
+ * Copy `package.json` and the lockfile to a temp directory before anything
+ * installs. `restore()` copies them back (and removes a lockfile that did not
+ * exist before, if the failed install created one); `dispose()` cleans up the
+ * temp copies once the run is over, success or failure.
+ */
+function snapshotProject(projectDir, pm) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ekanos-upgrade-'));
+    const packageJsonPath = path.join(projectDir, 'package.json');
+    // bun has shipped both a text (`bun.lock`) and a legacy binary
+    // (`bun.lockb`) lockfile; snapshot whichever is actually present.
+    const lockCandidates = pm.name === 'bun' ? ['bun.lock', 'bun.lockb'] : [lockfileName(pm)];
+    const lockName = lockCandidates.find((name) => fs.existsSync(path.join(projectDir, name)));
+    const lockfilePath = lockName
+        ? path.join(projectDir, lockName)
+        : path.join(projectDir, lockfileName(pm));
+    const lockfileExisted = lockName !== undefined;
+    fs.copyFileSync(packageJsonPath, path.join(tmpDir, 'package.json'));
+    if (lockfileExisted) {
+        fs.copyFileSync(lockfilePath, path.join(tmpDir, 'lockfile.snapshot'));
+    }
+    return {
+        restore: () => {
+            fs.copyFileSync(path.join(tmpDir, 'package.json'), packageJsonPath);
+            if (lockfileExisted) {
+                fs.copyFileSync(path.join(tmpDir, 'lockfile.snapshot'), lockfilePath);
+            }
+            else if (fs.existsSync(lockfilePath)) {
+                fs.rmSync(lockfilePath);
+            }
+        },
+        dispose: () => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        },
+    };
+}
+/**
+ * The one rollback path every failure funnels through: restore the snapshot,
+ * reinstall to put `node_modules` back in sync with the restored
+ * `package.json`/lockfile, and report exactly which step failed and what it
+ * said — with an explicit statement that the project was restored, so a
+ * partner (or an agent) never has to wonder whether they are looking at a
+ * half-upgraded tree.
+ */
+async function failAndRollback(ctx, snapshot, pm, projectDir, runInstall, failure) {
+    ctx.warn(`ekanos: the "${failure.step}" step failed — rolling back package.json ` +
+        'and the lockfile, then reinstalling to restore node_modules…');
+    snapshot.restore();
+    // The SAME injectable installer seam used for the forward install — a test
+    // that mocks it never shells out for the rollback path either.
+    const restore = await runInstall(['install'], pm.bin, projectDir);
+    return ctx.failWith({
+        code: `upgrade_${failure.step}_failed`,
+        message: failure.message,
+        hint: `The project HAS BEEN RESTORED to its pre-upgrade state (package.json, ` +
+            `lockfile and node_modules all rolled back${restore.code === 0
+                ? ''
+                : ' — though the restore install itself also failed with code ' +
+                    `${restore.code}; run "${pm.bin} install" by hand to finish ` +
+                    'repairing node_modules'}). Read the output in data.output, fix the underlying issue, and ` +
+            're-run "ekanos upgrade".',
+        exitCode: failure.exitCode,
+        data: { step: failure.step, output: failure.output },
+    });
+}
+async function defaultRunInstall(argv, bin, cwd) {
+    return new Promise((resolve, reject) => {
+        var _a, _b;
+        const child = spawn(bin, argv, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        let output = '';
+        (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        (_b = child.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        child.on('error', reject);
+        child.on('close', (code) => resolve({ code: code !== null && code !== void 0 ? code : 1, output }));
+    });
+}
+async function defaultRunValidateStep(projectDir) {
+    const loaded = loadProject(projectDir);
+    const findings = await collectAllFindings(loaded);
+    const errorCount = findings.filter((f) => f.severity === 'error').length;
+    return { ok: errorCount === 0, findings };
+}
+async function defaultRunTestStep(projectDir, pm) {
+    return new Promise((resolve, reject) => {
+        var _a, _b;
+        const child = spawn(pm.bin, ['run', 'test'], {
+            cwd: projectDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let output = '';
+        (_a = child.stdout) === null || _a === void 0 ? void 0 : _a.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        (_b = child.stderr) === null || _b === void 0 ? void 0 : _b.on('data', (chunk) => {
+            output += chunk.toString();
+        });
+        child.on('error', reject);
+        child.on('close', (code) => resolve({ code: code !== null && code !== void 0 ? code : 1, output }));
+    });
+}
+/**
+ * Read every `AGENT_CONTEXT_FILES` template source out of the project's
+ * CURRENT (pre-upgrade) local `@ekanos/cli` install, before anything installs
+ * over it. Missing entirely (the package isn't a resolvable local dependency)
+ * just means every file below is treated conservatively — see
+ * `regenerateAgentContextFiles`.
+ */
+function captureAgentTemplates(projectDir) {
+    const templatesDir = path.join(projectDir, 'node_modules', '@ekanos', 'cli', 'templates');
+    const captured = new Map();
+    for (const { template } of AGENT_CONTEXT_FILES) {
+        const templatePath = path.join(templatesDir, template);
+        try {
+            captured.set(template, fs.readFileSync(templatePath, 'utf8'));
+        }
+        catch (_a) {
+            // Not resolvable — left out of the map, handled as "can't verify" below.
+        }
+    }
+    return captured;
+}
+/**
+ * Create the docs-grounding artifacts a pre-0.1.7 project is missing, from
+ * the NEWLY installed CLI's bundled templates: `docs/api-notes.md`,
+ * `.mcp.json`, and any bundled skill trees. Strictly create-if-missing —
+ * an existing file is the partner's (api-notes is agent-authored, .mcp.json
+ * may carry local servers) and is never touched, force or not. Writes go
+ * through safe-fs like init's own scaffold pass.
+ */
+function scaffoldMissingDocsArtifacts(params) {
+    const vars = { SLUG: params.slug, DISPLAY_NAME: toDisplayName(params.slug) };
+    const created = [];
+    const needsAttention = [];
+    // This runs AFTER snapshot.dispose(): the toolchain upgrade has already
+    // succeeded and there is no rollback left to protect. A refused write here
+    // (a symlinked `docs/` or `.claude` ancestor — safe-fs throws rather than
+    // follow it) must therefore be REPORTED, never thrown — the same stance
+    // `regenerateAgentContextFiles` takes, for the same reason: a hard failure
+    // now would misreport a successful upgrade.
+    for (const { template, dest } of DOCS_GROUNDING_FILES) {
+        const destPath = path.join(params.projectDir, dest);
+        const kind = classifyPath(destPath);
+        // A real file or directory is the partner's — skipping it quietly IS the
+        // contract. A symlink (or fifo, socket, …) is not "already there": it is
+        // a path we refuse to write through, and silence would hide that — same
+        // reporting stance as regenerateAgentContextFiles.
+        if (kind === 'file' || kind === 'directory')
+            continue;
+        if (kind !== 'missing') {
+            needsAttention.push(dest);
+            continue;
+        }
+        const templatePath = path.join(params.newTemplatesDir, template);
+        if (!fs.existsSync(templatePath))
+            continue; // older target toolchain
+        try {
+            writeFileNoFollow(params.projectDir, destPath, renderTemplate(fs.readFileSync(templatePath, 'utf8'), vars));
+            created.push(dest);
+        }
+        catch (_a) {
+            needsAttention.push(dest);
+        }
+    }
+    try {
+        // 'collect': a refused file is recorded and the walk continues, so files
+        // that DID land — in this skill tree or an earlier one — stay in
+        // `created` instead of vanishing when a later write refuses.
+        const skills = copyBundledSkillTrees(params.projectDir, false, path.join(params.newTemplatesDir, 'skills'), 'collect');
+        created.push(...skills.created);
+        needsAttention.push(...skills.refused);
+    }
+    catch (_b) {
+        // Last resort (an unreadable templates dir, not a refused write — those
+        // are collected above).
+        needsAttention.push('.claude/skills');
+    }
+    return { created, needsAttention };
+}
+/**
+ * Regenerate `AGENTS.md`, `CLAUDE.md` and the Claude Code skill from the
+ * NEWLY installed CLI's bundled templates — using the exact byte-comparison
+ * discipline `harness-scaffold.ts` applies to the dev harness shell: a file
+ * whose current bytes match what the project's PRE-upgrade local CLI would
+ * have rendered (captured in `oldTemplates`, before install ran) is
+ * untouched by the partner and safe to regenerate; anything else has been
+ * edited and is left alone, reported so a human can merge it by hand. A
+ * stale AGENTS.md teaches an agent yesterday's contract — that is as harmful
+ * as a stale binary, which is why this runs on every successful upgrade
+ * rather than only on `init`.
+ */
+function regenerateAgentContextFiles(params) {
+    const vars = { SLUG: params.slug, DISPLAY_NAME: toDisplayName(params.slug) };
+    const updated = [];
+    const unchanged = [];
+    const needsAttention = [];
+    for (const { template, dest } of AGENT_CONTEXT_FILES) {
+        const destPath = path.join(params.projectDir, dest);
+        const kind = classifyPath(destPath);
+        if (kind === 'missing')
+            continue; // never scaffolded — nothing to upgrade
+        if (kind !== 'file') {
+            // A symlink (or anything else odd) is not ours to write through — same
+            // stance as init's scaffold pass, but reported instead of thrown: the
+            // upgrade itself already succeeded, so surface it for a human.
+            needsAttention.push(dest);
+            continue;
+        }
+        const current = fs.readFileSync(destPath, 'utf8');
+        const oldSource = params.oldTemplates.get(template);
+        const oldRendered = oldSource === undefined ? null : renderTemplate(oldSource, vars);
+        if (oldRendered === null || current !== oldRendered) {
+            needsAttention.push(dest);
+            continue;
+        }
+        const newTemplatePath = path.join(params.newTemplatesDir, template);
+        if (!fs.existsSync(newTemplatePath))
+            continue;
+        const newRendered = renderTemplate(fs.readFileSync(newTemplatePath, 'utf8'), vars);
+        if (newRendered === current) {
+            unchanged.push(dest);
+            continue;
+        }
+        try {
+            writeFileNoFollow(params.projectDir, destPath, newRendered);
+            updated.push(dest);
+        }
+        catch (_a) {
+            // A symlinked ANCESTOR (.claude centralized across projects) passes the
+            // leaf classifyPath check above but is refused by the guarded write —
+            // and this runs post-rollback, so a throw here would misreport a
+            // successful toolchain upgrade as failed. Report it instead, like every
+            // other post-rollback write path in this file.
+            needsAttention.push(dest);
+        }
+    }
+    return { updated, unchanged, needsAttention };
+}
+function checkSummary(source, deltas) {
+    var _a;
+    const lines = [`upgrade --check: target resolved from ${source}.`];
+    for (const [key, delta] of Object.entries(deltas)) {
+        lines.push(`  ${key}: ${(_a = delta.current) !== null && _a !== void 0 ? _a : '(not installed)'} → ${delta.target}` +
+            (delta.changed ? '' : ' (already current)'));
+    }
+    return lines.join('\n');
+}
+function planSummary(source, deltas) {
+    const changing = Object.entries(deltas)
+        .filter(([, d]) => d.changed)
+        .map(([key, d]) => { var _a; return `${key} ${(_a = d.current) !== null && _a !== void 0 ? _a : '(not installed)'} → ${d.target}`; });
+    return (`Upgrading (target resolved from ${source}):\n` +
+        changing.map((line) => `  ${line}`).join('\n'));
+}
+function successSummary(installedKeys, skippedKeys, deltas, regenerated, scaffolded) {
+    const installed = installedKeys
+        .map((key) => `${key} → ${deltas[key].target}`)
+        .join(', ');
+    const parts = [
+        installed.length > 0
+            ? `upgrade: OK — installed ${installed}.`
+            : 'upgrade: OK — nothing was a direct dependency of this project, so nothing was installed here.',
+    ];
+    if (skippedKeys.length > 0) {
+        // These changed in the resolved target but are transitive (or, for
+        // "cli", the invoked binary was global with no local devDependency) —
+        // never touched by the install step above.
+        const skipped = skippedKeys
+            .map((key) => `${key} → ${deltas[key].target}`)
+            .join(', ');
+        parts.push(`Not installed directly (transitive or not a local dependency): ${skipped}.`);
+    }
+    if (regenerated.updated.length > 0) {
+        parts.push(`regenerated ${regenerated.updated.join(', ')}.`);
+    }
+    if (scaffolded.created.length > 0) {
+        parts.push(`created ${scaffolded.created.join(', ')} (new in this toolchain — see ` +
+            `AGENTS.md's "API documentation" section).`);
+    }
+    if (scaffolded.needsAttention.length > 0) {
+        parts.push(`could not scaffold ${scaffolded.needsAttention.join(', ')} (a path ` +
+            'component is a symlink or unwritable) — the toolchain upgrade itself ' +
+            'succeeded. Fix the path, then run "ekanos init --slug <slug> --dir ." ' +
+            'WITHOUT --force: init is per-file idempotent and creates only what ' +
+            'is missing. Never use --force here — it overwrites every scaffolded ' +
+            'file, including src/integration.ts.');
+    }
+    if (regenerated.needsAttention.length > 0) {
+        parts.push(`${regenerated.needsAttention.join(', ')} were locally modified — ` +
+            'left untouched, merge the new template by hand.');
+    }
+    return parts.join(' ');
+}
+//# sourceMappingURL=upgrade.js.map