@topogram/cli 0.3.62 → 0.3.64

package/src/catalog.js

@@ -6,11 +6,52 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { installPackageSpec } from "./new-project.js";
+import { DEFAULT_CATALOG_SOURCE, defaultCatalogSource } from "./topogram-config.js";
+import { readGithubCatalogSourceText } from "./github-client.js";
 
-export const DEFAULT_CATALOG_SOURCE = "https://raw.githubusercontent.com/attebury/topograms/main/topograms.catalog.json";
 export const CATALOG_FILE_NAME = "topograms.catalog.json";
 export const TOPOGRAM_SOURCE_FILE = ".topogram-source.json";
 const KNOWN_CATALOG_SURFACES = new Set(["web", "api", "database", "native"]);
+const GITHUB_TOKEN_HOSTS = new Set([
+  "github.com",
+  "api.github.com",
+  "raw.githubusercontent.com"
+]);
+const FETCH_URL_SCRIPT = `
+const source = process.argv[1];
+const token = process.env.TOPOGRAM_FETCH_TOKEN || "";
+const tokenHosts = new Set(["github.com", "api.github.com", "raw.githubusercontent.com"]);
+function tokenAllowed(url) {
+  const hostname = new URL(url).hostname.toLowerCase();
+  return tokenHosts.has(hostname) || hostname.endsWith(".github.com");
+}
+async function readUrl(url, redirects = 0) {
+  if (redirects > 5) {
+    throw new Error("Too many redirects.");
+  }
+  const headers = {};
+  if (token && tokenAllowed(url)) {
+    headers.authorization = "Bearer " + token;
+  }
+  const response = await fetch(url, { headers, redirect: "manual" });
+  if (response.status >= 300 && response.status < 400 && response.headers.get("location")) {
+    const next = new URL(response.headers.get("location"), url).toString();
+    return readUrl(next, redirects + 1);
+  }
+  const text = await response.text();
+  if (!response.ok) {
+    const preview = text.trim().slice(0, 400);
+    throw new Error(String(response.status) + " " + response.statusText + (preview ? "\\n" + preview : ""));
+  }
+  return text;
+}
+try {
+  process.stdout.write(await readUrl(source));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+`;
 
 /**
  * @typedef {Object} CatalogTrust
@@ -82,7 +123,7 @@ function catalogDiagnostic(input) {
  * @returns {string}
  */
 export function catalogSourceOrDefault(source = null) {
-  return source || process.env.TOPOGRAM_CATALOG_SOURCE || DEFAULT_CATALOG_SOURCE;
+  return source || process.env.TOPOGRAM_CATALOG_SOURCE || defaultCatalogSource();
 }
 
 /**
@@ -397,65 +438,7 @@ function readCatalogText(source) {
  * @returns {string}
  */
 function readGithubCatalogText(source) {
-  const spec = source.slice("github:".length);
-  const [pathPart, ref] = spec.split("?ref=");
-  const segments = pathPart.split("/").filter(Boolean);
-  if (segments.length < 3) {
-    throw new Error(`Invalid GitHub catalog source '${source}'. Expected github:owner/repo/path/to/catalog.json.`);
-  }
-  const [owner, repo, ...fileSegments] = segments;
-  const apiPath = `repos/${owner}/${repo}/contents/${fileSegments.join("/")}`;
-  const args = ["api", apiPath, "--jq", ".content"];
-  if (ref) {
-    args.splice(2, 0, "-f", `ref=${ref}`);
-  }
-  const result = childProcess.spawnSync("gh", args, {
-    encoding: "utf8",
-    env: {
-      ...process.env,
-      GH_TOKEN: process.env.GH_TOKEN || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "",
-      PATH: process.env.PATH || ""
-    }
-  });
-  if (result.status !== 0) {
-    throw new Error(formatGithubCatalogError(source, result));
-  }
-  return Buffer.from(result.stdout.replace(/\s+/g, ""), "base64").toString("utf8");
-}
-
-/**
- * @param {string} source
- * @param {any} result
- * @returns {string}
- */
-function formatGithubCatalogError(source, result) {
-  const output = [result.error?.message, result.stderr, result.stdout].filter(Boolean).join("\n").trim();
-  const normalized = output.toLowerCase();
-  if (result.error?.code === "ENOENT") {
-    return [
-      `GitHub CLI (gh) is required to read catalog '${source}'.`,
-      "Install gh, or set TOPOGRAM_CATALOG_SOURCE to a local topograms.catalog.json file."
-    ].join("\n");
-  }
-  if (/\b(401|403)\b/.test(normalized) || normalized.includes("authentication") || normalized.includes("not logged in") || normalized.includes("forbidden")) {
-    return [
-      `Authentication is required to read private catalog '${source}'.`,
-      "Set GITHUB_TOKEN or GH_TOKEN with repository read access, or run gh auth login.",
-      output
-    ].filter(Boolean).join("\n");
-  }
-  if (/\b404\b/.test(normalized) || normalized.includes("not found")) {
-    return [
-      `Catalog source '${source}' was not found, or the current token does not have repository access.`,
-      "Check the github:owner/repo/path source and grant repository read access to the token or GitHub Actions workflow.",
-      output
-    ].filter(Boolean).join("\n");
-  }
-  return [
-    `Failed to read catalog '${source}' with gh api.`,
-    "Set GITHUB_TOKEN or GH_TOKEN, or run gh auth login.",
-    output || "unknown error"
-  ].join("\n");
+  return readGithubCatalogSourceText(source);
 }
 
 /**
@@ -463,15 +446,15 @@ function formatGithubCatalogError(source, result) {
  * @returns {string}
  */
 function readUrlText(source) {
-  const args = ["-fsSL", source];
   const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "";
-  if (token && source.includes("github.com")) {
-    args.unshift("-H", `Authorization: Bearer ${token}`);
-  }
-  const result = childProcess.spawnSync("curl", args, {
+  const tokenEnv = token && githubTokenAllowedForCatalogUrl(source)
+    ? { TOPOGRAM_FETCH_TOKEN: token }
+    : {};
+  const result = childProcess.spawnSync(process.execPath, ["--input-type=module", "-e", FETCH_URL_SCRIPT, source], {
     encoding: "utf8",
     env: {
       ...process.env,
+      ...tokenEnv,
       PATH: process.env.PATH || ""
     }
   });
@@ -482,6 +465,19 @@ function readUrlText(source) {
   return result.stdout;
 }
 
+/**
+ * @param {string} source
+ * @returns {boolean}
+ */
+function githubTokenAllowedForCatalogUrl(source) {
+  try {
+    const hostname = new URL(source).hostname.toLowerCase();
+    return GITHUB_TOKEN_HOSTS.has(hostname) || hostname.endsWith(".github.com");
+  } catch {
+    return false;
+  }
+}
+
 /**
  * @param {TopogramCatalog} catalog
  * @param {string} id

package/src/cli/catalog-alias.d.ts

@@ -0,0 +1 @@
+export function resolveCatalogTemplateAlias(templateName: string, catalogSource?: string | null): any;

package/src/cli/command-parser.js

@@ -0,0 +1,38 @@
+// @ts-check
+
+import { parseCoreCommandArgs } from "./command-parsers/core.js";
+import { parseGeneratorCommandArgs } from "./command-parsers/generator.js";
+import { parseImportCommandArgs } from "./command-parsers/import.js";
+import { parseLegacyWorkflowCommandArgs } from "./command-parsers/legacy-workflow.js";
+import { parseProjectCommandArgs } from "./command-parsers/project.js";
+import { parseSdlcCommandArgs } from "./command-parsers/sdlc.js";
+import { parseTemplateCommandArgs } from "./command-parsers/template.js";
+
+const COMMAND_PARSERS = [
+  parseCoreCommandArgs,
+  parseGeneratorCommandArgs,
+  parseTemplateCommandArgs,
+  parseProjectCommandArgs,
+  parseImportCommandArgs,
+  parseLegacyWorkflowCommandArgs,
+  parseSdlcCommandArgs
+];
+
+/**
+ * Parses command families that have already been split out of the CLI shim.
+ *
+ * Keep this module as a composition root. Command-family parsing belongs in
+ * `cli/command-parsers/*` so the parser does not become another CLI shim.
+ *
+ * @param {string[]} args
+ * @returns {import("./command-parsers/shared.js").SplitCommandArgs|null}
+ */
+export function parseSplitCommandArgs(args) {
+  for (const parser of COMMAND_PARSERS) {
+    const commandArgs = parser(args);
+    if (commandArgs) {
+      return commandArgs;
+    }
+  }
+  return null;
+}

package/src/cli/command-parsers/core.js

@@ -0,0 +1,102 @@
+// @ts-check
+
+import { commandPath } from "./shared.js";
+
+const QUERY_NAMES = new Set([
+  "task-mode",
+  "diff",
+  "slice",
+  "adoption-plan",
+  "maintained-boundary",
+  "maintained-conformance",
+  "maintained-drift",
+  "seam-check",
+  "domain-coverage",
+  "domain-list",
+  "review-boundary",
+  "write-scope",
+  "verification-targets",
+  "widget-behavior",
+  "change-plan",
+  "import-plan",
+  "risk-summary",
+  "canonical-writes",
+  "proceed-decision",
+  "review-packet",
+  "next-action",
+  "single-agent-plan",
+  "multi-agent-plan",
+  "resolved-workflow-context",
+  "workflow-preset-activation",
+  "workflow-preset-diff",
+  "workflow-preset-customization",
+  "work-packet",
+  "lane-status",
+  "handoff-status",
+  "auth-hints",
+  "auth-review-packet"
+]);
+
+/**
+ * @param {string[]} args
+ * @returns {import("./shared.js").SplitCommandArgs|null}
+ */
+export function parseCoreCommandArgs(args) {
+  if (args[0] === "new" || args[0] === "create") {
+    return args.includes("--list-templates")
+      ? { templateCommand: "list", inputPath: null }
+      : { newProject: true, inputPath: args[1] };
+  }
+  if (args[0] === "generate" && args[1] === "app") {
+    return { generateTarget: "app-bundle", write: true, inputPath: commandPath(args, 2), defaultOutDir: "./app" };
+  }
+  if (args[0] === "generate" && args[1] === "journeys") {
+    return { workflowName: "generate-journeys", inputPath: args[2] };
+  }
+  if (args[0] === "generate" && args[1] !== "journeys") {
+    return { generateTarget: "app-bundle", write: true, inputPath: commandPath(args, 1), defaultOutDir: "./app" };
+  }
+  if (args[0] === "emit") {
+    if (!args[1] || args[1].startsWith("-")) {
+      return { emitHelp: true, inputPath: null };
+    }
+    return { generateTarget: args[1], inputPath: commandPath(args, 2), emitArtifact: true };
+  }
+  if (args[0] === "version" || args[0] === "--version") {
+    return { version: true, inputPath: null };
+  }
+  if (args[0] === "query" && args[1] === "list") {
+    return { queryList: true, inputPath: null };
+  }
+  if (args[0] === "query" && args[1] === "show") {
+    return { queryShow: true, queryShowName: args[2] || null, inputPath: null };
+  }
+  if (args[0] === "query" && args[1] === "workflow-preset" && args[2] === "customize") {
+    return { workflowPresetCommand: "customize", inputPath: commandPath(args, 3) };
+  }
+  if (args[0] === "workflow-preset" && args[1] === "customize") {
+    return { workflowPresetCommand: "customize", inputPath: commandPath(args, 2) };
+  }
+  if (args[0] === "query" && QUERY_NAMES.has(args[1])) {
+    return { queryName: args[1], inputPath: commandPath(args, 2) };
+  }
+  if (args[0] === "doctor") {
+    return { doctor: true, inputPath: args[1] && !args[1].startsWith("-") ? args[1] : null };
+  }
+  if (args[0] === "check") {
+    return { check: true, inputPath: commandPath(args, 1) };
+  }
+  if (args[0] === "validate") {
+    return { validate: true, inputPath: args[1] };
+  }
+  if (args[0] === "agent" && args[1] === "brief") {
+    return { agentBrief: true, inputPath: commandPath(args, 2) };
+  }
+  if (args[0] === "widget" && args[1] === "check") {
+    return { widgetCheck: true, inputPath: commandPath(args, 2) };
+  }
+  if (args[0] === "widget" && args[1] === "behavior") {
+    return { widgetBehavior: true, inputPath: commandPath(args, 2) };
+  }
+  return null;
+}

package/src/cli/command-parsers/generator.js

@@ -0,0 +1,39 @@
+// @ts-check
+
+import { commandPath } from "./shared.js";
+
+/**
+ * @param {string[]} args
+ * @returns {import("./shared.js").SplitCommandArgs|null}
+ */
+export function parseGeneratorCommandArgs(args) {
+  if (args[0] === "generator" && args[1] === "list") {
+    return { generatorCommand: "list", inputPath: null };
+  }
+  if (args[0] === "generator" && args[1] === "show") {
+    return { generatorCommand: "show", inputPath: args[2] };
+  }
+  if (args[0] === "generator" && args[1] === "check") {
+    return { generatorCommand: "check", inputPath: args[2] };
+  }
+  if (args[0] === "generator" && args[1] === "policy" && args[2] === "init") {
+    return { generatorPolicyCommand: "init", inputPath: commandPath(args, 3) };
+  }
+  if (args[0] === "generator" && args[1] === "policy" && args[2] === "status") {
+    return { generatorPolicyCommand: "status", inputPath: commandPath(args, 3) };
+  }
+  if (args[0] === "generator" && args[1] === "policy" && args[2] === "check") {
+    return { generatorPolicyCommand: "check", inputPath: commandPath(args, 3) };
+  }
+  if (args[0] === "generator" && args[1] === "policy" && args[2] === "explain") {
+    return { generatorPolicyCommand: "explain", inputPath: commandPath(args, 3) };
+  }
+  if (args[0] === "generator" && args[1] === "policy" && args[2] === "pin") {
+    return {
+      generatorPolicyCommand: "pin",
+      generatorPolicyPinSpec: args[3] && !args[3].startsWith("-") ? args[3] : null,
+      inputPath: commandPath(args, 4)
+    };
+  }
+  return null;
+}

package/src/cli/command-parsers/import.js

@@ -0,0 +1,44 @@
+// @ts-check
+
+import { commandOperandFrom, commandPath } from "./shared.js";
+
+/**
+ * @param {string[]} args
+ * @returns {import("./shared.js").SplitCommandArgs|null}
+ */
+export function parseImportCommandArgs(args) {
+  if (args[0] === "import" && args[1] === "app") {
+    return { workflowName: "import-app", inputPath: args[2] };
+  }
+  if (args[0] === "import" && args[1] === "docs") {
+    return { workflowName: "scan-docs", inputPath: args[2] };
+  }
+  if (args[0] === "import" && args[1] === "diff") {
+    return { importCommand: "diff", inputPath: commandOperandFrom(args, 2, ".") };
+  }
+  if (args[0] === "import" && args[1] === "refresh") {
+    return { importCommand: "refresh", inputPath: commandOperandFrom(args, 2, ".") };
+  }
+  if (args[0] === "import" && args[1] === "check") {
+    return { importCommand: "check", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "import" && args[1] === "plan") {
+    return { importCommand: "plan", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "import" && args[1] === "adopt" && (args[2] === "--list" || args[2] === "list")) {
+    return { importCommand: "adopt-list", inputPath: commandPath(args, 3, ".") };
+  }
+  if (args[0] === "import" && args[1] === "adopt") {
+    return { importCommand: "adopt", importAdoptSelector: args[2], inputPath: commandPath(args, 3, ".") };
+  }
+  if (args[0] === "import" && args[1] === "status") {
+    return { importCommand: "status", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "import" && args[1] === "history") {
+    return { importCommand: "history", verify: args.includes("--verify"), inputPath: commandOperandFrom(args, 2, ".") };
+  }
+  if (args[0] === "import" && args[1] && !args[1].startsWith("-")) {
+    return { importCommand: "workspace", inputPath: args[1] };
+  }
+  return null;
+}

package/src/cli/command-parsers/legacy-workflow.js

@@ -0,0 +1,21 @@
+// @ts-check
+
+/**
+ * @param {string[]} args
+ * @returns {import("./shared.js").SplitCommandArgs|null}
+ */
+export function parseLegacyWorkflowCommandArgs(args) {
+  if (args[0] === "report" && args[1] === "gaps") {
+    return { workflowName: "report-gaps", inputPath: args[2] };
+  }
+  if (args[0] === "reconcile" && args[1] === "adopt") {
+    return { workflowName: "reconcile", inputPath: args[3], adoptValue: args[2] };
+  }
+  if (args[0] === "reconcile") {
+    return { workflowName: "reconcile", inputPath: args[1] };
+  }
+  if (args[0] === "adoption" && args[1] === "status") {
+    return { workflowName: "adoption-status", inputPath: args[2] };
+  }
+  return null;
+}

package/src/cli/command-parsers/project.js

@@ -0,0 +1,47 @@
+// @ts-check
+
+import { commandPath } from "./shared.js";
+
+/**
+ * @param {string[]} args
+ * @returns {import("./shared.js").SplitCommandArgs|null}
+ */
+export function parseProjectCommandArgs(args) {
+  if (args[0] === "source" && args[1] === "status") {
+    return { sourceCommand: "status", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "trust" && args[1] === "template") {
+    return { trustCommand: "template", force: args.includes("--force"), inputPath: commandPath(args, 2) };
+  }
+  if (args[0] === "trust" && args[1] === "status") {
+    return { trustCommand: "status", inputPath: commandPath(args, 2) };
+  }
+  if (args[0] === "trust" && args[1] === "diff") {
+    return { trustCommand: "diff", inputPath: commandPath(args, 2) };
+  }
+  if (args[0] === "release" && args[1] === "status") {
+    return { releaseCommand: "status", inputPath: null };
+  }
+  if (args[0] === "release" && args[1] === "roll-consumers") {
+    return { releaseCommand: "roll-consumers", releaseRollVersion: args[2], inputPath: null };
+  }
+  if (args[0] === "catalog" && args[1] === "list") {
+    return { catalogCommand: "list", inputPath: args[2] && !args[2].startsWith("-") ? args[2] : null };
+  }
+  if (args[0] === "catalog" && args[1] === "show") {
+    return { catalogCommand: "show", inputPath: args[2] };
+  }
+  if (args[0] === "catalog" && args[1] === "doctor") {
+    return { catalogCommand: "doctor", inputPath: args[2] && !args[2].startsWith("-") ? args[2] : null };
+  }
+  if (args[0] === "catalog" && args[1] === "check") {
+    return { catalogCommand: "check", inputPath: args[2] };
+  }
+  if (args[0] === "catalog" && args[1] === "copy") {
+    return { catalogCommand: "copy", catalogId: args[2], inputPath: args[3] };
+  }
+  if (args[0] === "package" && args[1] === "update-cli") {
+    return { packageCommand: "update-cli", inputPath: args.includes("--latest") ? "latest" : args[2] };
+  }
+  return null;
+}

package/src/cli/command-parsers/sdlc.js

@@ -0,0 +1,47 @@
+// @ts-check
+
+import { commandPath } from "./shared.js";
+
+/**
+ * @param {string[]} args
+ * @returns {import("./shared.js").SplitCommandArgs|null}
+ */
+export function parseSdlcCommandArgs(args) {
+  if (args[0] === "sdlc" && args[1] === "transition") {
+    return {
+      sdlcCommand: "transition",
+      inputPath: args[4] && !args[4].startsWith("-") ? args[4] : ".",
+      sdlcId: args[2],
+      sdlcTargetStatus: args[3]
+    };
+  }
+  if (args[0] === "sdlc" && args[1] === "check") {
+    return { sdlcCommand: "check", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "sdlc" && args[1] === "explain") {
+    return {
+      sdlcCommand: "explain",
+      sdlcId: args[2],
+      inputPath: args[3] && !args[3].startsWith("-") ? args[3] : "."
+    };
+  }
+  if (args[0] === "sdlc" && args[1] === "archive") {
+    return { sdlcCommand: "archive", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "sdlc" && args[1] === "unarchive") {
+    return { sdlcCommand: "unarchive", sdlcId: args[2], inputPath: commandPath(args, 3, ".") };
+  }
+  if (args[0] === "sdlc" && args[1] === "compact") {
+    return { sdlcCommand: "compact", sdlcArchiveFile: args[2], inputPath: "." };
+  }
+  if (args[0] === "sdlc" && args[1] === "new") {
+    return { sdlcCommand: "new", sdlcNewKind: args[2], sdlcNewSlug: args[3], inputPath: commandPath(args, 4, ".") };
+  }
+  if (args[0] === "sdlc" && args[1] === "adopt") {
+    return { sdlcCommand: "adopt", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "release") {
+    return { sdlcCommand: "release", inputPath: commandPath(args, 1, ".") };
+  }
+  return null;
+}

package/src/cli/command-parsers/shared.js

@@ -0,0 +1,51 @@
+// @ts-check
+
+/**
+ * @typedef {Record<string, any> & {
+ *   inputPath: string|null
+ * }} SplitCommandArgs
+ */
+
+/**
+ * @param {string[]} args
+ * @param {number} index
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+export function commandPath(args, index, fallback = "./topogram") {
+  const value = args[index];
+  return value && !value.startsWith("-") ? value : fallback;
+}
+
+/**
+ * @param {string[]} args
+ * @param {number} index
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+export function commandOperandFrom(args, index, fallback = ".") {
+  const valueFlags = new Set([
+    "--accept-current",
+    "--accept-candidate",
+    "--delete-current",
+    "--from",
+    "--out",
+    "--out-dir",
+    "--reason",
+    "--template",
+    "--version"
+  ]);
+  for (let i = index; i < args.length; i += 1) {
+    const value = args[i];
+    if (!value) {
+      continue;
+    }
+    if (!value.startsWith("-")) {
+      return value;
+    }
+    if (valueFlags.has(value)) {
+      i += 1;
+    }
+  }
+  return fallback;
+}

package/src/cli/command-parsers/template.js

@@ -0,0 +1,48 @@
+// @ts-check
+
+import { commandPath } from "./shared.js";
+
+/**
+ * @param {string[]} args
+ * @returns {import("./shared.js").SplitCommandArgs|null}
+ */
+export function parseTemplateCommandArgs(args) {
+  if (args[0] === "template" && args[1] === "list") {
+    return { templateCommand: "list", inputPath: null };
+  }
+  if (args[0] === "template" && args[1] === "show") {
+    return { templateCommand: "show", inputPath: args[2] };
+  }
+  if (args[0] === "template" && args[1] === "explain") {
+    return { templateCommand: "explain", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "template" && args[1] === "status") {
+    return { templateCommand: "status", inputPath: commandPath(args, 2) };
+  }
+  if (args[0] === "template" && args[1] === "detach") {
+    return { templateCommand: "detach", inputPath: commandPath(args, 2, ".") };
+  }
+  if (args[0] === "template" && args[1] === "policy" && args[2] === "init") {
+    return { templateCommand: "policy:init", inputPath: commandPath(args, 3) };
+  }
+  if (args[0] === "template" && args[1] === "policy" && args[2] === "check") {
+    return { templateCommand: "policy:check", inputPath: commandPath(args, 3) };
+  }
+  if (args[0] === "template" && args[1] === "policy" && args[2] === "explain") {
+    return { templateCommand: "policy:explain", inputPath: commandPath(args, 3) };
+  }
+  if (args[0] === "template" && args[1] === "policy" && args[2] === "pin") {
+    return {
+      templateCommand: "policy:pin",
+      templatePolicyPinSpec: args[3] && !args[3].startsWith("-") ? args[3] : null,
+      inputPath: commandPath(args, 4)
+    };
+  }
+  if (args[0] === "template" && args[1] === "check") {
+    return { templateCommand: "check", inputPath: args[2] };
+  }
+  if (args[0] === "template" && args[1] === "update") {
+    return { templateCommand: "update", inputPath: commandPath(args, 2) };
+  }
+  return null;
+}

package/src/cli/commands/agent.js

@@ -0,0 +1,47 @@
+// @ts-check
+
+import { buildAgentBrief, formatAgentBrief, normalizeAgentTopogramPath } from "../../agent-brief.js";
+import { stableStringify } from "../../format.js";
+import { parsePath } from "../../parser.js";
+import { formatProjectConfigErrors } from "../../project-config.js";
+import { formatValidationErrors } from "../../validator.js";
+
+/**
+ * @returns {void}
+ */
+export function printAgentHelp() {
+  console.log("Usage: topogram agent brief [path] [--json]");
+  console.log("");
+  console.log("Prints read-only first-run guidance for humans and agents working in a Topogram project.");
+  console.log("");
+  console.log("Defaults: path is ./topogram. The command validates the Topogram and project config, but does not write files, generate apps, load generator adapters, or execute template implementation.");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram agent brief");
+  console.log("  topogram agent brief --json");
+  console.log("  topogram agent brief ./topogram --json");
+}
+
+/**
+ * @param {string} inputPath
+ * @param {{ json?: boolean }} [options]
+ * @returns {number}
+ */
+export function runAgentBriefCommand(inputPath, options = {}) {
+  const ast = parsePath(normalizeAgentTopogramPath(inputPath));
+  const result = buildAgentBrief(inputPath, ast);
+  if (!result.ok) {
+    if (result.kind === "project") {
+      console.error(formatProjectConfigErrors(result.validation, result.configPath));
+    } else {
+      console.error(formatValidationErrors(result.validation));
+    }
+    return 1;
+  }
+  if (options.json) {
+    console.log(stableStringify(result.payload));
+  } else {
+    process.stdout.write(formatAgentBrief(result.payload));
+  }
+  return 0;
+}