@vekexasia/fucina 0.0.0

package/README.md

@@ -0,0 +1,78 @@
+# Fucina
+
+Issue dentro, PR fuori.
+
+Fucina is a thin layer over Sandcastle for label-driven AI workflows on GitHub.com repositories. Fucina owns labels, GitHub workflow conventions, prompts, configuration loading, and CLI setup; Sandcastle owns agent execution, sandboxing, branch strategy, sessions, and provider integration.
+
+## MVP labels
+
+Operational trigger labels are one-shot buttons: Fucina removes only the label that triggered the run when that run starts.
+
+- `fucina:explore` - analyze an open issue and comment with findings
+- `fucina:implement` - implement an open issue and create a draft PR
+- `fucina:review` - publish a read-only GitHub PR Review
+- `fucina:address-feedback` - address feedback on an internal PR branch
+- `fucina:in-progress` - visible running state
+- `fucina:blocked` - last run failed or was refused; removed on retry
+
+There is no MVP readiness label, `fucina:queued`, or `fucina:update-branch`. Runs share repository-wide GitHub Actions concurrency with `cancel-in-progress: false`, so GitHub Actions is the queue.
+
+## Install in a repo
+
+```bash
+npx @vekexasia/fucina@<version> install
+```
+
+`fucina install` writes workflows and `.fucina/config.json`, creates or updates labels, never commits, and does not overwrite existing files without confirmation or `--force`. Use `install-labels` only for label maintenance.
+
+Target repositories pin Fucina in the generated workflows with `npx @vekexasia/fucina@<version>`; Fucina is not a repository dependency.
+
+## Configuration
+
+Fucina reads environment variables first, then optional `.fucina/config.json`. Required values must come from one of those sources.
+
+Minimum config keys:
+
+- `agent` - one of Sandcastle providers `claudeCode`, `codex`, or `pi`
+- `model`
+- `agentCliVersion` - pinned CLI version installed by Fucina
+- `maxIterations` - optional, defaults to `1`
+
+Optional repository variable:
+
+- `FUCINA_ALLOWED_ACTORS` - comma-separated GitHub usernames allowed to run Fucina. When omitted, Fucina allows repository collaborators with write, maintain, or admin permission.
+
+Optional secret:
+
+- `AGENT_PAT` - Fucina uses `AGENT_PAT || GITHUB_TOKEN` and fails clearly when a PAT is required.
+
+## Sensitive instruction path protection
+
+Fucina protects files that can influence agent instructions from prompt injection by untrusted PR authors.
+
+The `sensitiveInstructionPaths` config key defaults to:
+- `.fucina/**`
+- `.github/workflows/**`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.claude/**`
+- `.codex/**`
+- `.pi/**`
+
+This list can be completely overridden in `.fucina/config.json`, but not via environment variables.
+
+When `fucina:review` runs on a PR:
+1. If the PR modifies files matching sensitive paths AND the PR author is not an Authorized Actor, the review blocks with `fucina:blocked`
+2. An error comment is posted with the exact command to approve: `/fucina trust-instructions <full-sha>`
+3. An Authorized Actor can post that slash command as a PR comment to explicitly trust the changes
+4. The approval is SHA-specific; if the PR is updated, a new approval is required
+
+This prevents untrusted contributors from injecting malicious instructions into agent workflows while allowing Authorized Actors to explicitly review and approve instruction changes.
+
+## Local development
+
+```bash
+npm install
+npm run typecheck
+npm run build
+```

package/dist/agent.js

@@ -0,0 +1,54 @@
+import { execFileSync } from "node:child_process";
+import { claudeCode, codex, pi, run as sandcastleRun } from "@ai-hero/sandcastle";
+import { noSandbox } from "@ai-hero/sandcastle/sandboxes/no-sandbox";
+import { loadConfig } from "./config.js";
+export async function runAgent(prompt, cwd = process.cwd()) {
+    if (process.env.FUCINA_SIMULATE_AGENT_OUTPUT)
+        return { stdout: process.env.FUCINA_SIMULATE_AGENT_OUTPUT, commits: [], branch: "simulated" };
+    const config = loadConfig(cwd);
+    installAgentCli(config.agent, config.agentCliVersion);
+    const agent = config.agent === "claudeCode" ? claudeCode(config.model) : config.agent === "codex" ? codex(config.model) : pi(config.model);
+    return sandcastleRun({ agent, sandbox: noSandbox(), cwd, prompt, maxIterations: config.maxIterations, logging: { type: "stdout" } });
+}
+export function agentCliPackage(agent) {
+    return agent === "claudeCode" ? "@anthropic-ai/claude-code" : undefined;
+}
+export function installAgentCli(agent, version) {
+    const pkg = agentCliPackage(agent);
+    if (pkg)
+        execFileSync("npm", ["install", "-g", `${pkg}@${version}`], { stdio: "inherit" });
+}
+export function parseFucinaJson(stdout) {
+    const match = stdout.match(/<fucina>([\s\S]*?)<\/fucina>/);
+    if (!match)
+        throw new Error("Agent output did not include <fucina> JSON");
+    let parsed;
+    try {
+        parsed = JSON.parse(match[1]);
+    }
+    catch (error) {
+        const summary = match[1].match(/"summary"\s*:\s*"([\s\S]*)"\s*}/)?.[1];
+        if (summary !== undefined)
+            parsed = { summary };
+        else
+            throw new Error(`Agent output <fucina> JSON was malformed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error("Agent output must be a JSON object");
+    const output = parsed;
+    if (typeof output.summary !== "string")
+        throw new Error("Agent output summary must be a string");
+    if (output.prUrl !== undefined && typeof output.prUrl !== "string")
+        throw new Error("Agent output prUrl must be a string");
+    return output;
+}
+export async function runFucinaAgent(agent, prompt) {
+    const result = await agent(prompt);
+    try {
+        return { result, parsed: parseFucinaJson(result.stdout) };
+    }
+    catch (error) {
+        const retry = await agent(`${prompt}\n\nYour previous output was invalid: ${error instanceof Error ? error.message : String(error)}. Return only <fucina>{"summary":"..."}</fucina>.`);
+        return { result: retry, parsed: parseFucinaJson(retry.stdout) };
+    }
+}

package/dist/auth.js

@@ -0,0 +1,33 @@
+import { gh } from "./gh.js";
+const writePermissions = new Set(["admin", "maintain", "write"]);
+export function assertAuthorized(event) {
+    return assertAuthorizedWithGh(event, gh);
+}
+export function assertAuthorizedWithGh(event, runGh) {
+    const allowed = process.env.FUCINA_ALLOWED_ACTORS?.split(",").map((name) => name.trim()).filter(Boolean);
+    if (allowed?.length) {
+        if (!allowed.includes(event.actor))
+            throw new Error(`${event.actor} is not allowed to run Fucina`);
+        return;
+    }
+    const repo = process.env.GITHUB_REPOSITORY ?? "OWNER/REPO";
+    const output = runGh(["api", `repos/${repo}/collaborators/${event.actor}/permission`, "--jq", ".permission"]).trim();
+    const value = output.startsWith("{") ? JSON.parse(output).permission : output;
+    if (!writePermissions.has(value))
+        throw new Error(`${event.actor} does not have write access to ${repo}`);
+}
+export function isAuthorizedActor(actor, runGh) {
+    try {
+        const allowed = process.env.FUCINA_ALLOWED_ACTORS?.split(",").map((name) => name.trim()).filter(Boolean);
+        if (allowed?.length) {
+            return allowed.includes(actor);
+        }
+        const repo = process.env.GITHUB_REPOSITORY ?? "OWNER/REPO";
+        const output = runGh(["api", `repos/${repo}/collaborators/${actor}/permission`, "--jq", ".permission"]).trim();
+        const value = output.startsWith("{") ? JSON.parse(output).permission : output;
+        return writePermissions.has(value);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { installLabels } from "./install-labels.js";
+import { install, upgrade } from "./install.js";
+import { run } from "./run.js";
+const command = process.argv[2];
+const force = process.argv.includes("--force");
+try {
+    if (command === "install")
+        install({ force });
+    else if (command === "upgrade")
+        upgrade({ force: true });
+    else if (command === "install-labels")
+        installLabels();
+    else if (command === "run")
+        await run();
+    else {
+        console.error("Usage: fucina <install|upgrade|install-labels|run> [--force]");
+        process.exit(1);
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+}

package/dist/comment.js

@@ -0,0 +1,3 @@
+export function withRunLink(body, runUrl) {
+    return runUrl ? `${body}\n\nWorkflow run: ${runUrl}` : body;
+}

package/dist/config.js

@@ -0,0 +1,22 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export const defaultSensitiveInstructionPaths = [".fucina/**", ".github/workflows/**", "AGENTS.md", "CLAUDE.md", ".claude/**", ".codex/**", ".pi/**"];
+export function loadConfig(cwd = process.cwd()) {
+    const path = join(cwd, ".fucina/config.json");
+    const file = existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+    const env = (name) => process.env[name]?.trim() || undefined;
+    const config = {
+        agent: env("FUCINA_AGENT") ?? file.agent,
+        model: env("FUCINA_MODEL") ?? file.model,
+        agentCliVersion: env("FUCINA_AGENT_CLI_VERSION") ?? file.agentCliVersion,
+        maxIterations: Number(env("FUCINA_MAX_ITERATIONS") ?? file.maxIterations ?? 1),
+        sensitiveInstructionPaths: Array.isArray(file.sensitiveInstructionPaths) ? file.sensitiveInstructionPaths : defaultSensitiveInstructionPaths,
+    };
+    if (!["claudeCode", "codex", "pi"].includes(config.agent))
+        throw new Error("FUCINA_AGENT or .fucina/config.json agent must be claudeCode, codex, or pi");
+    if (!config.model)
+        throw new Error("FUCINA_MODEL or .fucina/config.json model is required");
+    if (!config.agentCliVersion)
+        throw new Error("FUCINA_AGENT_CLI_VERSION or .fucina/config.json agentCliVersion is required");
+    return config;
+}

package/dist/event.js

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+export function readEvent() {
+    const path = process.env.GITHUB_EVENT_PATH;
+    if (!path)
+        throw new Error("GITHUB_EVENT_PATH is missing");
+    const event = JSON.parse(readFileSync(path, "utf8"));
+    const actor = event.sender?.login;
+    if (typeof actor !== "string")
+        throw new Error("Event has no sender login");
+    if (event.comment) {
+        const body = event.comment.body;
+        if (typeof body === "string" && body.trim().startsWith("/fucina ")) {
+            const label = body.trim().split("\n")[0];
+            if (event.issue) {
+                const isPR = !!event.issue.pull_request;
+                return { label, actor, kind: isPR ? "pull_request" : "issue", number: event.issue.number, title: event.issue.title, body: event.issue.body };
+            }
+        }
+    }
+    const label = event.label?.name;
+    if (typeof label !== "string")
+        throw new Error("Event has no label name");
+    if (event.issue) {
+        return { label, actor, kind: "issue", number: event.issue.number, title: event.issue.title, body: event.issue.body };
+    }
+    if (event.pull_request) {
+        return { label, actor, kind: "pull_request", number: event.pull_request.number, title: event.pull_request.title, body: event.pull_request.body };
+    }
+    throw new Error("Unsupported GitHub event");
+}

package/dist/gh.js

@@ -0,0 +1,13 @@
+import { execFileSync } from "node:child_process";
+export function gh(args) {
+    return execFileSync("gh", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+}
+export function ghOk(args) {
+    try {
+        gh(args);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/install-labels.js

@@ -0,0 +1,11 @@
+import { labels } from "./labels.js";
+import { ghOk } from "./gh.js";
+export function installLabels() {
+    for (const [name, description, color] of labels) {
+        const updated = ghOk(["label", "edit", name, "--description", description, "--color", color]);
+        if (!updated) {
+            ghOk(["label", "create", name, "--description", description, "--color", color]);
+        }
+        console.log(name);
+    }
+}

package/dist/install.js

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { defaultSensitiveInstructionPaths } from "./config.js";
+import { installLabels } from "./install-labels.js";
+const require = createRequire(import.meta.url);
+const version = require("../package.json").version;
+export function install(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    writeNew(join(cwd, ".fucina/config.json"), JSON.stringify({ agent: "", model: "", agentCliVersion: "", maxIterations: 1, sensitiveInstructionPaths: defaultSensitiveInstructionPaths }, null, 2) + "\n", options.force);
+    writeNew(join(cwd, ".github/workflows/fucina-issue.yml"), workflow("issues", "issues: write\n      pull-requests: write\n      contents: write", ["fucina:explore", "fucina:implement"]), options.force);
+    writeNew(join(cwd, ".github/workflows/fucina-review.yml"), workflow("pull_request_target", "contents: read\n      pull-requests: write\n      issues: write", ["fucina:review"], false), options.force);
+    writeNew(join(cwd, ".github/workflows/fucina-mutate.yml"), workflow("pull_request_target", "contents: write\n      pull-requests: write\n      issues: write", ["fucina:address-feedback"], false), options.force);
+    writeNew(join(cwd, ".github/workflows/fucina-slash.yml"), slashWorkflow(), options.force);
+    if (!options.skipLabels)
+        installLabels();
+}
+export function upgrade(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const configPath = join(cwd, ".fucina/config.json");
+    const current = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf8")) : {};
+    const next = { ...{ agent: "", model: "", agentCliVersion: "", maxIterations: 1, sensitiveInstructionPaths: defaultSensitiveInstructionPaths }, ...current };
+    writeNew(configPath, JSON.stringify(next, null, 2) + "\n", true);
+    writeNew(join(cwd, ".github/workflows/fucina-issue.yml"), workflow("issues", "issues: write\n      pull-requests: write\n      contents: write", ["fucina:explore", "fucina:implement"]), true);
+    writeNew(join(cwd, ".github/workflows/fucina-review.yml"), workflow("pull_request_target", "contents: read\n      pull-requests: write\n      issues: write", ["fucina:review"], false), true);
+    writeNew(join(cwd, ".github/workflows/fucina-mutate.yml"), workflow("pull_request_target", "contents: write\n      pull-requests: write\n      issues: write", ["fucina:address-feedback"], false), true);
+    writeNew(join(cwd, ".github/workflows/fucina-slash.yml"), slashWorkflow(), true);
+    if (!options.skipLabels)
+        installLabels();
+}
+function writeNew(path, content, force = false) {
+    if (existsSync(path) && !force)
+        throw new Error(`Refusing to overwrite ${path}; rerun with --force`);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content);
+}
+function workflow(event, permissions, labels, checkout = true) {
+    return `name: Fucina ${event === "issues" ? "Issue" : labels[0] === "fucina:review" ? "Review" : "Mutation"}
+
+on:
+  ${event}:
+    types: [labeled]
+
+concurrency:
+  group: fucina-\${{ github.repository }}
+  cancel-in-progress: false
+
+permissions:
+      ${permissions}
+
+jobs:
+  fucina:
+    if: \${{ ${labels.map((label) => `github.event.label.name == '${label}'`).join(" || ")} }}
+    runs-on: ubuntu-latest
+    steps:
+${checkout ? `      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+` : ""}      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Run Fucina
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: \${{ secrets.AGENT_PAT || secrets.GITHUB_TOKEN }}
+          AGENT_PAT: \${{ secrets.AGENT_PAT }}
+          CLAUDE_CODE_OAUTH_TOKEN: \${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          FUCINA_ALLOWED_ACTORS: \${{ vars.FUCINA_ALLOWED_ACTORS }}
+          FUCINA_AGENT: \${{ vars.FUCINA_AGENT }}
+          FUCINA_MODEL: \${{ vars.FUCINA_MODEL }}
+          FUCINA_AGENT_CLI_VERSION: \${{ vars.FUCINA_AGENT_CLI_VERSION }}
+          FUCINA_MAX_ITERATIONS: \${{ vars.FUCINA_MAX_ITERATIONS }}
+        run: npx @vekexasia/fucina@${version} run
+`;
+}
+function slashWorkflow() {
+    return `name: Fucina Slash Command
+
+on:
+  issue_comment:
+    types: [created]
+
+concurrency:
+  group: fucina-\${{ github.repository }}
+  cancel-in-progress: false
+
+permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+
+jobs:
+  fucina:
+    if: \${{ startsWith(github.event.comment.body, '/fucina ') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Run Fucina Slash Command
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: \${{ secrets.AGENT_PAT || secrets.GITHUB_TOKEN }}
+          AGENT_PAT: \${{ secrets.AGENT_PAT }}
+          FUCINA_ALLOWED_ACTORS: \${{ vars.FUCINA_ALLOWED_ACTORS }}
+        run: npx @vekexasia/fucina@${version} run
+`;
+}

package/dist/instructions.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+const modePrompts = {
+    explore: "Explore this issue read-only. Report difficulty, relevant files, verified claims, open questions, and a possible approach. Do not edit files.",
+    implement: "Implement the issue with the smallest correct change. Run the project checks. Commit with a conventional commit message. Do not push.",
+    review: "Review the PR read-only. Publish comments and a summary. Do not edit files, commit, or push. If changes are needed, explain them so the owner can add `fucina:address-feedback`.",
+};
+const maxInstructionBytes = 64 * 1024;
+export function composeAgentPrompt(mode, taskPrompt, cwd = process.cwd()) {
+    return [modePrompts[mode], loadInstructions(mode, cwd), taskPrompt].filter(Boolean).join("\n\n");
+}
+function loadInstructions(mode, cwd) {
+    const dir = join(cwd, ".fucina/instructions");
+    return ["safety", "global", mode].map((name) => readInstruction(join(dir, `${name}.md`))).filter(Boolean).join("\n\n");
+}
+function readInstruction(path) {
+    if (!existsSync(path))
+        return "";
+    try {
+        const stat = statSync(path);
+        if (!stat.isFile())
+            throw new Error("is not a file");
+        if (stat.size > maxInstructionBytes)
+            throw new Error(`is too large (${stat.size} bytes, max ${maxInstructionBytes})`);
+        const text = readFileSync(path, "utf8");
+        if (text.includes("\0"))
+            throw new Error("must be a markdown text file");
+        return text.trim();
+    }
+    catch (error) {
+        throw new Error(`Cannot load Fucina instruction ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/labels.js

@@ -0,0 +1,8 @@
+export const labels = [
+    ["fucina:explore", "Run read-only exploration", "0E8A16"],
+    ["fucina:implement", "Run implementation", "0E8A16"],
+    ["fucina:review", "Run automated PR review", "0E8A16"],
+    ["fucina:address-feedback", "Address review feedback on a PR", "0E8A16"],
+    ["fucina:in-progress", "Fucina workflow is running", "FBCA04"],
+    ["fucina:blocked", "Fucina workflow is blocked or failed", "D73A4A"],
+];

package/dist/modes/address-feedback.js

@@ -0,0 +1,23 @@
+import { execFileSync } from "node:child_process";
+import { runAgent, runFucinaAgent } from "../agent.js";
+import { withRunLink } from "../comment.js";
+export async function addressFeedback(event, deps) {
+    if (event.kind !== "pull_request")
+        throw new Error("fucina:address-feedback only runs on PRs");
+    const pr = JSON.parse(deps.gh(["pr", "view", String(event.number), "--json", "headRepositoryOwner,baseRepositoryOwner,headRefName,headRefOid,isCrossRepository"]));
+    if (pr.isCrossRepository)
+        throw new Error("Fucina mutation refuses PRs from forks");
+    const comments = deps.gh(["pr", "view", String(event.number), "--comments"]);
+    const { result, parsed } = await runFucinaAgent(deps.agent, `Address unresolved feedback on internal PR #${event.number}: ${event.title}\n\n${comments}\n\nReturn <fucina>{"summary":"..."}</fucina>.`);
+    if (!result.commits.length && !parsed.summary.trim())
+        throw new Error("Fucina address-feedback produced no useful commit or comment");
+    if (result.commits.length) {
+        const sh = deps.sh ?? ((args) => execFileSync(args[0], args.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] }));
+        sh(["git", "push", `--force-with-lease=${pr.headRefName}:${pr.headRefOid}`, "origin", `HEAD:${pr.headRefName}`]);
+    }
+    if (parsed.summary.trim())
+        deps.gh(["pr", "comment", String(event.number), "--body", withRunLink(parsed.summary, deps.runUrl)]);
+}
+export async function addressFeedbackDefault(event) {
+    return addressFeedback(event, { gh: () => "", agent: (prompt) => runAgent(prompt) });
+}

package/dist/modes/explore.js

@@ -0,0 +1,9 @@
+import { runAgent, runFucinaAgent } from "../agent.js";
+import { withRunLink } from "../comment.js";
+export async function explore(event, deps) {
+    const { parsed } = await runFucinaAgent(deps.agent, `Explore issue #${event.number}: ${event.title}\n\n${event.body ?? ""}\n\nReturn <fucina>{"summary":"..."}</fucina>.`);
+    deps.gh(["issue", "comment", String(event.number), "--body", withRunLink(parsed.summary, deps.runUrl)]);
+}
+export async function exploreDefault(event) {
+    return explore(event, { gh: () => "", agent: (prompt) => runAgent(prompt) });
+}

package/dist/modes/implement.js

@@ -0,0 +1,31 @@
+import { execFileSync } from "node:child_process";
+import { runAgent, runFucinaAgent } from "../agent.js";
+import { withRunLink } from "../comment.js";
+export async function implement(event, deps) {
+    if (event.kind !== "issue")
+        throw new Error("fucina:implement only runs on issues");
+    const state = deps.gh(["issue", "view", String(event.number), "--json", "state", "--jq", ".state"]).trim().toUpperCase();
+    if (state && state !== "OPEN")
+        throw new Error(`Fucina implement issue #${event.number} is not open`);
+    const comments = deps.gh(["issue", "view", String(event.number), "--comments"]);
+    const { result, parsed } = await runFucinaAgent(deps.agent, `Implement issue #${event.number}: ${event.title}\n\nIssue body:\n${event.body ?? ""}\n\nIssue comments:\n${comments}\n\nIf the requested work is GitHub-side bookkeeping, do it with gh and return a summary. Do not close issue #${event.number}; Fucina relies on PR merge/Closes for closure. Return <fucina>{"summary":"..."}</fucina>.`);
+    try {
+        deps.gh(["issue", "reopen", String(event.number)]);
+    }
+    catch { }
+    const sh = deps.sh ?? ((args) => execFileSync(args[0], args.slice(1), { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"] }));
+    const commitsAhead = Number(sh(["git", "rev-list", "--count", "origin/main..HEAD"]).trim());
+    if (!result.commits.length || !Number.isFinite(commitsAhead) || commitsAhead === 0) {
+        deps.gh(["issue", "comment", String(event.number), "--body", withRunLink(parsed.summary, deps.runUrl)]);
+        return;
+    }
+    const slug = event.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "work";
+    const branch = `fucina/issue-${event.number}-${slug}`;
+    sh(["git", "checkout", "-B", branch]);
+    sh(["git", "push", "--force-with-lease", "origin", branch]);
+    deps.gh(["pr", "create", "--draft", "--head", branch, "--title", `Implement #${event.number}: ${event.title}`, "--body", `Closes #${event.number}`]);
+    deps.gh(["issue", "comment", String(event.number), "--body", withRunLink(parsed.prUrl ?? parsed.summary, deps.runUrl)]);
+}
+export async function implementDefault(event) {
+    return implement(event, { gh: () => "", agent: (prompt) => runAgent(prompt) });
+}

package/dist/modes/review.js

@@ -0,0 +1,29 @@
+import { runAgent, runFucinaAgent } from "../agent.js";
+import { withRunLink } from "../comment.js";
+import { loadConfig } from "../config.js";
+import { isAuthorizedActor } from "../auth.js";
+import { getSensitiveFiles } from "../sensitive-paths.js";
+export async function review(event, deps) {
+    if (event.kind !== "pull_request")
+        throw new Error("fucina:review only runs on PRs");
+    const pr = JSON.parse(deps.gh(["api", `repos/${process.env.GITHUB_REPOSITORY}/pulls/${event.number}`, "--jq", "."]));
+    const prAuthor = pr.user.login;
+    const headSha = pr.head.sha;
+    const config = loadConfig(deps.cwd);
+    const filesData = JSON.parse(deps.gh(["api", `repos/${process.env.GITHUB_REPOSITORY}/pulls/${event.number}/files`, "--jq", "."]));
+    const changedFiles = filesData.map((f) => f.filename);
+    const sensitiveFiles = getSensitiveFiles(changedFiles, config.sensitiveInstructionPaths);
+    if (sensitiveFiles.length > 0 && !isAuthorizedActor(prAuthor, deps.gh)) {
+        const fileList = sensitiveFiles.map((f) => `  - ${f}`).join("\n");
+        throw new Error(`PR author @${prAuthor} is not an Authorized Actor and modified sensitive instruction paths:\n${fileList}\n\nAn Authorized Actor must explicitly trust these changes:\n\`/fucina trust-instructions ${headSha}\``);
+    }
+    const diff = deps.gh(["api", `repos/${process.env.GITHUB_REPOSITORY}/pulls/${event.number}`, "--header", "Accept: application/vnd.github.v3.diff"]);
+    const { result, parsed } = await runFucinaAgent(deps.agent, `Review PR #${event.number}: ${event.title}\n\nDiff:\n${diff}\n\nReturn <fucina>{"summary":"..."}</fucina>.`);
+    if (result.commits.length)
+        throw new Error("Fucina review must not mutate files, commit, or push");
+    deps.gh(["pr", "review", String(event.number), "--comment", "--body", withRunLink(parsed.summary, deps.runUrl)]);
+}
+export async function reviewDefault(event) {
+    const { gh } = await import("../gh.js");
+    return review(event, { gh, agent: (prompt) => runAgent(prompt), cwd: process.cwd() });
+}

package/dist/modes/trust-instructions.js

@@ -0,0 +1,23 @@
+import { withRunLink } from "../comment.js";
+export async function trustInstructions(event, sha, deps) {
+    if (event.kind !== "pull_request")
+        throw new Error("/fucina trust-instructions only works on PRs");
+    const pr = JSON.parse(deps.gh(["api", `repos/${process.env.GITHUB_REPOSITORY}/pulls/${event.number}`, "--jq", "."]));
+    const currentSha = pr.head.sha;
+    if (currentSha !== sha) {
+        throw new Error(`SHA mismatch: PR head is ${currentSha.substring(0, 7)} but you provided ${sha.substring(0, 7)}. The PR has been updated since you copied the command. Re-run the review to get the current SHA.`);
+    }
+    deps.gh(["pr", "edit", String(event.number), "--remove-label", "fucina:review"]);
+    deps.gh(["pr", "edit", String(event.number), "--remove-label", "fucina:blocked"]);
+    deps.gh(["pr", "edit", String(event.number), "--add-label", "fucina:review"]);
+    deps.gh(["pr", "comment", String(event.number), "--body", withRunLink(`Sensitive instruction changes at ${sha.substring(0, 7)} explicitly trusted. Review will proceed.`, deps.runUrl)]);
+}
+export async function trustInstructionsDefault(event, sha) {
+    const { gh } = await import("../gh.js");
+    return trustInstructions(event, sha, {
+        gh,
+        runUrl: process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID
+            ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`
+            : undefined
+    });
+}

package/dist/run.js

@@ -0,0 +1,66 @@
+import { assertAuthorizedWithGh } from "./auth.js";
+import { readEvent } from "./event.js";
+import { gh } from "./gh.js";
+import { runAgent } from "./agent.js";
+import { composeAgentPrompt } from "./instructions.js";
+import { explore } from "./modes/explore.js";
+import { addressFeedback } from "./modes/address-feedback.js";
+import { implement } from "./modes/implement.js";
+import { review } from "./modes/review.js";
+export async function run() {
+    return runEvent(readEvent(), { gh, agent: (prompt) => runAgent(prompt), cwd: process.cwd(), runUrl: process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}` : undefined });
+}
+export async function runEvent(event, deps) {
+    if (event.label.startsWith("/fucina ")) {
+        return await runSlashCommand(event, deps);
+    }
+    const target = event.kind === "issue" ? "issue" : "pr";
+    deps.gh([target, "edit", String(event.number), "--remove-label", event.label]);
+    try {
+        assertAuthorizedWithGh(event, deps.gh);
+        deps.gh([target, "edit", String(event.number), "--remove-label", "fucina:blocked"]);
+        deps.gh([target, "edit", String(event.number), "--add-label", "fucina:in-progress"]);
+        const mode = event.label.replace("fucina:", "");
+        const modeDeps = { ...deps, agent: (prompt) => deps.agent(composeAgentPrompt(mode, prompt, deps.cwd)) };
+        if (event.label === "fucina:explore" && event.kind === "issue")
+            return await explore(event, modeDeps);
+        if (event.label === "fucina:implement" && event.kind === "issue")
+            return await implement(event, modeDeps);
+        if (event.label === "fucina:address-feedback" && event.kind === "pull_request")
+            return await addressFeedback(event, modeDeps);
+        if (event.label === "fucina:review" && event.kind === "pull_request")
+            return await review(event, modeDeps);
+        throw new Error(`${event.label} is not valid for ${event.kind}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        deps.gh([target, "edit", String(event.number), "--remove-label", event.label]);
+        deps.gh([target, "edit", String(event.number), "--add-label", "fucina:blocked"]);
+        deps.gh([target, "comment", String(event.number), "--body", `Fucina ${event.label} failed.\n\nReason: ${message}\n${deps.runUrl ? `\nRetry by re-adding ${event.label}. Run: ${deps.runUrl}` : `\nRetry by re-adding ${event.label}.`}`]);
+        throw error;
+    }
+    finally {
+        deps.gh([target, "edit", String(event.number), "--remove-label", "fucina:in-progress"]);
+    }
+}
+async function runSlashCommand(event, deps) {
+    const target = event.kind === "issue" ? "issue" : "pr";
+    try {
+        assertAuthorizedWithGh(event, deps.gh);
+        const parts = event.label.split(/\s+/);
+        const command = parts[1];
+        if (command === "trust-instructions") {
+            const sha = parts[2];
+            if (!sha || sha.length !== 40)
+                throw new Error("trust-instructions requires a full 40-character SHA");
+            const { trustInstructions } = await import("./modes/trust-instructions.js");
+            return await trustInstructions(event, sha, deps);
+        }
+        throw new Error(`Unknown slash command: ${command}`);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        deps.gh([target, "comment", String(event.number), "--body", `Fucina slash command failed.\n\nReason: ${message}\n${deps.runUrl ? `\nRun: ${deps.runUrl}` : ""}`]);
+        throw error;
+    }
+}

package/dist/sensitive-paths.js

@@ -0,0 +1,11 @@
+export function matchesSensitivePaths(files, patterns) {
+    return files.some((file) => patterns.some((pattern) => matchesPattern(file, pattern)));
+}
+export function getSensitiveFiles(files, patterns) {
+    return files.filter((file) => patterns.some((pattern) => matchesPattern(file, pattern)));
+}
+function matchesPattern(file, pattern) {
+    if (pattern.endsWith("/**"))
+        return file === pattern.slice(0, -3) || file.startsWith(pattern.slice(0, -2));
+    return file === pattern;
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@vekexasia/fucina",
+  "version": "0.0.0",
+  "description": "Label-driven AI workflows for GitHub repositories.",
+  "type": "module",
+  "bin": {
+    "fucina": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx src/cli.ts",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@ai-hero/sandcastle": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/.github/workflows/fucina-issue.yml

@@ -0,0 +1,2 @@
+# Generated by `fucina install`.
+# See src/install.ts for the current template.

package/templates/.github/workflows/fucina-mutate.yml

@@ -0,0 +1,2 @@
+# Generated by `fucina install`.
+# See src/install.ts for the current template.

package/templates/.github/workflows/fucina-review.yml

@@ -0,0 +1,2 @@
+# Generated by `fucina install`.
+# See src/install.ts for the current template.