@topogram/cli 0.3.63 → 0.3.65

package/src/cli/commands/import/workspace.js

@@ -0,0 +1,230 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../../../format.js";
+import {
+  collectImportSourceFileRecords,
+  TOPOGRAM_IMPORT_FILE,
+  writeTopogramImportRecord
+} from "../../../import/provenance.js";
+import { runWorkflow } from "../../../workflows.js";
+import { shellCommandArg } from "../catalog.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {string} targetPath
+ * @returns {void}
+ */
+export function ensureEmptyImportTarget(targetPath) {
+  if (!fs.existsSync(targetPath)) {
+    fs.mkdirSync(targetPath, { recursive: true });
+    return;
+  }
+  if (!fs.statSync(targetPath).isDirectory()) {
+    throw new Error(`Cannot import into non-directory path '${targetPath}'.`);
+  }
+  const entries = fs.readdirSync(targetPath).filter((/** @type {string} */ entry) => entry !== ".DS_Store");
+  if (entries.length > 0) {
+    throw new Error(`Refusing to import into non-empty directory '${targetPath}'.`);
+  }
+}
+
+/**
+ * @param {string} outDir
+ * @param {Record<string, any>} files
+ * @returns {string[]}
+ */
+export function writeRelativeFiles(outDir, files) {
+  const written = [];
+  for (const [relativePath, contents] of Object.entries(files || {})) {
+    const normalizedRelativePath = relativePath.replaceAll(path.sep, "/");
+    const destination = path.join(outDir, normalizedRelativePath);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.writeFileSync(destination, typeof contents === "string" ? contents : `${stableStringify(contents)}\n`, "utf8");
+    written.push(normalizedRelativePath);
+  }
+  return written.sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * @returns {Record<string, any>}
+ */
+function importedProjectConfig() {
+  return {
+    version: "0.1",
+    outputs: {
+      maintained_app: {
+        path: "./app",
+        ownership: "maintained"
+      }
+    },
+    topology: {
+      runtimes: []
+    }
+  };
+}
+
+/**
+ * @param {string} sourceRoot
+ * @param {string} targetRoot
+ * @param {ReturnType<typeof runWorkflow>["summary"]} importSummary
+ * @returns {string}
+ */
+function importedWorkspaceReadme(sourceRoot, targetRoot, importSummary) {
+  return [
+    "# Imported Topogram Workspace",
+    "",
+    "This workspace was created from a brownfield app import.",
+    "",
+    `- Imported source: \`${sourceRoot}\``,
+    `- Target workspace: \`${targetRoot}\``,
+    `- Tracks: ${(importSummary.tracks || []).join(", ") || "none"}`,
+    `- Provenance: \`${TOPOGRAM_IMPORT_FILE}\``,
+    "",
+    "Imported Topogram artifacts are project-owned after creation. Edit them directly, promote candidates deliberately, and run `topogram check` before generation or maintained-app work.",
+    "",
+    "Useful commands:",
+    "",
+    "```sh",
+    "topogram import check",
+    "topogram check",
+    "topogram query import-plan ./topogram",
+    "```",
+    ""
+  ].join("\n");
+}
+
+/**
+ * @param {Record<string, any>} summary
+ * @returns {Record<string, number>}
+ */
+export function importCandidateCounts(summary) {
+  const candidates = summary.candidates || {};
+  return {
+    dbEntities: candidates.db?.entities?.length || 0,
+    dbEnums: candidates.db?.enums?.length || 0,
+    apiCapabilities: candidates.api?.capabilities?.length || 0,
+    apiRoutes: candidates.api?.routes?.length || 0,
+    uiScreens: candidates.ui?.screens?.length || 0,
+    uiRoutes: candidates.ui?.routes?.length || 0,
+    uiWidgets: candidates.ui?.widgets?.length || candidates.ui?.components?.length || 0,
+    workflows: candidates.workflows?.workflows?.length || 0,
+    verifications: candidates.verification?.verifications?.length || 0
+  };
+}
+
+/**
+ * @param {string} rootPath
+ * @returns {number}
+ */
+export function countFilesRecursive(rootPath) {
+  if (!fs.existsSync(rootPath)) {
+    return 0;
+  }
+  let count = 0;
+  for (const entry of fs.readdirSync(rootPath, { withFileTypes: true })) {
+    const childPath = path.join(rootPath, entry.name);
+    if (entry.isDirectory()) {
+      count += countFilesRecursive(childPath);
+    } else if (entry.isFile()) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+/**
+ * @param {string} sourcePath
+ * @param {string} targetPath
+ * @param {{ from?: string|null }} [options]
+ * @returns {{ ok: boolean, sourcePath: string, targetPath: string, topogramRoot: string, projectConfigPath: string, provenancePath: string, tracks: string[], sourceFiles: number, rawCandidateFiles: number, reconcileFiles: number, writtenFiles: string[], candidateCounts: Record<string, number>, nextCommands: string[] }}
+ */
+export function buildBrownfieldImportWorkspacePayload(sourcePath, targetPath, options = {}) {
+  const sourceRoot = path.resolve(sourcePath);
+  const targetRoot = path.resolve(targetPath);
+  if (!fs.existsSync(sourceRoot) || !fs.statSync(sourceRoot).isDirectory()) {
+    throw new Error(`Cannot import missing app directory '${sourcePath}'.`);
+  }
+  if (sourceRoot === targetRoot) {
+    throw new Error("Refusing to import into the same directory as the brownfield app.");
+  }
+  ensureEmptyImportTarget(targetRoot);
+
+  const topogramRoot = path.join(targetRoot, "topogram");
+  fs.mkdirSync(topogramRoot, { recursive: true });
+  const sourceFiles = collectImportSourceFileRecords(sourceRoot, { excludeRoots: [targetRoot] });
+  const importResult = runWorkflow("import-app", sourceRoot, { from: options.from || null });
+  const rawCandidateFiles = writeRelativeFiles(topogramRoot, importResult.files || {});
+
+  const projectConfigPath = path.join(targetRoot, "topogram.project.json");
+  fs.writeFileSync(projectConfigPath, `${stableStringify(importedProjectConfig())}\n`, "utf8");
+  fs.writeFileSync(path.join(targetRoot, "README.md"), importedWorkspaceReadme(sourceRoot, targetRoot, importResult.summary), "utf8");
+
+  const reconcileResult = runWorkflow("reconcile", targetRoot, {});
+  const reconcileFiles = writeRelativeFiles(topogramRoot, reconcileResult.files || {});
+  const candidateCounts = importCandidateCounts(importResult.summary);
+  const provenance = writeTopogramImportRecord(targetRoot, {
+    sourceRoot,
+    ignoredRoots: [targetRoot],
+    tracks: importResult.summary.tracks || [],
+    findingsCount: importResult.summary.findings_count || 0,
+    candidateCounts,
+    files: sourceFiles
+  });
+  const writtenFiles = [
+    "README.md",
+    "topogram.project.json",
+    TOPOGRAM_IMPORT_FILE,
+    ...rawCandidateFiles.map((filePath) => `topogram/${filePath}`),
+    ...reconcileFiles.map((filePath) => `topogram/${filePath}`)
+  ].sort((a, b) => a.localeCompare(b));
+  return {
+    ok: true,
+    sourcePath: sourceRoot,
+    targetPath: targetRoot,
+    topogramRoot,
+    projectConfigPath,
+    provenancePath: provenance.path,
+    tracks: importResult.summary.tracks || [],
+    sourceFiles: sourceFiles.length,
+    rawCandidateFiles: rawCandidateFiles.length,
+    reconcileFiles: reconcileFiles.length,
+    writtenFiles,
+    candidateCounts,
+    nextCommands: [
+      "topogram import check",
+      "topogram import plan",
+      "topogram import adopt bundle:task --dry-run",
+      "topogram import status",
+      "topogram check",
+      "topogram query import-plan ./topogram"
+    ]
+  };
+}
+
+/**
+ * @param {ReturnType<typeof buildBrownfieldImportWorkspacePayload>} payload
+ * @returns {void}
+ */
+export function printBrownfieldImportWorkspace(payload) {
+  console.log(`Imported brownfield app to ${payload.targetPath}.`);
+  console.log(`Source: ${payload.sourcePath}`);
+  console.log(`Topogram: ${payload.topogramRoot}`);
+  console.log(`Project config: ${payload.projectConfigPath}`);
+  console.log(`Import provenance: ${payload.provenancePath}`);
+  console.log(`Tracked source files: ${payload.sourceFiles}`);
+  console.log(`Raw candidate files: ${payload.rawCandidateFiles}`);
+  console.log(`Reconcile proposal files: ${payload.reconcileFiles}`);
+  console.log("Imported Topogram artifacts are project-owned after creation; source hashes record the app evidence trusted at import time.");
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${shellCommandArg(path.relative(process.cwd(), payload.targetPath) || ".")}`);
+  for (const command of payload.nextCommands) {
+    console.log(`  ${command}`);
+  }
+}

package/src/cli/commands/import-runner.js

@@ -0,0 +1,157 @@
+// @ts-check
+
+import { stableStringify } from "../../format.js";
+import {
+  buildBrownfieldImportAdoptListPayload,
+  buildBrownfieldImportAdoptPayload,
+  buildBrownfieldImportCheckPayload,
+  buildBrownfieldImportDiffPayload,
+  buildBrownfieldImportHistoryPayload,
+  buildBrownfieldImportPlanPayload,
+  buildBrownfieldImportRefreshPayload,
+  buildBrownfieldImportStatusPayload,
+  buildBrownfieldImportWorkspacePayload,
+  printBrownfieldImportAdopt,
+  printBrownfieldImportAdoptList,
+  printBrownfieldImportCheck,
+  printBrownfieldImportDiff,
+  printBrownfieldImportHistory,
+  printBrownfieldImportPlan,
+  printBrownfieldImportRefresh,
+  printBrownfieldImportStatus,
+  printBrownfieldImportWorkspace,
+  printImportHelp
+} from "./import.js";
+
+/**
+ * @param {{ commandArgs: Record<string, any>, inputPath: string|null|undefined, outPath?: string|null, fromValue?: string|null, reasonValue?: string|null, refreshAdopted?: boolean, dryRun?: boolean, write?: boolean, force?: boolean, json?: boolean }} context
+ * @returns {number}
+ */
+export function runImportCommand(context) {
+  const {
+    commandArgs,
+    inputPath,
+    outPath = null,
+    fromValue = null,
+    reasonValue = null,
+    refreshAdopted = false,
+    dryRun = false,
+    write = false,
+    force = false,
+    json = false
+  } = context;
+  const command = commandArgs.importCommand;
+
+  if (command === "workspace") {
+    if (!outPath) {
+      console.error("Missing required --out <target>.");
+      printImportHelp();
+      return 1;
+    }
+    const payload = buildBrownfieldImportWorkspacePayload(inputPath || "", outPath, { from: fromValue });
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printBrownfieldImportWorkspace(payload);
+    }
+    return 0;
+  }
+
+  if (command === "diff") {
+    const payload = buildBrownfieldImportDiffPayload(inputPath || ".", { sourcePath: fromValue });
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printBrownfieldImportDiff(payload);
+    }
+    return 0;
+  }
+
+  if (command === "refresh") {
+    const payload = buildBrownfieldImportRefreshPayload(inputPath || ".", { sourcePath: fromValue, dryRun });
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printBrownfieldImportRefresh(payload);
+    }
+    return payload.ok ? 0 : 1;
+  }
+
+  if (command === "check") {
+    const payload = buildBrownfieldImportCheckPayload(inputPath || ".");
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printBrownfieldImportCheck(payload);
+    }
+    return payload.ok ? 0 : 1;
+  }
+
+  if (command === "plan") {
+    const payload = buildBrownfieldImportPlanPayload(inputPath || ".");
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printBrownfieldImportPlan(payload);
+    }
+    return 0;
+  }
+
+  if (command === "adopt-list") {
+    const payload = buildBrownfieldImportAdoptListPayload(inputPath || ".");
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printBrownfieldImportAdoptList(payload);
+    }
+    return 0;
+  }
+
+  if (command === "adopt") {
+    if (!commandArgs.importAdoptSelector || commandArgs.importAdoptSelector.startsWith("-")) {
+      console.error("Missing required <selector>.");
+      printImportHelp();
+      return 1;
+    }
+    if (write && dryRun) {
+      console.error("Use either --dry-run or --write, not both.");
+      printImportHelp();
+      return 1;
+    }
+    const payload = buildBrownfieldImportAdoptPayload(commandArgs.importAdoptSelector, inputPath || ".", {
+      dryRun,
+      write,
+      force,
+      reason: reasonValue,
+      refreshAdopted
+    });
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printBrownfieldImportAdopt(payload);
+    }
+    return payload.ok ? 0 : 1;
+  }
+
+  if (command === "status") {
+    const payload = buildBrownfieldImportStatusPayload(inputPath || ".");
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printBrownfieldImportStatus(payload);
+    }
+    return payload.ok ? 0 : 1;
+  }
+
+  if (command === "history") {
+    const payload = buildBrownfieldImportHistoryPayload(inputPath || ".", { verify: commandArgs.verify });
+    if (json) {
+      console.log(stableStringify(payload));
+    } else {
+      printBrownfieldImportHistory(payload);
+    }
+    return payload.ok ? 0 : 1;
+  }
+
+  throw new Error(`Unknown import command '${command}'`);
+}

package/src/cli/commands/import.js

@@ -0,0 +1,35 @@
+// @ts-check
+
+export { printImportHelp } from "./import/help.js";
+export {
+  buildBrownfieldImportWorkspacePayload,
+  printBrownfieldImportWorkspace
+} from "./import/workspace.js";
+export {
+  buildBrownfieldImportRefreshPayload,
+  printBrownfieldImportRefresh
+} from "./import/refresh.js";
+export {
+  buildBrownfieldImportDiffPayload,
+  printBrownfieldImportDiff
+} from "./import/diff.js";
+export {
+  buildBrownfieldImportCheckPayload,
+  printBrownfieldImportCheck
+} from "./import/check.js";
+export {
+  buildBrownfieldImportPlanPayload,
+  printBrownfieldImportPlan,
+  buildBrownfieldImportAdoptListPayload,
+  printBrownfieldImportAdoptList
+} from "./import/plan.js";
+export {
+  buildBrownfieldImportAdoptPayload,
+  printBrownfieldImportAdopt
+} from "./import/adopt.js";
+export {
+  buildBrownfieldImportStatusPayload,
+  printBrownfieldImportStatus,
+  buildBrownfieldImportHistoryPayload,
+  printBrownfieldImportHistory
+} from "./import/status-history.js";

package/src/cli/commands/inspect.js

@@ -0,0 +1,55 @@
+// @ts-check
+
+import { stableStringify } from "../../format.js";
+import { parsePath } from "../../parser.js";
+import { resolveWorkspace } from "../../resolver.js";
+import { formatValidationErrors } from "../../validator.js";
+
+/**
+ * @param {Record<string, any>} workspaceAst
+ * @returns {void}
+ */
+function summarize(workspaceAst) {
+  const statements = workspaceAst.files.flatMap((/** @type {{ statements: any[] }} */ file) => file.statements);
+  const byKind = new Map();
+
+  for (const statement of statements) {
+    byKind.set(statement.kind, (byKind.get(statement.kind) || 0) + 1);
+  }
+
+  console.log(`Parsed ${workspaceAst.files.length} file(s) and ${statements.length} statement(s).`);
+  for (const [kind, count] of [...byKind.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    console.log(`- ${kind}: ${count}`);
+  }
+}
+
+/**
+ * @param {string|null|undefined} inputPath
+ * @returns {number}
+ */
+export function runResolveCommand(inputPath) {
+  const ast = parsePath(inputPath || ".");
+  const result = resolveWorkspace(ast);
+  if (!result.ok) {
+    console.error(formatValidationErrors(result.validation));
+    return 1;
+  }
+
+  console.log(JSON.stringify(result.graph, null, 2));
+  return 0;
+}
+
+/**
+ * @param {string|null|undefined} inputPath
+ * @param {{ json?: boolean }} [options]
+ * @returns {number}
+ */
+export function runParseCommand(inputPath, options = {}) {
+  const ast = parsePath(inputPath || ".");
+  if (options.json) {
+    console.log(stableStringify(ast));
+  } else {
+    summarize(ast);
+  }
+  return 0;
+}

package/src/cli/commands/new.js

@@ -0,0 +1,94 @@
+// @ts-check
+
+import path from "node:path";
+
+import { resolveCatalogTemplateAlias } from "../catalog-alias.js";
+import { GENERATOR_POLICY_FILE } from "../../generator-policy.js";
+import { createNewProject } from "../../new-project.js";
+
+const ENGINE_ROOT = path.resolve(decodeURIComponent(new URL("../../../", import.meta.url).pathname));
+const TEMPLATES_ROOT = path.join(ENGINE_ROOT, "templates");
+
+/**
+ * @param {ReturnType<typeof createNewProject>} result
+ * @param {string} cwd
+ * @returns {string}
+ */
+function displayProjectRootForNewProject(result, cwd) {
+  const relativeProjectRoot = path.relative(cwd, result.projectRoot);
+  return !relativeProjectRoot || relativeProjectRoot.startsWith("..")
+    ? result.projectRoot
+    : relativeProjectRoot;
+}
+
+/**
+ * @param {ReturnType<typeof createNewProject>} result
+ * @param {string} cwd
+ * @returns {void}
+ */
+export function printNewProjectResult(result, cwd) {
+  const template = result.template || {};
+  console.log(`Created Topogram project at ${result.projectRoot}.`);
+  console.log(`Template: ${result.templateName}`);
+  console.log(`Source: ${template.source || "unknown"}`);
+  if (template.sourceSpec) {
+    console.log(`Source spec: ${template.sourceSpec}`);
+  }
+  if (template.catalog) {
+    console.log(`Catalog: ${template.catalog.id} from ${template.catalog.source}`);
+    console.log(`Package: ${template.catalog.packageSpec}`);
+  }
+  console.log(`Executable implementation: ${template.includesExecutableImplementation ? "yes" : "no"}`);
+  console.log("Policy: topogram.template-policy.json");
+  console.log(`Generator policy: ${GENERATOR_POLICY_FILE}`);
+  console.log("Template files: .topogram-template-files.json");
+  if (template.includesExecutableImplementation) {
+    console.log("Trust: .topogram-template-trust.json");
+  }
+  for (const warning of result.warnings) {
+    console.warn(`Warning: ${warning}`);
+  }
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${displayProjectRootForNewProject(result, cwd)}`);
+  console.log("  npm install");
+  console.log("  npm run agent:brief");
+  console.log("  npm run doctor");
+  console.log("  npm run source:status");
+  console.log("  npm run template:explain");
+  console.log("  npm run check");
+  console.log("  npm run generator:policy:status");
+  console.log("  npm run generator:policy:check");
+  if (template.includesExecutableImplementation) {
+    console.log("  npm run template:policy:explain");
+    console.log("  npm run trust:status");
+  }
+  console.log("  npm run generate");
+  console.log("  npm run verify");
+}
+
+/**
+ * @param {string} inputPath
+ * @param {{ templateName: string, catalogSource?: string|null, cwd?: string }} options
+ * @returns {number}
+ */
+export function runNewProjectCommand(inputPath, options) {
+  const cwd = options.cwd || process.cwd();
+  const projectRoot = path.resolve(inputPath);
+  const relativeToEngine = path.relative(ENGINE_ROOT, projectRoot);
+  if (relativeToEngine === "" || (!relativeToEngine.startsWith("..") && !path.isAbsolute(relativeToEngine))) {
+    throw new Error(
+      `Refusing to create a generated project inside the engine directory. Use a path outside engine, for example '../${path.basename(projectRoot)}'.`
+    );
+  }
+  const resolvedTemplate = resolveCatalogTemplateAlias(options.templateName, options.catalogSource || null);
+  const result = createNewProject({
+    targetPath: inputPath,
+    templateName: resolvedTemplate.templateName,
+    templateProvenance: resolvedTemplate.provenance,
+    engineRoot: ENGINE_ROOT,
+    templatesRoot: TEMPLATES_ROOT
+  });
+  printNewProjectResult(result, cwd);
+  return 0;
+}

package/src/cli/commands/package/constants.js

@@ -0,0 +1,17 @@
+// @ts-check
+
+export const CLI_PACKAGE_NAME = "@topogram/cli";
+export const NPMJS_REGISTRY = "https://registry.npmjs.org";
+
+export const PACKAGE_UPDATE_CLI_CHECK_SCRIPTS = [
+  "cli:surface",
+  "doctor",
+  "catalog:show",
+  "catalog:template-show",
+  "check",
+  "pack:check",
+  "verify"
+];
+export const PACKAGE_UPDATE_CLI_INFO_SCRIPTS = ["cli:surface", "doctor", "catalog:show", "catalog:template-show"];
+export const PACKAGE_UPDATE_CLI_VERIFICATION_SCRIPTS = ["verify", "pack:check", "check"];
+export const ENGINE_ROOT = decodeURIComponent(new URL("../../../../", import.meta.url).pathname);