vigiles 2.0.0 → 2.2.0

package/dist/community-skills.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Ported community skills — proof that the generator form expresses the real,
+ * praised "agentic" skills (the deep tail the flat model can't hold), and that
+ * they are deterministically testable. Structural ports (not verbatim prose) of:
+ *
+ *  - devonjones/pr-review-loop — the corpus stress test: a bounded round loop
+ *    (7-round ceiling) with a quality-weighted exit, a per-finding for-each, and
+ *    a nested bounded CI retry sub-loop.
+ *  - test-driven-development (superpowers) — the red→green→refactor cycle.
+ *  - subagent-driven-development (superpowers) — per-task for-each with two
+ *    nested bounded review loops.
+ *
+ * These are exercised in community-skills.test.ts with a scripted model.
+ */
+import { type SkillProgram } from "./skill-driver.js";
+/** COLLECT → BATCH → FIX rounds; ceiling 7; exit when no actionable feedback. */
+export declare const prReviewLoop: SkillProgram;
+/** Red → Green → Refactor, once per behavior until done. */
+export declare const tdd: SkillProgram;
+/** Per task: bounded spec review, implement, bounded quality review, gate. */
+export declare const subagentDriven: SkillProgram;
+//# sourceMappingURL=community-skills.d.ts.map

package/dist/community-skills.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.subagentDriven = exports.tdd = exports.prReviewLoop = void 0;
+/**
+ * Ported community skills — proof that the generator form expresses the real,
+ * praised "agentic" skills (the deep tail the flat model can't hold), and that
+ * they are deterministically testable. Structural ports (not verbatim prose) of:
+ *
+ *  - devonjones/pr-review-loop — the corpus stress test: a bounded round loop
+ *    (7-round ceiling) with a quality-weighted exit, a per-finding for-each, and
+ *    a nested bounded CI retry sub-loop.
+ *  - test-driven-development (superpowers) — the red→green→refactor cycle.
+ *  - subagent-driven-development (superpowers) — per-task for-each with two
+ *    nested bounded review loops.
+ *
+ * These are exercised in community-skills.test.ts with a scripted model.
+ */
+const skill_driver_js_1 = require("./skill-driver.js");
+const spec_js_1 = require("./spec.js");
+/** COLLECT → BATCH → FIX rounds; ceiling 7; exit when no actionable feedback. */
+const prReviewLoop = function* () {
+    let round = 0;
+    for (;;) {
+        round++;
+        yield (0, skill_driver_js_1.act)("Collect all review comments on the PR");
+        yield (0, skill_driver_js_1.act)("Batch findings by file and severity");
+        for (;;) {
+            const next = yield (0, skill_driver_js_1.act)("Take the next P1/P2 finding, or say 'done'");
+            if (next === "done")
+                break;
+            yield (0, skill_driver_js_1.act)("Fix this finding");
+        }
+        let attempt = 0;
+        let ci = "fail";
+        while (attempt < 3 && ci !== "pass") {
+            attempt++;
+            ci = yield (0, skill_driver_js_1.act)("Run CI and report 'pass' or 'fail'");
+        }
+        yield (0, skill_driver_js_1.checkpoint)((0, spec_js_1.cmd)("true")); // CI must be green to continue the round
+        const more = yield (0, skill_driver_js_1.act)("Is there actionable (P1/P2) feedback left? 'yes'/'no'");
+        if (more === "no" || round >= 7)
+            break;
+    }
+    yield (0, skill_driver_js_1.finish)((0, spec_js_1.cmd)("true"));
+};
+exports.prReviewLoop = prReviewLoop;
+/** Red → Green → Refactor, once per behavior until done. */
+const tdd = function* () {
+    for (;;) {
+        const feature = yield (0, skill_driver_js_1.act)("Pick the next behavior to implement, or 'done'");
+        if (feature === "done")
+            break;
+        yield (0, skill_driver_js_1.act)("Write a failing test and watch it fail (RED)");
+        yield (0, skill_driver_js_1.act)("Write the minimum code to pass (GREEN)");
+        yield (0, skill_driver_js_1.checkpoint)((0, spec_js_1.cmd)("true")); // tests pass
+        yield (0, skill_driver_js_1.act)("Refactor while keeping tests green");
+        yield (0, skill_driver_js_1.checkpoint)((0, spec_js_1.cmd)("true")); // tests still pass
+    }
+    yield (0, skill_driver_js_1.finish)((0, spec_js_1.cmd)("true"));
+};
+exports.tdd = tdd;
+/** Per task: bounded spec review, implement, bounded quality review, gate. */
+const subagentDriven = function* () {
+    for (;;) {
+        const task = yield (0, skill_driver_js_1.act)("Take the next task from the plan, or 'done'");
+        if (task === "done")
+            break;
+        let a1 = 0;
+        let specOk = "no";
+        while (a1 < 3 && specOk !== "yes") {
+            a1++;
+            specOk = yield (0, skill_driver_js_1.act)("Dispatch a subagent to review the spec; approved? yes/no");
+        }
+        yield (0, skill_driver_js_1.act)("Implement the task");
+        let a2 = 0;
+        let qualityOk = "no";
+        while (a2 < 3 && qualityOk !== "yes") {
+            a2++;
+            qualityOk = yield (0, skill_driver_js_1.act)("Dispatch a subagent for quality review; approved? yes/no");
+        }
+        yield (0, skill_driver_js_1.checkpoint)((0, spec_js_1.cmd)("true"));
+    }
+    yield (0, skill_driver_js_1.finish)((0, spec_js_1.cmd)("true"));
+};
+exports.subagentDriven = subagentDriven;
+//# sourceMappingURL=community-skills.js.map

package/dist/compile-generator.d.ts

@@ -0,0 +1,48 @@
+/**
+ * vigiles — Generator → SKILL.md compiler.
+ *
+ * A generator skill (`function* () { … yield act/gate/result … }`) has dynamic
+ * control flow, so it can't be rendered by *executing* it. Instead we parse its
+ * SOURCE with the TypeScript compiler API and render the structure to markdown:
+ *
+ *   yield act("prose")            → a prose step
+ *   yield gate(cmd("npm test"))   → a `vigiles:gate` marker (+ verified ref)
+ *   yield result(cmd("npm test")) → a `vigiles:result` marker
+ *   if (cond) { … } else { … }    → "### If <cond>" / "### Otherwise"
+ *   for / while (…) { … }         → "### Repeat (…)"
+ *
+ * The emitted SKILL.md is what the agent reads (branches flattened to prose);
+ * the harness drives the real generator at run time (see `skill-driver.ts`).
+ * Gate references (`cmd`/`file`/`project`) are collected and verified, so the
+ * cross-referencing moat works on generators too (literal args only).
+ */
+export interface GeneratorError {
+    type: "stale-file" | "stale-command";
+    message: string;
+}
+export interface CompileGeneratorResult {
+    markdown: string;
+    errors: GeneratorError[];
+}
+export interface CompileGeneratorSkillResult {
+    markdown: string;
+    errors: GeneratorError[];
+}
+/**
+ * Compile a generator-skill spec source — `genSkill({ name, description },
+ * function* () { … })` — to a full SKILL.md (frontmatter + body + integrity
+ * hash), verifying gate references. This is the CLI entry for generator skills.
+ */
+export declare function compileGeneratorSkill(source: string, options?: {
+    basePath?: string;
+    specFile?: string;
+}): CompileGeneratorSkillResult;
+/**
+ * Compile a generator's SOURCE text to SKILL.md markdown + verified-ref
+ * errors. `frontmatter` (name/description/…) is prepended verbatim if given.
+ */
+export declare function compileGenerator(source: string, options?: {
+    basePath?: string;
+    frontmatter?: string;
+}): CompileGeneratorResult;
+//# sourceMappingURL=compile-generator.d.ts.map

package/dist/compile-generator.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * vigiles — Generator → SKILL.md compiler.
+ *
+ * A generator skill (`function* () { … yield act/gate/result … }`) has dynamic
+ * control flow, so it can't be rendered by *executing* it. Instead we parse its
+ * SOURCE with the TypeScript compiler API and render the structure to markdown:
+ *
+ *   yield act("prose")            → a prose step
+ *   yield gate(cmd("npm test"))   → a `vigiles:gate` marker (+ verified ref)
+ *   yield result(cmd("npm test")) → a `vigiles:result` marker
+ *   if (cond) { … } else { … }    → "### If <cond>" / "### Otherwise"
+ *   for / while (…) { … }         → "### Repeat (…)"
+ *
+ * The emitted SKILL.md is what the agent reads (branches flattened to prose);
+ * the harness drives the real generator at run time (see `skill-driver.ts`).
+ * Gate references (`cmd`/`file`/`project`) are collected and verified, so the
+ * cross-referencing moat works on generators too (literal args only).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileGeneratorSkill = compileGeneratorSkill;
+exports.compileGenerator = compileGenerator;
+const typescript_1 = __importDefault(require("typescript"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const compile_js_1 = require("./compile.js");
+/** Find the first generator function (`function*`) in a source file. */
+function findGenerator(sf) {
+    let found = null;
+    const visit = (n) => {
+        if (found)
+            return;
+        if ((typescript_1.default.isFunctionExpression(n) || typescript_1.default.isFunctionDeclaration(n)) &&
+            n.asteriskToken) {
+            found = n;
+            return;
+        }
+        typescript_1.default.forEachChild(n, visit);
+    };
+    visit(sf);
+    return found;
+}
+/** The called function's name, handling both `act(...)` and `ns.act(...)`. */
+function calleeName(call) {
+    const e = call.expression;
+    if (typescript_1.default.isIdentifier(e))
+        return e.text;
+    if (typescript_1.default.isPropertyAccessExpression(e))
+        return e.name.text;
+    return "";
+}
+/** A `cmd("…")` / `file("…")` / `project("…")` call → a gate reference. */
+function extractGateRef(node) {
+    if (!node || !typescript_1.default.isCallExpression(node))
+        return null;
+    const name = calleeName(node);
+    const a = node.arguments[0];
+    if (!a || !typescript_1.default.isStringLiteralLike(a))
+        return null;
+    if (name === "cmd")
+        return { kind: "cmd", value: a.text };
+    if (name === "file")
+        return { kind: "file", value: a.text };
+    if (name === "project")
+        return { kind: "role", value: a.text };
+    return null;
+}
+/** The first YieldExpression inside a statement (e.g. `const x = yield act(...)`). */
+function findYield(node) {
+    let y = null;
+    const visit = (n) => {
+        if (y)
+            return;
+        if (typescript_1.default.isYieldExpression(n)) {
+            y = n;
+            return;
+        }
+        typescript_1.default.forEachChild(n, visit);
+    };
+    visit(node);
+    return y;
+}
+function gateMarker(ref, terminal) {
+    const kind = terminal ? "result" : "gate";
+    if (ref.kind === "cmd")
+        return `<!-- vigiles:${kind} "${ref.value}" -->`;
+    if (ref.kind === "role")
+        return `<!-- vigiles:${kind} role:${ref.value} -->`;
+    return `<!-- vigiles:${kind} file:${ref.value} -->`;
+}
+function gateLabel(ref) {
+    if (ref.kind === "cmd")
+        return `\`${ref.value}\``;
+    if (ref.kind === "role")
+        return `the project's ${ref.value} command`;
+    return `${ref.value} exists`;
+}
+/** Render a single `yield act/gate/result(...)` into markdown lines. */
+function renderYield(y, lines, refs) {
+    const call = y.expression;
+    if (!call || !typescript_1.default.isCallExpression(call))
+        return;
+    const name = calleeName(call);
+    if (name === "act") {
+        const a = call.arguments[0];
+        if (a && typescript_1.default.isStringLiteralLike(a))
+            lines.push(a.text.trim(), "");
+        return;
+    }
+    const terminal = name === "finish" || name === "result";
+    if (!terminal && name !== "gate" && name !== "checkpoint")
+        return;
+    const ref = extractGateRef(call.arguments[0]);
+    if (!ref)
+        return;
+    refs.push(ref);
+    if (terminal) {
+        lines.push("## Result", "", `Done when ${gateLabel(ref)} passes.`, "", gateMarker(ref, true), "");
+    }
+    else {
+        lines.push(`**Gate** — ${gateLabel(ref)}; do not proceed until it passes.`, "", gateMarker(ref, false), "");
+    }
+}
+/** A renderer bound to one source file (for `getText` of conditions). */
+function makeRenderer(sf, refs) {
+    const lines = [];
+    const renderBlock = (stmt) => {
+        if (typescript_1.default.isBlock(stmt))
+            renderStatements(stmt.statements);
+        else
+            renderStatements([stmt]);
+    };
+    const renderIf = (s) => {
+        lines.push(`### If ${s.expression.getText(sf)}`, "");
+        renderBlock(s.thenStatement);
+        if (s.elseStatement) {
+            if (typescript_1.default.isIfStatement(s.elseStatement)) {
+                renderIf(s.elseStatement);
+            }
+            else {
+                lines.push(`### Otherwise`, "");
+                renderBlock(s.elseStatement);
+            }
+        }
+    };
+    const renderLoop = (s) => {
+        let header = "each iteration";
+        if (typescript_1.default.isWhileStatement(s))
+            header = `while ${s.expression.getText(sf)}`;
+        else if (typescript_1.default.isForOfStatement(s))
+            header = `for each item in ${s.expression.getText(sf)}`;
+        lines.push(`### Repeat (${header})`, "");
+        renderBlock(s.statement);
+    };
+    function renderStatements(stmts) {
+        for (const s of stmts) {
+            if (typescript_1.default.isVariableStatement(s) || typescript_1.default.isExpressionStatement(s)) {
+                const y = findYield(s);
+                if (y) {
+                    renderYield(y, lines, refs);
+                    continue;
+                }
+            }
+            if (typescript_1.default.isIfStatement(s)) {
+                renderIf(s);
+                continue;
+            }
+            if (typescript_1.default.isForStatement(s) ||
+                typescript_1.default.isForOfStatement(s) ||
+                typescript_1.default.isWhileStatement(s) ||
+                typescript_1.default.isDoStatement(s)) {
+                renderLoop(s);
+                continue;
+            }
+            // Other statements (plain logic, returns) carry no prose to render.
+        }
+    }
+    return {
+        run(body) {
+            renderStatements(body.statements);
+            return lines.join("\n").trimEnd();
+        },
+    };
+}
+/** Verify a collected gate reference against the project at `basePath`. */
+function verifyRef(ref, basePath) {
+    if (ref.kind === "file") {
+        return (0, node_fs_1.existsSync)((0, node_path_1.resolve)(basePath, ref.value))
+            ? null
+            : { type: "stale-file", message: `File not found: "${ref.value}"` };
+    }
+    if (ref.kind === "role")
+        return null; // resolved per host project at run time
+    // cmd: npm script or script-runner file
+    const npm = ref.value.match(/^npm\s+run\s+(\S+)/)?.[1];
+    if (npm) {
+        const scripts = (0, compile_js_1.readPackageScripts)(basePath);
+        return scripts && !scripts[npm]
+            ? {
+                type: "stale-command",
+                message: `Script "${npm}" not found in package.json`,
+            }
+            : null;
+    }
+    const scriptFile = ref.value.match(/^(?:python3?|node|bash|sh|ruby|deno run)\s+([^\s-]\S*\.[A-Za-z0-9]+)/)?.[1];
+    if (scriptFile && !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(basePath, scriptFile))) {
+        return {
+            type: "stale-command",
+            message: `Script "${scriptFile}" not found`,
+        };
+    }
+    return null;
+}
+/** Find the `genSkill({…}, function* () {…})` call in a source file. */
+function findGenSkillCall(sf) {
+    let found = null;
+    const visit = (n) => {
+        if (found)
+            return;
+        if (typescript_1.default.isCallExpression(n) && calleeName(n) === "genSkill") {
+            found = n;
+            return;
+        }
+        typescript_1.default.forEachChild(n, visit);
+    };
+    visit(sf);
+    return found;
+}
+/** Extract name/description/disable-model-invocation from a meta object literal. */
+function extractMeta(obj) {
+    const meta = {};
+    for (const p of obj.properties) {
+        if (!typescript_1.default.isPropertyAssignment(p) || !typescript_1.default.isIdentifier(p.name))
+            continue;
+        const key = p.name.text;
+        const v = p.initializer;
+        if (typescript_1.default.isStringLiteralLike(v)) {
+            if (key === "name")
+                meta.name = v.text;
+            else if (key === "description")
+                meta.description = v.text;
+        }
+        else if (key === "disableModelInvocation") {
+            meta.disableModelInvocation = v.kind === typescript_1.default.SyntaxKind.TrueKeyword;
+        }
+    }
+    return meta;
+}
+/**
+ * Compile a generator-skill spec source — `genSkill({ name, description },
+ * function* () { … })` — to a full SKILL.md (frontmatter + body + integrity
+ * hash), verifying gate references. This is the CLI entry for generator skills.
+ */
+function compileGeneratorSkill(source, options = {}) {
+    const basePath = options.basePath ?? process.cwd();
+    const specFile = options.specFile ?? "SKILL.md.spec.ts";
+    const sf = typescript_1.default.createSourceFile("s.ts", source, typescript_1.default.ScriptTarget.Latest, true);
+    const call = findGenSkillCall(sf);
+    const metaArg = call?.arguments[0];
+    const genArg = call?.arguments[1];
+    if (!metaArg ||
+        !typescript_1.default.isObjectLiteralExpression(metaArg) ||
+        !genArg ||
+        !typescript_1.default.isFunctionExpression(genArg) ||
+        !genArg.asteriskToken ||
+        !genArg.body) {
+        return {
+            markdown: "",
+            errors: [
+                {
+                    type: "stale-command",
+                    message: "Expected `genSkill({ name, description }, function* () { … })`.",
+                },
+            ],
+        };
+    }
+    const meta = extractMeta(metaArg);
+    const refs = [];
+    const body = makeRenderer(sf, refs).run(genArg.body);
+    const errors = refs
+        .map((r) => verifyRef(r, basePath))
+        .filter((e) => e !== null);
+    const fm = ["---", "", `name: ${meta.name ?? ""}`];
+    if (meta.description)
+        fm.push(`description: ${meta.description}`);
+    if (meta.disableModelInvocation !== undefined) {
+        fm.push(`disable-model-invocation: ${String(meta.disableModelInvocation)}`);
+    }
+    fm.push("", "---");
+    const content = `${fm.join("\n")}\n\n${body.trim()}\n`;
+    return { markdown: (0, compile_js_1.addHash)(content, specFile), errors };
+}
+/**
+ * Compile a generator's SOURCE text to SKILL.md markdown + verified-ref
+ * errors. `frontmatter` (name/description/…) is prepended verbatim if given.
+ */
+function compileGenerator(source, options = {}) {
+    const basePath = options.basePath ?? process.cwd();
+    const sf = typescript_1.default.createSourceFile("skill.ts", source, typescript_1.default.ScriptTarget.Latest, true);
+    const gen = findGenerator(sf);
+    if (!gen?.body) {
+        return {
+            markdown: "",
+            errors: [
+                { type: "stale-command", message: "No generator function found." },
+            ],
+        };
+    }
+    const refs = [];
+    const body = makeRenderer(sf, refs).run(gen.body);
+    const errors = refs
+        .map((r) => verifyRef(r, basePath))
+        .filter((e) => e !== null);
+    const markdown = options.frontmatter
+        ? `${options.frontmatter.trim()}\n\n${body}\n`
+        : `${body}\n`;
+    return { markdown, errors };
+}
+//# sourceMappingURL=compile-generator.js.map

package/dist/compile.d.ts

@@ -28,6 +28,10 @@ export interface CompileError {
     message: string;
     path?: string;
 }
+export declare function validateFileRef(filePath: string, basePath: string): CompileError | null;
+export declare function readPackageScripts(basePath: string): Record<string, string> | null;
+export declare function validateCommandRef(command: string, basePath: string): CompileError | null;
+export declare function validateSymbolRef(file: string, name: string, basePath: string): CompileError | null;
 export interface CompileClaudeResult {
     markdown: string;
     errors: CompileError[];