@acta-dev/cli 1.0.0 → 1.2.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";
@@ -250,9 +250,9 @@ var LINK_DESCRIPTIONS = {
 };
 function table(header, rows) {
   const head = `| ${header.join(" | ")} |`;
-  const sep = `| ${header.map(() => "---").join(" | ")} |`;
+  const sep2 = `| ${header.map(() => "---").join(" | ")} |`;
   const body = rows.map((r) => `| ${r.join(" | ")} |`).join("\n");
-  return [head, sep, body].join("\n");
+  return [head, sep2, body].join("\n");
 }
 function renderSkill() {
   const config = resolveConfig2({}, { rootDir: process.cwd() });
@@ -1215,13 +1215,365 @@ function formatShowDate(value) {
   return `${year}-${month}-${day}`;
 }
 
+// src/commands/site.ts
+import { spawn } from "child_process";
+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 { 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 resolveSiteServeOptions(args) {
+  const port = args.port === void 0 ? 4321 : Number(args.port);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error("Expected --port to be an integer between 0 and 65535.");
+  }
+  return {
+    host: args.host ?? "127.0.0.1",
+    port
+  };
+}
+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
+    },
+    serve: {
+      type: "boolean",
+      description: "Serve the generated site locally after building it",
+      default: false
+    },
+    host: {
+      type: "string",
+      description: "Host for --serve (default: 127.0.0.1)"
+    },
+    port: {
+      type: "string",
+      description: "Port for --serve (default: 4321)"
+    },
+    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);
+    const serve = Boolean(args.serve);
+    if (json && serve) {
+      return exitUsage("`acta site --serve` cannot be combined with --json.");
+    }
+    let serveOptions;
+    if (serve) {
+      try {
+        serveOptions = resolveSiteServeOptions(args);
+      } catch (error) {
+        return exitUsage(error instanceof Error ? error.message : String(error));
+      }
+    }
+    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}`);
+    if (serveOptions) {
+      try {
+        const preview = await serveStaticSite({
+          root: options.outDir,
+          base: options.base,
+          ...serveOptions
+        });
+        printLine(`  ${kleur6.bold("Serving:")} ${preview.url}`);
+        printLine();
+        printLine(kleur6.dim("Press Ctrl+C to stop the preview server."));
+        await waitForShutdown(preview);
+        return;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return exitFailure(message);
+      }
+    }
+    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));
+  });
+}
+var mimeTypes = {
+  ".css": "text/css; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".wasm": "application/wasm",
+  ".webp": "image/webp"
+};
+function previewUrl(host, port, base) {
+  const basePath = normalizeBasePath(base);
+  const path = basePath === "/" ? "/" : `${basePath}/`;
+  return `http://${host}:${port}${path}`;
+}
+async function serveStaticSite(options) {
+  const root = resolve3(options.root);
+  const basePath = normalizeBasePath(options.base);
+  const server = createServer(async (request, response) => {
+    const result = await resolveStaticSiteResponse({
+      root,
+      base: basePath,
+      method: request.method ?? "GET",
+      url: request.url ?? "/"
+    });
+    if (!result.path) {
+      if (request.method === "HEAD") {
+        response.statusCode = result.status;
+        response.setHeader("Content-Type", result.contentType);
+        response.end();
+        return;
+      }
+      sendText(response, result.status, result.text ?? "Not Found");
+      return;
+    }
+    response.statusCode = result.status;
+    response.setHeader("Content-Type", result.contentType);
+    if (result.contentLength !== void 0) {
+      response.setHeader("Content-Length", String(result.contentLength));
+    }
+    if (request.method === "HEAD") {
+      response.end();
+      return;
+    }
+    createReadStream(result.path).pipe(response);
+  });
+  await new Promise((resolvePromise, reject) => {
+    server.once("error", reject);
+    server.listen(options.port, options.host, () => {
+      server.off("error", reject);
+      resolvePromise();
+    });
+  }).catch((error) => {
+    if (isAddressInUse(error)) {
+      throw new Error(
+        `Port ${options.port} is already in use on ${options.host}. Try a different --port.`
+      );
+    }
+    throw error;
+  });
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : options.port;
+  return {
+    server,
+    url: previewUrl(options.host, port, options.base),
+    close: () => new Promise((resolvePromise, reject) => {
+      server.close((error) => error ? reject(error) : resolvePromise());
+    })
+  };
+}
+async function resolveStaticSiteResponse(options) {
+  if (options.method !== "GET" && options.method !== "HEAD") {
+    return {
+      status: 405,
+      contentType: "text/plain; charset=utf-8",
+      text: "Method Not Allowed"
+    };
+  }
+  const root = resolve3(options.root);
+  const basePath = normalizeBasePath(options.base);
+  const filePath = await resolveRequestPath(root, basePath, options.url);
+  if (!filePath) {
+    return { status: 404, contentType: "text/plain; charset=utf-8", text: "Not Found" };
+  }
+  try {
+    const fileStat = await stat(filePath);
+    const finalPath = fileStat.isDirectory() ? join6(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" };
+    }
+    return {
+      status: 200,
+      contentType: mimeTypes[extname(finalPath)] ?? "application/octet-stream",
+      contentLength: finalStat.size,
+      path: finalPath
+    };
+  } catch {
+    return { status: 404, contentType: "text/plain; charset=utf-8", text: "Not Found" };
+  }
+}
+async function resolveRequestPath(root, basePath, requestUrl) {
+  let pathname;
+  try {
+    pathname = decodeURIComponent(new URL(requestUrl, "http://localhost").pathname);
+  } catch {
+    return void 0;
+  }
+  if (basePath !== "/") {
+    if (pathname === basePath) {
+      pathname = "/";
+    } else if (pathname.startsWith(`${basePath}/`)) {
+      pathname = pathname.slice(basePath.length);
+    } else {
+      return void 0;
+    }
+  }
+  const normalized = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  const candidate = resolve3(root, `.${normalized}`);
+  const rel = relative2(root, candidate);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || rel === "" || rel.startsWith("/") || rel === ".") {
+    return rel === "." || rel === "" ? root : void 0;
+  }
+  return candidate;
+}
+function sendText(response, status, text) {
+  response.statusCode = status;
+  response.setHeader("Content-Type", "text/plain; charset=utf-8");
+  response.end(text);
+}
+function normalizeBasePath(base) {
+  if (!base || base === "/") return "/";
+  const withLeading = base.startsWith("/") ? base : `/${base}`;
+  return withLeading.replace(/\/+$/, "") || "/";
+}
+function waitForShutdown(preview) {
+  return new Promise((resolvePromise) => {
+    const shutdown = async () => {
+      process.off("SIGINT", shutdown);
+      process.off("SIGTERM", shutdown);
+      await preview.close();
+      resolvePromise();
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+  });
+}
+function isAddressInUse(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "EADDRINUSE";
+}
+
 // 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"
@@ -1253,16 +1605,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);
@@ -1275,12 +1627,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();
@@ -1291,7 +1643,7 @@ var validateCommand = defineCommand8({
 });
 
 // src/index.ts
-var main = defineCommand9({
+var main = defineCommand10({
   meta: {
     name: "acta",
     version: "0.0.0",
@@ -1305,6 +1657,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": "1.0.0",
+  "version": "1.2.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": "1.0.0"
+    "@acta-dev/core": "1.1.0",
+    "@acta-dev/web": "1.0.0"
   },
   "devDependencies": {
     "execa": "^9.6.1",