@eric0117/agentforge 0.1.0

package/dist/agents/io.js

@@ -0,0 +1,252 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LANG_INSTRUCTIONS } from "../skills-data.js";
+const here = dirname(fileURLToPath(import.meta.url));
+export const TEMPLATES = resolve(here, "..", "templates");
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RESET = "\x1b[0m";
+let VERBOSE = true;
+/**
+ * Toggle progress logging for adapter file operations.
+ * Used by `init` to quiet per-agent install output and instead print a single
+ * summary line per agent.
+ */
+export function setVerbose(v) {
+    VERBOSE = v;
+}
+function logIf(s) {
+    if (VERBOSE)
+        console.log(s);
+}
+export function ensureDir(full, label) {
+    if (existsSync(full)) {
+        logIf(`${DIM}  exists:${RESET}  ${label}/`);
+    }
+    else {
+        mkdirSync(full, { recursive: true });
+        logIf(`${GREEN}+${RESET} created: ${label}/`);
+    }
+}
+/**
+ * Render a template with the language placeholder substituted.
+ */
+export function renderTemplate(templateName, lang) {
+    const src = join(TEMPLATES, templateName);
+    if (!existsSync(src)) {
+        throw new Error(`template missing: ${src}`);
+    }
+    return readFileSync(src, "utf8").replaceAll("{{OUTPUT_LANGUAGE_INSTRUCTION}}", LANG_INSTRUCTIONS[lang]);
+}
+/**
+ * Write content to dst, respecting force / backup semantics:
+ *  - if dst exists and !force → skip with a message
+ *  - if dst exists and force → write a .bak alongside, then overwrite
+ *  - otherwise → write fresh
+ */
+export function writeRendered(dst, destRel, content, force) {
+    const exists = existsSync(dst);
+    if (exists && !force) {
+        logIf(`${YELLOW}  skipped:${RESET} ${destRel}  ${DIM}(exists; use --force / --force-skills / --force-claude to overwrite)${RESET}`);
+        return;
+    }
+    if (exists && force) {
+        // Pick a .bak name that doesn't already exist — preserves prior backups
+        // from earlier sync-skills runs instead of silently overwriting them.
+        let bak = `${dst}.bak`;
+        let bakRel = `${destRel}.bak`;
+        let n = 2;
+        while (existsSync(bak)) {
+            bak = `${dst}.bak.${n}`;
+            bakRel = `${destRel}.bak.${n}`;
+            n++;
+        }
+        writeFileSync(bak, readFileSync(dst, "utf8"));
+        logIf(`${DIM}  backup:${RESET}  ${bakRel}`);
+    }
+    // make sure parent dir exists
+    mkdirSync(dirname(dst), { recursive: true });
+    writeFileSync(dst, content);
+    logIf(`${GREEN}+${RESET} wrote:   ${destRel}`);
+}
+/**
+ * Split a SKILL.md.tpl into its YAML frontmatter and body.
+ * Returns { frontmatter: Record, body: string } where frontmatter is parsed
+ * loosely (only top-level key: value pairs; multi-line values are joined).
+ */
+/** Valid skill id: lowercase kebab-case, must start with a letter. */
+const SKILL_ID_RE = /^[a-z][a-z0-9-]*$/;
+/**
+ * Read the workspace master skills directory and parse every `*.md` file.
+ * Tolerant of files the user dropped in by hand: invalid file names, missing
+ * frontmatter, and `name:`/filename mismatches are surfaced as
+ * `skipped` (hard fail) or `warnings` (soft) — the rest still flow through.
+ */
+export function readMasterDir(masterDirAbs) {
+    if (!existsSync(masterDirAbs)) {
+        return { skills: [], skipped: [], warnings: [] };
+    }
+    // Guard: someone may have created `agentforge/skills` as a file by hand.
+    try {
+        if (!statSync(masterDirAbs).isDirectory()) {
+            return {
+                skills: [],
+                skipped: [
+                    {
+                        file: masterDirAbs,
+                        reason: "exists but is not a directory — remove it and run `agentforge init --force-skills` to recreate",
+                    },
+                ],
+                warnings: [],
+            };
+        }
+    }
+    catch (e) {
+        return {
+            skills: [],
+            skipped: [{ file: masterDirAbs, reason: `unreadable: ${e.message}` }],
+            warnings: [],
+        };
+    }
+    const allEntries = readdirSync(masterDirAbs, { withFileTypes: true });
+    const entries = allEntries
+        .filter((e) => e.name.endsWith(".md"))
+        .map((e) => e.name)
+        .sort();
+    const skills = [];
+    const skipped = [];
+    const warnings = [];
+    // Surface broken symlinks separately — they vanish from the normal
+    // file scan, which makes them very confusing.
+    const dangling = new Set();
+    for (const e of allEntries) {
+        if (!e.name.endsWith(".md"))
+            continue;
+        const abs = join(masterDirAbs, e.name);
+        try {
+            const lst = lstatSync(abs);
+            if (lst.isSymbolicLink() && !existsSync(abs)) {
+                skipped.push({
+                    file: e.name,
+                    reason: "dangling symlink — target doesn't exist",
+                });
+                dangling.add(e.name);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    for (const file of entries) {
+        if (dangling.has(file))
+            continue; // already reported above
+        const id = file.slice(0, -3); // strip `.md`
+        // (1) filename validity — agent adapters use this id as a directory /
+        // filename, so we have to be strict.
+        if (!SKILL_ID_RE.test(id)) {
+            skipped.push({
+                file,
+                reason: `invalid skill id "${id}" — must be kebab-case (lowercase letters/digits/hyphens, start with a letter)`,
+            });
+            continue;
+        }
+        let raw;
+        try {
+            raw = readFileSync(join(masterDirAbs, file), "utf8");
+        }
+        catch (e) {
+            skipped.push({ file, reason: `unreadable: ${e.message}` });
+            continue;
+        }
+        const { frontmatter, body } = splitFrontmatter(raw);
+        // (2) required frontmatter
+        if (!frontmatter["name"] || !frontmatter["description"]) {
+            skipped.push({
+                file,
+                reason: "missing frontmatter `name:` or `description:`",
+            });
+            continue;
+        }
+        // (2.5) YAML block scalars (`description: |` / `>`) — our parser only
+        // reads the first line of each key, so the multiline body would silently
+        // be lost. Reject with a clear hint to use a single-line description.
+        if (frontmatter["description"] === "|" ||
+            frontmatter["description"] === ">" ||
+            frontmatter["description"]?.startsWith("|") ||
+            frontmatter["description"]?.startsWith(">")) {
+            skipped.push({
+                file,
+                reason: "`description:` uses a YAML block scalar (`|` / `>`) which agentforge doesn't support — write it as one line on the same row as `description:`",
+            });
+            continue;
+        }
+        // (3) frontmatter `name:` must itself be kebab-case — agents echo it.
+        if (!SKILL_ID_RE.test(frontmatter["name"])) {
+            skipped.push({
+                file,
+                reason: `frontmatter \`name: ${frontmatter["name"]}\` is not kebab-case (lowercase letters/digits/hyphens, start with a letter)`,
+            });
+            continue;
+        }
+        // (4) frontmatter name vs filename mismatch — adapters would emit one as
+        // the dir/file and the other inside the frontmatter, so we'd ship two
+        // different identities for the same skill. Skip rather than propagate.
+        if (frontmatter["name"] !== id) {
+            skipped.push({
+                file,
+                reason: `frontmatter \`name: ${frontmatter["name"]}\` doesn't match the filename id \`${id}\`. Rename the file or the \`name:\` field so they agree, then re-run \`agentforge sync-skills\`.`,
+            });
+            continue;
+        }
+        // (4) suspiciously empty body — only HTML comments / whitespace.
+        const stripped = body
+            .replace(/<!--[\s\S]*?-->/g, "")
+            .replace(/\s+/g, "")
+            .trim();
+        if (stripped.length < 20) {
+            warnings.push({
+                file,
+                warning: "body looks like a placeholder (no real content yet). Fill it in and re-run `agentforge sync-skills`.",
+            });
+        }
+        skills.push({ id, frontmatter, body, raw });
+    }
+    return { skills, skipped, warnings };
+}
+/**
+ * Write a single master skill file. Honors force/backup semantics
+ * shared with adapter writes.
+ */
+export function writeMasterSkill(masterDirAbs, id, content, force) {
+    const dst = join(masterDirAbs, `${id}.md`);
+    const destRel = `agentforge/skills/${id}.md`;
+    writeRendered(dst, destRel, content, force);
+}
+export function splitFrontmatter(rendered) {
+    if (!rendered.startsWith("---")) {
+        return { frontmatter: {}, body: rendered };
+    }
+    const end = rendered.indexOf("\n---", 3);
+    if (end < 0)
+        return { frontmatter: {}, body: rendered };
+    const head = rendered.slice(4, end); // skip leading "---\n"
+    const body = rendered.slice(end + 4).replace(/^\n+/, "");
+    const fm = {};
+    let currentKey = null;
+    for (const raw of head.split("\n")) {
+        const m = raw.match(/^([A-Za-z_][\w-]*):\s?(.*)$/);
+        if (m) {
+            currentKey = m[1];
+            // Trim trailing whitespace so invisible spaces don't tank later
+            // validation (e.g. `name: my-skill   ` failing SKILL_ID_RE).
+            fm[currentKey] = m[2].trimEnd();
+        }
+        else if (currentKey && raw.trim() !== "") {
+            // continuation line for the previous key
+            fm[currentKey] = `${fm[currentKey]} ${raw.trim()}`.trim();
+        }
+    }
+    return { frontmatter: fm, body };
+}

package/dist/agents/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+import { runAddAgent } from "./add-agent.js";
+import { runAddSkill } from "./add-skill.js";
+import { AGENT_IDS } from "./agents/index.js";
+import { runDoctor } from "./doctor.js";
+import { runEnter } from "./enter.js";
+import { runInit } from "./init.js";
+import { runRename } from "./rename.js";
+import { runListSkills } from "./list-skills.js";
+import { runRemoveAgent } from "./remove-agent.js";
+import { runRemoveSkill } from "./remove-skill.js";
+import { runSyncSkills } from "./sync-skills.js";
+const HELP = `agentforge — multi-repo workspace bootstrapper for Claude Code, Cursor, and OpenAI Codex CLI
+
+Usage:
+
+  Workspace setup
+  ───────────────
+  agentforge init [path]                       Bootstrap a workspace (creates agentforge/,
+        [--force | --force-skills | --force-claude]   anvil/, artifacts/, and per-agent
+        [--yes] [--lang en|ko|ja]                     skill directories).
+        [--agent claude,cursor,codex | --agent all]
+
+  agentforge add-agent [agents] [path]         Add Claude / Cursor / Codex to an existing
+        [--force | --force-skills | --force-claude]   workspace.
+        [--yes] [--lang en|ko|ja]
+
+  agentforge remove-agent <agent> [path]       Uninstall an agent's skill directory.
+        [--yes]
+
+  Skills
+  ──────
+  agentforge list-skills [path]                Show every skill installed in the workspace.
+
+  agentforge add-skill [path]                  Author a new master skill (with optional
+        [--from <file>] [--no-edit] [--yes]    starter from --from <file>) and install it
+                                               to every agent.
+
+  agentforge remove-skill <name> [path]        Remove a skill from master + every agent.
+        [--yes]
+
+  agentforge sync-skills [path]                Propagate master skill edits in
+        [--force-claude]                       agentforge/skills/ to every agent.
+                                               Backs up existing files to .bak.
+
+  Features
+  ────────
+  agentforge enter [slug]                      cd into a feature worktree (anvil/<slug>/)
+                                               and launch \`claude\` there. No args lists
+                                               active features.
+
+  agentforge rename <old-slug> <new-slug>      Rename a feature: moves the worktrees,
+        [--yes] [--force]                      renames any branch named <old-slug>,
+                                               rewrites slug references in CLAUDE.md.
+                                               Refuses dirty worktrees without --force.
+
+  Diagnostics
+  ───────────
+  agentforge doctor [path]                     Check the workspace for misconfiguration.
+
+  agentforge help                              Show this message.
+  agentforge --help
+
+Notes:
+  • Workspaces have a master skills folder at <workspace>/agentforge/skills/ and a
+    config file at <workspace>/agentforge/config.json. Edits to master files are
+    propagated to every installed agent by \`sync-skills\`.
+  • Existing per-agent files are preserved by default; --force* variants back up
+    the previous content to .bak before overwriting.
+  • Skills are triggered by natural language inside your AI session — you don't run
+    them via this CLI. See <workspace>/CLAUDE.md (or AGENTS.md / .cursor/rules/CLAUDE.mdc)
+    for the trigger phrases.
+`;
+function parseArgs(argv) {
+    const out = {
+        positional: [],
+        forceSkills: false,
+        forceClaude: false,
+        yes: false,
+        help: false,
+        noEdit: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--force" || a === "-f") {
+            out.forceSkills = true;
+            out.forceClaude = true;
+        }
+        else if (a === "--force-skills")
+            out.forceSkills = true;
+        else if (a === "--force-claude")
+            out.forceClaude = true;
+        else if (a === "--yes" || a === "-y")
+            out.yes = true;
+        else if (a === "--help" || a === "-h")
+            out.help = true;
+        else if (a === "--lang") {
+            const v = argv[++i];
+            if (v === "en" || v === "ko" || v === "ja")
+                out.lang = v;
+            else {
+                process.stderr.write(`invalid --lang value: ${v} (use en | ko | ja)\n`);
+                process.exit(1);
+            }
+        }
+        else if (a.startsWith("--lang=")) {
+            const v = a.slice("--lang=".length);
+            if (v === "en" || v === "ko" || v === "ja")
+                out.lang = v;
+            else {
+                process.stderr.write(`invalid --lang value: ${v} (use en | ko | ja)\n`);
+                process.exit(1);
+            }
+        }
+        else if (a === "--agent") {
+            const v = argv[++i];
+            if (out.agents !== undefined) {
+                process.stderr.write(`\nerror: --agent specified more than once. Combine them: \`--agent claude,cursor,codex\` or \`--agent all\`.\n\n`);
+                process.exit(1);
+            }
+            out.agents = parseAgents(v);
+        }
+        else if (a.startsWith("--agent=")) {
+            if (out.agents !== undefined) {
+                process.stderr.write(`\nerror: --agent specified more than once. Combine them: \`--agent claude,cursor,codex\` or \`--agent all\`.\n\n`);
+                process.exit(1);
+            }
+            out.agents = parseAgents(a.slice("--agent=".length));
+        }
+        else if (a === "--from") {
+            out.fromFile = argv[++i];
+        }
+        else if (a.startsWith("--from=")) {
+            out.fromFile = a.slice("--from=".length);
+        }
+        else if (a === "--no-edit") {
+            out.noEdit = true;
+        }
+        else if (a.startsWith("--") || /^-[a-zA-Z]/.test(a)) {
+            // Unknown flag — refuse instead of silently treating as positional.
+            // Without this, `init --bogus /tmp/x` would resolve("--bogus") as the
+            // workspace path and produce a baffling error downstream.
+            const known = [
+                "--force",
+                "--force-skills",
+                "--force-claude",
+                "--yes",
+                "--help",
+                "--lang",
+                "--agent",
+                "--from",
+                "--no-edit",
+                "-f",
+                "-y",
+                "-h",
+            ];
+            const guess = nearestCommand(a, known);
+            let msg = `\nerror: unknown flag: ${a}\n`;
+            if (guess)
+                msg += `\nDid you mean: \x1b[36m${guess}\x1b[0m?\n`;
+            msg += `\n`;
+            process.stderr.write(msg);
+            process.exit(1);
+        }
+        else if (!out.command) {
+            out.command = a;
+        }
+        else {
+            // Reject empty-string positional args — they're almost always an unset
+            // shell var (`agentforge init "$WS"` with WS unset) and would silently
+            // collapse to cwd through resolve("").
+            if (a === "") {
+                process.stderr.write(`\nerror: empty positional argument. Did you mean to expand a shell variable that wasn't set?\n\n`);
+                process.exit(1);
+            }
+            out.positional.push(a);
+        }
+    }
+    return out;
+}
+function looksLikeAgentSpec(s) {
+    if (s === "all")
+        return true;
+    const parts = s.split(",").map((p) => p.trim());
+    if (parts.length === 0)
+        return false;
+    return parts.every((p) => AGENT_IDS.includes(p));
+}
+function parseAgents(value) {
+    if (!value) {
+        process.stderr.write(`--agent requires a value (claude | cursor | codex | all)\n`);
+        process.exit(1);
+    }
+    if (value === "all")
+        return AGENT_IDS.slice();
+    const ids = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const valid = new Set(AGENT_IDS);
+    const bad = ids.filter((id) => !valid.has(id));
+    if (bad.length > 0 || ids.length === 0) {
+        process.stderr.write(`invalid --agent value(s): ${bad.join(", ") || value} (use claude | cursor | codex | all)\n`);
+        process.exit(1);
+    }
+    return Array.from(new Set(ids));
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help || !args.command || args.command === "help") {
+        process.stdout.write(HELP);
+        process.exit(args.help || args.command === "help" ? 0 : 1);
+    }
+    switch (args.command) {
+        case "init":
+            await runInit({
+                pathArg: args.positional[0],
+                forceSkills: args.forceSkills,
+                forceClaude: args.forceClaude,
+                yes: args.yes,
+                lang: args.lang,
+                agents: args.agents,
+            });
+            return;
+        case "add-agent": {
+            // [agents] [path]: first positional may be agents spec or path
+            let agents = args.agents;
+            let pathArg;
+            const [p0, p1] = args.positional;
+            if (p0 != null) {
+                if (looksLikeAgentSpec(p0)) {
+                    if (!agents)
+                        agents = parseAgents(p0);
+                    if (p1 != null)
+                        pathArg = p1;
+                }
+                else {
+                    pathArg = p0;
+                }
+            }
+            await runAddAgent({
+                agents,
+                pathArg,
+                forceSkills: args.forceSkills,
+                forceClaude: args.forceClaude,
+                yes: args.yes,
+                lang: args.lang,
+            });
+            return;
+        }
+        case "remove-agent": {
+            const [p0, p1] = args.positional;
+            if (!p0 || !AGENT_IDS.includes(p0)) {
+                process.stderr.write(`usage: agentforge remove-agent <claude|cursor|codex> [path]\n`);
+                process.exit(1);
+            }
+            await runRemoveAgent({
+                agent: p0,
+                pathArg: p1,
+                yes: args.yes,
+            });
+            return;
+        }
+        case "list-skills":
+            await runListSkills({ pathArg: args.positional[0] });
+            return;
+        case "add-skill":
+            await runAddSkill({
+                pathArg: args.positional[0],
+                fromFile: args.fromFile,
+                noEdit: args.noEdit,
+                yes: args.yes,
+            });
+            return;
+        case "remove-skill": {
+            const [name, pathArg] = args.positional;
+            if (!name) {
+                process.stderr.write(`usage: agentforge remove-skill <name> [path]\n`);
+                process.exit(1);
+            }
+            await runRemoveSkill({ name, pathArg, yes: args.yes });
+            return;
+        }
+        case "sync-skills":
+            await runSyncSkills({
+                pathArg: args.positional[0],
+                forceSkills: args.forceSkills,
+                forceClaude: args.forceClaude,
+            });
+            return;
+        case "doctor":
+            await runDoctor({ pathArg: args.positional[0] });
+            return;
+        case "enter":
+            await runEnter({ slug: args.positional[0] });
+            return;
+        case "rename":
+            await runRename({
+                oldSlug: args.positional[0],
+                newSlug: args.positional[1],
+                yes: args.yes,
+                force: args.forceSkills || args.forceClaude,
+            });
+            return;
+    }
+    const known = [
+        "init",
+        "add-agent",
+        "remove-agent",
+        "list-skills",
+        "add-skill",
+        "remove-skill",
+        "sync-skills",
+        "enter",
+        "rename",
+        "doctor",
+        "help",
+    ];
+    const guess = nearestCommand(args.command, known);
+    let msg = `unknown command: ${args.command}\n`;
+    if (guess)
+        msg += `\nDid you mean: \x1b[36m${guess}\x1b[0m?\n`;
+    msg += `\nRun \x1b[36magentforge help\x1b[0m for the full command list.\n`;
+    process.stderr.write(msg);
+    process.exit(1);
+}
+function nearestCommand(input, known) {
+    let best = null;
+    for (const cmd of known) {
+        const d = levenshtein(input.toLowerCase(), cmd);
+        if (best === null || d < best.dist)
+            best = { cmd, dist: d };
+    }
+    // Only suggest if reasonably close — 3 edits or 40% of length.
+    if (!best)
+        return null;
+    const threshold = Math.max(2, Math.floor(input.length * 0.4));
+    return best.dist <= threshold ? best.cmd : null;
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const prev = new Array(n + 1).fill(0).map((_, i) => i);
+    const cur = new Array(n + 1).fill(0);
+    for (let i = 1; i <= m; i++) {
+        cur[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            cur[j] = Math.min(cur[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j <= n; j++)
+            prev[j] = cur[j];
+    }
+    return prev[n];
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    // readConfig throws "failed to read .../config.json: ..." — reframe.
+    if (msg.startsWith("failed to read ") && msg.includes("config.json")) {
+        process.stderr.write(`\n\x1b[31m✗\x1b[0m \x1b[1magentforge/config.json is invalid.\x1b[0m\n  \x1b[2m${msg.slice("failed to read ".length)}\x1b[0m\n\n` +
+            `  Fix the file directly, or re-create the workspace with \x1b[36magentforge init <path> --force\x1b[0m\n` +
+            `  (existing files are backed up to .bak before overwriting).\n\n`);
+    }
+    else {
+        console.error(`\nerror: ${msg}`);
+    }
+    process.exit(1);
+});

package/dist/confirm.js

@@ -0,0 +1,20 @@
+import * as readline from "node:readline/promises";
+const CYAN = "\x1b[36m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+/** Simple y/N prompt. Non-TTY → returns `def`. */
+export async function confirm(message, def = false) {
+    if (!process.stdin.isTTY)
+        return def;
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const hint = def ? "[Y/n]" : "[y/N]";
+    const ans = await rl.question(`${CYAN}?${RESET} ${message} ${DIM}${hint}${RESET} `);
+    rl.close();
+    const t = ans.trim().toLowerCase();
+    if (t === "")
+        return def;
+    return t === "y" || t === "yes";
+}