@acta-dev/cli 1.2.0 → 1.4.0

package/dist/index.js

@@ -3,7 +3,7 @@
 // src/index.ts
 import { realpathSync } from "fs";
 import { fileURLToPath } from "url";
-import { defineCommand as defineCommand10, runMain } from "citty";
+import { defineCommand as defineCommand11, runMain } from "citty";
 
 // src/commands/build.ts
 import { buildArtifacts } from "@acta-dev/core";
@@ -222,14 +222,17 @@ var graphCommand = defineCommand2({
 });
 
 // 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 { existsSync as existsSync3 } from "fs";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { join as join3, resolve as resolve2 } from "path";
 import { createInterface } from "readline";
 import { resolveConfig as resolveConfig3 } from "@acta-dev/core";
 import { defineCommand as defineCommand3 } from "citty";
 
 // src/skill.ts
+import { existsSync as existsSync2 } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join as join2 } from "path";
 import {
   adrStatuses,
   documentKinds,
@@ -239,6 +242,7 @@ import {
   specStatuses
 } from "@acta-dev/core";
 var SKILL_NAME = "acta-document";
+var skillFormats = ["codex", "claude", "both"];
 var LINK_DESCRIPTIONS = {
   related: "Loosely related documents.",
   supersedes: "This document supersedes the target; mirror with `replacedBy`.",
@@ -388,6 +392,212 @@ ${block}
 ` : `${block}
 `;
 }
+async function installAgentSkill(cwd, format) {
+  const skillPaths = [];
+  const skillContent = renderSkill();
+  if (format === "codex" || format === "both") {
+    const skillDir = join2(cwd, ".agents", "skills", SKILL_NAME);
+    await mkdir(skillDir, { recursive: true });
+    const skillPath = join2(skillDir, "SKILL.md");
+    await writeFile(skillPath, skillContent, "utf8");
+    skillPaths.push(skillPath);
+    const agentsPath = join2(cwd, "AGENTS.md");
+    const existing = existsSync2(agentsPath) ? await readFile(agentsPath, "utf8") : "";
+    await writeFile(agentsPath, upsertAgentsBlock(existing), "utf8");
+    if (format === "codex") {
+      return { skillPaths, agentsPath };
+    }
+  }
+  if (format === "claude" || format === "both") {
+    const skillDir = join2(cwd, ".claude", "skills", SKILL_NAME);
+    await mkdir(skillDir, { recursive: true });
+    const skillPath = join2(skillDir, "SKILL.md");
+    await writeFile(skillPath, skillContent, "utf8");
+    skillPaths.push(skillPath);
+  }
+  return format === "both" ? { skillPaths, agentsPath: join2(cwd, "AGENTS.md") } : { skillPaths };
+}
+
+// src/commands/deploy-workflows.ts
+var DEPLOY_PROVIDERS = ["pages", "cloudflare", "vercel", "netlify"];
+var DEPLOY_WORKFLOW_TEMPLATES = {
+  pages: `name: Deploy Acta Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: acta-pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Acta static viewer
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Build Acta site
+        run: pnpm dlx @acta-dev/cli site --base "/\${{ github.event.repository.name }}"
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: .acta/site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+`,
+  cloudflare: `name: Deploy Acta to Cloudflare Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    name: Deploy Acta static viewer
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Build Acta site
+        run: pnpm dlx @acta-dev/cli site
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: \${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: \${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy .acta/site --project-name="\${{ vars.CLOUDFLARE_PROJECT_NAME }}"
+`,
+  vercel: `name: Deploy Acta to Vercel
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    name: Deploy Acta static viewer
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Build Acta site
+        run: pnpm dlx @acta-dev/cli site
+
+      - name: Deploy to Vercel
+        run: pnpm dlx vercel .acta/site --prod --yes --token="\${{ secrets.VERCEL_TOKEN }}"
+        env:
+          VERCEL_ORG_ID: \${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: \${{ secrets.VERCEL_PROJECT_ID }}
+`,
+  netlify: `name: Deploy Acta to Netlify
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    name: Deploy Acta static viewer
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Build Acta site
+        run: pnpm dlx @acta-dev/cli site
+
+      - name: Deploy to Netlify
+        run: pnpm dlx netlify-cli deploy --dir=.acta/site --prod
+        env:
+          NETLIFY_AUTH_TOKEN: \${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: \${{ secrets.NETLIFY_SITE_ID }}
+`
+};
+function isDeployProvider(value) {
+  return DEPLOY_PROVIDERS.includes(value);
+}
 
 // src/commands/init.ts
 var ADR_TEMPLATE = `---
@@ -566,7 +776,7 @@ async function confirm(message) {
   });
 }
 async function safeWriteFile(filePath, content, yes) {
-  if (existsSync2(filePath)) {
+  if (existsSync3(filePath)) {
     if (!yes) {
       const ok = await confirm(`  Overwrite ${filePath}?`);
       if (!ok) {
@@ -577,7 +787,7 @@ async function safeWriteFile(filePath, content, yes) {
       printWarn(`Overwriting ${filePath}`);
     }
   }
-  await writeFile(filePath, content, "utf8");
+  await writeFile2(filePath, content, "utf8");
   return true;
 }
 var initCommand = defineCommand3({
@@ -602,9 +812,13 @@ var initCommand = defineCommand3({
       description: "Install GitHub Actions workflow template",
       default: false
     },
+    deploy: {
+      type: "string",
+      description: "Install a deploy workflow template: pages, cloudflare, vercel or netlify"
+    },
     skill: {
       type: "boolean",
-      description: "Install the acta-document agent skill and AGENTS.md guidance",
+      description: "Compatibility alias for `acta skill --init` after scaffolding",
       default: false
     },
     config: {
@@ -616,10 +830,14 @@ var initCommand = defineCommand3({
   async run({ args }) {
     const cwd = resolve2(process.cwd());
     const yes = args.yes;
+    const deploy = args.deploy;
+    if (deploy !== void 0 && !isDeployProvider(deploy)) {
+      return exitUsage(`Expected --deploy to be one of: ${DEPLOY_PROVIDERS.join(", ")}.`);
+    }
     const config = resolveConfig3({}, { rootDir: cwd });
     printLine("Initializing Acta docs structure...");
     printLine();
-    const configPath = join2(cwd, "acta.config.ts");
+    const configPath = join3(cwd, "acta.config.ts");
     const configWritten = await safeWriteFile(configPath, CONFIG_TEMPLATE, yes);
     if (configWritten) printSuccess(`Created ${configPath}`);
     const dirs = [
@@ -628,47 +846,55 @@ var initCommand = defineCommand3({
       config.resolvedDocs.templatesDir
     ];
     for (const dir of dirs) {
-      await mkdir(dir, { recursive: true });
+      await mkdir2(dir, { recursive: true });
       printSuccess(`Created dir ${dir}`);
     }
-    const adrTplPath = join2(config.resolvedDocs.templatesDir, "adr.md");
-    const specTplPath = join2(config.resolvedDocs.templatesDir, "spec.md");
+    const adrTplPath = join3(config.resolvedDocs.templatesDir, "adr.md");
+    const specTplPath = join3(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");
+    const gitignorePath = join3(cwd, ".gitignore");
+    if (existsSync3(gitignorePath)) {
+      const { readFile: readFile4, appendFile } = await import("fs/promises");
+      const content = await readFile4(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 lefthookPath = join3(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 workflowsDir = join3(cwd, ".github", "workflows");
+      await mkdir2(workflowsDir, { recursive: true });
+      const workflowPath = join3(workflowsDir, "acta-ci.yml");
       const workflowWritten = await safeWriteFile(workflowPath, GITHUB_ACTION_TEMPLATE, yes);
       if (workflowWritten) printSuccess(`Created ${workflowPath}`);
     }
+    if (deploy !== void 0) {
+      const workflowsDir = join3(cwd, ".github", "workflows");
+      await mkdir2(workflowsDir, { recursive: true });
+      const workflowPath = join3(workflowsDir, `acta-deploy-${deploy}.yml`);
+      const workflowWritten = await safeWriteFile(
+        workflowPath,
+        DEPLOY_WORKFLOW_TEMPLATES[deploy],
+        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`);
+      const result = await installAgentSkill(cwd, "both");
+      for (const skillPath of result.skillPaths) {
+        printSuccess(`Installed ${skillPath}`);
+      }
+      if (result.agentsPath) {
+        printSuccess(`Updated ${result.agentsPath} with Acta agent guidance`);
+      }
     }
     printLine();
     printSuccess("Acta initialized. Run `acta validate` to check your documents.");
@@ -782,9 +1008,9 @@ var listCommand = defineCommand4({
 });
 
 // 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 { existsSync as existsSync4 } from "fs";
+import { writeFile as writeFile3 } from "fs/promises";
+import { join as join5, relative } from "path";
 import { adrStatuses as adrStatuses2, specStatuses as specStatuses2 } from "@acta-dev/core";
 import { defineCommand as defineCommand5 } from "citty";
 
@@ -805,11 +1031,11 @@ function titleToSlug(title) {
 }
 
 // src/template.ts
-import { readFile } from "fs/promises";
-import { join as join3 } from "path";
+import { readFile as readFile2 } from "fs/promises";
+import { join as join4 } from "path";
 async function renderTemplate(kind, vars, config) {
-  const templateFile = join3(config.resolvedDocs.templatesDir, `${kind}.md`);
-  const raw = await readFile(templateFile, "utf8");
+  const templateFile = join4(config.resolvedDocs.templatesDir, `${kind}.md`);
+  const raw = await readFile2(templateFile, "utf8");
   return interpolate(raw, vars);
 }
 function interpolate(raw, vars) {
@@ -854,8 +1080,8 @@ async function createDocument(kind, title, opts) {
   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)) {
+  const destPath = join5(dir, filename);
+  if (existsSync4(destPath)) {
     exitFailure(`File already exists: ${destPath}`);
   }
   const content = await renderTemplate(
@@ -863,7 +1089,7 @@ async function createDocument(kind, title, opts) {
     { id, title: title.trim(), date: nowIsoDateTime(), status, tags: parseTags(opts.tags) },
     config
   );
-  await writeFile2(destPath, content, "utf8");
+  await writeFile3(destPath, content, "utf8");
   if (opts.json) {
     printJson({
       id,
@@ -971,8 +1197,8 @@ 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 { readFile as readFile3, rename, writeFile as writeFile4 } from "fs/promises";
+import { basename, dirname, join as join6 } from "path";
 import { internalLinkKeys as internalLinkKeys2, loadProject as loadProject3 } from "@acta-dev/core";
 import { defineCommand as defineCommand6 } from "citty";
 import kleur4 from "kleur";
@@ -996,7 +1222,7 @@ function buildRenumberPlan(fromId, toId, project) {
   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 newPath = join6(dirname(target.file.path), newFilename);
   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,
@@ -1007,7 +1233,7 @@ function buildRenumberPlan(fromId, toId, project) {
   };
 }
 async function rewriteDocument(filePath, oldId, newId, isTarget) {
-  const raw = await readFile2(filePath, "utf8");
+  const raw = await readFile3(filePath, "utf8");
   const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!match) {
     throw new Error(`Cannot parse frontmatter in ${filePath}`);
@@ -1091,11 +1317,11 @@ var renumberCommand = defineCommand6({
     printLine();
     for (const { doc, path } of plan.affectedDocs) {
       const rewritten = await rewriteDocument(path, fromId, toId, false);
-      await writeFile3(path, rewritten, "utf8");
+      await writeFile4(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 writeFile4(plan.oldPath, rewrittenTarget, "utf8");
     await rename(plan.oldPath, plan.newPath);
     printSuccess(`Renamed ${basename(plan.oldPath)} \u2192 ${plan.newFilename}`);
     printLine();
@@ -1221,7 +1447,7 @@ import { createReadStream } from "fs";
 import { stat } from "fs/promises";
 import { createServer } from "http";
 import { createRequire } from "module";
-import { dirname as dirname2, extname, join as join6, relative as relative2, resolve as resolve3, sep } from "path";
+import { dirname as dirname2, extname, join as join7, relative as relative2, resolve as resolve3, sep } from "path";
 import { buildArtifacts as buildArtifacts2 } from "@acta-dev/core";
 import { defineCommand as defineCommand8 } from "citty";
 import kleur6 from "kleur";
@@ -1388,13 +1614,13 @@ function resolveWebPackageDir() {
   }
 }
 function resolveAstroBin(webDir) {
-  const require2 = createRequire(join6(webDir, "package.json"));
+  const require2 = createRequire(join7(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);
+    return join7(dirname2(astroPkgJsonPath), binRel);
   } catch {
     return void 0;
   }
@@ -1502,7 +1728,7 @@ async function resolveStaticSiteResponse(options) {
   }
   try {
     const fileStat = await stat(filePath);
-    const finalPath = fileStat.isDirectory() ? join6(filePath, "index.html") : filePath;
+    const finalPath = fileStat.isDirectory() ? join7(filePath, "index.html") : filePath;
     const finalStat = fileStat.isDirectory() ? await stat(finalPath) : fileStat;
     if (!finalStat.isFile()) {
       return { status: 404, contentType: "text/plain; charset=utf-8", text: "Not Found" };
@@ -1567,13 +1793,54 @@ function isAddressInUse(error) {
   return typeof error === "object" && error !== null && "code" in error && error.code === "EADDRINUSE";
 }
 
+// src/commands/skill.ts
+import { resolve as resolve4 } from "path";
+import { defineCommand as defineCommand9 } from "citty";
+function parseSkillFormat(value) {
+  const format = value ?? "both";
+  if (!skillFormats.includes(format)) {
+    exitUsage(`Unknown skill format "${format}". Use: codex, claude, both`);
+  }
+  return format;
+}
+var skillCommand = defineCommand9({
+  meta: {
+    name: "skill",
+    description: "Install or refresh the bundled acta-document agent skill"
+  },
+  args: {
+    init: {
+      type: "boolean",
+      description: "Install or overwrite the bundled acta-document skill",
+      default: false
+    },
+    format: {
+      type: "string",
+      description: "Skill target format: codex | claude | both (default: both)"
+    }
+  },
+  async run({ args }) {
+    if (!args.init) {
+      exitUsage("Usage: acta skill --init [--format codex|claude|both]");
+    }
+    const cwd = resolve4(process.cwd());
+    const result = await installAgentSkill(cwd, parseSkillFormat(args.format));
+    for (const skillPath of result.skillPaths) {
+      printSuccess(`Installed ${skillPath}`);
+    }
+    if (result.agentsPath) {
+      printSuccess(`Updated ${result.agentsPath} with Acta agent guidance`);
+    }
+  }
+});
+
 // src/commands/validate.ts
-import { mkdir as mkdir2, writeFile as writeFile4 } from "fs/promises";
-import { join as join7 } from "path";
+import { mkdir as mkdir3, writeFile as writeFile5 } from "fs/promises";
+import { join as join8 } from "path";
 import { validateLoadedProject } from "@acta-dev/core";
-import { defineCommand as defineCommand9 } from "citty";
+import { defineCommand as defineCommand10 } from "citty";
 import kleur7 from "kleur";
-var validateCommand = defineCommand9({
+var validateCommand = defineCommand10({
   meta: {
     name: "validate",
     description: "Validate frontmatter, IDs, links, sections and repository rules"
@@ -1604,9 +1871,9 @@ var validateCommand = defineCommand9({
       return;
     }
     if (args.ci) {
-      await mkdir2(config.resolvedBuild.outDir, { recursive: true });
-      const outPath = join7(config.resolvedBuild.outDir, "validation.json");
-      await writeFile4(outPath, `${JSON.stringify(result, null, 2)}
+      await mkdir3(config.resolvedBuild.outDir, { recursive: true });
+      const outPath = join8(config.resolvedBuild.outDir, "validation.json");
+      await writeFile5(outPath, `${JSON.stringify(result, null, 2)}
 `, "utf8");
       if (result.errors.length > 0) {
         for (const issue of result.errors) {
@@ -1643,7 +1910,7 @@ var validateCommand = defineCommand9({
 });
 
 // src/index.ts
-var main = defineCommand10({
+var main = defineCommand11({
   meta: {
     name: "acta",
     version: "0.0.0",
@@ -1658,6 +1925,7 @@ var main = defineCommand10({
     graph: graphCommand,
     build: buildCommand,
     site: siteCommand,
+    skill: skillCommand,
     renumber: renumberCommand
   }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acta-dev/cli",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Acta CLI — TypeScript-first docs-as-code tooling for ADR and spec documents in Git. Provides the `acta` binary.",
   "keywords": [
     "adr",