@event4u/agent-config 16.0.0 → 16.1.0

package/src/install/manifestFiles.ts

@@ -0,0 +1,312 @@
+/**
+ * The installed-tools manifest's per-tool `files[]` inventory — building it,
+ * reading back what a previous install recorded, and reconciling the two.
+ *
+ * THE GAP THIS CLOSES.
+ *
+ * `files[].sha256` is the only record of what this installer wrote where. The
+ * conflict tracker added in Phase 5.1 reads exactly that field to tell a
+ * managed file still carrying our bytes from one the user has edited
+ * (`recordedOwnership.classifyOwnership`). A path with no recorded digest
+ * classifies `unknown`, and `unknown` writes.
+ *
+ * So a run that DROPS a recorded digest does not merely lose bookkeeping — it
+ * re-arms the overwrite that preservation exists to prevent, one run later.
+ * Three drops were live, and all three end in the same silent data loss:
+ *
+ * 1. **A preserved file was never recorded.** The writer pushes a path into
+ *    `written_paths` only when it actually copies; the preserve branch returns
+ *    early. The manifest is rebuilt from `written_paths`, so the very run that
+ *    protected an edit erased the digest proving it was an edit. The next run
+ *    saw `unknown` and overwrote — preservation survived exactly one install.
+ * 2. **A failed deploy wiped its tool's whole inventory.** `deploy_failed`
+ *    produced an empty list, and an empty list is authoritative replacement,
+ *    not "nothing to say".
+ * 3. **Every tool outside the current selection lost its inventory too.**
+ *    `installed_tools.read_manifest` is a hand-rolled parser that drops nested
+ *    `files[]` by design (ADR-200), so the entries carried into the rewrite
+ *    came back empty and were written back empty. `upsert_tool`'s "keep what
+ *    was there" fallback could never fire, because nothing was ever there by
+ *    the time it looked.
+ *
+ * (3) is why this module hydrates rather than patching the preserve branch:
+ * the same digest loss reaches the same file through three doors, and repairing
+ * one leaves the other two open.
+ *
+ * WHY A FOURTH READER OF THIS FILE.
+ *
+ * `installed_tools.read_manifest` (degraded by design), `install_drift`
+ * (digests it re-hashes itself) and `recordedOwnership.readRecordedHashes` (a
+ * flat path→digest map, no tool attribution, no `kind`) already read it. None
+ * answers the question here — *which tool recorded which entries, verbatim,
+ * so they can be written back unchanged* — and widening either of the latter
+ * two would change a shape their own tests pin. What this module does not
+ * duplicate is `manifest_path()`: that stays the single place deciding where
+ * the manifest is, so the `AGENT_CONFIG_INSTALLED_TOOLS` override behaves
+ * identically in all four.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import * as YAML from 'yaml';
+
+import { sha256OfFile } from './fsPrimitives.js';
+import { sidecarPathFor } from './preserve.js';
+
+/** One `tools[].files[]` record, in the shape the manifest writer emits. */
+export type ManifestFileEntry = Record<string, unknown>;
+
+/** A recorded entry plus the absolute path it resolves to on this machine. */
+export interface RecordedFile {
+    /** The entry exactly as recorded — written back byte-identical. */
+    readonly entry: ManifestFileEntry;
+    /** `entry.path` with `~` expanded and resolved against the project root. */
+    readonly resolved: string;
+}
+
+/** What a previous install recorded for one tool. */
+export interface RecordedToolInventory {
+    readonly files: readonly RecordedFile[];
+    readonly mergedKeys: readonly ManifestFileEntry[];
+}
+
+/** Tool id → what the manifest records for it. */
+export type RecordedByTool = ReadonlyMap<string, RecordedToolInventory>;
+
+/** Build one `files[]` record for `p`. */
+export function fileEntry(p: string, kind: string, hashContent: boolean): ManifestFileEntry {
+    return { path: p, kind, sha256: hashContent ? sha256OfFile(p) : null };
+}
+
+/** A deploy tuple: `[written, skipped, status, paths]`. */
+export type DeployTuple = readonly [number, number, string, string[]];
+
+/**
+ * Turn deploy results into the per-tool inventory this run is authoritative for.
+ *
+ * `null` — not an empty list — for a tool whose deploy did not complete. The
+ * distinction is the whole point: an empty list says "this tool owns no files
+ * now", which replaces and therefore erases; `null` says "this run learned
+ * nothing about this tool", which is what a failed deploy actually knows, and
+ * the caller carries the previous inventory forward instead.
+ */
+export function filesByToolFromDeploy(
+    deployResults: Record<string, DeployTuple>,
+): Record<string, ManifestFileEntry[] | null> {
+    const out: Record<string, ManifestFileEntry[] | null> = {};
+    for (const toolId of Object.keys(deployResults)) {
+        const [, , status, paths] = deployResults[toolId] as DeployTuple;
+        if (status === 'deployed') {
+            out[toolId] = paths.map((p) => fileEntry(p, 'deployed', true));
+        } else if (status === 'marker') {
+            out[toolId] = paths.map((p) => fileEntry(p, 'marker', true));
+        } else {
+            out[toolId] = null;
+        }
+    }
+    return out;
+}
+
+/**
+ * The bridge marker each selected tool claims, as a one-entry inventory.
+ *
+ * `bridgeMarker` is injected because the marker table lives with the installer's
+ * tool registry; passing it keeps that registry in one place instead of giving
+ * this module a second copy to drift from. Bridge entries are recorded WITHOUT
+ * a digest — a bridge is a pointer the consumer owns and edits, so there is
+ * nothing for this tree to claim ownership of, and `classifyOwnership` reads a
+ * null digest as `unknown` and leaves the file alone.
+ */
+export function filesByToolFromBridges(
+    tools: Set<string>,
+    projectRoot: string,
+    scope: string,
+    bridgeMarker: (toolId: string, scope: string) => string,
+): Record<string, ManifestFileEntry[]> {
+    const out: Record<string, ManifestFileEntry[]> = {};
+    for (const toolId of [...tools].sort()) {
+        const marker = bridgeMarker(toolId, scope);
+        if (!marker) continue;
+        const markerPath = isAbsolute(marker) ? marker : join(projectRoot, marker);
+        out[toolId] = [fileEntry(markerPath, 'bridge', false)];
+    }
+    return out;
+}
+
+/** Expand a leading `~`, matching `installed_tools.expanduser`. */
+function expanduser(p: string): string {
+    if (p === '~') return homedir();
+    if (p.startsWith('~/') || (process.platform === 'win32' && p.startsWith('~\\'))) {
+        return join(homedir(), p.slice(2));
+    }
+    return p;
+}
+
+/** Resolve a manifest-recorded path the way every other reader of this file does. */
+function resolveRecorded(raw: string, projectRoot: string): string {
+    const expanded = expanduser(raw);
+    return isAbsolute(expanded) ? resolve(expanded) : resolve(projectRoot, expanded);
+}
+
+/**
+ * Read `tools[].files[]` and `tools[].merged_keys[]` per tool.
+ *
+ * A missing, unreadable or malformed manifest yields an empty map rather than
+ * throwing — an install must never fail because a lockfile is corrupt, and an
+ * empty answer degrades to exactly the behaviour this module replaced.
+ */
+export function readRecordedByTool(manifestPath: string, projectRoot: string): RecordedByTool {
+    const out = new Map<string, RecordedToolInventory>();
+    if (!existsSync(manifestPath)) return out;
+    let doc: unknown;
+    try {
+        doc = YAML.parse(readFileSync(manifestPath, 'utf8'));
+    } catch {
+        return out;
+    }
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return out;
+    const tools = (doc as Record<string, unknown>)['tools'];
+    if (!Array.isArray(tools)) return out;
+
+    for (const tool of tools) {
+        if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) continue;
+        const rec = tool as Record<string, unknown>;
+        const name = rec['name'];
+        if (typeof name !== 'string' || name.length === 0) continue;
+        const files: RecordedFile[] = [];
+        const rawFiles = rec['files'];
+        if (Array.isArray(rawFiles)) {
+            for (const entry of rawFiles) {
+                if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue;
+                const raw = (entry as Record<string, unknown>)['path'];
+                if (typeof raw !== 'string' || raw.length === 0) continue;
+                files.push({
+                    entry: entry as ManifestFileEntry,
+                    resolved: resolveRecorded(raw, projectRoot),
+                });
+            }
+        }
+        const rawMerged = rec['merged_keys'];
+        const mergedKeys = Array.isArray(rawMerged) ? (rawMerged as ManifestFileEntry[]) : [];
+        out.set(name, { files, mergedKeys });
+    }
+    return out;
+}
+
+/**
+ * Put the nested inventories back onto entries read by the degraded parser.
+ *
+ * `installed_tools.read_manifest` returns every tool with `files: []` and
+ * `merged_keys: []` whatever the file held, and those entries are what the
+ * rewrite carries forward for tools the current run does not touch. Without
+ * this, installing tool A erases tool B's recorded digests — and B's managed
+ * files then classify `unknown` and get overwritten the next time B installs.
+ *
+ * Mutates in place and returns the same array: the caller's `entries` list is
+ * already its own copy, and rebuilding it would drop unknown-but-recorded
+ * keys that this module has no business deciding about.
+ */
+export function hydrateRecordedInventories(
+    entries: ManifestFileEntry[],
+    prior: RecordedByTool,
+): ManifestFileEntry[] {
+    for (const entry of entries) {
+        const name = entry['name'];
+        if (typeof name !== 'string') continue;
+        const recorded = prior.get(name);
+        if (recorded === undefined) continue;
+        if (Array.isArray(entry['files']) && (entry['files'] as unknown[]).length === 0) {
+            entry['files'] = recorded.files.map((f) => f.entry);
+        }
+        if (Array.isArray(entry['merged_keys']) && (entry['merged_keys'] as unknown[]).length === 0) {
+            entry['merged_keys'] = [...recorded.mergedKeys];
+        }
+    }
+    return entries;
+}
+
+/**
+ * The inventory to record for one tool this run.
+ *
+ * - `fresh === null | undefined` → the previous inventory, unchanged. A run
+ *   that learned nothing about a tool records what was already known.
+ * - otherwise → what this run wrote, plus a carried-forward entry for every
+ *   PRESERVED path this tool recorded before.
+ *
+ * The carried entry keeps the path and kind it had, and takes the digest of
+ * the content STAGED this run. Both halves are load-bearing.
+ *
+ * The digest means "the package content this installer last produced for this
+ * path". A preserved run produced that content too — it staged it in the
+ * sidecar instead of writing it — so recording it keeps the field's meaning
+ * exact and makes the documented resolution work: merge the sidecar and the
+ * file matches, so the conflict clears and the next install refreshes it
+ * normally. Carrying the OLDER digest instead would leave a correctly merged
+ * file looking modified forever, resolvable only with `--force`.
+ *
+ * What it must never be is a re-hash of the target. That records the USER's
+ * content as ours, and the run after that classifies the edit
+ * `recorded-unchanged` and overwrites it — the same data loss, one
+ * indirection further away.
+ */
+export function reconcileToolFiles(
+    fresh: readonly ManifestFileEntry[] | null | undefined,
+    prior: RecordedToolInventory | undefined,
+    preserved: PreservedIndex,
+): ManifestFileEntry[] | null {
+    if (fresh === null || fresh === undefined) {
+        return prior === undefined ? null : prior.files.map((f) => f.entry);
+    }
+    if (prior === undefined || preserved.size === 0) return [...fresh];
+    const seen = new Set<string>();
+    for (const entry of fresh) {
+        const raw = entry['path'];
+        if (typeof raw === 'string') seen.add(resolve(expanduser(raw)));
+    }
+    const out = [...fresh];
+    for (const file of prior.files) {
+        const staged = preserved.get(file.resolved);
+        if (staged === undefined || seen.has(file.resolved)) continue;
+        out.push(staged.sha256 === null ? file.entry : { ...file.entry, sha256: staged.sha256 });
+        if (staged.sidecar !== null) out.push(staged.sidecar);
+    }
+    return out;
+}
+
+/**
+ * Resolved target path → the manifest entry for the sidecar staged beside it.
+ *
+ * The attribution problem this solves: a preserved path is not in any tool's
+ * written list, so nothing in the deploy results says which tool owns it. The
+ * PREVIOUS manifest does — it recorded that path under a tool — so
+ * {@link reconcileToolFiles} matches on the prior inventory and the sidecar
+ * rides along with its target rather than being filed by guesswork.
+ */
+export type PreservedIndex = ReadonlyMap<string, PreservedRecord>;
+
+/** What one preserved target contributes to the manifest. */
+export interface PreservedRecord {
+    /** Digest of the content staged for it, or `null` when nothing was staged. */
+    readonly sha256: string | null;
+    /** The sidecar's own entry — this run's proof that it staged that file. */
+    readonly sidecar: ManifestFileEntry | null;
+}
+
+/** Build the {@link PreservedIndex} from the tracker's per-run state. */
+export function preservedIndex(
+    preservedTargets: readonly string[],
+    staged: ReadonlyMap<string, string | null>,
+): PreservedIndex {
+    const out = new Map<string, PreservedRecord>();
+    for (const target of preservedTargets) {
+        const sidecar = sidecarPathFor(target);
+        const sha = staged.get(sidecar) ?? null;
+        out.set(resolve(target), {
+            sha256: sha,
+            sidecar: sha === null ? null : { path: sidecar, kind: 'sidecar', sha256: sha },
+        });
+    }
+    return out;
+}

package/src/install/preflight.ts

@@ -155,8 +155,22 @@ export function checkConflicts(inputs: PlanInputs): PreflightFinding[] {
         id: 'conflicts' as const,
         severity: 'warning' as const,
         path: c.path,
-        message: `existing file conflicts with planned ${c.kind} content`,
-        remedy: 'resolve interactively, or pass --force to overwrite',
+        message:
+            c.ownership === 'recorded-modified'
+                ? `managed ${c.kind} file has been edited since we wrote it`
+                : `existing file conflicts with planned ${c.kind} content`,
+        // A remedy here may only describe what an install actually does. Before
+        // the owner ruling of 2026-09-21 the writer overwrote every deployed
+        // file unconditionally, so the `recorded-modified` arm told the
+        // operator to back their edit up. It now preserves that file and stages
+        // the package content beside it, so the same sentence would be false in
+        // the opposite direction — it would understate a protection that ships.
+        // The `unknown` arm is unchanged: nothing is recorded for that path, so
+        // the writer still writes over it.
+        remedy:
+            c.ownership === 'recorded-modified'
+                ? 'installing preserves your edit and stages package content as <path>.agent-config.new; --force replaces it instead'
+                : 'back up this file — installing writes the planned content over it',
     }));
 }
 

package/src/install/preserve.ts

@@ -0,0 +1,205 @@
+/**
+ * Preserve a user-modified managed file — road-to-a-conformance-check-that-can-fail
+ * Phase 5.1, owner ruling 2026-09-21 (option (a), after a 1/1 council split).
+ *
+ * THE GAP THIS CLOSES. Until this module existed, `agent-config init` overwrote
+ * every deployed file unconditionally: the conflict resolver in
+ * `src/scripts/install.ts` returned `write` for every target, and the module
+ * header recorded `--force` as an accepted no-op "because installs always
+ * overwrite". The planner produced a `ConflictEntry` list naming the files the
+ * user had edited, and the writer read none of it — so the report named the
+ * file and the next install replaced it.
+ *
+ * WHAT THE RULING CHANGES. A managed file whose bytes diverge from the digest
+ * the install manifest recorded is preserved; the package content it would
+ * have been replaced with is staged beside it as a sidecar, and the run ends
+ * with a distinct exit code so the resulting staleness is loud rather than
+ * silent.
+ *
+ * NO SEMANTIC CLASSIFICATION, DELIBERATELY. Any divergence from the recorded
+ * digest gets identical treatment. There is no comment-only detection, no
+ * format-aware diff, no three-way merge — each would drag a per-format parser
+ * into the installer's trusted computing base, and a syntactically trivial
+ * edit can still be an intentional one. One byte of divergence is the whole
+ * test.
+ *
+ * NO FALLBACK TO OVERWRITING. There is no conflict threshold above which
+ * preservation stops, no resource-pressure escape, and no bulk accept flag.
+ * `--force` is the single escape hatch and it is explicit, per-run and
+ * documented. Failing closed here means leaving a file alone, which is the
+ * recoverable direction.
+ *
+ * NO UNPROVEN OWNERSHIP CLAIM OVER AN EXISTING SIDECAR. A pathname matching the
+ * convention is not provenance, and destroying an unrecognised file while
+ * claiming to protect files would be the defect this module exists to remove,
+ * wearing the fix's clothes. So a file at the sidecar path is replaced only
+ * when the manifest RECORDS this tree staging those exact bytes; a sidecar
+ * still holding an older version's content is therefore refreshed rather than
+ * refused, because leaving it unmerged is the staging workflow working. Bytes
+ * matching neither the current content nor anything recorded are left alone and
+ * the run stops.
+ */
+
+import { classifyOwnership } from './recordedOwnership.js';
+
+/**
+ * Suffix appended to a preserved file's path to name its staged package copy.
+ *
+ * Tool-owned on purpose. A bare `.new` is a namespace editors, patch tools and
+ * humans already write into, so an install that claimed it would collide with
+ * files it has no relationship to; `.agent-config.new` says who wrote it.
+ */
+export const SIDECAR_SUFFIX = '.agent-config.new';
+
+/**
+ * Exit code for a run that installed everything it could but preserved at
+ * least one user-modified file.
+ *
+ * Distinct from `0` (fully current) and from `1` (the run failed). It is the
+ * load-bearing half of the ruling: preserving an edit leaves the active
+ * installation stale, and a stale install that exits `0` is silently stale.
+ * `2` is already argparse's usage-error code, so this is `3`.
+ */
+export const EXIT_COMPLETED_WITH_CONFLICTS = 3;
+
+/** What the writer should do with one planned target. */
+export type DeployWriteDecision = 'write' | 'preserve';
+
+/** Inputs to {@link decideDeployWrite}. */
+export interface DeployWriteInputs {
+    /** True when the target already exists on disk. */
+    readonly exists: boolean;
+    /**
+     * The SHA-256 the install manifest recorded for this target.
+     *
+     * `undefined` — not recorded at all. `null` — recorded without a digest
+     * (bridge entries carry `sha256: null`). Both mean this tree cannot say
+     * whether the bytes on disk are ours.
+     */
+    readonly recordedSha256: string | null | undefined;
+    /**
+     * The SHA-256 of the bytes on disk, computed immediately before the caller
+     * mutates the file — not at plan time.
+     *
+     * The planner's `ConflictEntry` list is advisory state, not a safety
+     * capability: minutes can pass between planning and writing, and a file
+     * edited in that window would be classified from a digest that no longer
+     * describes it. Re-hashing at the write site closes that window.
+     *
+     * `null` when the file could not be read.
+     */
+    readonly onDiskSha256: string | null;
+    /** True when the run carries `--force`. */
+    readonly force: boolean;
+}
+
+/**
+ * Decide whether the writer may replace one managed file.
+ *
+ * A target that does not exist is written. A forced run writes. Otherwise the
+ * recorded-ownership verdict decides: `recorded-modified` preserves, and both
+ * `recorded-unchanged` and `unknown` write.
+ *
+ * The `unknown` arm is the one worth stating out loud, because it is what
+ * keeps this change from being a regression. No recorded digest means no
+ * divergence to measure — a tree with no manifest, a global anchor that holds
+ * none, or a bridge entry recorded without a hash. Preserving there would
+ * stage a sidecar beside every pre-existing file on a first install, which is
+ * not protection, it is noise. The ruling covers a file this tree can show it
+ * wrote and can show has changed since; everything else keeps the behavior it
+ * had, and `recordedOwnership` already documents that floor.
+ */
+export function decideDeployWrite(inputs: DeployWriteInputs): DeployWriteDecision {
+    if (!inputs.exists) return 'write';
+    if (inputs.force) return 'write';
+    const ownership = classifyOwnership(inputs.recordedSha256, inputs.onDiskSha256);
+    return ownership === 'recorded-modified' ? 'preserve' : 'write';
+}
+
+/** Path of the sidecar staged beside `target`. */
+export function sidecarPathFor(target: string): string {
+    return `${target}${SIDECAR_SUFFIX}`;
+}
+
+/**
+ * Per-file report line for a preserved target.
+ *
+ * Says three things in one breath, and all three are load-bearing: the edit
+ * survived, the package content is somewhere findable, and the active
+ * installation is not current — that last clause is what turns a silently
+ * stale tree into a stated one.
+ */
+export function preservedFileMessage(target: string, sidecar: string): string {
+    return (
+        `Preserved user-modified ${target}. Package content was written to ${sidecar}; ` +
+        'the active installation is not current. Review and merge it, or rerun with ' +
+        '--force to replace the managed file.'
+    );
+}
+
+/** End-of-run summary naming the conflict count and what it means. */
+export function conflictSummaryMessage(count: number): string {
+    const noun = count === 1 ? 'file' : 'files';
+    return (
+        `Completed with conflicts: ${count} user-modified ${noun} preserved. ` +
+        `Package content is staged alongside as *${SIDECAR_SUFFIX}; the active installation ` +
+        `is not current until you merge it, or rerun with --force to replace the managed ${noun}.`
+    );
+}
+
+/**
+ * Refusal message for a sidecar path already holding bytes this run cannot
+ * attribute to itself.
+ *
+ * The run fails rather than continuing: the package content was never written
+ * anywhere, so the target is neither refreshed nor staged, and calling that
+ * "completed with conflicts" would report a staging that did not happen.
+ */
+export function foreignSidecarMessage(target: string, sidecar: string): string {
+    return (
+        `Refusing to replace ${sidecar}: it already exists with different content and this ` +
+        `install cannot show it wrote it. Package content for ${target} was NOT staged. ` +
+        'Move or delete that file and re-run, or rerun with --force to replace the managed file instead.'
+    );
+}
+
+/**
+ * Summary payload for the GUI wizard's `done` SSE frame.
+ *
+ * `conflicts` rides on the installer's own `done` frame when the run preserved
+ * a user-modified managed file (exit {@link EXIT_COMPLETED_WITH_CONFLICTS}).
+ * The wizard forwards it rather than dropping it: a preserved edit means the
+ * active installation is not current, and that frame is the browser's only
+ * channel for saying so. Omitted when zero, so the historical summary shape is
+ * unchanged for every run that has no conflicts.
+ *
+ * It lives here rather than in the route because the conflict semantics are
+ * this module's, and because `src/server/routes/wizard.ts` sits against the
+ * 1,500-line source ceiling that `check_source_size_budget` ratchets.
+ */
+/**
+ * Did the installer COMPLETE, whatever it exited with?
+ *
+ * `3` is a completion with preserved files, not a failure. The wizard's
+ * fallback path — the one that speaks when the installer dies before its
+ * terminal frame — tested `exitCode === 0` and reported everything else as
+ * `BRIDGE_FAILED`, so a run that installed everything it could and kept the
+ * user's edits was announced to the operator as a failed install.
+ *
+ * Here rather than in the route for the same reason as {@link installDoneSummary}:
+ * the semantics are this module's, and `src/server/routes/wizard.ts` sits
+ * against the 1,500-line source ceiling that `check_source_size_budget`
+ * ratchets.
+ */
+export function installCompleted(exitCode: number): boolean {
+    return exitCode === 0 || exitCode === EXIT_COMPLETED_WITH_CONFLICTS;
+}
+
+export function installDoneSummary(
+    frame: Record<string, unknown>,
+    written: number,
+    total: number,
+): { written: number; total: number; conflicts?: number } {
+    const conflicts = typeof frame.conflicts === 'number' ? frame.conflicts : 0;
+    return conflicts > 0 ? { written, total, conflicts } : { written, total };
+}