pi-session-mcp 0.7.0 → 0.8.0

package/dist/skill-customize.js

@@ -0,0 +1,183 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { result } from "./setup-result.js";
+import { readSkillTree, shippedSkillsDirectory, SKILL_NAME_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.
+ */
+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}$/;
+export class SkillBasesError extends Error {
+    constructor() {
+        super("Skill bases file is not usable");
+        this.name = "SkillBasesError";
+    }
+}
+/** Strictly validated contents of the bases file; an absent file or override directory is an empty record. */
+export async function readSkillBases(overrideDirectory) {
+    const path = join(overrideDirectory, SKILL_BASES_FILE);
+    let text;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.size > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        const bytes = await readFile(path);
+        if (bytes.length > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        text = bytes.toString("utf8");
+    }
+    catch (error) {
+        if (error instanceof SkillBasesError)
+            throw error;
+        if (typeof error === "object" && error !== null && error.code === "ENOENT")
+            return Object.freeze({});
+        throw new SkillBasesError();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SkillBasesError();
+    }
+    if (!isPlainObject(parsed) || Object.keys(parsed).sort().join() !== "bases,schemaVersion" || parsed.schemaVersion !== 1)
+        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)))
+        throw new SkillBasesError();
+    return Object.freeze(Object.fromEntries(entries));
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    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");
+    if (content.length > MAX_SKILL_BASES_BYTES)
+        throw new SkillBasesError();
+    const temporary = join(overrideDirectory, `.${SKILL_BASES_FILE.slice(1)}.${randomBytes(6).toString("hex")}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        try {
+            await handle.writeFile(content);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, join(overrideDirectory, SKILL_BASES_FILE));
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function report(request, status, code) {
+    // The name is echoed only when it is a valid skill name, so arbitrary input never reaches a report.
+    const alias = SKILL_NAME_PATTERN.test(request.name) ? request.name : "invalid";
+    const target = { client: "skills", scope: "override", alias };
+    const finding = { target, 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 done = (status, code) => report(request, status, code);
+    if (!SKILL_NAME_PATTERN.test(request.name))
+        return done("failed", "skill_not_shipped");
+    try {
+        const shippedDirectory = join(shippedSkillsDirectory(request.packageRoot), request.name);
+        let shipped;
+        try {
+            shipped = await readSkillTree(shippedDirectory);
+        }
+        catch (error) {
+            if (error instanceof SkillTreeError && error.code === "skill_tree_missing")
+                return done("failed", "skill_not_shipped");
+            return done("failed", "skill_customize_failed");
+        }
+        const overrideDirectory = skillOverrideDirectory(request.configPath);
+        let bases;
+        try {
+            bases = await readSkillBases(overrideDirectory);
+        }
+        catch (error) {
+            if (error instanceof SkillBasesError)
+                return done("failed", "skill_bases_corrupt");
+            throw error;
+        }
+        const overridePath = join(overrideDirectory, request.name);
+        let exists = true;
+        try {
+            const info = await lstat(overridePath);
+            if (!info.isDirectory())
+                return done("failed", "skill_override_invalid");
+        }
+        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");
+        }
+        try {
+            await readSkillTree(overridePath);
+        }
+        catch (error) {
+            if (error instanceof SkillTreeError)
+                return done("failed", "skill_override_invalid");
+            throw error;
+        }
+        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 });
+        }
+        // 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);
+    }
+    catch (error) {
+        await rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/skill-library.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The skill library: skills shipped in the package's `skills/` directory, and the operator's
+ * override directory `skills/` next to the configuration file. An override with the same name
+ * replaces the shipped skill; a new name adds a skill. Nothing else is searched.
+ */
+/** Agent Skills name rule: lowercase letters and digits in hyphen-separated groups, 1 to 64 characters. */
+export declare const SKILL_NAME_PATTERN: RegExp;
+/** A `skillCatalog` value `builtin:<name>` names a library skill instead of a path. */
+export declare const BUILTIN_SKILL_PREFIX = "builtin:";
+/** Skills for the controlling agent, which setup installs into Claude Code and Codex. */
+export declare const CONTROLLER_SKILLS: readonly string[];
+export declare const MAX_SKILL_TREE_FILES = 32;
+export declare const MAX_SKILL_TREE_BYTES: number;
+/** `dist/`, `.pi-session-mcp-cli/` and `src/` all sit one level below the package root. */
+export declare const PACKAGE_ROOT: string;
+export declare function shippedSkillsDirectory(packageRoot?: string): string;
+/** The override directory belongs to the configuration, never to a workspace or the shell's directory. */
+export declare function skillOverrideDirectory(configPath: string): string;
+export interface LibrarySkill {
+    readonly name: string;
+    readonly source: "override" | "shipped";
+    /** Absolute directory that holds the skill's `SKILL.md`. Internal; never reported. */
+    readonly directory: string;
+}
+export interface LibraryRoots {
+    readonly overrideDirectory: string;
+    readonly packageRoot?: string;
+}
+/** The override wins over the shipped skill of the same name; undefined when neither exists. */
+export declare function resolveLibrarySkill(name: string, roots: LibraryRoots): LibrarySkill | undefined;
+/** The `SKILL.md` a `builtin:<name>` catalog value stands for; a missing skill keeps the shipped location. */
+export declare function builtinSkillPath(name: string, roots: LibraryRoots): string;
+export interface SkillTreeFile {
+    /** Path relative to the skill directory, with `/` separators. */
+    readonly path: string;
+    readonly bytes: Buffer;
+}
+export interface SkillTree {
+    readonly files: readonly SkillTreeFile[];
+    /** SHA-256 hex over the sorted relative paths and contents; path-free and stable. */
+    readonly fingerprint: 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");
+}
+export interface ReadSkillTreeOptions {
+    /**
+     * `skip` (default) ignores entries whose name starts with `.`, as for a source tree. `reject`
+     * fails on them, for an installed copy: setup never writes hidden entries, so one there is
+     * operator content that a fingerprint over the visible files would not protect.
+     */
+    readonly hidden?: "skip" | "reject";
+}
+/**
+ * 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
+ * tree, a missing `SKILL.md`, or more than the file and byte limits fail, so the tree can be
+ * copied and compared exactly.
+ */
+export declare function readSkillTree(directory: string, options?: ReadSkillTreeOptions): Promise<SkillTree>;

package/dist/skill-library.js

@@ -0,0 +1,120 @@
+import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
+import { lstat, readdir, readFile, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * The skill library: skills shipped in the package's `skills/` directory, and the operator's
+ * override directory `skills/` next to the configuration file. An override with the same name
+ * replaces the shipped skill; a new name adds a skill. Nothing else is searched.
+ */
+/** Agent Skills name rule: lowercase letters and digits in hyphen-separated groups, 1 to 64 characters. */
+export const SKILL_NAME_PATTERN = /^(?=.{1,64}$)[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A `skillCatalog` value `builtin:<name>` names a library skill instead of a path. */
+export const BUILTIN_SKILL_PREFIX = "builtin:";
+/** Skills for the controlling agent, which setup installs into Claude Code and Codex. */
+export const CONTROLLER_SKILLS = Object.freeze(["pi-session-orchestration"]);
+export const MAX_SKILL_TREE_FILES = 32;
+export const MAX_SKILL_TREE_BYTES = 1024 * 1024;
+const MAX_SKILL_TREE_DEPTH = 8;
+/** `dist/`, `.pi-session-mcp-cli/` and `src/` all sit one level below the package root. */
+export const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+export function shippedSkillsDirectory(packageRoot = PACKAGE_ROOT) {
+    return join(packageRoot, "skills");
+}
+/** The override directory belongs to the configuration, never to a workspace or the shell's directory. */
+export function skillOverrideDirectory(configPath) {
+    return join(dirname(resolve(configPath)), "skills");
+}
+function isRegularFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** The override wins over the shipped skill of the same name; undefined when neither exists. */
+export function resolveLibrarySkill(name, roots) {
+    if (!SKILL_NAME_PATTERN.test(name))
+        return undefined;
+    const override = join(roots.overrideDirectory, name);
+    if (isRegularFile(join(override, "SKILL.md")))
+        return Object.freeze({ name, source: "override", directory: override });
+    const shipped = join(shippedSkillsDirectory(roots.packageRoot), name);
+    if (isRegularFile(join(shipped, "SKILL.md")))
+        return Object.freeze({ name, source: "shipped", directory: shipped });
+    return undefined;
+}
+/** The `SKILL.md` a `builtin:<name>` catalog value stands for; a missing skill keeps the shipped location. */
+export function builtinSkillPath(name, roots) {
+    const skill = resolveLibrarySkill(name, roots);
+    return join(skill?.directory ?? join(shippedSkillsDirectory(roots.packageRoot), name), "SKILL.md");
+}
+export class SkillTreeError extends Error {
+    code;
+    constructor(code) {
+        super("Skill directory is not usable");
+        this.code = code;
+        this.name = "SkillTreeError";
+    }
+}
+/**
+ * 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
+ * tree, a missing `SKILL.md`, or more than the file and byte limits fail, so the tree can be
+ * copied and compared exactly.
+ */
+export async function readSkillTree(directory, options = {}) {
+    let root;
+    try {
+        root = await realpath(directory);
+    }
+    catch {
+        throw new SkillTreeError("skill_tree_missing");
+    }
+    const files = [];
+    let bytes = 0;
+    const visit = async (current, prefix, depth) => {
+        if (depth > MAX_SKILL_TREE_DEPTH)
+            throw new SkillTreeError("skill_tree_invalid");
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            throw new SkillTreeError("skill_tree_invalid");
+        }
+        for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))) {
+            if (entry.name.startsWith(".")) {
+                if (options.hidden === "reject")
+                    throw new SkillTreeError("skill_tree_invalid");
+                continue;
+            }
+            const path = join(current, entry.name);
+            const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+            const info = await lstat(path);
+            if (info.isDirectory()) {
+                await visit(path, relativePath, depth + 1);
+                continue;
+            }
+            if (!info.isFile())
+                throw new SkillTreeError("skill_tree_invalid");
+            if (files.length + 1 > MAX_SKILL_TREE_FILES || bytes + info.size > MAX_SKILL_TREE_BYTES)
+                throw new SkillTreeError("skill_tree_too_large");
+            const content = await readFile(path);
+            // Counted as read, so a file that grew after lstat cannot pass the limit.
+            bytes += content.length;
+            if (bytes > MAX_SKILL_TREE_BYTES)
+                throw new SkillTreeError("skill_tree_too_large");
+            files.push(Object.freeze({ path: relativePath, bytes: content }));
+        }
+    };
+    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") });
+}