@kontourai/flow-agents 0.1.1

package/build/src/tools/filter-installed-packs.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadJson, writeText } from "./common.js";
+function splitPacks(value) {
+    return new Set(value.split(",").map((item) => item.trim()).filter(Boolean));
+}
+function namesFor(packs) {
+    return new Set((packs.packs ?? []).map((pack) => String(pack.name ?? "")));
+}
+function entries(pack, field) {
+    const value = pack[field];
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function assertSafeName(name, label) {
+    if (!/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/.test(name))
+        throw new Error(`${label} contains unsafe pack member name: ${name}`);
+}
+function assertContained(rootDir, target) {
+    const rootReal = fs.realpathSync(rootDir);
+    const parentReal = fs.realpathSync(path.dirname(target));
+    const resolved = path.resolve(parentReal, path.basename(target));
+    const relative = path.relative(rootReal, resolved);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error(`refusing to remove path outside install root: ${target}`);
+    if (fs.existsSync(target)) {
+        const targetReal = fs.realpathSync(target);
+        const targetRelative = path.relative(rootReal, targetReal);
+        if (!targetRelative || targetRelative.startsWith("..") || path.isAbsolute(targetRelative))
+            throw new Error(`refusing to remove path outside install root: ${target}`);
+    }
+}
+function packSelection(packs, requested) {
+    const selectedNames = new Set();
+    for (const pack of packs.packs ?? [])
+        if (pack.default === true)
+            selectedNames.add(String(pack.name));
+    for (const name of requested)
+        selectedNames.add(name);
+    const unknown = [...selectedNames].filter((name) => !namesFor(packs).has(name)).sort();
+    if (unknown.length)
+        throw new Error(`unknown pack(s): ${unknown.join(", ")}`);
+    const selected = { skills: new Set(), agents: new Set(), powers: new Set() };
+    for (const pack of packs.packs ?? []) {
+        if (!selectedNames.has(String(pack.name)))
+            continue;
+        for (const field of Object.keys(selected)) {
+            for (const item of entries(pack, field))
+                selected[field].add(item);
+        }
+    }
+    return [selectedNames, selected];
+}
+function allPackMembers(packs, field) {
+    const values = new Set();
+    for (const pack of packs.packs ?? [])
+        for (const item of entries(pack, field))
+            values.add(item);
+    return values;
+}
+function removePath(rootDir, target, dryRun) {
+    if (!fs.existsSync(target))
+        return false;
+    assertContained(rootDir, target);
+    if (dryRun) {
+        console.log(`would remove ${target}`);
+        return true;
+    }
+    fs.rmSync(target, { recursive: true, force: true });
+    console.log(`removed ${target}`);
+    return true;
+}
+function pruneNamedDirs(rootDir, parent, known, keep, dryRun) {
+    let removed = 0;
+    for (const name of [...known].filter((name) => !keep.has(name)).sort()) {
+        assertSafeName(name, parent);
+        if (removePath(rootDir, path.join(rootDir, parent, name), dryRun))
+            removed += 1;
+    }
+    return removed;
+}
+function pruneAgentFiles(rootDir, parent, suffix, known, keep, dryRun) {
+    let removed = 0;
+    for (const name of [...known].filter((name) => !keep.has(name)).sort()) {
+        assertSafeName(name, parent);
+        if (removePath(rootDir, path.join(rootDir, parent, `${name}${suffix}`), dryRun))
+            removed += 1;
+    }
+    return removed;
+}
+export function main(argv = process.argv.slice(2)) {
+    const args = argv;
+    const dryRun = args.includes("--dry-run");
+    const rootArg = args.find((arg) => !arg.startsWith("--"));
+    const packsFlag = args.indexOf("--packs");
+    if (!rootArg || packsFlag < 0 || !args[packsFlag + 1]) {
+        console.error("usage: filter-installed-packs <root> --packs <packs> [--dry-run]");
+        return 2;
+    }
+    const rootDir = path.resolve(rootArg);
+    const packsPath = path.join(rootDir, "packaging", "packs.json");
+    if (!fs.existsSync(packsPath))
+        throw new Error(`pack manifest not found: ${packsPath}`);
+    const packs = loadJson(packsPath);
+    const [selectedNames, selected] = packSelection(packs, splitPacks(args[packsFlag + 1]));
+    let removed = 0;
+    removed += pruneNamedDirs(rootDir, "skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
+    removed += pruneNamedDirs(rootDir, ".claude/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
+    removed += pruneNamedDirs(rootDir, ".codex/skills", allPackMembers(packs, "skills"), selected.skills, dryRun);
+    removed += pruneNamedDirs(rootDir, "powers", allPackMembers(packs, "powers"), selected.powers, dryRun);
+    removed += pruneAgentFiles(rootDir, "agents", ".json", allPackMembers(packs, "agents"), selected.agents, dryRun);
+    removed += pruneAgentFiles(rootDir, ".claude/agents", ".md", allPackMembers(packs, "agents"), selected.agents, dryRun);
+    removed += pruneAgentFiles(rootDir, ".codex/agents", ".toml", allPackMembers(packs, "agents"), selected.agents, dryRun);
+    const summary = {
+        selected_packs: [...selectedNames].sort(),
+        removed_entries: removed,
+        kept: Object.fromEntries(Object.entries(selected).map(([field, values]) => [field, [...values].sort()])),
+    };
+    if (!dryRun)
+        writeText(path.join(rootDir, ".flow-agents/installed-packs.json"), `${JSON.stringify(summary, null, 2)}\n`);
+    console.log(JSON.stringify(summary, null, 2));
+    return 0;
+}
+if (process.argv[1] && fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1])))
+    try {
+        process.exit(main());
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }

package/build/src/tools/generate-context-map.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { exists, loadJson, markdownTable, oneLine, readText, rel, root, writeText } from "./common.js";
+const defaultOutput = path.join(root, "docs/context-map.md");
+const dirDescriptions = {
+    agents: "Canonical agent specs and routing prompts.",
+    "agent-cards": "Install/discovery cards that point at canonical agents.",
+    context: "Shared contracts, routing notes, templates, and reusable guidance.",
+    docs: "Long-lived project documentation and GitHub Pages content.",
+    evals: "Static, integration, install, and behavioral eval fixtures.",
+    powers: "Optional MCP/tool integration packs.",
+    prompts: "Reusable prompt entry points.",
+    schemas: "JSON Schema contracts for machine-readable workflow artifacts.",
+    scripts: "Build, validation, hook, telemetry, workflow, and import/export utilities.",
+    skills: "On-demand capability instructions and workflow primitives.",
+};
+const workflowSkills = new Set(["idea-to-backlog", "pull-work", "plan-work", "execute-plan", "review-work", "verify-work", "evidence-gate", "release-readiness", "learning-review", "deliver", "fix-bug", "tdd-workflow"]);
+const commands = [
+    ["Source tree", "npm run validate:source"],
+    ["Static suite", "bash evals/run.sh static"],
+    ["Integration suite", "bash evals/run.sh integration"],
+    ["Workflow artifacts", "npm run workflow:validate-artifacts -- --require-sidecars --require-critique .flow-agents/<slug>"],
+    ["Workflow sidecars", "npm run workflow:sidecar -- --help"],
+    ["Context map drift", "npm run context-map:check"],
+    ["Bundle build", "npm run build:bundles"],
+];
+function frontmatter(text) {
+    if (!text.startsWith("---"))
+        return {};
+    const end = text.indexOf("\n---", 3);
+    if (end < 0)
+        return {};
+    const fields = {};
+    const lines = text.slice(3, end).split(/\r?\n/);
+    for (let index = 0; index < lines.length;) {
+        const match = /^([A-Za-z0-9_-]+):\s*(.+)$/.exec(lines[index].trim());
+        if (!match) {
+            index += 1;
+            continue;
+        }
+        const key = match[1];
+        const value = match[2].trim();
+        index += 1;
+        if ([">", ">-", "|", "|-"].includes(value)) {
+            const block = [];
+            while (index < lines.length && (lines[index].startsWith(" ") || !lines[index].trim())) {
+                if (lines[index].trim())
+                    block.push(lines[index].trim());
+                index += 1;
+            }
+            fields[key] = block.join(" ");
+        }
+        else {
+            const parts = [value.replace(/^"|"$/g, "")];
+            while (index < lines.length && (lines[index].startsWith(" ") || !lines[index].trim())) {
+                if (lines[index].trim())
+                    parts.push(lines[index].trim().replace(/^"|"$/g, ""));
+                index += 1;
+            }
+            fields[key] = parts.join(" ");
+        }
+    }
+    return fields;
+}
+function repoShape(manifest) {
+    const canonical = new Set(Array.isArray(manifest.canonical_copy_dirs) ? manifest.canonical_copy_dirs.map(String) : []);
+    const dirs = [...new Set([...canonical, ...Object.keys(dirDescriptions)])].sort();
+    const rows = dirs.filter((dir) => exists(path.join(root, dir))).map((dir) => [dir, canonical.has(dir) ? "canonical copy" : "source", dirDescriptions[dir] ?? "Project directory."]);
+    for (const dir of Array.isArray(manifest.optional_copy_dirs) ? manifest.optional_copy_dirs.map(String) : []) {
+        rows.push([dir, "optional", "Optional local/user pack copied when present."]);
+    }
+    rows.push(["dist", "generated", "Generated bundle exports. Do not edit by hand."]);
+    rows.push([".flow-agents", "runtime", "Cross-session workflow artifacts and sidecars. Not committed by default."]);
+    return rows;
+}
+function listSkillRows() {
+    const workflowRows = [];
+    const supportRows = [];
+    const skillsDir = path.join(root, "skills");
+    for (const name of fs.readdirSync(skillsDir).sort()) {
+        const skillPath = path.join(skillsDir, name, "SKILL.md");
+        if (!exists(skillPath))
+            continue;
+        const meta = frontmatter(readText(skillPath));
+        const row = [meta.name ?? name, rel(skillPath), oneLine(meta.description ?? "")];
+        if (workflowSkills.has(row[0]))
+            workflowRows.push(row);
+        else
+            supportRows.push(row);
+    }
+    return [workflowRows, supportRows];
+}
+function agents() {
+    const dir = path.join(root, "agents");
+    return fs.readdirSync(dir).filter((name) => name.endsWith(".json")).sort().map((name) => {
+        const file = path.join(dir, name);
+        const data = loadJson(file);
+        const tools = Array.isArray(data.tools) ? data.tools : Array.isArray(data.allowedTools) ? data.allowedTools : [];
+        return [String(data.name ?? path.basename(name, ".json")), String(data.model ?? ""), String(tools.length), oneLine(String(data.description ?? ""))];
+    });
+}
+function schemas() {
+    const dir = path.join(root, "schemas");
+    return fs.readdirSync(dir).filter((name) => name.endsWith(".schema.json")).sort().map((name) => {
+        const data = loadJson(path.join(dir, name));
+        return [name, oneLine(String(data.title ?? "")), oneLine(String(data.$id ?? ""))];
+    });
+}
+function powers() {
+    const dir = path.join(root, "powers");
+    return fs.readdirSync(dir).sort().flatMap((name) => exists(path.join(dir, name, "POWER.md")) ? [[name, rel(path.join(dir, name, "POWER.md"))]] : []);
+}
+function packs() {
+    const data = loadJson(path.join(root, "packaging/packs.json"));
+    return (data.packs ?? []).map((pack) => [
+        String(pack.name ?? ""),
+        pack.default ? "yes" : "no",
+        String(Array.isArray(pack.skills) ? pack.skills.length : 0),
+        String(Array.isArray(pack.agents) ? pack.agents.length : 0),
+        String(Array.isArray(pack.powers) ? pack.powers.length : 0),
+        oneLine(String(pack.description ?? "")),
+    ]);
+}
+function latestRuntimeStates(includeRuntime) {
+    if (!includeRuntime) {
+        return [
+            "Runtime workflow state is excluded from the committed map.",
+            "Regenerate locally with `npm run context-map -- --include-runtime` to include recent `.flow-agents` state.",
+        ];
+    }
+    const workflowDir = path.join(root, ".flow-agents");
+    if (!exists(workflowDir))
+        return ["No local workflow state found under `.flow-agents`."];
+    const states = fs.readdirSync(workflowDir).map((name) => path.join(workflowDir, name, "state.json")).filter(exists).sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+    if (!states.length)
+        return ["No local workflow state found under `.flow-agents`."];
+    const rows = states.slice(0, 8).map((file) => {
+        const data = loadJson(file);
+        const next = typeof data.next_action === "object" && data.next_action ? data.next_action : {};
+        return [String(data.task_slug ?? path.basename(path.dirname(file))), String(data.status ?? ""), String(data.phase ?? ""), oneLine(String(next.summary ?? ""))];
+    });
+    return markdownTable(["Task", "Status", "Phase", "Next Action"], rows);
+}
+function render(includeRuntime) {
+    const manifest = loadJson(path.join(root, "packaging/manifest.json"));
+    const [workflowRows, supportRows] = listSkillRows();
+    return [
+        "---", "title: Context Map", "---", "", "# Context Map", "",
+        "Generated by `npm run context-map`. Regenerate after changing agents, skills, schemas, workflow contracts, or core commands.", "",
+        "## How To Use This", "",
+        "- Start here when a session is long, resumed, or context-constrained.",
+        "- Load only the specific skill, contract, schema, or doc that matches the task.",
+        "- Treat `.flow-agents` as runtime state and `dist/` as generated output.", "",
+        "## Repository Shape", "", ...markdownTable(["Path", "Role", "Purpose"], repoShape(manifest)), "",
+        "## Core Commands", "", ...markdownTable(["Use", "Command"], commands), "",
+        "## Workflow Sidecars", "",
+        "Machine-readable workflow state lives beside Markdown artifacts in `.flow-agents/<slug>/`.", "",
+        ...markdownTable(["Schema", "Title", "ID"], schemas()), "",
+        "Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`.", "",
+        "## Workflow Skills", "", ...markdownTable(["Skill", "Source", "When To Load"], workflowRows), "",
+        "## Support Skills", "", ...markdownTable(["Skill", "Source", "When To Load"], supportRows), "",
+        "## Agents", "", ...markdownTable(["Agent", "Model", "Tools", "Role"], agents()), "",
+        "## Optional Powers", "", ...markdownTable(["Power", "Source"], powers()), "",
+        "## Packs", "",
+        "Pack composition is defined in `packaging/packs.json`. The current builder exports pack metadata in bundle catalogs, and generated install scripts support opt-in `FLOW_AGENTS_PACKS` filtering while leaving all packs installed by default.", "",
+        ...markdownTable(["Pack", "Default", "Skills", "Agents", "Powers", "Purpose"], packs()), "",
+        "## Current Workflow State", "", ...latestRuntimeStates(includeRuntime), "",
+        "## Context Loading Rules", "",
+        "- For delivery work, load `deliver`, then the specific primitive skill for the current phase.",
+        "- For planning, verification, release, learning, or artifact validation, load `context/contracts/artifact-contract.md` plus the phase contract.",
+        "- For unknown external APIs or libraries, use `search-first` before implementation.",
+        "- For large or noisy sessions, prefer sidecars and this map over rereading broad docs.",
+        "- For generated exports, edit source files and rebuild instead of editing `dist/`.", "",
+    ].join("\n");
+}
+export function main(argv = process.argv.slice(2)) {
+    const args = argv;
+    const check = args.includes("--check");
+    const includeRuntime = args.includes("--include-runtime");
+    const outputIndex = args.indexOf("--output");
+    const output = outputIndex >= 0 && args[outputIndex + 1] ? path.resolve(args[outputIndex + 1]) : defaultOutput;
+    const text = render(includeRuntime);
+    if (check) {
+        const current = exists(output) ? readText(output) : "";
+        if (current !== text) {
+            console.error(`${rel(output)} is stale; run npm run context-map`);
+            return 1;
+        }
+        console.log(`${rel(output)} is current.`);
+        return 0;
+    }
+    writeText(output, text);
+    console.log(`Wrote ${rel(output)}`);
+    return 0;
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());

package/build/src/tools/validate-package.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+export function main(argv = process.argv.slice(2)) {
+    const [prefixArg, localFlag] = argv;
+    if (!prefixArg) {
+        console.error("Usage: validate-package <package-prefix> [--local]");
+        return 2;
+    }
+    const prefix = localFlag === "--local" ? `local-${prefixArg}` : prefixArg;
+    const agentsDir = path.join(process.env.HOME ?? "", ".kiro/agents");
+    console.log(`Package: ${prefix}\n`);
+    const files = fs.existsSync(agentsDir) ? fs.readdirSync(agentsDir).filter((name) => name.startsWith(`${prefix}-`) && name.endsWith(".json")).map((name) => path.join(agentsDir, name)) : [];
+    console.log(`Agents: ${files.length} found`);
+    if (files.length === 0) {
+        console.log("✗ No agents found");
+        return 1;
+    }
+    console.log("");
+    let errors = 0;
+    let specOk = 0;
+    let specFail = 0;
+    for (const file of files) {
+        const data = JSON.parse(fs.readFileSync(file, "utf8"));
+        const name = data.name ?? "";
+        if (!data.name || !data.prompt || !data.model || !data.description) {
+            console.log(`  ✗ ${path.basename(file)}: missing required field(s)`);
+            specFail += 1;
+        }
+        else if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            console.log(`  ✗ ${name}: invalid name format`);
+            specFail += 1;
+        }
+        else
+            specOk += 1;
+    }
+    console.log(`${specFail === 0 ? "✓" : "✗"} Agent specs: ${specOk}/${files.length} well-formed`);
+    errors += specFail;
+    let hookTotal = 0;
+    let hookFail = 0;
+    for (const file of files) {
+        const data = JSON.parse(fs.readFileSync(file, "utf8"));
+        for (const [hookType, entries] of Object.entries(data.hooks ?? {})) {
+            for (const entry of Array.isArray(entries) ? entries : []) {
+                hookTotal += 1;
+                const command = String(entry.command ?? "");
+                if (!command)
+                    continue;
+                const script = command.replace(/^bash\s+/, "").split(/\s+/)[0].replace(/^~/, process.env.HOME ?? "");
+                if (!fs.existsSync(script)) {
+                    console.log(`  ✗ ${data.name} → ${hookType}: ${path.basename(script)} (not found)`);
+                    hookFail += 1;
+                }
+            }
+        }
+    }
+    console.log(`${hookFail === 0 ? "✓" : "✗"} Hook scripts: ${hookTotal - hookFail}/${hookTotal} resolved`);
+    errors += hookFail;
+    console.log("✓ Resources: checked\n");
+    console.log(errors === 0 ? "Result: PASS" : `Result: FAIL (${errors} error(s))`);
+    return errors === 0 ? 0 : 1;
+}
+if (import.meta.url === `file://${process.argv[1]}`)
+    process.exit(main());