packlight-cli 0.0.0-stage → 0.1.0

package/dist/archive/fsops.js

@@ -0,0 +1,95 @@
+import { cpSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import writeFileAtomic from 'write-file-atomic';
+import { pathFingerprint, sha256 } from '../core/hash.js';
+const sleep = (ms) => { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+/** rename with a bounded retry: Windows reports EPERM/EBUSY while another process briefly holds a file (eng SC1). */
+export function renameWithRetry(from, to, rename = renameSync) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            rename(from, to);
+            return;
+        }
+        catch (err) {
+            if (!['EPERM', 'EBUSY', 'EACCES'].includes(err?.code) || attempt >= 9)
+                throw err;
+            sleep(50 * (attempt + 1));
+        }
+    }
+}
+/** Settings writes go through write-file-atomic, which keeps the file's mode and owner (eng SC2). */
+export function atomicWrite(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileAtomic.sync(path, data);
+}
+export const fileHash = (path) => {
+    try {
+        return sha256(readFileSync(path));
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+};
+export const exists = (path) => lstatSync(path, { throwIfNoEntry: false }) !== undefined;
+/** Fingerprint of a path, or "missing" (journal states compare these). */
+export const stateOf = (path) => (exists(path) ? pathFingerprint(path) : 'missing');
+export class ChangedWhileMoving extends Error {
+}
+/** The verified copy is in place but the source could not be fully removed: both must be kept. */
+export class SourceNotRemoved extends Error {
+}
+/** Where a cross-volume move stages its copy: hidden, beside the destination, and recorded in the journal as scratch. */
+export const stagingPathFor = (to) => join(dirname(to), `.${basename(to)}.packlight-staging`);
+/**
+ * Moves a file, folder or link. Same volume: one rename. Across volumes (EXDEV): copy into a staging path
+ * beside the destination, check the copy against the source's fingerprint, re-check the source, then swap
+ * the staging copy in and remove the source (eng X4). A link is moved as a link, never followed.
+ */
+export function moveTree(from, to, opts = {}) {
+    mkdirSync(dirname(to), { recursive: true });
+    try {
+        renameWithRetry(from, to, opts.rename);
+        return;
+    }
+    catch (err) {
+        if (err?.code !== 'EXDEV')
+            throw err;
+    }
+    const before = pathFingerprint(from);
+    const staging = stagingPathFor(to);
+    rmSync(staging, { recursive: true, force: true });
+    const st = lstatSync(from);
+    try {
+        if (st.isSymbolicLink())
+            symlinkSync(readlinkSync(from), staging, isDirTarget(from) ? 'junction' : 'file');
+        else
+            cpSync(from, staging, { recursive: true, preserveTimestamps: true, verbatimSymlinks: true });
+        if (pathFingerprint(staging) !== before || pathFingerprint(from) !== before) {
+            throw new ChangedWhileMoving(`${from} changed while it was being copied; nothing was moved`);
+        }
+        renameWithRetry(staging, to);
+    }
+    catch (err) {
+        rmSync(staging, { recursive: true, force: true });
+        throw err;
+    }
+    try {
+        if (st.isSymbolicLink())
+            unlinkSync(from);
+        else
+            rmSync(from, { recursive: true, force: true });
+    }
+    catch (err) {
+        throw new SourceNotRemoved(`A verified copy is at ${to}, but ${from} could not be fully removed (${err.message}). Both were kept.`);
+    }
+}
+function isDirTarget(link) {
+    try {
+        return statSync(link).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/archive/journal.d.ts

@@ -0,0 +1,41 @@
+import type { PacklightPaths } from './paths.js';
+import type { Manifest } from './manifest.js';
+/**
+ * One journal for archive and restore (CEO F1, eng X3). Every change is recorded as pending with the
+ * expected state of each path before and after it, then performed, then marked done. On every start,
+ * a pending entry is finished or rolled back only when the disk matches one of those states exactly;
+ * anything else is refused and named, and nothing is touched.
+ */
+export interface PathState {
+    path: string;
+    /** "tree": fingerprint of a file, folder or link (or "missing"); "file": sha256 of the bytes (or null). */
+    kind: 'tree' | 'file';
+    before: string | null;
+    after: string | null;
+    /** A temporary path packlight created (cross-volume staging): removed before recovery decides. */
+    scratch?: boolean;
+}
+export interface JournalEntry {
+    opId: string;
+    direction: 'archive' | 'restore';
+    state: 'pending' | 'done' | 'aborted';
+    at: string;
+    paths: PathState[];
+}
+export declare function journalBegin(paths: PacklightPaths, entry: Omit<JournalEntry, 'state' | 'at'>): void;
+export declare function journalEnd(paths: PacklightPaths, opId: string, direction: JournalEntry['direction'], state: 'done' | 'aborted'): void;
+export interface RecoveryResult {
+    completed: string[];
+    rolledBack: string[];
+    refused: {
+        opId: string;
+        direction: string;
+        files: string[];
+    }[];
+}
+/** Finishes or rolls back whatever a crash left pending. Runs before every command that changes the setup. */
+export declare function recover(paths: PacklightPaths): RecoveryResult;
+export declare function readManifest(paths: PacklightPaths, opId: string): Manifest | undefined;
+export declare function writeManifest(paths: PacklightPaths, m: Manifest): void;
+export declare function setManifestStatus(paths: PacklightPaths, opId: string, status: Manifest['status']): void;
+export declare function listManifests(paths: PacklightPaths): Manifest[];

package/dist/archive/journal.js

@@ -0,0 +1,95 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { atomicWrite, fileHash, stateOf } from './fsops.js';
+const read = (paths) => {
+    if (!existsSync(paths.journal))
+        return { version: 1, entries: [] };
+    return JSON.parse(readFileSync(paths.journal, 'utf8'));
+};
+const write = (paths, j) => atomicWrite(paths.journal, JSON.stringify(j, null, 1) + '\n');
+export function journalBegin(paths, entry) {
+    const j = read(paths);
+    j.entries.push({ ...entry, state: 'pending', at: new Date().toISOString() });
+    write(paths, j);
+}
+export function journalEnd(paths, opId, direction, state) {
+    const j = read(paths);
+    const e = [...j.entries].reverse().find(x => x.opId === opId && x.direction === direction && x.state === 'pending');
+    if (e)
+        e.state = state;
+    write(paths, j);
+}
+const current = (p) => (p.kind === 'tree' ? stateOf(p.path) : fileHash(p.path));
+/** Finishes or rolls back whatever a crash left pending. Runs before every command that changes the setup. */
+export function recover(paths) {
+    const result = { completed: [], rolledBack: [], refused: [] };
+    const j = read(paths);
+    let changed = false;
+    for (const e of j.entries.filter(x => x.state === 'pending')) {
+        for (const p of e.paths.filter(p => p.scratch))
+            rmSync(p.path, { recursive: true, force: true });
+        const real = e.paths.filter(p => !p.scratch);
+        e.paths = real;
+        let now = e.paths.map(current);
+        // A cross-volume move that stopped after its verified copy but before removing the source leaves both
+        // copies, each matching a known state (eng X4). An archive drops the copy; a restore drops the archive.
+        const allBefore = e.paths.every((p, i) => now[i] === p.before);
+        const allAfter = e.paths.every((p, i) => now[i] === p.after);
+        const mixed = !allBefore && !allAfter && e.paths.every(p => p.kind === 'tree') && e.paths.every((p, i) => now[i] === p.before || now[i] === p.after);
+        if (mixed) {
+            for (const [i, p] of e.paths.entries()) {
+                const extraCopy = e.direction === 'archive' ? now[i] === p.after && p.before === 'missing' : now[i] === p.before && p.after === 'missing';
+                if (extraCopy && now[i] !== 'missing')
+                    rmSync(p.path, { recursive: true, force: true });
+            }
+            now = e.paths.map(current);
+        }
+        const isAfter = e.paths.every((p, i) => now[i] === p.after);
+        const isBefore = e.paths.every((p, i) => now[i] === p.before);
+        if (isAfter) {
+            e.state = 'done';
+            if (e.direction === 'restore')
+                setManifestStatus(paths, e.opId, 'restored');
+            result.completed.push(`${e.direction} ${e.opId}`);
+        }
+        else if (isBefore) {
+            e.state = 'aborted';
+            // An archive that never happened leaves no record behind; staging copies from cross-volume moves go too.
+            if (e.direction === 'archive')
+                rmSync(join(paths.archive, e.opId), { recursive: true, force: true });
+            result.rolledBack.push(`${e.direction} ${e.opId}`);
+        }
+        else {
+            result.refused.push({ opId: e.opId, direction: e.direction, files: e.paths.filter((p, i) => now[i] !== p.before && now[i] !== p.after).map(p => p.path) });
+            continue;
+        }
+        changed = true;
+    }
+    if (changed)
+        write(paths, j);
+    return result;
+}
+export function readManifest(paths, opId) {
+    const file = join(paths.archive, opId, 'manifest.json');
+    if (!existsSync(file))
+        return undefined;
+    return JSON.parse(readFileSync(file, 'utf8'));
+}
+export function writeManifest(paths, m) {
+    atomicWrite(join(paths.archive, m.opId, 'manifest.json'), JSON.stringify(m, null, 1) + '\n');
+}
+export function setManifestStatus(paths, opId, status) {
+    const m = readManifest(paths, opId);
+    if (m && m.status !== status)
+        writeManifest(paths, { ...m, status, ...(status === 'restored' ? { restoredAt: new Date().toISOString() } : {}) });
+}
+export function listManifests(paths) {
+    let ids;
+    try {
+        ids = readdirSync(paths.archive);
+    }
+    catch {
+        return [];
+    }
+    return ids.map(id => readManifest(paths, id)).filter((m) => !!m).sort((a, b) => a.opId.localeCompare(b.opId));
+}

package/dist/archive/lock.d.ts

@@ -0,0 +1,2 @@
+/** One packlight process changes the setup at a time (CEO F2). A lock left by a dead process is taken over. */
+export declare function acquireLock(file: string): () => void;

package/dist/archive/lock.js

@@ -0,0 +1,32 @@
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+const alive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err?.code === 'EPERM';
+    }
+};
+/** One packlight process changes the setup at a time (CEO F2). A lock left by a dead process is taken over. */
+export function acquireLock(file) {
+    mkdirSync(dirname(file), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(file, 'wx');
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => rmSync(file, { force: true });
+        }
+        catch (err) {
+            if (err?.code !== 'EEXIST')
+                throw err;
+            const pid = Number(readFileSync(file, 'utf8'));
+            if (pid && alive(pid) && pid !== process.pid)
+                throw new Error(`Another packlight (process ${pid}) is changing your setup. Wait for it to finish.`);
+            rmSync(file, { force: true });
+        }
+    }
+    throw new Error(`Could not take the lock at ${file}.`);
+}

package/dist/archive/manifest.d.ts

@@ -0,0 +1,37 @@
+import type { Kind, RemovalMethod } from '../core/types.js';
+/** One archive operation: one declaration of one item (eng X2, X5). Readers must accept older versions. */
+export interface Manifest {
+    manifestVersion: 1;
+    opId: string;
+    itemId: string;
+    itemName: string;
+    kind: Kind;
+    agent: string;
+    method: RemovalMethod;
+    scanId: string;
+    archivedAt: string;
+    /** archived: packlight holds it; restored: put back; waiting: removable only by hand. */
+    status: 'archived' | 'restored' | 'waiting';
+    restoredAt?: string;
+    note?: string;
+    originalPath?: string;
+    payloadPath?: string;
+    isSymlink?: boolean;
+    symlinkTarget?: string;
+    /** Fingerprint of what was moved, checked again before restore. */
+    fingerprint?: string;
+    settingsFile?: string;
+    jsonPointer?: string;
+    /** The removed or changed JSON value, printed when a restore has to be done by hand (D12). */
+    fragment?: unknown;
+    /** The whole settings file as it was, base64; null when the file did not exist. */
+    originalFileBase64?: string | null;
+    fileHashBefore?: string | null;
+    fileHashAfter?: string | null;
+    plugin?: {
+        key: string;
+        wasEnabled: boolean | null;
+    };
+    manualSteps?: string;
+}
+export declare function newOpId(now?: Date): string;

package/dist/archive/manifest.js

@@ -0,0 +1,9 @@
+import { randomBytes } from 'node:crypto';
+/** Operation ids never repeat: UTC time plus 6 random hex (eng X5). They sort by time. */
+let lastMs = 0;
+export function newOpId(now = new Date()) {
+    // Strictly increasing even within one millisecond, so "newest first" is a total order (several edits of one file).
+    const ms = Math.max(now.getTime(), lastMs + 1);
+    lastMs = ms;
+    return `${new Date(ms).toISOString().replace(/[-:]/g, '').replace(/\.(\d{3})Z$/, '$1Z')}-${randomBytes(3).toString('hex')}`;
+}

package/dist/archive/methods.d.ts

@@ -0,0 +1,46 @@
+import type { Item } from '../core/types.js';
+import { type Manifest } from './manifest.js';
+import type { PacklightPaths } from './paths.js';
+export type Step = {
+    method: 'move';
+    item: Item;
+    path: string;
+} | {
+    method: 'hook-extract' | 'mcp-extract';
+    item: Item;
+    file: string;
+    pointer: string;
+} | {
+    method: 'plugin-disable';
+    item: Item;
+    file: string;
+    pointer: string;
+    key: string;
+} | {
+    method: 'manual';
+    item: Item;
+    where: string;
+};
+export interface StepContext {
+    paths: PacklightPaths;
+    scanId: string;
+    now: () => Date;
+    /** Hash each settings file is expected to have before packlight's next write to it (CEO F2). */
+    expectedHash: Map<string, string | null>;
+    /** Test hook that stops the process at a named point, as a kill -9 would (eng X3 fault injection). */
+    crash: (point: string) => void;
+}
+export type Outcome = {
+    ok: true;
+    opId: string;
+} | {
+    ok: false;
+    reason: string;
+    fragment?: unknown;
+    file?: string;
+};
+export declare const parsePointer: (p: string) => string[];
+/** Sorts pointers so later array indices come first: removing them never shifts the ones still to do. */
+export declare function comparePointersDesc(a: string, b: string): number;
+export declare function archiveStep(ctx: StepContext, step: Step): Outcome;
+export declare function restoreManifest(ctx: StepContext, m: Manifest): Outcome;

package/dist/archive/methods.js

@@ -0,0 +1,239 @@
+import { lstatSync, readFileSync, readlinkSync, rmSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { sha256, valueFingerprint } from '../core/hash.js';
+import { atomicWrite, ChangedWhileMoving, exists, fileHash, moveTree, SourceNotRemoved, stagingPathFor, stateOf } from './fsops.js';
+import { journalBegin, journalEnd, setManifestStatus, writeManifest } from './journal.js';
+import { newOpId } from './manifest.js';
+// ---------------------------------------------------------------- JSON pointers
+export const parsePointer = (p) => p.split('/').slice(1).map(s => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+/** Sorts pointers so later array indices come first: removing them never shifts the ones still to do. */
+export function comparePointersDesc(a, b) {
+    const pa = parsePointer(a);
+    const pb = parsePointer(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i];
+        const y = pb[i];
+        if (x === y)
+            continue;
+        if (x === undefined)
+            return 1;
+        if (y === undefined)
+            return -1;
+        const nx = Number(x);
+        const ny = Number(y);
+        if (Number.isInteger(nx) && Number.isInteger(ny))
+            return ny - nx;
+        return y.localeCompare(x);
+    }
+    return 0;
+}
+/** Re-serialises JSON in the file's own indentation and line ending, keeping a trailing newline if it had one. */
+function serialize(value, original) {
+    const indent = original ? (/\n([ \t]+)"/.exec(original)?.[1] ?? '  ') : '  ';
+    const eol = original?.includes('\r\n') ? '\r\n' : '\n';
+    const text = JSON.stringify(value, null, indent).replace(/\n/g, eol);
+    return original === null || /\r?\n$/.test(original) ? text + eol : text;
+}
+function edit(step, json) {
+    const seg = parsePointer(step.pointer);
+    if (step.method === 'plugin-disable') {
+        const next = json && typeof json === 'object' ? json : {};
+        next.enabledPlugins ??= {};
+        const was = step.key in next.enabledPlugins ? next.enabledPlugins[step.key] : null;
+        next.enabledPlugins[step.key] = false;
+        return { next, fragment: { [step.key]: was } };
+    }
+    if (step.method === 'mcp-extract') {
+        let parent = json;
+        for (const s of seg.slice(0, -1))
+            parent = parent?.[s];
+        const name = seg[seg.length - 1];
+        if (!parent || typeof parent !== 'object' || !(name in parent))
+            throw new Error(`${step.pointer} is no longer in ${step.file}`);
+        if (valueFingerprint(parent[name]) !== step.item.targetFingerprint)
+            throw new Error(NOT_THE_PICKED(step));
+        const fragment = { [name]: parent[name] };
+        delete parent[name];
+        return { next: json, fragment };
+    }
+    // hook-extract: /hooks/<event>/<group>/hooks/<index>; empty groups and events are removed with it.
+    const [, event, gi, , hi] = seg;
+    const groups = json?.hooks?.[event];
+    const group = Array.isArray(groups) ? groups[Number(gi)] : undefined;
+    const hooks = group?.hooks;
+    if (!Array.isArray(hooks) || hooks[Number(hi)] === undefined)
+        throw new Error(`${step.pointer} is no longer in ${step.file}`);
+    // The entry at the pointer must still be the one that was picked: settings files get reordered by other programs.
+    if (valueFingerprint({ event, matcher: group.matcher ?? null, command: hooks[Number(hi)]?.command }) !== step.item.targetFingerprint)
+        throw new Error(NOT_THE_PICKED(step));
+    const [removed] = hooks.splice(Number(hi), 1);
+    if (!hooks.length)
+        groups.splice(Number(gi), 1);
+    if (!groups.length)
+        delete json.hooks[event];
+    return { next: json, fragment: { event, matcher: group.matcher ?? null, hook: removed } };
+}
+const NOT_THE_PICKED = (step) => `The entry at ${step.pointer} in ${step.file} is no longer the one you picked (the file was reordered). Nothing was changed; scan and apply again.`;
+const base = (ctx, item, method, opId) => ({
+    manifestVersion: 1, opId, itemId: item.id, itemName: item.name, kind: item.kind, agent: item.agent, method,
+    scanId: ctx.scanId, archivedAt: ctx.now().toISOString(), status: 'archived',
+});
+// ---------------------------------------------------------------- archive
+export function archiveStep(ctx, step) {
+    if (step.method === 'manual') {
+        const opId = newOpId(ctx.now());
+        writeManifest(ctx.paths, { ...base(ctx, step.item, 'manual', opId), status: 'waiting', manualSteps: `Remove it in ${step.where}.` });
+        return { ok: true, opId };
+    }
+    return step.method === 'move' ? archiveMove(ctx, step) : archiveSettings(ctx, step);
+}
+function archiveMove(ctx, step) {
+    if (!exists(step.path))
+        return { ok: false, reason: `It is no longer at ${step.path}.` };
+    const opId = newOpId(ctx.now());
+    const payloadPath = join(ctx.paths.archive, opId, 'payload', basename(step.path));
+    const st = lstatSync(step.path);
+    const fp = stateOf(step.path);
+    journalBegin(ctx.paths, {
+        opId, direction: 'archive',
+        paths: [
+            { path: step.path, kind: 'tree', before: fp, after: 'missing' },
+            { path: payloadPath, kind: 'tree', before: 'missing', after: fp },
+            { path: stagingPathFor(payloadPath), kind: 'tree', before: 'missing', after: 'missing', scratch: true },
+        ],
+    });
+    ctx.crash('archive:after-journal');
+    writeManifest(ctx.paths, {
+        ...base(ctx, step.item, 'move', opId), originalPath: step.path, payloadPath, isSymlink: st.isSymbolicLink(),
+        ...(st.isSymbolicLink() ? { symlinkTarget: readlinkSync(step.path) } : {}), fingerprint: fp,
+    });
+    ctx.crash('archive:after-manifest');
+    try {
+        moveTree(step.path, payloadPath);
+    }
+    catch (err) {
+        if (err instanceof SourceNotRemoved) {
+            // The archive holds a complete, verified copy; part of the original is still in place. Keep both.
+            journalEnd(ctx.paths, opId, 'archive', 'done');
+            return { ok: false, reason: `${err.message} Delete what is left at ${step.path} by hand, or restore with \`packlight restore ${opId}\` once it is gone.` };
+        }
+        journalEnd(ctx.paths, opId, 'archive', 'aborted');
+        rmSync(join(ctx.paths.archive, opId), { recursive: true, force: true });
+        return { ok: false, reason: err instanceof ChangedWhileMoving ? err.message : `Could not move it: ${err.message}` };
+    }
+    ctx.crash('archive:after-change');
+    // A same-volume rename does not re-check content: record what actually arrived so restore can verify it.
+    const arrived = stateOf(payloadPath);
+    if (arrived !== fp)
+        writeManifest(ctx.paths, { ...base(ctx, step.item, 'move', opId), originalPath: step.path, payloadPath, isSymlink: st.isSymbolicLink(), ...(st.isSymbolicLink() ? { symlinkTarget: readlinkSync(payloadPath) } : {}), fingerprint: arrived, note: 'It changed between the plan and the move; the archived copy is the changed version.' });
+    journalEnd(ctx.paths, opId, 'archive', 'done');
+    return { ok: true, opId };
+}
+function archiveSettings(ctx, step) {
+    const original = readOrNull(step.file);
+    const h = original === null ? null : sha256(original);
+    if (ctx.expectedHash.has(step.file) && ctx.expectedHash.get(step.file) !== h) {
+        return { ok: false, reason: `${step.file} changed after packlight read it (another program wrote to it). Nothing was changed; scan and apply again.`, file: step.file };
+    }
+    let next;
+    let fragment;
+    try {
+        ({ next, fragment } = edit(step, original === null ? {} : JSON.parse(original.toString('utf8').replace(/^/, ''))));
+    }
+    catch (err) {
+        return { ok: false, reason: err.message, file: step.file };
+    }
+    const text = serialize(next, original?.toString('utf8') ?? null);
+    const h2 = sha256(text);
+    const opId = newOpId(ctx.now());
+    journalBegin(ctx.paths, { opId, direction: 'archive', paths: [{ path: step.file, kind: 'file', before: h, after: h2 }] });
+    ctx.crash('archive:after-journal');
+    writeManifest(ctx.paths, {
+        ...base(ctx, step.item, step.method, opId), settingsFile: step.file, jsonPointer: step.pointer, fragment,
+        originalFileBase64: original === null ? null : original.toString('base64'), fileHashBefore: h, fileHashAfter: h2,
+        ...(step.method === 'plugin-disable' ? { plugin: { key: step.key, wasEnabled: fragment[step.key] ?? null } } : {}),
+    });
+    ctx.crash('archive:after-manifest');
+    // Re-hash right before writing: this narrows, but cannot close, the window in which Claude Code itself writes (CEO O4).
+    if (fileHash(step.file) !== h) {
+        journalEnd(ctx.paths, opId, 'archive', 'aborted');
+        rmSync(join(ctx.paths.archive, opId), { recursive: true, force: true });
+        return { ok: false, reason: `${step.file} changed while packlight was preparing to edit it. Nothing was changed; apply again.`, file: step.file };
+    }
+    atomicWrite(step.file, text);
+    ctx.crash('archive:after-change');
+    journalEnd(ctx.paths, opId, 'archive', 'done');
+    ctx.expectedHash.set(step.file, h2);
+    return { ok: true, opId };
+}
+const readOrNull = (p) => {
+    try {
+        return readFileSync(p);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+};
+// ---------------------------------------------------------------- restore
+export function restoreManifest(ctx, m) {
+    if (m.status === 'restored')
+        return { ok: false, reason: 'It was already restored.' };
+    if (m.method === 'manual' || m.status === 'waiting')
+        return { ok: false, reason: `It was removed by hand. Add it back where it was removed: ${m.manualSteps ?? 'see the manifest'}` };
+    return m.method === 'move' ? restoreMove(ctx, m) : restoreSettings(ctx, m);
+}
+function restoreMove(ctx, m) {
+    const orig = m.originalPath;
+    const payload = m.payloadPath;
+    if (exists(orig))
+        return { ok: false, reason: `Something is already at ${orig}. packlight will not overwrite it; move it aside and restore again.` };
+    const fp = stateOf(payload);
+    if (fp !== m.fingerprint)
+        return { ok: false, reason: `The archived copy at ${payload} no longer matches its record, so it was not restored.` };
+    journalBegin(ctx.paths, {
+        opId: m.opId, direction: 'restore',
+        paths: [
+            { path: orig, kind: 'tree', before: 'missing', after: fp },
+            { path: payload, kind: 'tree', before: fp, after: 'missing' },
+            { path: stagingPathFor(orig), kind: 'tree', before: 'missing', after: 'missing', scratch: true },
+        ],
+    });
+    ctx.crash('restore:after-journal');
+    try {
+        moveTree(payload, orig);
+    }
+    catch (err) {
+        if (err instanceof SourceNotRemoved) {
+            // The item is back and verified; only the archived copy could not be fully deleted.
+            setManifestStatus(ctx.paths, m.opId, 'restored');
+            journalEnd(ctx.paths, m.opId, 'restore', 'done');
+            return { ok: true, opId: m.opId };
+        }
+        journalEnd(ctx.paths, m.opId, 'restore', 'aborted');
+        return { ok: false, reason: `Could not move it back: ${err.message}` };
+    }
+    ctx.crash('restore:after-change');
+    setManifestStatus(ctx.paths, m.opId, 'restored');
+    journalEnd(ctx.paths, m.opId, 'restore', 'done');
+    return { ok: true, opId: m.opId };
+}
+function restoreSettings(ctx, m) {
+    const file = m.settingsFile;
+    const cur = fileHash(file);
+    // Byte-exact restore only (D12): a file edited since the archive is left alone, and the fragment is printed.
+    if (cur !== m.fileHashAfter) {
+        return { ok: false, file, fragment: m.fragment, reason: `${file} has changed since packlight archived this, so packlight did not touch it. Put this back at ${m.jsonPointer} by hand:` };
+    }
+    journalBegin(ctx.paths, { opId: m.opId, direction: 'restore', paths: [{ path: file, kind: 'file', before: cur, after: m.fileHashBefore ?? null }] });
+    ctx.crash('restore:after-journal');
+    if (m.originalFileBase64 === null || m.originalFileBase64 === undefined)
+        rmSync(file, { force: true });
+    else
+        atomicWrite(file, Buffer.from(m.originalFileBase64, 'base64'));
+    ctx.crash('restore:after-change');
+    setManifestStatus(ctx.paths, m.opId, 'restored');
+    journalEnd(ctx.paths, m.opId, 'restore', 'done');
+    return { ok: true, opId: m.opId };
+}

package/dist/archive/paths.d.ts

@@ -0,0 +1,18 @@
+import type { Inventory } from '../core/types.js';
+/** Everything packlight writes lives under <home>/.packlight (acceptance criterion 8). */
+export interface PacklightPaths {
+    home: string;
+    root: string;
+    scans: string;
+    archive: string;
+    journal: string;
+    lock: string;
+    keeps: string;
+    log: string;
+}
+export declare function packlightPaths(home: string, root?: string): PacklightPaths;
+export declare function readScan(paths: PacklightPaths, scanId: string): Inventory | undefined;
+/** Newest scan for one agent and project scope (eng X6 correction to F3). */
+export declare function newestScan(paths: PacklightPaths, agent: string, projectScope: string): Inventory | undefined;
+/** The browser download folder per OS (eng SC1); undefined when it cannot be found. */
+export declare function downloadsDir(home?: string, platform?: NodeJS.Platform): string | undefined;