@topogram/cli 0.3.63 → 0.3.65

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;
+}

package/src/cli/commands/catalog/check.js

@@ -0,0 +1,31 @@
+// @ts-check
+
+import { checkCatalogSource } from "../../../catalog.js";
+
+/**
+ * @param {string} source
+ * @returns {ReturnType<typeof checkCatalogSource>}
+ */
+export function buildCatalogCheckPayload(source) {
+  if (!source) {
+    throw new Error("topogram catalog check requires <path-or-url>.");
+  }
+  return checkCatalogSource(source);
+}
+
+/**
+ * @param {ReturnType<typeof checkCatalogSource>} payload
+ * @returns {void}
+ */
+export function printCatalogCheck(payload) {
+  console.log(payload.ok ? "Catalog check passed." : "Catalog check failed.");
+  console.log(`Source: ${payload.source}`);
+  if (payload.catalog) {
+    console.log(`Version: ${payload.catalog.version}`);
+    console.log(`Entries: ${payload.catalog.entries.length}`);
+  }
+  for (const diagnostic of payload.diagnostics) {
+    const label = diagnostic.severity === "warning" ? "Warning" : "Error";
+    console.log(`${label}: ${diagnostic.message}`);
+  }
+}

package/src/cli/commands/catalog/copy.js

@@ -0,0 +1,59 @@
+// @ts-check
+
+import path from "node:path";
+
+import {
+  copyCatalogTopogramEntry,
+  findCatalogEntry,
+  loadCatalog,
+  TOPOGRAM_SOURCE_FILE
+} from "../../../catalog.js";
+import { shellCommandArg } from "./shared.js";
+
+/**
+ * @param {string} id
+ * @param {string} targetPath
+ * @param {{ source?: string|null, version?: string|null }} options
+ * @returns {{ ok: boolean, source: string, id: string, kind: "topogram", packageSpec: string, targetPath: string, provenancePath: string, files: string[], diagnostics: any[], errors: string[] }}
+ */
+export function buildCatalogCopyPayload(id, targetPath, options) {
+  if (!id || id.startsWith("-")) {
+    throw new Error("topogram catalog copy requires <id>.");
+  }
+  if (!targetPath || targetPath.startsWith("-")) {
+    throw new Error("topogram catalog copy requires <target>.");
+  }
+  const loaded = loadCatalog(options.source || null);
+  const entry = findCatalogEntry(loaded.catalog, id, "topogram");
+  if (!entry) {
+    throw new Error(`Catalog topogram entry '${id}' was not found in ${loaded.source}.`);
+  }
+  const copied = copyCatalogTopogramEntry(entry, targetPath, {
+    catalogSource: loaded.source,
+    version: options.version || null
+  });
+  return {
+    source: loaded.source,
+    ...copied,
+    diagnostics: [],
+    errors: []
+  };
+}
+
+/**
+ * @param {ReturnType<typeof buildCatalogCopyPayload>} payload
+ * @returns {void}
+ */
+export function printCatalogCopy(payload) {
+  console.log(`Copied catalog topogram '${payload.id}' to ${payload.targetPath}.`);
+  console.log(`Package: ${payload.packageSpec}`);
+  console.log(`Source provenance: ${payload.provenancePath}`);
+  console.log(`Files: ${payload.files.length}`);
+  console.log(`${TOPOGRAM_SOURCE_FILE} records catalog-copy provenance only. Local edits are allowed.`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${shellCommandArg(path.relative(process.cwd(), payload.targetPath) || ".")}`);
+  console.log("  topogram source status --local");
+  console.log("  topogram check");
+  console.log("  topogram generate");
+}