pi-session-mcp 0.8.0 → 0.8.1

package/dist/skill-customize.js

@@ -1,18 +1,24 @@
 import { randomBytes } from "node:crypto";
 import { constants } from "node:fs";
-import { lstat, mkdir, open, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { lstat, mkdir, open, readFile, rename, rm, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { acquireOverrideLock, OverrideLockError } from "./override-lock.js";
 import { result } from "./setup-result.js";
-import { readSkillTree, shippedSkillsDirectory, SKILL_NAME_PATTERN, SkillTreeError, skillOverrideDirectory } from "./skill-library.js";
+import { LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, readSkillTree, releasedSkillFingerprint, shippedSkillsDirectory, SKILL_NAME_PATTERN, SKILL_TREE_FINGERPRINT_PATTERN, SkillTreeError, skillOverrideDirectory, } from "./skill-library.js";
 /**
  * `--customize-skill <name>`: copies a shipped skill into the operator's override directory as a
  * starting point, and records the shipped fingerprint it was based on. The operator's files are
  * never overwritten or edited; a changed original is only reported and acknowledged by moving
  * the recorded base. Reports carry the skill name and a code, never a path or file content.
+ *
+ * Applying is a cross-process transaction: everything from reading the bases file to replacing it
+ * runs under the kernel lock of `override-lock.ts`, so two runs for different skills cannot lose
+ * each other's base. A dry run takes no lock and writes nothing.
  */
 export const SKILL_BASES_FILE = ".pi-session-mcp-bases.json";
 export const MAX_SKILL_BASES_BYTES = 64 * 1024;
-const FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+/** Written by this version; version 1 (0.8.0) holds only legacy fingerprints and is still read. */
+const BASES_SCHEMA_VERSION = 2;
 export class SkillBasesError extends Error {
     constructor() {
         super("Skill bases file is not usable");
@@ -46,13 +52,17 @@ export async function readSkillBases(overrideDirectory) {
     catch {
         throw new SkillBasesError();
     }
-    if (!isPlainObject(parsed) || Object.keys(parsed).sort().join() !== "bases,schemaVersion" || parsed.schemaVersion !== 1)
+    if (!isPlainObject(parsed) || Object.keys(parsed).sort().join() !== "bases,schemaVersion")
+        throw new SkillBasesError();
+    const version = parsed.schemaVersion;
+    if (version !== 1 && version !== BASES_SCHEMA_VERSION)
         throw new SkillBasesError();
     const bases = parsed.bases;
     if (!isPlainObject(bases))
         throw new SkillBasesError();
     const entries = Object.entries(bases);
-    if (!entries.every(([name, value]) => SKILL_NAME_PATTERN.test(name) && typeof value === "string" && FINGERPRINT_PATTERN.test(value)))
+    const validValue = (value) => typeof value === "string" && (LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(value) || (version === BASES_SCHEMA_VERSION && SKILL_TREE_FINGERPRINT_PATTERN.test(value)));
+    if (!entries.every(([name, value]) => SKILL_NAME_PATTERN.test(name) && validValue(value)))
         throw new SkillBasesError();
     return Object.freeze(Object.fromEntries(entries));
 }
@@ -62,10 +72,25 @@ function isPlainObject(value) {
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
-/** Atomic replacement: a private temporary file in the same directory, then a rename. */
-async function writeSkillBases(overrideDirectory, bases) {
-    const sorted = Object.fromEntries(Object.entries(bases).sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
-    const content = Buffer.from(`${JSON.stringify({ schemaVersion: 1, bases: sorted })}\n`, "utf8");
+async function syncDirectory(path) {
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Atomic replacement: a private temporary file in the same directory, fsynced, then a rename and a
+ * directory fsync. Every provable legacy entry is migrated to its version 2 value on the way; an
+ * entry that no released tree names stays verbatim. A failure before the rename leaves the
+ * previous file untouched.
+ */
+async function writeSkillBases(overrideDirectory, bases, released, beforeRename) {
+    const migrated = Object.entries(bases).map(([name, value]) => [name, LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(value) ? releasedSkillFingerprint(name, value, released) ?? value : value]);
+    const sorted = Object.fromEntries(migrated.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
+    const content = Buffer.from(`${JSON.stringify({ schemaVersion: BASES_SCHEMA_VERSION, bases: sorted })}\n`, "utf8");
     if (content.length > MAX_SKILL_BASES_BYTES)
         throw new SkillBasesError();
     const temporary = join(overrideDirectory, `.${SKILL_BASES_FILE.slice(1)}.${randomBytes(6).toString("hex")}.tmp`);
@@ -78,12 +103,14 @@ async function writeSkillBases(overrideDirectory, bases) {
         finally {
             await handle.close();
         }
+        await beforeRename?.();
         await rename(temporary, join(overrideDirectory, SKILL_BASES_FILE));
     }
     catch (error) {
         await unlink(temporary).catch(() => undefined);
         throw error;
     }
+    await syncDirectory(overrideDirectory);
 }
 function isMissing(error) {
     return typeof error === "object" && error !== null && error.code === "ENOENT";
@@ -96,7 +123,40 @@ function report(request, status, code) {
     // A planned change reports `planned` overall, like a registration dry-run.
     return result(request.apply ? "apply" : "dry-run", [finding], status === "planned" ? "planned" : undefined);
 }
-export async function customizeSkill(request) {
+const OUTDATED = Object.freeze({ kind: "record", planned: "skill_override_outdated", applied: "skill_base_updated" });
+/** Pure with respect to the library: reads the override tree, never changes anything. */
+async function decide(name, overridePath, shipped, bases, released) {
+    try {
+        if (!(await lstat(overridePath)).isDirectory())
+            return { kind: "failed", code: "skill_override_invalid" };
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        return { kind: "copy", planned: "skill_customize_planned", applied: "skill_customized" };
+    }
+    let override;
+    try {
+        override = await readSkillTree(overridePath);
+    }
+    catch (error) {
+        if (error instanceof SkillTreeError)
+            return { kind: "failed", code: "skill_override_invalid" };
+        throw error;
+    }
+    const base = Object.hasOwn(bases, name) ? bases[name] : undefined;
+    // Without a base an identical override is a customization whose bases commit failed earlier.
+    if (base === undefined)
+        return override.fingerprint === shipped.fingerprint ? { kind: "record", planned: "skill_customize_planned", applied: "skill_customized" } : OUTDATED;
+    if (SKILL_TREE_FINGERPRINT_PATTERN.test(base))
+        return base === shipped.fingerprint ? { kind: "current" } : OUTDATED;
+    // A legacy base only names a released original when a trusted reference tree has that value.
+    const original = releasedSkillFingerprint(name, base, released);
+    if (original === undefined)
+        return { kind: "record", planned: "skill_base_unverified", applied: "skill_base_updated" };
+    return original === shipped.fingerprint ? { kind: "record", planned: "skill_base_migration_planned", applied: "skill_base_migrated" } : OUTDATED;
+}
+export async function customizeSkill(request, dependencies = {}) {
     const done = (status, code) => report(request, status, code);
     if (!SKILL_NAME_PATTERN.test(request.name))
         return done("failed", "skill_not_shipped");
@@ -112,69 +172,94 @@ export async function customizeSkill(request) {
             return done("failed", "skill_customize_failed");
         }
         const overrideDirectory = skillOverrideDirectory(request.configPath);
-        let bases;
-        try {
-            bases = await readSkillBases(overrideDirectory);
-        }
-        catch (error) {
-            if (error instanceof SkillBasesError)
+        const overridePath = join(overrideDirectory, request.name);
+        const read = async () => {
+            try {
+                return await readSkillBases(overrideDirectory);
+            }
+            catch (error) {
+                if (error instanceof SkillBasesError)
+                    return undefined;
+                throw error;
+            }
+        };
+        if (!request.apply) {
+            // No lock and no write: the report is a snapshot of what an apply would decide.
+            const bases = await read();
+            if (bases === undefined)
                 return done("failed", "skill_bases_corrupt");
-            throw error;
+            const decision = await decide(request.name, overridePath, shipped, bases, dependencies.released);
+            if (decision.kind === "failed")
+                return done("failed", decision.code);
+            return decision.kind === "current" ? done("unchanged", "skill_override_current") : done("planned", decision.planned);
         }
-        const overridePath = join(overrideDirectory, request.name);
-        let exists = true;
+        await mkdir(overrideDirectory, { recursive: true, mode: 0o700 });
+        let lock;
         try {
-            const info = await lstat(overridePath);
-            if (!info.isDirectory())
-                return done("failed", "skill_override_invalid");
+            lock = await acquireOverrideLock(overrideDirectory, dependencies.lock);
         }
         catch (error) {
-            if (!isMissing(error))
-                throw error;
-            exists = false;
-        }
-        if (!exists) {
-            if (!request.apply)
-                return done("planned", "skill_customize_planned");
-            await copyShippedSkill(shipped.files, overrideDirectory, overridePath, request.name);
-            await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint });
-            return done("ok", "skill_customized");
+            if (error instanceof OverrideLockError)
+                return done("failed", error.code === "override_lock_busy" ? "skill_customize_lock_busy" : "skill_customize_lock_unavailable");
+            throw error;
         }
         try {
-            await readSkillTree(overridePath);
+            await dependencies.afterLock?.();
+            // Read only now: a snapshot from before the lock may miss a base another run just wrote.
+            const bases = await read();
+            if (bases === undefined)
+                return done("failed", "skill_bases_corrupt");
+            const decision = await decide(request.name, overridePath, shipped, bases, dependencies.released);
+            if (decision.kind === "failed")
+                return done("failed", decision.code);
+            if (decision.kind === "current")
+                return done("unchanged", "skill_override_current");
+            if (decision.kind === "copy")
+                await copyShippedSkill(shipped.files, overrideDirectory, overridePath, request.name);
+            await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint }, dependencies.released, dependencies.beforeBasesRename);
+            return done("ok", decision.applied);
         }
-        catch (error) {
-            if (error instanceof SkillTreeError)
-                return done("failed", "skill_override_invalid");
-            throw error;
+        finally {
+            await lock.release();
         }
-        if (bases[request.name] === shipped.fingerprint)
-            return done("unchanged", "skill_override_current");
-        if (!request.apply)
-            return done("planned", "skill_override_outdated");
-        // Only the recorded base moves: it acknowledges that the operator reviewed the changed original.
-        await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint });
-        return done("ok", "skill_base_updated");
     }
     catch {
         return done("failed", "skill_customize_failed");
     }
 }
 async function copyShippedSkill(files, overrideDirectory, overridePath, name) {
-    await mkdir(overrideDirectory, { recursive: true, mode: 0o700 });
     const temporary = join(overrideDirectory, `.${name}.${randomBytes(6).toString("hex")}.tmp`);
     try {
         await mkdir(temporary, { mode: 0o755 });
         for (const file of files) {
             const destination = join(temporary, ...file.path.split("/"));
             await mkdir(dirname(destination), { recursive: true });
-            await writeFile(destination, file.bytes, { flag: "wx", mode: 0o644 });
+            const handle = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
+            try {
+                await handle.writeFile(file.bytes);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        // Every directory entry of the temporary tree is durable before the rename and the bases commit.
+        const directories = new Set([temporary]);
+        for (const file of files) {
+            let cursor = dirname(join(temporary, ...file.path.split("/")));
+            while (cursor !== temporary) {
+                directories.add(cursor);
+                cursor = dirname(cursor);
+            }
         }
+        for (const directory of [...directories].sort((left, right) => right.length - left.length))
+            await syncDirectory(directory);
         // The override must not appear while the copy runs, and an operator's directory is never replaced.
         if (await lstat(overridePath).then(() => true, (error) => { if (isMissing(error))
             return false; throw error; }))
             throw new Error("override appeared");
         await rename(temporary, overridePath);
+        await syncDirectory(overrideDirectory);
     }
     catch (error) {
         await rm(temporary, { recursive: true, force: true }).catch(() => undefined);

package/dist/skill-library.d.ts

@@ -37,13 +37,58 @@ export interface SkillTreeFile {
 }
 export interface SkillTree {
     readonly files: readonly SkillTreeFile[];
-    /** SHA-256 hex over the sorted relative paths and contents; path-free and stable. */
+    /** Version 2 fingerprint (`v2:` and SHA-256 hex) of the paths and contents; path-free and stable. */
     readonly fingerprint: string;
+    /**
+     * The version 1 fingerprint that 0.8.0 recorded, only to recognize such records. It is
+     * ambiguous and never proves identity on its own; see `provesLegacyFingerprint`.
+     */
+    readonly legacyFingerprint: string;
 }
 export declare class SkillTreeError extends Error {
     readonly code: "skill_tree_missing" | "skill_tree_invalid" | "skill_tree_too_large";
     constructor(code: "skill_tree_missing" | "skill_tree_invalid" | "skill_tree_too_large");
 }
+/** A version 2 skill tree fingerprint as it is stored. */
+export declare const SKILL_TREE_FINGERPRINT_PATTERN: RegExp;
+/** A version 1 fingerprint as 0.8.0 stored it: bare SHA-256 hex. */
+export declare const LEGACY_SKILL_TREE_FINGERPRINT_PATTERN: RegExp;
+/**
+ * Version 2: a domain and version tag, the file count, then per file in byte order of the path
+ * the length-prefixed UTF-8 path and the length-prefixed content. Every field has an explicit
+ * length, so two different trees never share an encoding.
+ */
+export declare function skillTreeFingerprint(files: readonly SkillTreeFile[]): string;
+/**
+ * Version 1, as 0.8.0 computed it: `path NUL content NUL` per file in reading order. File
+ * content may contain NUL bytes, so two different trees can share this value.
+ */
+export declare function legacySkillTreeFingerprint(files: readonly SkillTreeFile[]): string;
+export interface ReleasedSkillTree {
+    readonly name: string;
+    readonly release: string;
+    readonly legacyFingerprint: string;
+    readonly fingerprint: string;
+}
+/**
+ * The shipped skills of every release that recorded version 1 fingerprints (0.8.0 only), as
+ * trusted references for recognizing such records. Computed from the `v0.8.0` tag and checked
+ * against the published npm package.
+ */
+export declare const RELEASED_SKILL_TREES: readonly ReleasedSkillTree[];
+/**
+ * Whether a version 1 fingerprint from a record proves that `candidate` is the tree it names:
+ * a trusted reference, a released shipped tree of this name or one of `references` (such as
+ * the current library tree), has exactly this version 1 fingerprint and is byte-identical to
+ * `candidate` by its version 2 fingerprint. The version 1 fingerprint alone never suffices.
+ */
+export declare function provesLegacyFingerprint(name: string, legacyFingerprint: string, candidate: Pick<SkillTree, "fingerprint">, references?: readonly Pick<SkillTree, "fingerprint" | "legacyFingerprint">[], released?: readonly ReleasedSkillTree[]): boolean;
+/**
+ * The version 2 fingerprint of the released shipped skill that a version 1 fingerprint names,
+ * or undefined. Only released trees qualify: the current shipped tree could share a version 1
+ * fingerprint with an older original without being that original.
+ */
+export declare function releasedSkillFingerprint(name: string, legacyFingerprint: string, released?: readonly ReleasedSkillTree[]): string | undefined;
 export interface ReadSkillTreeOptions {
     /**
      * `skip` (default) ignores entries whose name starts with `.`, as for a source tree. `reject`

package/dist/skill-library.js

@@ -59,6 +59,77 @@ export class SkillTreeError extends Error {
         this.name = "SkillTreeError";
     }
 }
+/** A version 2 skill tree fingerprint as it is stored. */
+export const SKILL_TREE_FINGERPRINT_PATTERN = /^v2:[0-9a-f]{64}$/;
+/** A version 1 fingerprint as 0.8.0 stored it: bare SHA-256 hex. */
+export const LEGACY_SKILL_TREE_FINGERPRINT_PATTERN = /^[0-9a-f]{64}$/;
+const FINGERPRINT_DOMAIN = "pi-session-mcp skill tree v2\n";
+function uint32(value) {
+    const bytes = Buffer.alloc(4);
+    bytes.writeUInt32BE(value);
+    return bytes;
+}
+function uint64(value) {
+    const bytes = Buffer.alloc(8);
+    bytes.writeBigUInt64BE(BigInt(value));
+    return bytes;
+}
+/**
+ * Version 2: a domain and version tag, the file count, then per file in byte order of the path
+ * the length-prefixed UTF-8 path and the length-prefixed content. Every field has an explicit
+ * length, so two different trees never share an encoding.
+ */
+export function skillTreeFingerprint(files) {
+    const entries = files.map((file) => ({ path: Buffer.from(file.path, "utf8"), bytes: file.bytes }))
+        .sort((left, right) => Buffer.compare(left.path, right.path));
+    const hash = createHash("sha256").update(FINGERPRINT_DOMAIN, "utf8").update(uint32(entries.length));
+    entries.forEach((entry, index) => {
+        if (index > 0 && Buffer.compare(entries[index - 1].path, entry.path) === 0)
+            throw new SkillTreeError("skill_tree_invalid");
+        hash.update(uint32(entry.path.length)).update(entry.path).update(uint64(entry.bytes.length)).update(entry.bytes);
+    });
+    return `v2:${hash.digest("hex")}`;
+}
+/**
+ * Version 1, as 0.8.0 computed it: `path NUL content NUL` per file in reading order. File
+ * content may contain NUL bytes, so two different trees can share this value.
+ */
+export function legacySkillTreeFingerprint(files) {
+    const hash = createHash("sha256");
+    for (const file of files)
+        hash.update(file.path).update("\0").update(file.bytes).update("\0");
+    return hash.digest("hex");
+}
+/**
+ * The shipped skills of every release that recorded version 1 fingerprints (0.8.0 only), as
+ * trusted references for recognizing such records. Computed from the `v0.8.0` tag and checked
+ * against the published npm package.
+ */
+export const RELEASED_SKILL_TREES = Object.freeze([
+    Object.freeze({ name: "pi-session-orchestration", release: "0.8.0", legacyFingerprint: "e2a72b558ea14748a4badd0058ff65b8731cc125033a666706b103842784673a", fingerprint: "v2:39edc4c4783dec7f90345b22844a17e5e48b465722bb0f1b20059d6ee51e1523" }),
+    Object.freeze({ name: "pi-session-implementation", release: "0.8.0", legacyFingerprint: "5f719b44da266d3f66dd5bf3c18f3e3e04ca7df357e2fe2eedbf0409e6c1bf64", fingerprint: "v2:f8ce75eff83a5c952f6ca51c04e1e8025cb7c2c558c30d692f291a3f6594eb12" }),
+    Object.freeze({ name: "pi-session-review", release: "0.8.0", legacyFingerprint: "8cf58ccb8d473a3eedf12ce6b902b1e91dd9e2fef83ad110c4d8e2e6164cb257", fingerprint: "v2:610c0b4829eeb1ce6c9b2000ad73f8e88ca230707eef7f7b1708a80767952bf0" }),
+]);
+/**
+ * Whether a version 1 fingerprint from a record proves that `candidate` is the tree it names:
+ * a trusted reference, a released shipped tree of this name or one of `references` (such as
+ * the current library tree), has exactly this version 1 fingerprint and is byte-identical to
+ * `candidate` by its version 2 fingerprint. The version 1 fingerprint alone never suffices.
+ */
+export function provesLegacyFingerprint(name, legacyFingerprint, candidate, references = [], released = RELEASED_SKILL_TREES) {
+    if (!LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(legacyFingerprint) || !SKILL_TREE_FINGERPRINT_PATTERN.test(candidate.fingerprint))
+        return false;
+    const trusted = [...released.filter((tree) => tree.name === name), ...references];
+    return trusted.some((tree) => tree.legacyFingerprint === legacyFingerprint && tree.fingerprint === candidate.fingerprint);
+}
+/**
+ * The version 2 fingerprint of the released shipped skill that a version 1 fingerprint names,
+ * or undefined. Only released trees qualify: the current shipped tree could share a version 1
+ * fingerprint with an older original without being that original.
+ */
+export function releasedSkillFingerprint(name, legacyFingerprint, released = RELEASED_SKILL_TREES) {
+    return released.find((tree) => tree.name === name && tree.legacyFingerprint === legacyFingerprint)?.fingerprint;
+}
 /**
  * Reads the regular files below a skill directory in a stable order. Entries whose name starts
  * with `.` are skipped or rejected (see options). A symbolic link or special file inside the
@@ -113,8 +184,5 @@ export async function readSkillTree(directory, options = {}) {
     await visit(root, "", 0);
     if (!files.some((file) => file.path === "SKILL.md"))
         throw new SkillTreeError("skill_tree_missing");
-    const hash = createHash("sha256");
-    for (const file of files)
-        hash.update(file.path).update("\0").update(file.bytes).update("\0");
-    return Object.freeze({ files: Object.freeze(files), fingerprint: hash.digest("hex") });
+    return Object.freeze({ files: Object.freeze(files), fingerprint: skillTreeFingerprint(files), legacyFingerprint: legacySkillTreeFingerprint(files) });
 }