@penpair/core 0.2.0 → 0.3.1

package/dist/run-file.js

@@ -8,93 +8,192 @@ import { normalize } from "./registry.js";
 import { runOnPage, runOperation } from "./operation.js";
 const digest = (value) => createHash("sha256").update(value).digest("hex");
 async function sourceFile(root, entry) {
-    if (!/\.m?js$/.test(entry))
+    if (!/\.m?js$/.test(entry)) {
         throw new Error("Plugin bodies must be .js or .mjs files; host imports and TypeScript transpilation are not performed");
+    }
     const target = await resolveProjectInput(root, entry);
     const handle = await open(target, "r");
     let body;
     try {
         const info = await handle.stat();
-        if (!info.isFile() || info.size > maxSnippetBytes)
+        if (!info.isFile() || info.size > maxSnippetBytes) {
             throw new Error("Script file exceeds the 90 KB input bound or is not a regular file");
+        }
         body = (await handle.readFile("utf8")).replace(/^\uFEFF/, "");
     }
     finally {
         await handle.close();
     }
-    if (body.includes("\0"))
+    if (body.includes("\0")) {
         throw new Error("Plugin script contains a NUL character");
+    }
     const header = body.trimStart().split(/\r?\n/)[0]?.trim();
     const declaration = header === "// penpair: read" ? "read" : header === "// penpair: write" ? "write" : "unknown";
     // The idempotency assertion must be in the initial comment block, before executable source.
     const comments = [];
     for (const line of body.trimStart().split(/\r?\n/)) {
-        if (!line.trim().startsWith("//"))
+        if (!line.trim().startsWith("//")) {
             break;
+        }
         comments.push(line.trim());
     }
-    return { file: path.relative(await realpath(root), target).split(path.sep).join("/"), sha256: digest(body), body, declaration, idempotent: comments.includes("// penpair: idempotent") };
+    return {
+        file: path
+            .relative(await realpath(root), target)
+            .split(path.sep)
+            .join("/"),
+        sha256: digest(body),
+        body,
+        declaration,
+        idempotent: comments.includes("// penpair: idempotent"),
+    };
 }
 function checked(value) {
     const error = compiles(value.code);
-    if (error)
+    if (error) {
         throw new Error(`${value.name}: invalid plugin body: ${error}`);
+    }
     return value;
 }
 /** Reads and compiles explicitly selected files without importing project modules on the host. */
 export async function prepareFileScript(root, file, options = {}) {
     const includes = options.include ?? [];
-    if (includes.length > 20 || new Set(includes).size !== includes.length)
+    if (includes.length > 20 || new Set(includes).size !== includes.length) {
         throw new Error("Use at most 20 distinct ordered includes");
+    }
     const params = options.params ?? {};
-    if (Object.keys(params).length > 100 || Object.keys(params).some(key => !/^[A-Za-z][A-Za-z0-9]*$/.test(key)))
+    if (Object.keys(params).length > 100 ||
+        Object.keys(params).some((key) => !/^[A-Za-z][A-Za-z0-9]*$/.test(key))) {
         throw new Error("Use at most 100 named parameters (letters followed by letters/digits)");
-    if (options.page && Object.hasOwn(params, "page"))
+    }
+    if (options.page && Object.hasOwn(params, "page")) {
         throw new Error("--page owns CFG.page; do not also pass --param page");
-    if (Object.hasOwn(params, "inspection"))
+    }
+    if (Object.hasOwn(params, "inspection")) {
         throw new Error("CFG.inspection is reserved for the independently captured write inspection");
+    }
     const helpers = [];
     for (const include of includes) {
         const virtual = options.virtualIncludes?.[include];
-        const helper = virtual === undefined ? await sourceFile(root, include) : { file: include, body: virtual, sha256: digest(virtual), declaration: virtual.startsWith("// penpair: read\n") ? "read" : "unknown", idempotent: false };
-        if (helper.declaration !== "read")
+        const helper = virtual === undefined
+            ? await sourceFile(root, include)
+            : {
+                file: include,
+                body: virtual,
+                sha256: digest(virtual),
+                declaration: virtual.startsWith("// penpair: read\n") ? "read" : "unknown",
+                idempotent: false,
+            };
+        if (helper.declaration !== "read") {
             throw new Error(`Include ${include} must declare // penpair: read for its top-level inclusion effects`);
+        }
         helpers.push(helper);
     }
     const main = await sourceFile(root, file);
-    const prelude = helpers.map(helper => `// Included helper\n${helper.body}\n`).join("\n");
-    const cfg = { ...params, ...(options.page ? { page: options.page } : {}) };
-    const build = (label, body, effect, inspected) => checked(snippet(label, `${requirePage}\n${prelude}\n${body}`, { ...cfg, ...(effect === "write" ? { inspection: inspected ?? null } : {}) }, effect));
+    const prelude = helpers.map((helper) => `// Included helper\n${helper.body}\n`).join("\n");
+    const cfg = {
+        ...params,
+        ...(options.page
+            ? {
+                page: options.page,
+            }
+            : {}),
+    };
+    const build = (label, body, effect, inspected) => checked(snippet(label, `${requirePage}\n${prelude}\n${body}`, {
+        ...cfg,
+        ...(effect === "write"
+            ? {
+                inspection: inspected ?? null,
+            }
+            : {}),
+    }, effect));
     if (main.declaration === "read") {
-        if (options.inspect || options.readback)
+        if (options.inspect || options.readback) {
             throw new Error("Read scripts do not take write inspect/readback phases");
-        return { kind: "read", source: [...helpers, main].map(({ file, sha256 }) => ({ file, sha256 })), params: cfg, page: options.page, read: build("run-file-read", main.body, "read") };
+        }
+        return {
+            kind: "read",
+            source: [
+                ...helpers,
+                main,
+            ].map(({ file, sha256 }) => ({
+                file,
+                sha256,
+            })),
+            params: cfg,
+            page: options.page,
+            read: build("run-file-read", main.body, "read"),
+        };
     }
-    if (main.declaration !== "write" || !main.idempotent || !options.inspect || !options.readback)
+    if (main.declaration !== "write" || !main.idempotent || !options.inspect || !options.readback) {
         throw new Error("Write script execution requires // penpair: write, // penpair: idempotent, and explicit --inspect/--readback files. Declarations are trusted code contracts, not a sandbox.");
-    const inspect = await sourceFile(root, options.inspect), readback = await sourceFile(root, options.readback);
-    if (inspect.declaration !== "read" || readback.declaration !== "read")
+    }
+    const inspect = await sourceFile(root, options.inspect);
+    const readback = await sourceFile(root, options.readback);
+    if (inspect.declaration !== "read" || readback.declaration !== "read") {
         throw new Error("Inspection and readback files must declare // penpair: read");
+    }
     // Reuse the registry's positive evidence verifier; never equate an acknowledgment with a verified write.
-    const normalized = normalize({ name: "run-file", description: "Explicitly selected reviewed file operation", kind: "write", inspect: inspect.body, apply: main.body, readback: readback.body }, "project");
-    const operation = { ...normalized.operation, page: () => options.page,
+    const normalized = normalize({
+        name: "run-file",
+        description: "Explicitly selected reviewed file operation",
+        kind: "write",
+        inspect: inspect.body,
+        apply: main.body,
+        readback: readback.body,
+    }, "project");
+    const operation = {
+        ...normalized.operation,
+        page: () => options.page,
         inspect: () => build("run-file-inspect", inspect.body, "read"),
         apply: (_params, inspected) => build("run-file-apply", main.body, "write", inspected),
-        readback: () => build("run-file-readback", readback.body, "read"), };
+        readback: () => build("run-file-readback", readback.body, "read"),
+    };
     operation.inspect({});
     operation.apply({});
     operation.readback({});
-    return { kind: "write", source: [...helpers, main, inspect, readback].map(({ file, sha256 }) => ({ file, sha256 })), params: cfg, page: options.page, operation };
+    return {
+        kind: "write",
+        source: [
+            ...helpers,
+            main,
+            inspect,
+            readback,
+        ].map(({ file, sha256 }) => ({
+            file,
+            sha256,
+        })),
+        params: cfg,
+        page: options.page,
+        operation,
+    };
 }
 export async function runFileScript(client, prepared, options = {}) {
     if (prepared.kind === "read") {
-        if (options.apply || options.journal)
+        if (options.apply || options.journal) {
             throw new Error("Read files do not accept apply or write recovery options");
-        const result = await runOnPage(client, prepared.read, prepared.page, { ...options, effect: "read", retries: 0 });
-        if (result.ok !== true)
+        }
+        const result = await runOnPage(client, prepared.read, prepared.page, {
+            ...options,
+            effect: "read",
+            retries: 0,
+        });
+        if (result.ok !== true) {
             throw new Error("Read script returned no explicit ok acknowledgment");
-        return { phase: "read", kind: "declared-read", source: prepared.source, data: result };
+        }
+        return {
+            phase: "read",
+            kind: "declared-read",
+            source: prepared.source,
+            data: result,
+        };
     }
-    const report = await runOperation(client, prepared.operation, { parameters: prepared.params, sourceFiles: prepared.source }, options);
-    return { ...report, source: prepared.source };
+    const report = await runOperation(client, prepared.operation, {
+        parameters: prepared.params,
+        sourceFiles: prepared.source,
+    }, options);
+    return {
+        ...report,
+        source: prepared.source,
+    };
 }

package/dist/shots.js

@@ -12,8 +12,9 @@ import { pngSize } from "./baselines.js";
 import { observationHash } from "./journal.js";
 /** Exact names across the selected page. A match never silently resolves an ambiguity. */
 export async function findShapesByName(client, name, page, options = {}) {
-    if (!name || !page)
+    if (!name || !page) {
         throw new Error("Name lookup requires an exact name and explicit page");
+    }
     const result = await runOnPage(client, snippet("find-shape-name", `${requirePage}
 const matches = [], stack = [...penpot.currentPage.root.children]; let visited = 0;
 while (stack.length && visited < 10000) {
@@ -21,54 +22,127 @@ while (stack.length && visited < 10000) {
   if (shape.name === CFG.name) matches.push({id:shape.id,name:shape.name,type:shape.type});
   for (const child of shape.children || []) stack.push(child);
 }
-return {ok:true,fileId:penpot.currentFile.id,pageId:penpot.currentPage.id,revision:penpot.currentFile.revn,matches,truncated:stack.length>0};`, { name, page }, "read"), page, options);
-    if (result.truncated)
+return {ok:true,fileId:penpot.currentFile.id,pageId:penpot.currentPage.id,revision:penpot.currentFile.revn,matches,truncated:stack.length>0};`, {
+        name,
+        page,
+    }, "read"), page, options);
+    if (result.truncated) {
         throw new PenpairError("incomplete-output", "Shape name search exceeded 10000 nodes; narrow the page");
-    if (result.ok !== true || typeof result.truncated !== "boolean" || typeof result.fileId !== "string" || !result.fileId || typeof result.pageId !== "string" || !result.pageId || !Number.isInteger(result.revision) || !Array.isArray(result.matches) || result.matches.some((match) => !match || typeof match.id !== "string" || typeof match.name !== "string" || typeof match.type !== "string"))
+    }
+    if (result.ok !== true ||
+        typeof result.truncated !== "boolean" ||
+        typeof result.fileId !== "string" ||
+        !result.fileId ||
+        typeof result.pageId !== "string" ||
+        !result.pageId ||
+        !Number.isInteger(result.revision) ||
+        !Array.isArray(result.matches) ||
+        result.matches.some((match) => !match ||
+            typeof match.id !== "string" ||
+            typeof match.name !== "string" ||
+            typeof match.type !== "string")) {
         throw new Error("Shape search returned incomplete identity evidence");
+    }
     return result;
 }
 export async function exportShapeByName(client, name, page, options = {}) {
     const lookup = await findShapesByName(client, name, page, options);
-    if (lookup.matches.length !== 1)
+    if (lookup.matches.length !== 1) {
         throw new Error(`Exact name ${JSON.stringify(name)} matched ${lookup.matches.length} shapes on ${JSON.stringify(page)}. Candidates: ${JSON.stringify(lookup.matches.slice(0, 20))}. Use an ID for an ambiguous name.`);
-    const result = await exportShapePng(client, lookup.matches[0].id, { ...options, page });
-    if (result.capture.fileId !== lookup.fileId || result.capture.pageId !== lookup.pageId || result.capture.revision !== lookup.revision)
+    }
+    const result = await exportShapePng(client, lookup.matches[0].id, {
+        ...options,
+        page,
+    });
+    if (result.capture.fileId !== lookup.fileId ||
+        result.capture.pageId !== lookup.pageId ||
+        result.capture.revision !== lookup.revision) {
         throw new Error("Named export source changed after lookup; no output was published");
+    }
     return result;
 }
 /** Ad-hoc captures use immutable generations, but never carry baseline approval records. */
 export async function captureShots(client, root, params, options = {}) {
-    const listing = await runOnPage(client, frames({ page: params.page }), params.page, options);
-    if (typeof listing.fileId !== "string" || typeof listing.pageId !== "string" || !Number.isInteger(listing.revn) || !Array.isArray(listing.frames))
+    const listing = await runOnPage(client, frames({
+        page: params.page,
+    }), params.page, options);
+    if (typeof listing.fileId !== "string" ||
+        typeof listing.pageId !== "string" ||
+        !Number.isInteger(listing.revn) ||
+        !Array.isArray(listing.frames)) {
         throw new Error("Shots listing lacks identity/revision evidence");
+    }
     const selected = listing.frames.filter((frame) => !params.prefix || frame.name.startsWith(params.prefix));
-    const report = { schemaVersion: 1, complete: false, fileId: listing.fileId, pageId: listing.pageId, revision: Number(listing.revn), captures: [], wrote: [] };
-    if (!selected.length || selected.length > 100)
-        return { ...report, reason: !selected.length ? "No matching top-level frames" : "More than 100 frames; narrow the prefix" };
+    const report = {
+        schemaVersion: 1,
+        complete: false,
+        fileId: listing.fileId,
+        pageId: listing.pageId,
+        revision: Number(listing.revn),
+        captures: [],
+        wrote: [],
+    };
+    if (!selected.length || selected.length > 100) {
+        return {
+            ...report,
+            reason: !selected.length
+                ? "No matching top-level frames"
+                : "More than 100 frames; narrow the prefix",
+        };
+    }
     const folder = await resolveProjectOutput(root, params.out ?? "design/shots");
-    const runId = randomUUID(), generation = `captures/${runId}`;
+    const runId = randomUUID();
+    const generation = `captures/${runId}`;
     const images = [];
     for (const [index, frame] of selected.entries()) {
         options.signal?.throwIfAborted();
         options.onStep?.(`exporting ${JSON.stringify(frame.name)}`);
-        const result = await exportShapePng(client, frame.id, { ...options, page: params.page, stable: true });
-        if (!result.stable)
-            return { ...report, reason: "A frame did not stabilize; no output was published" };
-        if (result.capture.fileId !== report.fileId || result.capture.pageId !== report.pageId || result.capture.revision !== report.revision)
+        const result = await exportShapePng(client, frame.id, {
+            ...options,
+            page: params.page,
+            stable: true,
+        });
+        if (!result.stable) {
+            return {
+                ...report,
+                reason: "A frame did not stabilize; no output was published",
+            };
+        }
+        if (result.capture.fileId !== report.fileId ||
+            result.capture.pageId !== report.pageId ||
+            result.capture.revision !== report.revision) {
             throw new Error("Shots source changed during capture; no output was published");
+        }
         const size = pngSize(result.png);
-        if (!size || size.width <= 0 || size.height <= 0)
+        if (!size || size.width <= 0 || size.height <= 0) {
             throw new Error("Shot export is missing valid PNG dimensions");
-        report.captures.push({ layout: result.layout, ...size, name: frame.name, file: `${generation}/shot-${String(index + 1).padStart(4, "0")}.png`, sha256: createHash("sha256").update(result.png).digest("hex"), capture: result.capture });
+        }
+        report.captures.push({
+            layout: result.layout,
+            ...size,
+            name: frame.name,
+            file: `${generation}/shot-${String(index + 1).padStart(4, "0")}.png`,
+            sha256: createHash("sha256").update(result.png).digest("hex"),
+            capture: result.capture,
+        });
         images.push(result.png);
     }
-    const after = await runOnPage(client, frames({ page: params.page }), params.page, options);
-    const identity = (entry) => ({ fileId: entry.fileId, pageId: entry.pageId, revision: entry.revn, frames: entry.frames });
-    if (observationHash(identity(listing)) !== observationHash(identity(after)))
+    const after = await runOnPage(client, frames({
+        page: params.page,
+    }), params.page, options);
+    const identity = (entry) => ({
+        fileId: entry.fileId,
+        pageId: entry.pageId,
+        revision: entry.revn,
+        frames: entry.frames,
+    });
+    if (observationHash(identity(listing)) !== observationHash(identity(after))) {
         throw new Error("Shots source changed before publication; previous output was preserved");
+    }
     options.signal?.throwIfAborted();
-    await mkdir(path.join(folder, "captures"), { recursive: true });
+    await mkdir(path.join(folder, "captures"), {
+        recursive: true,
+    });
     const staged = path.join(folder, `.stage-${runId}`);
     await mkdir(staged);
     try {
@@ -80,11 +154,19 @@ export async function captureShots(client, root, params, options = {}) {
         await rename(staged, path.join(folder, generation));
         options.signal?.throwIfAborted();
         report.complete = true;
-        report.wrote = [...report.captures.map((entry) => entry.file), "penpair-shots.json"];
-        await atomicWriteFile(path.join(folder, "penpair-shots.json"), `${JSON.stringify(report, null, 2)}\n`, { replace: true });
+        report.wrote = [
+            ...report.captures.map((entry) => entry.file),
+            "penpair-shots.json",
+        ];
+        await atomicWriteFile(path.join(folder, "penpair-shots.json"), `${JSON.stringify(report, null, 2)}\n`, {
+            replace: true,
+        });
         return report;
     }
     finally {
-        await rm(staged, { recursive: true, force: true });
+        await rm(staged, {
+            recursive: true,
+            force: true,
+        });
     }
 }

package/dist/skill-check-entry.d.ts

@@ -0,0 +1,17 @@
+import { type SkillInstructionCheck } from "./skill-check-instructions.js";
+export interface SkillDiagnostic {
+    name: string;
+    path: string;
+    implicitInvocation: boolean | null;
+    entrypoint: "current" | "modified" | "unavailable";
+    problems: string[];
+    warnings: string[];
+}
+interface EntryOptions {
+    root: string;
+    name: string;
+    bundledDirectory: string;
+    instructions: SkillInstructionCheck;
+}
+export declare function checkSkillEntry(options: EntryOptions): Promise<SkillDiagnostic>;
+export {};

package/dist/skill-check-entry.js

@@ -0,0 +1,89 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { parseSkillMetadata, parseSkillYaml } from "./skill-metadata.js";
+import { readSkillFile } from "./skill-file.js";
+import { resolveSkillLink } from "./skill-check-instructions.js";
+async function invocationAllowed(root, skillPath) {
+    const relative = path.posix.join(path.posix.dirname(skillPath), "agents/openai.yaml");
+    const present = await lstat(path.join(root, relative)).catch((error) => {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+        return undefined;
+    });
+    if (!present) {
+        return true;
+    }
+    const metadata = parseSkillYaml(await readSkillFile(root, relative));
+    if (metadata.policy === undefined) {
+        return true;
+    }
+    if (!metadata.policy || typeof metadata.policy !== "object" || Array.isArray(metadata.policy)) {
+        throw new Error("Invalid invocation policy");
+    }
+    const allowed = metadata.policy.allow_implicit_invocation;
+    if (allowed !== undefined && typeof allowed !== "boolean") {
+        throw new Error("Invocation policy must use a boolean");
+    }
+    return allowed !== false;
+}
+export async function checkSkillEntry(options) {
+    const { root, name, bundledDirectory, instructions } = options;
+    const skillPath = path.posix.join(".agents/skills", name, "SKILL.md");
+    const report = {
+        name,
+        path: skillPath,
+        implicitInvocation: null,
+        entrypoint: "unavailable",
+        problems: [],
+        warnings: [],
+    };
+    try {
+        const source = await readSkillFile(root, skillPath);
+        parseSkillMetadata(source, name);
+        const bundled = await readFile(path.join(bundledDirectory, name, "SKILL.md"), "utf8");
+        report.entrypoint = source === bundled ? "current" : "modified";
+        if (report.entrypoint === "modified") {
+            report.warnings.push("The discoverable entrypoint differs from the bundled skill; review intentional customization before refresh.");
+        }
+        const localLinks = [
+            ...source.matchAll(/\[[^\]]+\]\(([^)]+)\)/g),
+        ]
+            .map((match) => match[1])
+            .filter((target) => target && !target.startsWith("#") && !/^[a-z][a-z0-9+.-]*:/i.test(target));
+        if (localLinks.length > 100) {
+            throw new Error("Too many local resource links");
+        }
+        for (const target of localLinks) {
+            await resolveSkillLink(root, skillPath, target);
+        }
+        report.implicitInvocation = await invocationAllowed(root, skillPath);
+        if (!report.implicitInvocation) {
+            report.problems.push("Implicit invocation is disabled in openai.yaml; explicit invocation remains available.");
+        }
+        for (const folder of [
+            ".skills",
+            ".claude/skills",
+        ]) {
+            const otherPath = path.posix.join(folder, name, "SKILL.md");
+            const other = await readSkillFile(root, otherPath).catch(() => undefined);
+            if (other !== undefined && other !== source) {
+                report.problems.push("Codex and another installed skill copy differ; review the conflicting copies before refreshing.");
+            }
+        }
+        const routes = instructions.links[name] ?? [];
+        if (!routes.length) {
+            report.problems.push("No generated task route links this skill from the selected instruction file.");
+        }
+        const resolvedSkill = await realpath(path.join(root, skillPath));
+        for (const target of routes) {
+            if ((await resolveSkillLink(root, instructions.path, target)) !== resolvedSkill) {
+                report.problems.push("An instruction route points to a different skill copy.");
+            }
+        }
+    }
+    catch {
+        report.problems.push("Skill discovery, frontmatter, local resources or UI policy is missing, invalid or resolves outside the project; inspect the local files and preview a skill refresh.");
+    }
+    return report;
+}

package/dist/skill-check-instructions.d.ts

@@ -0,0 +1,7 @@
+export interface SkillInstructionCheck {
+    path: string;
+    problems: string[];
+    links: Record<string, string[]>;
+}
+export declare function resolveSkillLink(root: string, from: string, target: string): Promise<string>;
+export declare function checkSkillInstructions(root: string, instructionFile: string): Promise<SkillInstructionCheck>;

package/dist/skill-check-instructions.js

@@ -0,0 +1,39 @@
+import path from "node:path";
+import { readSkillFile } from "./skill-file.js";
+import { skillInstructionMarkers } from "./skill-instructions.js";
+import { resolveProjectInput } from "./project-input.js";
+export async function resolveSkillLink(root, from, target) {
+    const decoded = decodeURIComponent(target.split("#")[0]);
+    if (!decoded || path.isAbsolute(decoded) || /^[a-z][a-z0-9+.-]*:/i.test(decoded)) {
+        throw new Error("Skill resource link must resolve inside the project");
+    }
+    const relative = path.relative(root, path.resolve(root, path.dirname(from), decoded));
+    return resolveProjectInput(root, relative);
+}
+export async function checkSkillInstructions(root, instructionFile) {
+    const report = {
+        path: instructionFile,
+        problems: [],
+        links: {},
+    };
+    try {
+        const resolved = await resolveProjectInput(root, instructionFile);
+        report.path = path.relative(root, resolved).split(path.sep).join("/");
+        const source = await readSkillFile(root, report.path);
+        const { start, end } = skillInstructionMarkers;
+        if (source.split(start).length !== 2 ||
+            source.split(end).length !== 2 ||
+            source.indexOf(start) > source.indexOf(end)) {
+            throw new Error("Missing or malformed installer-owned skill routing block");
+        }
+        const block = source.slice(source.indexOf(start) + start.length, source.indexOf(end));
+        const routing = block.split("| Skill | Purpose |")[0];
+        for (const match of routing.matchAll(/\[([a-z0-9-]+)\]\(([^)]+)\)/g)) {
+            (report.links[match[1]] ??= []).push(match[2]);
+        }
+    }
+    catch {
+        report.problems.push("Project instructions are missing, unreadable or lack a valid owned routing block; preview skills install --agents with this destination.");
+    }
+    return report;
+}

package/dist/skill-check.d.ts

@@ -0,0 +1,15 @@
+import { type SkillDiagnostic } from "./skill-check-entry.js";
+import { type SkillInstructionCheck } from "./skill-check-instructions.js";
+export interface SkillCheckOptions {
+    root: string;
+    agents?: string;
+    only?: string[];
+}
+export interface SkillCheckReport {
+    agent: "codex";
+    ready: boolean;
+    instructions: Pick<SkillInstructionCheck, "path" | "problems">;
+    skills: SkillDiagnostic[];
+    limitations: string[];
+}
+export declare function checkSkills(options: SkillCheckOptions): Promise<SkillCheckReport>;

package/dist/skill-check.js

@@ -0,0 +1,36 @@
+import { realpath } from "node:fs/promises";
+import { bundledSkillsDirectory, listBundledSkills } from "./skills.js";
+import { checkSkillEntry } from "./skill-check-entry.js";
+import { checkSkillInstructions } from "./skill-check-instructions.js";
+export async function checkSkills(options) {
+    const root = await realpath(options.root);
+    const bundledDirectory = bundledSkillsDirectory();
+    const names = await listBundledSkills(bundledDirectory);
+    const selected = options.only ?? names;
+    if (!selected.length || selected.some((name) => !names.includes(name))) {
+        throw new Error("Select one or more bundled skill names; use penpair skills to list them");
+    }
+    const instructions = await checkSkillInstructions(root, options.agents ?? "AGENTS.md");
+    const skills = await Promise.all([
+        ...new Set(selected),
+    ].map((name) => checkSkillEntry({
+        root,
+        name,
+        bundledDirectory,
+        instructions,
+    })));
+    return {
+        agent: "codex",
+        ready: !instructions.problems.length && skills.every((skill) => !skill.problems.length),
+        instructions: {
+            path: instructions.path,
+            problems: instructions.problems,
+        },
+        skills,
+        limitations: [
+            "Offline project-file checks only; no connection, adapter/provider execution, credential reads or writes.",
+            "Does not inspect global Codex settings, session skill catalogs, context budgets or UI selection badges.",
+            "A valid install and allowed invocation policy do not prove model selection, correct workflow application, visual quality or owner approval.",
+        ],
+    };
+}

package/dist/skill-file.d.ts

@@ -0,0 +1,2 @@
+/** Read only bounded regular files inside the explicitly selected project. */
+export declare function readSkillFile(root: string, relative: string): Promise<string>;

package/dist/skill-file.js

@@ -0,0 +1,31 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { resolveProjectInput } from "./project-input.js";
+import { maxSkillBytes } from "./skill-metadata.js";
+/** Read only bounded regular files inside the explicitly selected project. */
+export async function readSkillFile(root, relative) {
+    const resolved = await resolveProjectInput(root, relative);
+    const handle = await open(resolved, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.size > maxSkillBytes) {
+            throw new Error("Skill input must be a regular file within the 128 KB limit");
+        }
+        const buffer = Buffer.alloc(maxSkillBytes + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+            if (!bytesRead) {
+                break;
+            }
+            length += bytesRead;
+        }
+        if (length > maxSkillBytes) {
+            throw new Error("Skill input exceeds the 128 KB limit");
+        }
+        return buffer.subarray(0, length).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/skill-instructions.d.ts

@@ -1,3 +1,7 @@
+export declare const skillInstructionMarkers: {
+    start: string;
+    end: string;
+};
 export interface InstructionReport {
     path: string | null;
     status: "not-selected" | "choice-required" | "unchanged" | "preview" | "written";