@acta-dev/cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Boris Khakhin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @acta-dev/cli
+
+The `acta` command-line tool — TypeScript-first docs-as-code for **ADR** and **spec** documents in a Git repository.
+
+Markdown stays the source of truth; Acta adds a strict document model, validation, graph artifacts and CLI workflows so a team can understand why decisions were made and which specs depend on them.
+
+## Install
+
+```sh
+npm install -g @acta-dev/cli
+# or run without installing:
+npx @acta-dev/cli init
+```
+
+The installed binary is `acta`.
+
+## Quick start
+
+```sh
+acta init
+acta new adr "Adopt Acta"
+acta new spec "Document workflow"
+acta validate
+acta build
+```
+
+`acta init` creates `acta.config.ts`, `docs/decisions/`, `docs/specs/` and starter templates under `docs/templates/`.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `acta init` | Create config, document folders and templates. |
+| `acta new adr\|spec <title>` | Create a document with the next available ID. |
+| `acta list` | List documents, filterable by kind/status/tag. |
+| `acta show <id>` | Show metadata, sections, links and backlinks. |
+| `acta validate` | Validate frontmatter, IDs, links, sections and graph rules. |
+| `acta graph` | Print the relationship graph as Mermaid or JSON. |
+| `acta build` | Write `.acta/dist` JSON artifacts. |
+| `acta renumber <from> <to>` | Rename an ID and update internal links. |
+
+Full reference: [github.com/jentix/acta](https://github.com/jentix/acta).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+declare const actaCliPackage = "@acta-dev/cli";
+declare function getCliBootstrapInfo(): {
+    name: string;
+    packageName: string;
+    version: string;
+};
+
+export { actaCliPackage, getCliBootstrapInfo };

package/dist/index.js

@@ -0,0 +1,1152 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+import { defineCommand as defineCommand9, runMain } from "citty";
+
+// src/commands/build.ts
+import { buildArtifacts } from "@acta-dev/core";
+import { defineCommand } from "citty";
+import kleur2 from "kleur";
+
+// src/context.ts
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+import { loadConfig, resolveConfig } from "@acta-dev/core";
+async function resolveContext(opts) {
+  const cwd = resolve(opts.cwd ?? process.cwd());
+  if (opts.config) {
+    const config2 = await loadConfig(opts.config);
+    return { config: config2, cwd };
+  }
+  for (const dir of [cwd, join(cwd, ".."), join(cwd, "../..")]) {
+    const candidate = join(dir, "acta.config.ts");
+    if (existsSync(candidate)) {
+      const config2 = await loadConfig(candidate);
+      return { config: config2, cwd };
+    }
+  }
+  const config = resolveConfig({}, { rootDir: cwd });
+  return { config, cwd };
+}
+
+// src/output.ts
+import kleur from "kleur";
+function printLine(msg = "") {
+  process.stdout.write(`${msg}
+`);
+}
+function printError(msg) {
+  process.stderr.write(`${kleur.red("error")} ${msg}
+`);
+}
+function printWarn(msg) {
+  process.stderr.write(`${kleur.yellow("warn")} ${msg}
+`);
+}
+function printSuccess(msg) {
+  process.stdout.write(`${kleur.green("\u2713")} ${msg}
+`);
+}
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+function exitFailure(msg) {
+  if (msg) printError(msg);
+  process.exit(1);
+}
+function exitUsage(msg) {
+  process.stderr.write(`${kleur.red("usage error")} ${msg}
+`);
+  process.exit(2);
+}
+function printIssues(issues) {
+  for (const issue of issues) {
+    const prefix = issue.severity === "error" ? kleur.red("\u2717 error") : kleur.yellow("\u26A0 warn ");
+    const location = issue.documentId ? kleur.bold(issue.documentId) : issue.path ?? "";
+    printLine(`  ${prefix}  ${location}  ${issue.message}`);
+  }
+}
+function printValidationSummary(errorCount, warningCount, valid) {
+  if (valid) {
+    printSuccess(
+      `Validation passed  ${kleur.dim(`(${warningCount} warning${warningCount !== 1 ? "s" : ""})`)}`
+    );
+  } else {
+    printLine(
+      `  ${kleur.red(`${errorCount} error${errorCount !== 1 ? "s" : ""}`)}  ${kleur.yellow(`${warningCount} warning${warningCount !== 1 ? "s" : ""}`)}`
+    );
+  }
+}
+function printTable(rows) {
+  if (rows.length === 0) return;
+  const widths = rows[0]?.map((_, col) => Math.max(...rows.map((row) => (row[col] ?? "").length)));
+  for (const row of rows) {
+    printLine(row.map((cell, col) => cell.padEnd(widths[col] ?? 0)).join("  "));
+  }
+}
+
+// src/commands/build.ts
+var buildCommand = defineCommand({
+  meta: {
+    name: "build",
+    description: "Build normalized JSON artifacts for the web viewer, CI and integrations"
+  },
+  args: {
+    json: {
+      type: "boolean",
+      description: "Print the build manifest as JSON",
+      default: false
+    },
+    config: {
+      type: "string",
+      alias: "c",
+      description: "Path to acta.config.ts"
+    }
+  },
+  async run({ args }) {
+    const { config } = await resolveContext({ config: args.config });
+    if (!args.json) {
+      printLine("Building artifacts...");
+    }
+    const result = await buildArtifacts({ config });
+    const { manifest, validation } = result;
+    if (args.json) {
+      printJson({ ...manifest, outDir: config.resolvedBuild.outDir });
+      process.exit(validation.errorCount > 0 ? 1 : 0);
+      return;
+    }
+    printLine();
+    printSuccess(`Build complete`);
+    printLine(`  ${kleur2.bold("Documents:")}  ${manifest.documentCount}`);
+    printLine(
+      `  ${kleur2.bold("Errors:")}     ${manifest.errorCount === 0 ? kleur2.green("0") : kleur2.red(String(manifest.errorCount))}`
+    );
+    printLine(
+      `  ${kleur2.bold("Warnings:")}   ${manifest.warningCount === 0 ? kleur2.dim("0") : kleur2.yellow(String(manifest.warningCount))}`
+    );
+    printLine(`  ${kleur2.bold("Output:")}     ${config.resolvedBuild.outDir}`);
+    printLine(`  ${kleur2.bold("Built at:")}   ${manifest.builtAt}`);
+    if (validation.errorCount > 0) {
+      printLine();
+      printWarn(
+        `Build completed with ${validation.errorCount} validation error${validation.errorCount !== 1 ? "s" : ""}. Run \`acta validate\` for details.`
+      );
+      process.exit(1);
+    }
+  }
+});
+
+// src/commands/graph.ts
+import { buildGraph, loadProject } from "@acta-dev/core";
+import { defineCommand as defineCommand2 } from "citty";
+var STATUS_FILL = {
+  accepted: "#4ade80",
+  proposed: "#60a5fa",
+  rejected: "#f87171",
+  deprecated: "#a3a3a3",
+  superseded: "#d1d5db",
+  active: "#4ade80",
+  draft: "#60a5fa",
+  paused: "#fbbf24",
+  implemented: "#34d399",
+  obsolete: "#a3a3a3"
+};
+function nodeLabel(node) {
+  const safeTitle = node.title.replace(/"/g, "'");
+  return `${node.id}["${node.id}<br/>${safeTitle}"]:::${node.kind}_${sanitizeStatus(node.status)}`;
+}
+function sanitizeStatus(status) {
+  return status.replace(/[^a-z0-9]/g, "_");
+}
+function edgeLabel(edge) {
+  return `  ${edge.source} -->|${edge.type}| ${edge.target}`;
+}
+function toMermaid(graph) {
+  const lines = ["flowchart LR"];
+  const classNames = /* @__PURE__ */ new Set();
+  for (const node of graph.nodes) {
+    lines.push(`  ${nodeLabel(node)}`);
+    classNames.add(`${node.kind}_${sanitizeStatus(node.status)}`);
+  }
+  if (graph.edges.length > 0) {
+    lines.push("");
+    for (const edge of graph.edges) {
+      lines.push(edgeLabel(edge));
+    }
+  }
+  if (classNames.size > 0) {
+    lines.push("");
+    for (const cls of classNames) {
+      const status = cls.replace(/^adr_|^spec_/, "").replace(/_/g, "");
+      const fill = STATUS_FILL[status] ?? "#e5e7eb";
+      lines.push(`  classDef ${cls} fill:${fill},stroke:#6b7280,color:#111827`);
+    }
+  }
+  return lines.join("\n");
+}
+var graphCommand = defineCommand2({
+  meta: {
+    name: "graph",
+    description: "Print the document relationship graph as Mermaid or JSON"
+  },
+  args: {
+    format: {
+      type: "string",
+      alias: "f",
+      description: "Output format: mermaid | json (default: mermaid)",
+      default: "mermaid"
+    },
+    config: {
+      type: "string",
+      alias: "c",
+      description: "Path to acta.config.ts"
+    }
+  },
+  async run({ args }) {
+    const fmt = args.format ?? "mermaid";
+    if (fmt !== "mermaid" && fmt !== "json") {
+      exitUsage(`Unknown format "${fmt}". Use: mermaid, json`);
+    }
+    const { config } = await resolveContext({ config: args.config });
+    const project = await loadProject({ config });
+    const graph = buildGraph(project.documents);
+    if (fmt === "json") {
+      printJson(graph);
+    } else {
+      printLine(toMermaid(graph));
+    }
+  }
+});
+
+// src/commands/init.ts
+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 { defineCommand as defineCommand3 } from "citty";
+var ADR_TEMPLATE = `---
+id: ADR-0000
+kind: adr
+title: Template ADR
+status: proposed
+date: YYYY-MM-DD
+tags: []
+component: []
+owners: []
+summary: Short summary of the architectural decision.
+links:
+  related: []
+  supersedes: []
+  replacedBy: []
+  decidedBy: []
+  dependsOn: []
+  validates: []
+  references: []
+---
+
+# Context
+
+Describe the forces, constraints, and problem that make this decision necessary.
+
+# Decision
+
+State the decision clearly.
+
+# Consequences
+
+Describe expected tradeoffs, follow-up work, and operational impact.
+
+# Alternatives
+
+List the meaningful options considered and why they were not chosen.
+`;
+var SPEC_TEMPLATE = `---
+id: SPEC-0000
+kind: spec
+title: Template Spec
+status: draft
+date: YYYY-MM-DD
+tags: []
+component: []
+owners: []
+summary: Short summary of the technical specification.
+links:
+  related: []
+  decidedBy: []
+  dependsOn: []
+  validates: []
+  references: []
+---
+
+# Summary
+
+Describe the feature, system, or technical change.
+
+# Goals
+
+List the outcomes this spec must achieve.
+
+# Requirements
+
+Define functional and non-functional requirements.
+
+# Proposed design
+
+Describe the planned design.
+
+# Open questions
+
+Track unresolved decisions.
+`;
+var CONFIG_TEMPLATE = `import { defineConfig } from "@acta-dev/core";
+
+export default defineConfig({
+  docs: {
+    adrDir: "docs/decisions",
+    specDir: "docs/specs",
+    templatesDir: "docs/templates",
+  },
+  ids: {
+    adrPrefix: "ADR",
+    specPrefix: "SPEC",
+    width: 4,
+  },
+  validation: {
+    draftMaxAgeDays: 30,
+    requiredSections: {
+      adr: ["Context", "Decision", "Consequences"],
+      spec: ["Summary", "Goals", "Requirements"],
+    },
+    orphanDocuments: "warning",
+    asymmetricSupersedes: "error",
+  },
+  build: {
+    outDir: ".acta/dist",
+    cacheDir: ".acta/cache",
+  },
+});
+`;
+var LEFTHOOK_TEMPLATE = `pre-commit:
+  commands:
+    biome:
+      glob: "*.{js,jsx,ts,tsx,json,jsonc,css,md,yml,yaml}"
+      run: pnpm exec biome check --write --files-ignore-unknown=true {staged_files}
+      stage_fixed: true
+
+pre-push:
+  commands:
+    typecheck:
+      run: pnpm typecheck
+    test:
+      run: pnpm test
+`;
+var GITHUB_ACTION_TEMPLATE = `name: Acta CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  verify:
+    name: Verify
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: package.json
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Check formatting
+        run: pnpm format:check
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build
+
+      - name: Validate Acta docs
+        run: pnpm exec acta validate
+
+      - name: Build Acta artifacts
+        run: pnpm exec acta build
+`;
+async function confirm(message) {
+  return new Promise((resolvePromise) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`${message} [y/N] `, (answer) => {
+      rl.close();
+      resolvePromise(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
+async function safeWriteFile(filePath, content, yes) {
+  if (existsSync2(filePath)) {
+    if (!yes) {
+      const ok = await confirm(`  Overwrite ${filePath}?`);
+      if (!ok) {
+        printWarn(`Skipped ${filePath}`);
+        return false;
+      }
+    } else {
+      printWarn(`Overwriting ${filePath}`);
+    }
+  }
+  await writeFile(filePath, content, "utf8");
+  return true;
+}
+var initCommand = defineCommand3({
+  meta: {
+    name: "init",
+    description: "Create Acta config, document folders and templates in the current repository"
+  },
+  args: {
+    yes: {
+      type: "boolean",
+      alias: "y",
+      description: "Skip prompts and overwrite existing files",
+      default: false
+    },
+    hooks: {
+      type: "boolean",
+      description: "Install Lefthook workflow template",
+      default: false
+    },
+    "github-action": {
+      type: "boolean",
+      description: "Install GitHub Actions workflow template",
+      default: false
+    },
+    config: {
+      type: "string",
+      alias: "c",
+      description: "Path to acta.config.ts (default: acta.config.ts)"
+    }
+  },
+  async run({ args }) {
+    const cwd = resolve2(process.cwd());
+    const yes = args.yes;
+    const config = resolveConfig2({}, { rootDir: cwd });
+    printLine("Initializing Acta docs structure...");
+    printLine();
+    const configPath = join2(cwd, "acta.config.ts");
+    const configWritten = await safeWriteFile(configPath, CONFIG_TEMPLATE, yes);
+    if (configWritten) printSuccess(`Created ${configPath}`);
+    const dirs = [
+      config.resolvedDocs.adrDir,
+      config.resolvedDocs.specDir,
+      config.resolvedDocs.templatesDir
+    ];
+    for (const dir of dirs) {
+      await mkdir(dir, { recursive: true });
+      printSuccess(`Created dir ${dir}`);
+    }
+    const adrTplPath = join2(config.resolvedDocs.templatesDir, "adr.md");
+    const specTplPath = join2(config.resolvedDocs.templatesDir, "spec.md");
+    const adrWritten = await safeWriteFile(adrTplPath, ADR_TEMPLATE, yes);
+    if (adrWritten) printSuccess(`Created ${adrTplPath}`);
+    const specWritten = await safeWriteFile(specTplPath, SPEC_TEMPLATE, yes);
+    if (specWritten) printSuccess(`Created ${specTplPath}`);
+    const gitignorePath = join2(cwd, ".gitignore");
+    if (existsSync2(gitignorePath)) {
+      const { readFile: readFile3, appendFile } = await import("fs/promises");
+      const content = await readFile3(gitignorePath, "utf8");
+      if (!content.includes(".acta/")) {
+        await appendFile(gitignorePath, "\n# Acta build artifacts\n.acta/\n");
+        printSuccess(`Added .acta/ to .gitignore`);
+      }
+    }
+    if (args.hooks) {
+      const lefthookPath = join2(cwd, "lefthook.yml");
+      const lefthookWritten = await safeWriteFile(lefthookPath, LEFTHOOK_TEMPLATE, yes);
+      if (lefthookWritten) printSuccess(`Created ${lefthookPath}`);
+    }
+    if (args["github-action"]) {
+      const workflowsDir = join2(cwd, ".github", "workflows");
+      await mkdir(workflowsDir, { recursive: true });
+      const workflowPath = join2(workflowsDir, "acta-ci.yml");
+      const workflowWritten = await safeWriteFile(workflowPath, GITHUB_ACTION_TEMPLATE, yes);
+      if (workflowWritten) printSuccess(`Created ${workflowPath}`);
+    }
+    printLine();
+    printSuccess("Acta initialized. Run `acta validate` to check your documents.");
+  }
+});
+
+// src/commands/list.ts
+import { loadProject as loadProject2 } from "@acta-dev/core";
+import { defineCommand as defineCommand4 } from "citty";
+import kleur3 from "kleur";
+var STATUS_COLORS = {
+  // ADR
+  proposed: (s) => kleur3.cyan(s),
+  accepted: (s) => kleur3.green(s),
+  rejected: (s) => kleur3.red(s),
+  deprecated: (s) => kleur3.yellow(s),
+  superseded: (s) => kleur3.dim(s),
+  // Spec
+  draft: (s) => kleur3.cyan(s),
+  active: (s) => kleur3.green(s),
+  paused: (s) => kleur3.yellow(s),
+  implemented: (s) => kleur3.green(s),
+  obsolete: (s) => kleur3.dim(s)
+};
+function colorStatus(status) {
+  return (STATUS_COLORS[status] ?? ((s) => s))(status);
+}
+var listCommand = defineCommand4({
+  meta: {
+    name: "list",
+    description: "List ADR and spec documents with optional filters"
+  },
+  args: {
+    kind: {
+      type: "string",
+      alias: "k",
+      description: "Filter by kind: adr | spec"
+    },
+    status: {
+      type: "string",
+      alias: "s",
+      description: "Filter by status"
+    },
+    tag: {
+      type: "string",
+      alias: "t",
+      description: "Filter by tag"
+    },
+    json: {
+      type: "boolean",
+      description: "Output as JSON",
+      default: false
+    },
+    config: {
+      type: "string",
+      alias: "c",
+      description: "Path to acta.config.ts"
+    }
+  },
+  async run({ args }) {
+    const { config } = await resolveContext({ config: args.config });
+    const project = await loadProject2({ config });
+    let docs = project.documents;
+    if (args.kind) {
+      if (args.kind !== "adr" && args.kind !== "spec") {
+        process.stderr.write(`error: unknown kind "${args.kind}". Use: adr, spec
+`);
+        process.exit(2);
+      }
+      docs = docs.filter((d) => d.kind === args.kind);
+    }
+    if (args.status) {
+      docs = docs.filter((d) => d.status === args.status);
+    }
+    if (args.tag) {
+      const tag = args.tag;
+      docs = docs.filter((d) => d.tags.includes(tag));
+    }
+    docs = docs.slice().sort((a, b) => {
+      if (a.kind !== b.kind) return a.kind.localeCompare(b.kind);
+      return a.id.localeCompare(b.id);
+    });
+    if (args.json) {
+      printJson(
+        docs.map((d) => ({
+          id: d.id,
+          kind: d.kind,
+          title: d.title,
+          status: d.status,
+          date: d.date,
+          tags: d.tags,
+          component: d.component,
+          owners: d.owners,
+          summary: d.summary
+        }))
+      );
+      return;
+    }
+    if (docs.length === 0) {
+      printLine("No documents found.");
+      return;
+    }
+    const rows = [
+      [kleur3.bold("ID"), kleur3.bold("KIND"), kleur3.bold("STATUS"), kleur3.bold("TITLE")],
+      ...docs.map((d) => [kleur3.bold(d.id), d.kind, colorStatus(d.status), d.title])
+    ];
+    printTable(rows);
+    printLine();
+    printLine(kleur3.dim(`${docs.length} document${docs.length !== 1 ? "s" : ""}`));
+  }
+});
+
+// src/commands/new.ts
+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 { defineCommand as defineCommand5 } from "citty";
+
+// src/id.ts
+function allocateNextId(kind, documents, config) {
+  const prefix = kind === "adr" ? config.ids.adrPrefix : config.ids.specPrefix;
+  const existing = documents.filter((doc) => doc.kind === kind).map((doc) => {
+    const match = doc.id.match(/(\d+)$/);
+    return match?.[1] !== void 0 ? parseInt(match[1], 10) : 0;
+  });
+  const next = existing.length > 0 ? Math.max(...existing) + 1 : 1;
+  return `${prefix}-${String(next).padStart(config.ids.width, "0")}`;
+}
+
+// src/slug.ts
+function titleToSlug(title) {
+  return title.toLowerCase().normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[^a-z0-9]+/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+}
+
+// src/template.ts
+import { readFile } from "fs/promises";
+import { join as join3 } from "path";
+async function renderTemplate(kind, vars, config) {
+  const templateFile = join3(config.resolvedDocs.templatesDir, `${kind}.md`);
+  const raw = await readFile(templateFile, "utf8");
+  return interpolate(raw, vars);
+}
+function interpolate(raw, vars) {
+  let rendered = raw.replace(/^(id:\s*).*$/m, `$1${vars.id}`).replace(/^(title:\s*).*$/m, `$1${vars.title}`).replace(/^(date:\s*).*$/m, `$1${vars.date}`).replace(/^(status:\s*).*$/m, `$1${vars.status}`);
+  if (vars.tags) {
+    rendered = rendered.replace(/^(tags:\s*).*$/m, `$1[${vars.tags.join(", ")}]`);
+  }
+  return rendered;
+}
+function nowIsoDateTime() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// src/commands/new.ts
+async function createDocument(kind, title, opts) {
+  if (!title || title.trim() === "") {
+    exitUsage(`Title is required. Usage: acta new ${kind} "My title"`);
+  }
+  const { config } = await resolveContext({ config: opts.config });
+  const { loadProject: loadProject5 } = await import("@acta-dev/core");
+  const project = await loadProject5({ config });
+  let id;
+  if (opts.id) {
+    const prefix = kind === "adr" ? config.ids.adrPrefix : config.ids.specPrefix;
+    if (!opts.id.startsWith(`${prefix}-`)) {
+      exitUsage(`ID "${opts.id}" does not match ${kind} prefix "${prefix}-"`);
+    }
+    const existing = project.documents.find((d) => d.id === opts.id);
+    if (existing) {
+      exitFailure(`Document "${opts.id}" already exists at ${existing.file.path}`);
+    }
+    id = opts.id;
+  } else {
+    id = allocateNextId(kind, project.documents, config);
+  }
+  const defaultStatus = kind === "adr" ? "proposed" : "draft";
+  const status = opts.status ?? defaultStatus;
+  const validStatuses = kind === "adr" ? adrStatuses : specStatuses;
+  if (!validStatuses.includes(status)) {
+    exitUsage(`Invalid status "${status}" for ${kind}. Valid: ${validStatuses.join(", ")}`);
+  }
+  const slug = titleToSlug(title.trim());
+  const filename = `${id}-${slug}.md`;
+  const dir = kind === "adr" ? config.resolvedDocs.adrDir : config.resolvedDocs.specDir;
+  const destPath = join4(dir, filename);
+  if (existsSync3(destPath)) {
+    exitFailure(`File already exists: ${destPath}`);
+  }
+  const content = await renderTemplate(
+    kind,
+    { id, title: title.trim(), date: nowIsoDateTime(), status, tags: parseTags(opts.tags) },
+    config
+  );
+  await writeFile2(destPath, content, "utf8");
+  if (opts.json) {
+    printJson({
+      id,
+      kind,
+      title: title.trim(),
+      status,
+      path: destPath,
+      relativePath: relative(process.cwd(), destPath)
+    });
+    return;
+  }
+  printSuccess(`Created ${destPath}`);
+}
+var newCommand = defineCommand5({
+  meta: {
+    name: "new",
+    description: "Create a new ADR or spec from the configured templates"
+  },
+  args: {
+    config: {
+      type: "string",
+      alias: "c",
+      description: "Path to acta.config.ts"
+    }
+  },
+  subCommands: {
+    adr: defineCommand5({
+      meta: { name: "adr", description: "Create a new ADR with the next available ID" },
+      args: {
+        title: {
+          type: "positional",
+          description: "Document title",
+          required: true
+        },
+        id: {
+          type: "string",
+          description: "Override auto-allocated ID (e.g. ADR-0007)"
+        },
+        status: {
+          type: "string",
+          description: "Initial status (default: proposed)"
+        },
+        tags: {
+          type: "string",
+          description: "Comma-separated tags"
+        },
+        json: {
+          type: "boolean",
+          description: "Print the created document id and path as JSON",
+          default: false
+        },
+        config: {
+          type: "string",
+          alias: "c",
+          description: "Path to acta.config.ts"
+        }
+      },
+      async run({ args }) {
+        await createDocument("adr", args.title, args);
+      }
+    }),
+    spec: defineCommand5({
+      meta: { name: "spec", description: "Create a new spec with the next available ID" },
+      args: {
+        title: {
+          type: "positional",
+          description: "Document title",
+          required: true
+        },
+        id: {
+          type: "string",
+          description: "Override auto-allocated ID (e.g. SPEC-0005)"
+        },
+        status: {
+          type: "string",
+          description: "Initial status (default: draft)"
+        },
+        tags: {
+          type: "string",
+          description: "Comma-separated tags"
+        },
+        json: {
+          type: "boolean",
+          description: "Print the created document id and path as JSON",
+          default: false
+        },
+        config: {
+          type: "string",
+          alias: "c",
+          description: "Path to acta.config.ts"
+        }
+      },
+      async run({ args }) {
+        await createDocument("spec", args.title, args);
+      }
+    })
+  }
+});
+function parseTags(value) {
+  if (!value) {
+    return void 0;
+  }
+  const tags = value.split(",").map((tag) => tag.trim()).filter(Boolean);
+  return tags.length > 0 ? tags : void 0;
+}
+
+// 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 { defineCommand as defineCommand6 } from "citty";
+import kleur4 from "kleur";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+function buildRenumberPlan(fromId, toId, project) {
+  const target = project.documents.find((d) => d.id.toLowerCase() === fromId.toLowerCase());
+  if (!target) {
+    exitFailure(`Document "${fromId}" not found.`);
+  }
+  const collision = project.documents.find((d) => d.id.toLowerCase() === toId.toLowerCase());
+  if (collision) {
+    exitFailure(`Target ID "${toId}" already exists at ${collision.file.path}.`);
+  }
+  const fromPrefix = fromId.replace(/-\d+$/, "");
+  const toPrefix = toId.replace(/-\d+$/, "");
+  if (fromPrefix !== toPrefix) {
+    exitUsage(
+      `Cannot renumber across kinds. FROM prefix "${fromPrefix}" \u2260 TO prefix "${toPrefix}".`
+    );
+  }
+  const oldFilename = basename(target.file.path);
+  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 }));
+  return {
+    target,
+    oldPath: target.file.path,
+    newPath,
+    newFilename,
+    affectedDocs
+  };
+}
+async function rewriteDocument(filePath, oldId, newId, isTarget) {
+  const raw = await readFile2(filePath, "utf8");
+  const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) {
+    throw new Error(`Cannot parse frontmatter in ${filePath}`);
+  }
+  const [, frontmatterYaml, body] = match;
+  const fm = parseYaml(frontmatterYaml);
+  if (isTarget) {
+    fm.id = newId;
+  }
+  const linksObj = fm.links;
+  if (linksObj && typeof linksObj === "object") {
+    for (const key of internalLinkKeys) {
+      const arr = linksObj[key];
+      if (Array.isArray(arr)) {
+        linksObj[key] = arr.map((v) => v === oldId ? newId : v);
+      }
+    }
+  }
+  const newFrontmatter = stringifyYaml(fm, { lineWidth: 0 }).trimEnd();
+  return `---
+${newFrontmatter}
+---
+${body}`;
+}
+var renumberCommand = defineCommand6({
+  meta: {
+    name: "renumber",
+    description: "Rename a document ID and update its filename plus internal links"
+  },
+  args: {
+    from: {
+      type: "positional",
+      description: "Current document ID (e.g. ADR-0001)",
+      required: true
+    },
+    to: {
+      type: "positional",
+      description: "New document ID (e.g. ADR-0007)",
+      required: true
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Print what would change without writing",
+      default: false
+    },
+    config: {
+      type: "string",
+      alias: "c",
+      description: "Path to acta.config.ts"
+    }
+  },
+  async run({ args }) {
+    const fromId = args.from;
+    const toId = args.to;
+    const dryRun = args["dry-run"];
+    if (!fromId || !toId) {
+      exitUsage("Usage: acta renumber <FROM> <TO>");
+    }
+    const { config } = await resolveContext({ config: args.config });
+    const project = await loadProject3({ config });
+    const plan = buildRenumberPlan(fromId, toId, project);
+    printLine();
+    printLine(kleur4.bold("Renumber plan:"));
+    printLine(`  ${kleur4.dim("rename")}  ${plan.target.id} \u2192 ${kleur4.bold(toId)}`);
+    printLine(
+      `  ${kleur4.dim("file")}    ${basename(plan.oldPath)} \u2192 ${kleur4.bold(plan.newFilename)}`
+    );
+    if (plan.affectedDocs.length > 0) {
+      printLine(`  ${kleur4.dim("update links in:")}`);
+      for (const { doc } of plan.affectedDocs) {
+        printLine(`    ${doc.id}  ${doc.file.relativePath}`);
+      }
+    } else {
+      printLine(`  ${kleur4.dim("no other documents reference this ID")}`);
+    }
+    if (dryRun) {
+      printLine();
+      printWarn("Dry run \u2014 no changes written.");
+      return;
+    }
+    printLine();
+    for (const { doc, path } of plan.affectedDocs) {
+      const rewritten = await rewriteDocument(path, fromId, toId, false);
+      await writeFile3(path, rewritten, "utf8");
+      printSuccess(`Updated links in ${doc.id}`);
+    }
+    const rewrittenTarget = await rewriteDocument(plan.oldPath, fromId, toId, true);
+    await writeFile3(plan.oldPath, rewrittenTarget, "utf8");
+    await rename(plan.oldPath, plan.newPath);
+    printSuccess(`Renamed ${basename(plan.oldPath)} \u2192 ${plan.newFilename}`);
+    printLine();
+    printSuccess(`Renumber complete: ${fromId} \u2192 ${toId}`);
+    const { validateLoadedProject: validateLoadedProject2 } = await import("@acta-dev/core");
+    const result = await validateLoadedProject2({ config });
+    if (!result.valid) {
+      printLine();
+      printWarn(
+        `Renumber introduced ${result.errorCount} validation error${result.errorCount !== 1 ? "s" : ""}. Run \`acta validate\` for details.`
+      );
+      process.exit(1);
+    }
+  }
+});
+
+// src/commands/show.ts
+import { loadProject as loadProject4 } from "@acta-dev/core";
+import { defineCommand as defineCommand7 } from "citty";
+import kleur5 from "kleur";
+var showCommand = defineCommand7({
+  meta: {
+    name: "show",
+    description: "Show metadata, sections, links and backlinks for one document"
+  },
+  args: {
+    id: {
+      type: "positional",
+      description: "Document ID (e.g. ADR-0001)",
+      required: true
+    },
+    json: {
+      type: "boolean",
+      description: "Output full document as JSON",
+      default: false
+    },
+    config: {
+      type: "string",
+      alias: "c",
+      description: "Path to acta.config.ts"
+    }
+  },
+  async run({ args }) {
+    if (!args.id) {
+      exitUsage("ID is required. Usage: acta show <ID>");
+    }
+    const { config } = await resolveContext({ config: args.config });
+    const project = await loadProject4({ config });
+    const doc = project.documents.find((d) => d.id.toLowerCase() === args.id.toLowerCase());
+    if (!doc) {
+      exitFailure(`Document "${args.id}" not found.`);
+    }
+    if (args.json) {
+      printJson(doc);
+      return;
+    }
+    printLine();
+    printLine(`${kleur5.bold(doc.id)}  ${kleur5.dim(doc.kind)}  ${doc.status}`);
+    printLine(kleur5.bold(doc.title));
+    printLine(kleur5.dim(doc.file.relativePath));
+    printLine();
+    if (doc.summary) {
+      printLine(doc.summary);
+      printLine();
+    }
+    printLine(
+      `${kleur5.bold("Date:")}     ${formatShowDate(doc.date)}${doc.updated ? `  (updated ${formatShowDate(doc.updated)})` : ""}`
+    );
+    if (doc.tags.length > 0) {
+      printLine(`${kleur5.bold("Tags:")}     ${doc.tags.join(", ")}`);
+    }
+    if (doc.component.length > 0) {
+      printLine(`${kleur5.bold("Component:")} ${doc.component.join(", ")}`);
+    }
+    if (doc.owners.length > 0) {
+      printLine(`${kleur5.bold("Owners:")}   ${doc.owners.join(", ")}`);
+    }
+    if (doc.sections.length > 0) {
+      printLine();
+      printLine(kleur5.bold("Sections:"));
+      for (const section of doc.sections) {
+        printLine(`  ${"#".repeat(section.level)} ${section.title}`);
+      }
+    }
+    const linkEntries = Object.entries(doc.links).filter(([, ids]) => ids.length > 0);
+    if (linkEntries.length > 0) {
+      printLine();
+      printLine(kleur5.bold("Links:"));
+      for (const [key, ids] of linkEntries) {
+        printLine(`  ${kleur5.cyan(key)}: ${ids.join(", ")}`);
+      }
+    }
+    const backlinkEntries = Object.entries(doc.backlinks).filter(
+      ([, ids]) => ids.length > 0
+    );
+    if (backlinkEntries.length > 0) {
+      printLine();
+      printLine(kleur5.bold("Backlinks:"));
+      for (const [key, ids] of backlinkEntries) {
+        printLine(`  ${kleur5.cyan(key)}: ${ids.join(", ")}`);
+      }
+    }
+    printLine();
+  }
+});
+function formatShowDate(value) {
+  if (!value) {
+    return "";
+  }
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return value;
+  }
+  const year = parsed.getUTCFullYear();
+  const month = String(parsed.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(parsed.getUTCDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+// src/commands/validate.ts
+import { mkdir as mkdir2, writeFile as writeFile4 } from "fs/promises";
+import { join as join6 } from "path";
+import { validateLoadedProject } from "@acta-dev/core";
+import { defineCommand as defineCommand8 } from "citty";
+import kleur6 from "kleur";
+var validateCommand = defineCommand8({
+  meta: {
+    name: "validate",
+    description: "Validate frontmatter, IDs, links, sections and repository rules"
+  },
+  args: {
+    ci: {
+      type: "boolean",
+      description: "Write validation.json to outDir and use concise output",
+      default: false
+    },
+    json: {
+      type: "boolean",
+      description: "Print machine-readable result to stdout",
+      default: false
+    },
+    config: {
+      type: "string",
+      alias: "c",
+      description: "Path to acta.config.ts"
+    }
+  },
+  async run({ args }) {
+    const { config } = await resolveContext({ config: args.config });
+    const result = await validateLoadedProject({ config });
+    if (args.json) {
+      printJson(result);
+      process.exit(result.valid ? 0 : 1);
+      return;
+    }
+    if (args.ci) {
+      await mkdir2(config.resolvedBuild.outDir, { recursive: true });
+      const outPath = join6(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}`);
+        }
+      }
+      for (const issue of result.warnings) {
+        printLine(`${kleur6.yellow("warn")}   ${issue.documentId ?? ""}  ${issue.message}`);
+      }
+      printLine(`Written ${outPath}`);
+      process.exit(result.valid ? 0 : 1);
+      return;
+    }
+    if (result.issues.length === 0) {
+      printValidationSummary(0, 0, true);
+    } else {
+      const errors = result.issues.filter((i) => i.severity === "error");
+      const warnings = result.issues.filter((i) => i.severity === "warning");
+      if (errors.length > 0) {
+        printLine();
+        printLine(kleur6.bold("Errors:"));
+        printIssues(errors);
+      }
+      if (warnings.length > 0) {
+        printLine();
+        printLine(kleur6.bold("Warnings:"));
+        printIssues(warnings);
+      }
+      printLine();
+      printValidationSummary(result.errorCount, result.warningCount, result.valid);
+    }
+    process.exit(result.valid ? 0 : 1);
+  }
+});
+
+// src/index.ts
+var main = defineCommand9({
+  meta: {
+    name: "acta",
+    version: "0.0.0",
+    description: "Docs-as-code CLI for authoring, validating and building ADR/spec repositories"
+  },
+  subCommands: {
+    init: initCommand,
+    new: newCommand,
+    list: listCommand,
+    show: showCommand,
+    validate: validateCommand,
+    graph: graphCommand,
+    build: buildCommand,
+    renumber: renumberCommand
+  }
+});
+var actaCliPackage = "@acta-dev/cli";
+function getCliBootstrapInfo() {
+  return {
+    name: "acta",
+    packageName: actaCliPackage,
+    version: "0.0.0"
+  };
+}
+function isDirectExecution() {
+  if (!process.argv[1]) {
+    return false;
+  }
+  return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+}
+if (isDirectExecution()) {
+  await runMain(main);
+}
+export {
+  actaCliPackage,
+  getCliBootstrapInfo
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@acta-dev/cli",
+  "version": "0.1.1",
+  "description": "Acta CLI — TypeScript-first docs-as-code tooling for ADR and spec documents in Git. Provides the `acta` binary.",
+  "keywords": [
+    "adr",
+    "spec",
+    "docs-as-code",
+    "architecture-decision-records",
+    "cli",
+    "documentation",
+    "markdown"
+  ],
+  "license": "MIT",
+  "author": "jentix",
+  "homepage": "https://github.com/jentix/acta#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jentix/acta.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/jentix/acta/issues"
+  },
+  "type": "module",
+  "bin": {
+    "acta": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12 <26"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "citty": "^0.2.2",
+    "kleur": "^4.1.5",
+    "yaml": "^2.8.3",
+    "@acta-dev/core": "0.1.1"
+  },
+  "devDependencies": {
+    "execa": "^9.6.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}