@skillsmith/core 0.12.2 → 0.12.4

package/dist/src/install/fan-out.leftovers.js

@@ -0,0 +1,251 @@
+/**
+ * SMI-6529: what a crashed or interrupted fan-out refresh leaves next to a
+ * destination, and what may be done about it — the hidden backup, staging and
+ * parked folders, the one case where a stranded backup is restored, and the
+ * warnings the user sees. Split out of fan-out.overwrite.ts in round 16 to
+ * stay under the 500-line gate; it holds the naming helpers both halves share.
+ *
+ * Nothing here deletes anything with content: `rmdir` refuses a folder that
+ * holds anything, and neither a folder's name nor its contents proves who owns
+ * it now (round 14), so everything else is reported and left alone.
+ *
+ * @module @skillsmith/core/install/fan-out.leftovers
+ */
+import * as path from 'node:path';
+import * as fsp from 'node:fs/promises';
+import { PARK_TAG, parkedPattern } from './remove-if-same.js';
+function errorCode(err) {
+    const code = err?.code;
+    return code ?? (err instanceof Error ? err.message : String(err));
+}
+/**
+ * One message for entries a scan could not inspect. Round 25 (cross-model
+ * review): the parent listing succeeding does not mean every entry under it
+ * could be read, and an entry that could not be read is not an entry that
+ * isn't there.
+ */
+function unreadableNote(items, dest) {
+    if (items.length === 0)
+        return undefined;
+    return (`${items.join('; ')}, so anything an interrupted refresh or removal left beside ${dest} ` +
+        `may not be fully reported.`);
+}
+export const BACKUP_TAG = '.skillsmith-backup-';
+export const STAGING_TAG = '.skillsmith-staging-';
+export function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Hidden sibling name prefix for `dest`, e.g. `.foo.skillsmith-backup-`. */
+export function siblingPrefix(dest, tag) {
+    return '.' + path.basename(dest) + tag;
+}
+/** Exact match for a `mkdtemp` folder made from `siblingPrefix(dest, tag)` (6-char suffix). */
+export function siblingPattern(dest, tag) {
+    return new RegExp('^' + escapeRegExp(siblingPrefix(dest, tag)) + '[A-Za-z0-9]{6}$');
+}
+/**
+ * Names `removeIfSame` parks `dest`, or one of its backup or staging folders,
+ * under while removing it (`.<name>.skillsmith-removing-<32 hex>`). Exact, so
+ * a sibling skill's names (`foo.bar` for `foo`) never match.
+ */
+function parkedPatterns(dest) {
+    const park = escapeRegExp(PARK_TAG) + '[0-9a-f]{32}$';
+    return [
+        parkedPattern(dest),
+        ...[BACKUP_TAG, STAGING_TAG].map((tag) => new RegExp('^\\.' + escapeRegExp(siblingPrefix(dest, tag)) + '[A-Za-z0-9]{6}' + park)),
+    ];
+}
+export async function lstatOrNull(p) {
+    try {
+        return await fsp.lstat(p);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/** Whether the link manifest records `dest` as a copy Skillsmith made. */
+export function isRecordedCopy(dest, manifest) {
+    const resolved = path.resolve(dest);
+    return manifest.links.some((link) => link.kind === 'copy' && path.resolve(link.to) === resolved);
+}
+/**
+ * Remove `folder` if it is empty, and say whether it was. `rmdir` refuses a
+ * folder with anything in it, so this can never delete content. Call only
+ * under the destination lock: our own backup folder is briefly empty mid-swap.
+ */
+async function removeIfEmpty(folder) {
+    try {
+        await fsp.rmdir(folder);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Housekeeping under the destination lock, before any write:
+ *  - remove an empty backup folder (a crash before anything was moved in);
+ *  - restore a backup stranded by a crash between the rename-aside and the
+ *    swap: the destination is missing, this is the only backup whose
+ *    `original` is a real directory, and the manifest still records the
+ *    destination as a copy. Backups are only ever made of recorded copies,
+ *    so an unrecorded one has been uninstalled since, and restoring it would
+ *    bring back a stale, untracked copy. With two or more, nothing says which
+ *    is newest (a name can sort anywhere), so none is restored (round 9).
+ *
+ * Any other backup is left in place for `listLeftoverBackups` to report, and
+ * so is a staging folder left by a crashed write: round 14 (cross-model
+ * review) stopped deleting those here, since neither a folder's name nor its
+ * contents proves who owns it now. Returns the backup folders restored from.
+ */
+export async function recoverDestination(dest, manifest) {
+    const parent = path.dirname(dest);
+    let entries;
+    try {
+        entries = await fsp.readdir(parent);
+    }
+    catch (err) {
+        return {
+            restored: [],
+            unreadable: `${parent} could not be listed (${errorCode(err)}), so anything an interrupted refresh ` +
+                `left beside ${dest} was neither recovered nor reported.`,
+        };
+    }
+    const backup = siblingPattern(dest, BACKUP_TAG);
+    const candidates = [];
+    const unreadable = [];
+    for (const name of entries) {
+        const folder = path.join(parent, name);
+        if (!backup.test(name))
+            continue;
+        if (await removeIfEmpty(folder))
+            continue;
+        let originalStat;
+        try {
+            originalStat = await lstatOrNull(path.join(folder, 'original'));
+        }
+        catch (err) {
+            // Round 25 (cross-model review): this swallowed the failure and treated
+            // the folder as "not a candidate", so a backup that could not be read
+            // was silently skipped instead of reported.
+            unreadable.push(`${folder} could not be inspected (${errorCode(err)})`);
+            continue;
+        }
+        if (originalStat?.isDirectory())
+            candidates.push(folder);
+    }
+    const note = unreadableNote(unreadable, dest);
+    const folder = candidates.length === 1 ? candidates[0] : undefined;
+    if (folder === undefined || !isRecordedCopy(dest, manifest)) {
+        return { restored: [], unreadable: note };
+    }
+    // Round 19 (Opus): this check sits immediately before the rename below,
+    // which is as narrow as Node allows — there is no atomic no-clobber rename
+    // for a directory — so an entry created inside that window would be
+    // replaced (measured: an empty directory). Not restoring at all would lose
+    // the crash recovery this exists for, so the window is accepted and stated.
+    if ((await lstatOrNull(dest)) !== null)
+        return { restored: [], unreadable: note };
+    await fsp.rename(path.join(folder, 'original'), dest);
+    await fsp.rmdir(folder).catch(() => { });
+    return { restored: [folder], unreadable: note };
+}
+/**
+ * Backup folders for `dest` that are still present: copies an interrupted
+ * refresh left behind (after the swap, or unrestorable). Round 7: these are
+ * reported to the user rather than kept silently or deleted. Round 8: an
+ * empty one holds nothing to report and is removed. Round 9: on a volume
+ * that ignores case, a backup made under another spelling of the name
+ * (`.Foo.` for `foo`) belongs to this destination too, so it is reported;
+ * it is never removed or restored, since on a case-sensitive volume the
+ * same name belongs to a different destination. Round 14: a staging folder
+ * left by a crashed write is reported the same way. Round 15: so is what a
+ * crashed or failed removal left under a parked name. Call under the lock.
+ */
+export async function listLeftoverBackups(dest) {
+    const parent = path.dirname(dest);
+    let entries;
+    try {
+        entries = await fsp.readdir(parent);
+    }
+    catch (err) {
+        return {
+            folders: [],
+            unreadable: `${parent} could not be listed (${errorCode(err)}), so anything an interrupted refresh ` +
+                `or removal left beside ${dest} is not reported here.`,
+        };
+    }
+    const exact = siblingPattern(dest, BACKUP_TAG);
+    const staging = siblingPattern(dest, STAGING_TAG);
+    const parked = parkedPatterns(dest);
+    const anyCase = new RegExp(exact.source, 'i');
+    const leftovers = [];
+    const unreadable = [];
+    for (const name of entries) {
+        const folder = path.join(parent, name);
+        if (exact.test(name) || staging.test(name) || parked.some((p) => p.test(name))) {
+            if (!(await removeIfEmpty(folder)))
+                leftovers.push(folder);
+        }
+        else if (anyCase.test(name)) {
+            const variant = await isCaseVariantOf(folder, dest);
+            if ('unreadable' in variant)
+                unreadable.push(variant.unreadable);
+            else if (variant.variant)
+                leftovers.push(folder);
+        }
+    }
+    return { folders: leftovers, unreadable: unreadableNote(unreadable, dest) };
+}
+/**
+ * Whether backup `folder` (named for another spelling of `dest`) is, on this
+ * volume, the same entry as the name spelled for `dest`, and holds content.
+ * On a case-sensitive volume that name doesn't exist, or is a different entry.
+ */
+async function isCaseVariantOf(folder, dest) {
+    const suffix = path.basename(folder).slice(-6);
+    const ownName = path.join(path.dirname(dest), siblingPrefix(dest, BACKUP_TAG) + suffix);
+    // Round 25 (cross-model review): both of these swallowed a failed inspection
+    // and answered "not a variant", and the read below answered "empty", so a
+    // folder that could not be read was reported as nothing at all.
+    let a;
+    let b;
+    try {
+        ;
+        [a, b] = await Promise.all([lstatOrNull(folder), lstatOrNull(ownName)]);
+    }
+    catch (err) {
+        return { unreadable: `${folder} could not be inspected (${errorCode(err)})` };
+    }
+    if (a === null || b === null || a.dev !== b.dev || a.ino !== b.ino)
+        return { variant: false };
+    let contents;
+    try {
+        contents = await fsp.readdir(folder);
+    }
+    catch (err) {
+        return { unreadable: `${folder} could not be listed (${errorCode(err)})` };
+    }
+    return { variant: contents.length > 0 };
+}
+/** User-facing warning for a leftover backup, staging folder or parked entry. */
+export function leftoverBackupWarning(folder) {
+    const name = path.basename(folder);
+    if (name.includes(PARK_TAG)) {
+        // Round 18: who owns a parked entry is not known — see parkedLeftoverWarning.
+        return (`an interrupted removal moved something aside to the hidden path ${folder} and did not ` +
+            `finish. It may be part of this skill's copy, or something another program put there. ` +
+            `Check it, then restore or delete it yourself.`);
+    }
+    // Round 23 (Opus): this used to call the contents "an earlier copy" of the
+    // skill. That is an ownership claim it cannot make — the move-aside window
+    // can displace another program's entry into this folder — and it is the same
+    // claim the parked wording above dropped.
+    const what = name.includes(STAGING_TAG) ? 'a partial copy' : 'a copy';
+    return (`an interrupted refresh left ${what} in the hidden folder ${folder}. It is either what this ` +
+        `skill replaced, or something another program put at the path while the refresh was moving ` +
+        `the old copy aside. Check it, then restore or delete it yourself.`);
+}
+//# sourceMappingURL=fan-out.leftovers.js.map

package/dist/src/install/fan-out.leftovers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.leftovers.js","sourceRoot":"","sources":["../../../src/install/fan-out.leftovers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAA;AAGvC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAe7D,SAAS,SAAS,CAAC,GAAY;IAC7B,MAAM,IAAI,GAAI,GAA6B,EAAE,IAAI,CAAA;IACjD,OAAO,IAAI,IAAI,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;AACnE,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CAAC,KAAe,EAAE,IAAY;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IACxC,OAAO,CACL,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,+DAA+D,IAAI,GAAG;QACzF,4BAA4B,CAC7B,CAAA;AACH,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,qBAAqB,CAAA;AAC/C,MAAM,CAAC,MAAM,WAAW,GAAG,sBAAsB,CAAA;AAEjD,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,OAAO,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAA;AACjD,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,GAAW;IACrD,OAAO,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,CAAA;AACxC,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,GAAW;IACtD,OAAO,IAAI,MAAM,CAAC,GAAG,GAAG,YAAY,CAAC,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAA;AACrF,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,IAAY;IAClC,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,GAAG,eAAe,CAAA;IACrD,OAAO;QACL,aAAa,CAAC,IAAI,CAAC;QACnB,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,GAAG,CAC9B,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,YAAY,CAAC,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,GAAG,gBAAgB,GAAG,IAAI,CAAC,CAC/F;KACF,CAAA;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,CAAS;IACzC,IAAI,CAAC;QACH,OAAO,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QACjE,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,QAAsB;IACjE,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACnC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC,CAAA;AAClG,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,aAAa,CAAC,MAAc;IACzC,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QACvB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAY,EACZ,QAAsB;IAEtB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,IAAI,OAAiB,CAAA;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,QAAQ,EAAE,EAAE;YACZ,UAAU,EACR,GAAG,MAAM,yBAAyB,SAAS,CAAC,GAAG,CAAC,wCAAwC;gBACxF,eAAe,IAAI,sCAAsC;SAC5D,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IAC/C,MAAM,UAAU,GAAa,EAAE,CAAA;IAC/B,MAAM,UAAU,GAAa,EAAE,CAAA;IAC/B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QACtC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,SAAQ;QAChC,IAAI,MAAM,aAAa,CAAC,MAAM,CAAC;YAAE,SAAQ;QACzC,IAAI,YAA0B,CAAA;QAC9B,IAAI,CAAC;YACH,YAAY,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAA;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,wEAAwE;YACxE,sEAAsE;YACtE,4CAA4C;YAC5C,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,4BAA4B,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YACvE,SAAQ;QACV,CAAC;QACD,IAAI,YAAY,EAAE,WAAW,EAAE;YAAE,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC1D,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;IAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IAClE,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;QAC5D,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAA;IAC3C,CAAC;IACD,wEAAwE;IACxE,2EAA2E;IAC3E,oEAAoE;IACpE,2EAA2E;IAC3E,4EAA4E;IAC5E,IAAI,CAAC,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI;QAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAA;IACjF,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,IAAI,CAAC,CAAA;IACrD,MAAM,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IACvC,OAAO,EAAE,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAA;AACjD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,IAAY;IACpD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACjC,IAAI,OAAiB,CAAA;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACrC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,EAAE;YACX,UAAU,EACR,GAAG,MAAM,yBAAyB,SAAS,CAAC,GAAG,CAAC,wCAAwC;gBACxF,0BAA0B,IAAI,wBAAwB;SACzD,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IAC9C,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;IACjD,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IACnC,MAAM,OAAO,GAAG,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC7C,MAAM,SAAS,GAAa,EAAE,CAAA;IAC9B,MAAM,UAAU,GAAa,EAAE,CAAA;IAC/B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;QACtC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAC/E,IAAI,CAAC,CAAC,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;gBAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5D,CAAC;aAAM,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;YACnD,IAAI,YAAY,IAAI,OAAO;gBAAE,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;iBAC3D,IAAI,OAAO,CAAC,OAAO;gBAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAClD,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC,EAAE,CAAA;AAC7E,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,eAAe,CAC5B,MAAc,EACd,IAAY;IAEZ,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,MAAM,CAAC,CAAA;IACvF,6EAA6E;IAC7E,0EAA0E;IAC1E,gEAAgE;IAChE,IAAI,CAAe,CAAA;IACnB,IAAI,CAAe,CAAA;IACnB,IAAI,CAAC;QACH,CAAC;QAAA,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IAC1E,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,4BAA4B,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAA;IAC/E,CAAC;IACD,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;IAC7F,IAAI,QAAkB,CAAA;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,yBAAyB,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAA;IAC5E,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAA;AACzC,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAClC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,8EAA8E;QAC9E,OAAO,CACL,mEAAmE,MAAM,eAAe;YACxF,uFAAuF;YACvF,+CAA+C,CAChD,CAAA;IACH,CAAC;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,6EAA6E;IAC7E,0CAA0C;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,QAAQ,CAAA;IACrE,OAAO,CACL,+BAA+B,IAAI,yBAAyB,MAAM,2BAA2B;QAC7F,4FAA4F;QAC5F,mEAAmE,CACpE,CAAA;AACH,CAAC"}

package/dist/src/install/fan-out.locks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Run `fn` holding the cross-process file lock `<target>.lock`, waiting
+ * without blocking the event loop. Callers in one process contend on it too.
+ */
+export declare function withFileLock<T>(target: string, label: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Run `fn` holding the lock for `dest`: first queue behind any other call
+ * for the same destination in this process, then take the cross-process
+ * file lock `.<name>.skillsmith-fanout.lock` next to it.
+ */
+export declare function withDestinationLock<T>(dest: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=fan-out.locks.d.ts.map

package/dist/src/install/fan-out.locks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.locks.d.ts","sourceRoot":"","sources":["../../../src/install/fan-out.locks.ts"],"names":[],"mappings":"AA4EA;;;GAGG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAmB3F"}

package/dist/src/install/fan-out.locks.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview The per-destination locking used by every fan-out write: an
+ *   in-process queue so same-process callers serialize, and a cross-process
+ *   file lock taken without ever blocking the event loop.
+ * @module @skillsmith/core/install/fan-out.locks
+ *
+ * Split out of `fan-out.overwrite.ts` in SMI-6529 round 27, when that file
+ * reached 505 lines against the 500-line standard — the same sibling-split
+ * convention `fan-out.leftovers.ts` already follows. `fan-out.overwrite.ts`
+ * re-exports both entry points, so existing importers are unchanged.
+ */
+import * as path from 'node:path';
+import * as fsp from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { acquireOwnedLock, StuckLockError } from '../config/owned-lock.js';
+import { siblingPrefix } from './fan-out.leftovers.js';
+const LOCK_TAG = '.skillsmith-fanout';
+/** How long to wait for another process's lock on the same destination (ms). */
+const DESTINATION_LOCK_TIMEOUT_MS = 30_000;
+/** Pause between attempts while another process holds the lock (ms). */
+const DESTINATION_LOCK_POLL_MS = 50;
+/**
+ * Refusals that end on their own, so they are waited out: a live holder, a
+ * busy reclaim lock, and a holder we may not reclaim because auto-reclaim is
+ * off (it still ends when that holder releases). An unparseable or legacy
+ * claim never goes away by itself, so it fails at once.
+ */
+const RETRYABLE_REASONS = new Set([
+    'held',
+    'reclaim_unavailable',
+    'reclaim_disabled',
+]);
+// Same-process callers for one destination queue here, so only one of them
+// holds the file lock at a time; the file lock arbitrates between processes.
+const inProcessQueue = new Map();
+/**
+ * Queue key for `dest`: its parent's real path plus its name, so a symlinked
+ * spelling of the same folder shares one queue (round 7). A case-only variant
+ * on a case-insensitive volume still gets its own key, but it then only waits
+ * asynchronously on the shared file lock below, never blocking.
+ */
+async function queueKey(dest) {
+    const parent = path.dirname(path.resolve(dest));
+    const realParent = await fsp.realpath(parent).catch(() => parent);
+    return path.join(realParent, path.basename(dest));
+}
+/**
+ * Take the cross-process file lock without ever blocking the event loop.
+ * `acquireOwnedLock` normally waits with a synchronous sleep, which froze a
+ * whole MCP server for up to 10 s (round 7). Here each attempt is one
+ * non-waiting try (`timeoutMs: 0`) that still reclaims a dead holder's lock
+ * at once (`reclaimProbeAfterMs: 0`) and never waits on the reclaim lock
+ * either (`reclaimLockTimeoutMs: 0`, round 8). Between attempts we await.
+ */
+async function acquireFileLock(target, label) {
+    const deadline = Date.now() + DESTINATION_LOCK_TIMEOUT_MS;
+    for (;;) {
+        try {
+            return acquireOwnedLock(target, {
+                timeoutMs: 0,
+                reclaimProbeAfterMs: 0,
+                reclaimLockTimeoutMs: 0,
+                label,
+            });
+        }
+        catch (err) {
+            const retryable = err instanceof StuckLockError && RETRYABLE_REASONS.has(err.reason);
+            if (!retryable || Date.now() >= deadline)
+                throw err;
+            await delay(DESTINATION_LOCK_POLL_MS);
+        }
+    }
+}
+/**
+ * Run `fn` holding the cross-process file lock `<target>.lock`, waiting
+ * without blocking the event loop. Callers in one process contend on it too.
+ */
+export async function withFileLock(target, label, fn) {
+    const release = await acquireFileLock(target, label);
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Run `fn` holding the lock for `dest`: first queue behind any other call
+ * for the same destination in this process, then take the cross-process
+ * file lock `.<name>.skillsmith-fanout.lock` next to it.
+ */
+export async function withDestinationLock(dest, fn) {
+    const key = await queueKey(dest);
+    const previous = inProcessQueue.get(key) ?? Promise.resolve();
+    let releaseQueue = () => { };
+    const mine = new Promise((resolve) => {
+        releaseQueue = resolve;
+    });
+    const tail = previous.then(() => mine);
+    inProcessQueue.set(key, tail);
+    await previous;
+    try {
+        const parent = path.dirname(dest);
+        await fsp.mkdir(parent, { recursive: true });
+        const lockTarget = path.join(parent, siblingPrefix(dest, LOCK_TAG));
+        return await withFileLock(lockTarget, 'fan-out destination lock', fn);
+    }
+    finally {
+        releaseQueue();
+        if (inProcessQueue.get(key) === tail)
+            inProcessQueue.delete(key);
+    }
+}
+//# sourceMappingURL=fan-out.locks.js.map

package/dist/src/install/fan-out.locks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.locks.js","sourceRoot":"","sources":["../../../src/install/fan-out.locks.ts"],"names":[],"mappings":"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"}

package/dist/src/install/fan-out.manifest.d.ts

@@ -0,0 +1,64 @@
+/** How a fan-out destination was made: a relative symlink, or a recursive copy. */
+export type LinkKind = 'symlink' | 'copy';
+/** One fan-out Skillsmith made: which skill, from where, to where, how, and when. */
+export interface LinkRecord {
+    skillId: string;
+    from: string;
+    to: string;
+    kind: LinkKind;
+    createdAt: string;
+}
+/** The on-disk link manifest: every fan-out Skillsmith has recorded. */
+export interface LinkManifest {
+    version: 1;
+    links: LinkRecord[];
+}
+/**
+ * Resolve the manifest file path. Sits under `~/.skillsmith/` so it shares
+ * the existing allow-list entry for that directory (DEFAULT_ALLOWED_DIRS in
+ * `pathValidation.ts`).
+ */
+export declare function getLinkManifestPath(): string;
+/** What reading the manifest found. `unreadable` means it exists but must not be written over. */
+export interface ManifestRead {
+    state: 'ok' | 'missing' | 'corrupt' | 'unreadable';
+    manifest: LinkManifest;
+    reason?: string;
+}
+/**
+ * Read the manifest and report its state. Valid JSON with a higher version is
+ * `unreadable`, not `corrupt`: a newer Skillsmith wrote it, and moving it
+ * aside would drop its records too (SMI-6529 round 10).
+ */
+export declare function readManifestFile(): Promise<ManifestRead>;
+/** Error for a manifest that exists but can't be read; nothing is written over it. */
+export declare function unreadableManifestError(reason: string | undefined): Error;
+/**
+ * Load the manifest for reading. Returns an empty manifest if the file is
+ * missing, unreadable or corrupt — fan-out is best-effort, never crash on
+ * cold start. Changes go through {@link updateManifest}, which never
+ * overwrites a file it couldn't read.
+ */
+export declare function loadManifest(): Promise<LinkManifest>;
+/**
+ * Apply `change` to the manifest and save it, under the manifest's own lock.
+ * Returns a warning for the user, if any.
+ *
+ * SMI-6529 round 9: destination locks only serialize calls for one
+ * destination, so fan-outs of different skills loaded, changed and saved the
+ * manifest at the same time, through one shared temp file; twelve concurrent
+ * fan-outs kept one record, and could leave the file corrupt. Callers may
+ * hold a destination lock when they call this, but no destination lock is
+ * ever requested while this lock is held, so the two can't deadlock.
+ *
+ * A corrupt file used to be replaced with an empty manifest, dropping every
+ * other skill's record. It is now moved aside, with a warning; a file that
+ * can't be read at all is left alone and the call fails.
+ */
+export declare function updateManifest(change: (manifest: LinkManifest) => void): Promise<string | undefined>;
+/**
+ * Persist the manifest atomically (write-temp + rename) so a crash mid-write
+ * never leaves the file in a partial state.
+ */
+export declare function saveManifest(manifest: LinkManifest): Promise<void>;
+//# sourceMappingURL=fan-out.manifest.d.ts.map

package/dist/src/install/fan-out.manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.manifest.d.ts","sourceRoot":"","sources":["../../../src/install/fan-out.manifest.ts"],"names":[],"mappings":"AAiBA,mFAAmF;AACnF,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;AAEzC,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,QAAQ,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAA;IACV,KAAK,EAAE,UAAU,EAAE,CAAA;CACpB;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,IAAI,GAAG,SAAS,GAAG,SAAS,GAAG,YAAY,CAAA;IAClD,QAAQ,EAAE,YAAY,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,CAAC,CA4B9D;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,CAKzE;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,YAAY,CAAC,CAE1D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,GACvC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmB7B;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAYxE"}

package/dist/src/install/fan-out.manifest.js

@@ -0,0 +1,130 @@
+/**
+ * SMI-4578 / SMI-6529: the fan-out link manifest
+ * (`~/.skillsmith/links/manifest.json`), split out of fan-out.ts to stay
+ * under the 500-line gate.
+ *
+ * Reads are best-effort. Every change goes through {@link updateManifest},
+ * which takes the manifest's own lock and never overwrites a file it couldn't
+ * read.
+ *
+ * @module @skillsmith/core/install/fan-out.manifest
+ */
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+import * as fsp from 'node:fs/promises';
+import { assertNotRealUserHome } from '../services/skill-manifest.js';
+import { withFileLock } from './fan-out.overwrite.js';
+const MANIFEST_VERSION = 1;
+/**
+ * Resolve the manifest file path. Sits under `~/.skillsmith/` so it shares
+ * the existing allow-list entry for that directory (DEFAULT_ALLOWED_DIRS in
+ * `pathValidation.ts`).
+ */
+export function getLinkManifestPath() {
+    return path.join(homedir(), '.skillsmith', 'links', 'manifest.json');
+}
+/**
+ * Read the manifest and report its state. Valid JSON with a higher version is
+ * `unreadable`, not `corrupt`: a newer Skillsmith wrote it, and moving it
+ * aside would drop its records too (SMI-6529 round 10).
+ */
+export async function readManifestFile() {
+    const empty = { version: MANIFEST_VERSION, links: [] };
+    let raw;
+    try {
+        raw = await fsp.readFile(getLinkManifestPath(), 'utf-8');
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return { state: 'missing', manifest: empty };
+        return { state: 'unreadable', manifest: empty, reason: code ?? String(err) };
+    }
+    try {
+        // Round 11: a byte-order mark some editors add isn't corruption.
+        const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+        const parsed = JSON.parse(text);
+        if (parsed?.version === MANIFEST_VERSION && Array.isArray(parsed.links)) {
+            return { state: 'ok', manifest: parsed };
+        }
+        if (typeof parsed?.version === 'number' && parsed.version > MANIFEST_VERSION) {
+            return {
+                state: 'unreadable',
+                manifest: empty,
+                reason: `version ${parsed.version}, written by a newer Skillsmith`,
+            };
+        }
+    }
+    catch {
+        // Not JSON: reported as corrupt below.
+    }
+    return { state: 'corrupt', manifest: empty };
+}
+/** Error for a manifest that exists but can't be read; nothing is written over it. */
+export function unreadableManifestError(reason) {
+    return new Error(`could not read the fan-out link manifest at ${getLinkManifestPath()} (${reason}); ` +
+        `refusing to overwrite it.`);
+}
+/**
+ * Load the manifest for reading. Returns an empty manifest if the file is
+ * missing, unreadable or corrupt — fan-out is best-effort, never crash on
+ * cold start. Changes go through {@link updateManifest}, which never
+ * overwrites a file it couldn't read.
+ */
+export async function loadManifest() {
+    return (await readManifestFile()).manifest;
+}
+/**
+ * Apply `change` to the manifest and save it, under the manifest's own lock.
+ * Returns a warning for the user, if any.
+ *
+ * SMI-6529 round 9: destination locks only serialize calls for one
+ * destination, so fan-outs of different skills loaded, changed and saved the
+ * manifest at the same time, through one shared temp file; twelve concurrent
+ * fan-outs kept one record, and could leave the file corrupt. Callers may
+ * hold a destination lock when they call this, but no destination lock is
+ * ever requested while this lock is held, so the two can't deadlock.
+ *
+ * A corrupt file used to be replaced with an empty manifest, dropping every
+ * other skill's record. It is now moved aside, with a warning; a file that
+ * can't be read at all is left alone and the call fails.
+ */
+export async function updateManifest(change) {
+    const manifestPath = getLinkManifestPath();
+    assertNotRealUserHome(manifestPath, 'write');
+    await fsp.mkdir(path.dirname(manifestPath), { recursive: true });
+    return withFileLock(manifestPath, 'fan-out link manifest lock', async () => {
+        const read = await readManifestFile();
+        if (read.state === 'unreadable')
+            throw unreadableManifestError(read.reason);
+        let warning;
+        if (read.state === 'corrupt') {
+            const aside = `${manifestPath}.corrupt-${Date.now()}`;
+            await fsp.rename(manifestPath, aside);
+            warning =
+                `the fan-out link manifest at ${manifestPath} could not be parsed; it was moved to ` +
+                    `${aside} and a new one started. Copies recorded only in the old file are no longer tracked.`;
+        }
+        change(read.manifest);
+        await saveManifest(read.manifest);
+        return warning;
+    });
+}
+/**
+ * Persist the manifest atomically (write-temp + rename) so a crash mid-write
+ * never leaves the file in a partial state.
+ */
+export async function saveManifest(manifest) {
+    const manifestPath = getLinkManifestPath();
+    // SMI-6343 follow-up (adversarial review): a fourth parallel manifest-write
+    // implementation (a different file, `links/manifest.json`, but the same
+    // homedir-derived-with-no-override shape). The $HOME sandbox
+    // (vitest.setup.ts) was this file's only defense until this guard.
+    assertNotRealUserHome(manifestPath, 'write');
+    const dir = path.dirname(manifestPath);
+    await fsp.mkdir(dir, { recursive: true });
+    const tmp = `${manifestPath}.${process.pid}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(manifest, null, 2), 'utf-8');
+    await fsp.rename(tmp, manifestPath);
+}
+//# sourceMappingURL=fan-out.manifest.js.map

package/dist/src/install/fan-out.manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.manifest.js","sourceRoot":"","sources":["../../../src/install/fan-out.manifest.ts"],"names":[],"mappings":"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"}