@acta-dev/cli 0.1.1 → 1.1.0

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { realpathSync } from "fs";
 import { fileURLToPath } from "url";
-import { defineCommand as defineCommand9, runMain } from "citty";
+import { defineCommand as defineCommand10, runMain } from "citty";
 
 // src/commands/build.ts
 import { buildArtifacts } from "@acta-dev/core";
@@ -226,8 +226,170 @@ import { existsSync as existsSync2 } from "fs";
 import { mkdir, writeFile } from "fs/promises";
 import { join as join2, resolve as resolve2 } from "path";
 import { createInterface } from "readline";
-import { resolveConfig as resolveConfig2 } from "@acta-dev/core";
+import { resolveConfig as resolveConfig3 } from "@acta-dev/core";
 import { defineCommand as defineCommand3 } from "citty";
+
+// src/skill.ts
+import {
+  adrStatuses,
+  documentKinds,
+  internalLinkKeys,
+  linkKeys,
+  resolveConfig as resolveConfig2,
+  specStatuses
+} from "@acta-dev/core";
+var SKILL_NAME = "acta-document";
+var LINK_DESCRIPTIONS = {
+  related: "Loosely related documents.",
+  supersedes: "This document supersedes the target; mirror with `replacedBy`.",
+  replacedBy: "This document is replaced by the target.",
+  decidedBy: "This spec was decided by an ADR.",
+  dependsOn: "This document depends on the target decision.",
+  validates: "This spec validates/implements an ADR decision.",
+  references: "External URLs only; must be valid http(s)."
+};
+function table(header, rows) {
+  const head = `| ${header.join(" | ")} |`;
+  const sep = `| ${header.map(() => "---").join(" | ")} |`;
+  const body = rows.map((r) => `| ${r.join(" | ")} |`).join("\n");
+  return [head, sep, body].join("\n");
+}
+function renderSkill() {
+  const config = resolveConfig2({}, { rootDir: process.cwd() });
+  const dirFor = {
+    adr: config.docs.adrDir,
+    spec: config.docs.specDir
+  };
+  const prefixFor = {
+    adr: config.ids.adrPrefix,
+    spec: config.ids.specPrefix
+  };
+  const required = config.validation.requiredSections;
+  const kindRows = documentKinds.map((kind) => [
+    `\`${kind}\``,
+    `\`${prefixFor[kind]}\``,
+    `\`${dirFor[kind]}/\``
+  ]);
+  const linkRows = linkKeys.map((key) => [
+    `\`${key}\``,
+    key === "references" ? "external" : "internal",
+    LINK_DESCRIPTIONS[key]
+  ]);
+  const frontmatter = [
+    "---",
+    `name: ${SKILL_NAME}`,
+    "description: >-",
+    "  Create and maintain Acta ADR/spec documents with the `acta` CLI. Use after",
+    "  implementing a feature, fixing a notable bug, or making an architectural",
+    "  decision, or when asked to document a decision, write an ADR, or create a spec.",
+    "allowed-tools: Bash",
+    "---"
+  ].join("\n");
+  return `${frontmatter}
+
+# Acta: document decisions and specs
+
+Acta is a docs-as-code CLI that keeps Architecture Decision Records (ADRs) and
+specs validated and linked in Git. Drive it through the \`acta\` binary; every
+data command supports \`--json\` for reliable parsing. **Never scrape human
+output \u2014 always pass \`--json\` and parse stdout.** Human logs go to stderr.
+
+## When to use
+
+- After implementing a feature or system \u2192 write a \`spec\`.
+- After making an architectural decision (or choosing between options) \u2192 write an \`adr\`.
+- When the user asks to "document this decision", "write an ADR", or "create a spec".
+
+## Document model
+
+${table(["Kind", "ID prefix", "Directory"], kindRows)}
+
+IDs are \`<PREFIX>-<NNNN>\` (zero-padded to width ${config.ids.width}); the CLI allocates the next ID.
+
+**ADR statuses:** ${adrStatuses.map((s) => `\`${s}\``).join(", ")} (default \`proposed\`).
+**Spec statuses:** ${specStatuses.map((s) => `\`${s}\``).join(", ")} (default \`draft\`).
+
+### Link types (frontmatter \`links:\`)
+
+${table(["Key", "Kind", "Meaning"], linkRows)}
+
+Internal link keys (${internalLinkKeys.map((k) => `\`${k}\``).join(", ")}) reference other
+document IDs. \`references\` holds external URLs only.
+
+### Required sections
+
+- **ADR:** ${required.adr.map((s) => `\`# ${s}\``).join(", ")}
+- **Spec:** ${required.spec.map((s) => `\`# ${s}\``).join(", ")}
+
+## Procedure
+
+1. **Pick the kind.** Architectural decision \u2192 \`adr\`. Feature/system \u2192 \`spec\`.
+2. **Create it** and capture the path from JSON:
+   \`\`\`sh
+   acta new adr "Short title" --json   # or: acta new spec "Short title" --json
+   \`\`\`
+   Returns \`{ "id", "kind", "title", "status", "path", "relativePath" }\`. Edit \`path\`.
+3. **Fill frontmatter:** set \`status\`, \`tags\`, \`component\`, \`owners\`, a one-line
+   \`summary\`, and \`links\` (use the link types above; \`references\` for external URLs).
+4. **Fill required sections** (see above) with real content \u2014 no placeholders.
+5. **Validate and fix-loop:**
+   \`\`\`sh
+   acta validate --json
+   \`\`\`
+   Returns \`{ "valid", "errorCount", "warningCount", "issues": [{ severity, code, documentId, message, path, line }] }\`.
+   If \`valid\` is \`false\`, fix each \`issues[].message\` and re-run. Repeat until
+   \`valid\` is \`true\` (cap at ~5 iterations; if still failing, report the issues).
+6. **Verify links** with \`acta show <id> --json\` (inspect \`links\` and \`backlinks\`).
+
+## Command reference (all accept \`--json\` unless noted)
+
+- \`acta new adr|spec "<title>" [--status <s>] [--tags a,b] [--id <ID>]\` \u2192 created doc.
+- \`acta list [--kind adr|spec] [--status <s>] [--tag <t>]\` \u2192 array of documents.
+- \`acta show <id>\` \u2192 one normalized document with \`links\` + \`backlinks\`.
+- \`acta validate\` \u2192 validation result; exit \`1\` if invalid.
+- \`acta graph --format json|mermaid|dot\` \u2192 relationship graph.
+- \`acta build\` \u2192 build manifest (\`documentCount\`, \`errorCount\`, \`warningCount\`).
+
+Exit codes: \`0\` ok \xB7 \`1\` validation/operation failure \xB7 \`2\` usage error.
+`;
+}
+var AGENTS_BLOCK_START = "<!-- acta:skill:start -->";
+var AGENTS_BLOCK_END = "<!-- acta:skill:end -->";
+function renderAgentsBlock() {
+  const adr = adrStatuses.join(", ");
+  const spec = specStatuses.join(", ");
+  return `${AGENTS_BLOCK_START}
+## Documenting work with Acta
+
+After implementing a feature or making an architectural decision, record it with
+the \`acta\` CLI (always use \`--json\` and parse stdout):
+
+1. \`acta new adr|spec "Title" --json\` \u2014 \`adr\` for decisions, \`spec\` for features. Capture \`path\`.
+2. Fill frontmatter (\`status\`, \`tags\`, \`component\`, \`owners\`, \`summary\`, \`links\`) and required sections.
+3. \`acta validate --json\` \u2014 fix each \`issues[].message\` and repeat until \`valid\` is \`true\`.
+4. \`acta show <id> --json\` \u2014 verify \`links\`/\`backlinks\`.
+
+ADR statuses: ${adr}. Spec statuses: ${spec}. Link keys: ${linkKeys.join(", ")}.
+${AGENTS_BLOCK_END}`;
+}
+function upsertAgentsBlock(existing) {
+  const block = renderAgentsBlock();
+  const start = existing.indexOf(AGENTS_BLOCK_START);
+  const end = existing.indexOf(AGENTS_BLOCK_END);
+  if (start !== -1 && end !== -1 && end > start) {
+    const before = existing.slice(0, start);
+    const after = existing.slice(end + AGENTS_BLOCK_END.length);
+    return `${before}${block}${after}`;
+  }
+  const trimmed = existing.replace(/\s+$/, "");
+  return trimmed.length > 0 ? `${trimmed}
+
+${block}
+` : `${block}
+`;
+}
+
+// src/commands/init.ts
 var ADR_TEMPLATE = `---
 id: ADR-0000
 kind: adr
@@ -440,6 +602,11 @@ var initCommand = defineCommand3({
       description: "Install GitHub Actions workflow template",
       default: false
     },
+    skill: {
+      type: "boolean",
+      description: "Install the acta-document agent skill and AGENTS.md guidance",
+      default: false
+    },
     config: {
       type: "string",
       alias: "c",
@@ -449,7 +616,7 @@ var initCommand = defineCommand3({
   async run({ args }) {
     const cwd = resolve2(process.cwd());
     const yes = args.yes;
-    const config = resolveConfig2({}, { rootDir: cwd });
+    const config = resolveConfig3({}, { rootDir: cwd });
     printLine("Initializing Acta docs structure...");
     printLine();
     const configPath = join2(cwd, "acta.config.ts");
@@ -491,6 +658,18 @@ var initCommand = defineCommand3({
       const workflowWritten = await safeWriteFile(workflowPath, GITHUB_ACTION_TEMPLATE, yes);
       if (workflowWritten) printSuccess(`Created ${workflowPath}`);
     }
+    if (args.skill) {
+      const skillDir = join2(cwd, ".claude", "skills", "acta-document");
+      await mkdir(skillDir, { recursive: true });
+      const skillPath = join2(skillDir, "SKILL.md");
+      const skillWritten = await safeWriteFile(skillPath, renderSkill(), yes);
+      if (skillWritten) printSuccess(`Created ${skillPath}`);
+      const { readFile: readFile3 } = await import("fs/promises");
+      const agentsPath = join2(cwd, "AGENTS.md");
+      const existing = existsSync2(agentsPath) ? await readFile3(agentsPath, "utf8") : "";
+      await writeFile(agentsPath, upsertAgentsBlock(existing), "utf8");
+      printSuccess(`Updated ${agentsPath} with Acta agent guidance`);
+    }
     printLine();
     printSuccess("Acta initialized. Run `acta validate` to check your documents.");
   }
@@ -606,7 +785,7 @@ var listCommand = defineCommand4({
 import { existsSync as existsSync3 } from "fs";
 import { writeFile as writeFile2 } from "fs/promises";
 import { join as join4, relative } from "path";
-import { adrStatuses, specStatuses } from "@acta-dev/core";
+import { adrStatuses as adrStatuses2, specStatuses as specStatuses2 } from "@acta-dev/core";
 import { defineCommand as defineCommand5 } from "citty";
 
 // src/id.ts
@@ -668,7 +847,7 @@ async function createDocument(kind, title, opts) {
   }
   const defaultStatus = kind === "adr" ? "proposed" : "draft";
   const status = opts.status ?? defaultStatus;
-  const validStatuses = kind === "adr" ? adrStatuses : specStatuses;
+  const validStatuses = kind === "adr" ? adrStatuses2 : specStatuses2;
   if (!validStatuses.includes(status)) {
     exitUsage(`Invalid status "${status}" for ${kind}. Valid: ${validStatuses.join(", ")}`);
   }
@@ -794,7 +973,7 @@ function parseTags(value) {
 // src/commands/renumber.ts
 import { readFile as readFile2, rename, writeFile as writeFile3 } from "fs/promises";
 import { basename, dirname, join as join5 } from "path";
-import { internalLinkKeys, loadProject as loadProject3 } from "@acta-dev/core";
+import { internalLinkKeys as internalLinkKeys2, loadProject as loadProject3 } from "@acta-dev/core";
 import { defineCommand as defineCommand6 } from "citty";
 import kleur4 from "kleur";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
@@ -818,7 +997,7 @@ function buildRenumberPlan(fromId, toId, project) {
   const oldSlug = oldFilename.replace(`${target.id}-`, "").replace(/\.md$/, "");
   const newFilename = `${toId}-${oldSlug}.md`;
   const newPath = join5(dirname(target.file.path), newFilename);
-  const affectedDocs = project.documents.filter((d) => d.id !== target.id).filter((d) => internalLinkKeys.some((key) => d.links[key].includes(target.id))).map((d) => ({ doc: d, path: d.file.path }));
+  const affectedDocs = project.documents.filter((d) => d.id !== target.id).filter((d) => internalLinkKeys2.some((key) => d.links[key].includes(target.id))).map((d) => ({ doc: d, path: d.file.path }));
   return {
     target,
     oldPath: target.file.path,
@@ -840,7 +1019,7 @@ async function rewriteDocument(filePath, oldId, newId, isTarget) {
   }
   const linksObj = fm.links;
   if (linksObj && typeof linksObj === "object") {
-    for (const key of internalLinkKeys) {
+    for (const key of internalLinkKeys2) {
       const arr = linksObj[key];
       if (Array.isArray(arr)) {
         linksObj[key] = arr.map((v) => v === oldId ? newId : v);
@@ -1036,13 +1215,155 @@ function formatShowDate(value) {
   return `${year}-${month}-${day}`;
 }
 
+// src/commands/site.ts
+import { spawn } from "child_process";
+import { createRequire } from "module";
+import { dirname as dirname2, join as join6, resolve as resolve3 } from "path";
+import { buildArtifacts as buildArtifacts2 } from "@acta-dev/core";
+import { defineCommand as defineCommand8 } from "citty";
+import kleur6 from "kleur";
+function resolveSiteOptions(config, args, cwd = process.cwd()) {
+  return {
+    outDir: args.out ? resolve3(cwd, args.out) : config.resolvedSite.outDir,
+    base: args.base ?? config.site.base,
+    site: args.site ?? config.site.url
+  };
+}
+function buildSiteEnv(config, options) {
+  const env = {
+    ...process.env,
+    ASTRO_TELEMETRY_DISABLED: "1",
+    ACTA_PROJECT_ROOT: config.rootDir,
+    ACTA_DIST_DIR: config.resolvedBuild.outDir,
+    ACTA_SITE_OUT: options.outDir
+  };
+  if (options.base !== void 0) env.ACTA_BASE = options.base;
+  if (options.site !== void 0) env.ACTA_SITE = options.site;
+  return env;
+}
+var siteCommand = defineCommand8({
+  meta: {
+    name: "site",
+    description: "Build a deployable static web viewer from your docs into the site output dir"
+  },
+  args: {
+    out: {
+      type: "string",
+      description: "Output directory for the generated site (default: .acta/site)"
+    },
+    base: {
+      type: "string",
+      description: "Base path for hosting under a subpath (e.g. /my-repo for project Pages)"
+    },
+    site: {
+      type: "string",
+      description: "Absolute site URL used for canonical links and sitemaps"
+    },
+    "skip-build": {
+      type: "boolean",
+      description: "Reuse existing artifacts instead of running `acta build` first",
+      default: false
+    },
+    config: {
+      type: "string",
+      alias: "c",
+      description: "Path to acta.config.ts"
+    },
+    json: {
+      type: "boolean",
+      description: "Print the result as JSON",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const { config } = await resolveContext({ config: args.config });
+    const json = Boolean(args.json);
+    let documentCount = 0;
+    if (!args["skip-build"]) {
+      if (!json) printLine("Building artifacts...");
+      const { manifest, validation } = await buildArtifacts2({ config });
+      documentCount = manifest.documentCount;
+      if (validation.errorCount > 0 && !json) {
+        printWarn(
+          `Building site with ${validation.errorCount} validation error${validation.errorCount !== 1 ? "s" : ""}. Run \`acta validate\` for details.`
+        );
+      }
+    }
+    const webDir = resolveWebPackageDir();
+    if (!webDir) {
+      return exitFailure(
+        "Could not locate @acta-dev/web. Install it alongside @acta-dev/cli to use `acta site`."
+      );
+    }
+    const astroBin = resolveAstroBin(webDir);
+    if (!astroBin) {
+      return exitFailure("Could not locate the Astro binary inside @acta-dev/web.");
+    }
+    const options = resolveSiteOptions(config, args);
+    if (!json) printLine("Building static viewer...");
+    const env = buildSiteEnv(config, options);
+    const code = await runAstroBuild(astroBin, webDir, env, json);
+    if (code !== 0) {
+      return exitFailure(`Astro build failed with exit code ${code}.`);
+    }
+    if (json) {
+      printJson({
+        ok: true,
+        outDir: options.outDir,
+        base: options.base ?? null,
+        site: options.site ?? null,
+        documentCount
+      });
+      return;
+    }
+    printLine();
+    printSuccess("Site built");
+    printLine(`  ${kleur6.bold("Output:")}  ${options.outDir}`);
+    if (options.base) printLine(`  ${kleur6.bold("Base:")}    ${options.base}`);
+    printLine();
+    printLine(kleur6.dim("Deploy the contents of the output directory to any static host."));
+  }
+});
+function resolveWebPackageDir() {
+  const require2 = createRequire(import.meta.url);
+  try {
+    return dirname2(require2.resolve("@acta-dev/web/package.json"));
+  } catch {
+    return void 0;
+  }
+}
+function resolveAstroBin(webDir) {
+  const require2 = createRequire(join6(webDir, "package.json"));
+  try {
+    const astroPkgJsonPath = require2.resolve("astro/package.json");
+    const astroPkg = require2("astro/package.json");
+    const binRel = typeof astroPkg.bin === "string" ? astroPkg.bin : astroPkg.bin?.astro;
+    if (!binRel) return void 0;
+    return join6(dirname2(astroPkgJsonPath), binRel);
+  } catch {
+    return void 0;
+  }
+}
+function runAstroBuild(astroBin, webDir, env, json) {
+  return new Promise((resolvePromise) => {
+    const child = spawn(process.execPath, [astroBin, "build"], {
+      cwd: webDir,
+      env,
+      // Astro logs go to stderr so JSON on stdout stays clean.
+      stdio: json ? ["ignore", "ignore", "inherit"] : "inherit"
+    });
+    child.on("close", (code) => resolvePromise(code ?? 1));
+    child.on("error", () => resolvePromise(1));
+  });
+}
+
 // src/commands/validate.ts
 import { mkdir as mkdir2, writeFile as writeFile4 } from "fs/promises";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 import { validateLoadedProject } from "@acta-dev/core";
-import { defineCommand as defineCommand8 } from "citty";
-import kleur6 from "kleur";
-var validateCommand = defineCommand8({
+import { defineCommand as defineCommand9 } from "citty";
+import kleur7 from "kleur";
+var validateCommand = defineCommand9({
   meta: {
     name: "validate",
     description: "Validate frontmatter, IDs, links, sections and repository rules"
@@ -1074,16 +1395,16 @@ var validateCommand = defineCommand8({
     }
     if (args.ci) {
       await mkdir2(config.resolvedBuild.outDir, { recursive: true });
-      const outPath = join6(config.resolvedBuild.outDir, "validation.json");
+      const outPath = join7(config.resolvedBuild.outDir, "validation.json");
       await writeFile4(outPath, `${JSON.stringify(result, null, 2)}
 `, "utf8");
       if (result.errors.length > 0) {
         for (const issue of result.errors) {
-          printLine(`${kleur6.red("error")}  ${issue.documentId ?? ""}  ${issue.message}`);
+          printLine(`${kleur7.red("error")}  ${issue.documentId ?? ""}  ${issue.message}`);
         }
       }
       for (const issue of result.warnings) {
-        printLine(`${kleur6.yellow("warn")}   ${issue.documentId ?? ""}  ${issue.message}`);
+        printLine(`${kleur7.yellow("warn")}   ${issue.documentId ?? ""}  ${issue.message}`);
       }
       printLine(`Written ${outPath}`);
       process.exit(result.valid ? 0 : 1);
@@ -1096,12 +1417,12 @@ var validateCommand = defineCommand8({
       const warnings = result.issues.filter((i) => i.severity === "warning");
       if (errors.length > 0) {
         printLine();
-        printLine(kleur6.bold("Errors:"));
+        printLine(kleur7.bold("Errors:"));
         printIssues(errors);
       }
       if (warnings.length > 0) {
         printLine();
-        printLine(kleur6.bold("Warnings:"));
+        printLine(kleur7.bold("Warnings:"));
         printIssues(warnings);
       }
       printLine();
@@ -1112,7 +1433,7 @@ var validateCommand = defineCommand8({
 });
 
 // src/index.ts
-var main = defineCommand9({
+var main = defineCommand10({
   meta: {
     name: "acta",
     version: "0.0.0",
@@ -1126,6 +1447,7 @@ var main = defineCommand9({
     validate: validateCommand,
     graph: graphCommand,
     build: buildCommand,
+    site: siteCommand,
     renumber: renumberCommand
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acta-dev/cli",
-  "version": "0.1.1",
+  "version": "1.1.0",
   "description": "Acta CLI — TypeScript-first docs-as-code tooling for ADR and spec documents in Git. Provides the `acta` binary.",
   "keywords": [
     "adr",
@@ -45,7 +45,8 @@
     "citty": "^0.2.2",
     "kleur": "^4.1.5",
     "yaml": "^2.8.3",
-    "@acta-dev/core": "0.1.1"
+    "@acta-dev/core": "1.1.0",
+    "@acta-dev/web": "1.0.0"
   },
   "devDependencies": {
     "execa": "^9.6.1",