@topogram/cli 0.3.63 → 0.3.64

package/src/cli/commands/trust.js

@@ -0,0 +1,219 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../../format.js";
+import { loadProjectConfig } from "../../project-config.js";
+import {
+  getTemplateTrustDiff,
+  getTemplateTrustStatus,
+  implementationRequiresTrust,
+  TEMPLATE_TRUST_FILE,
+  templateTrustRecoveryGuidance,
+  writeTemplateTrustRecord
+} from "../../template-trust.js";
+import { writeTemplateFilesManifest } from "../../new-project.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @returns {void}
+ */
+export function printTrustHelp() {
+  console.log("Usage: topogram trust status [path] [--json]");
+  console.log("   or: topogram trust diff [path] [--json]");
+  console.log("   or: topogram trust template [path] [--force]");
+  console.log("");
+  console.log("Inspects or refreshes executable template implementation trust after human review.");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram trust status");
+  console.log("  topogram trust diff");
+  console.log("  topogram trust template");
+}
+
+/**
+ * @param {AnyRecord} projectConfigInfo
+ * @returns {{ config: any, configPath: string, configDir: string }}
+ */
+function implementationInfoFromProject(projectConfigInfo) {
+  return {
+    config: projectConfigInfo.config.implementation,
+    configPath: projectConfigInfo.configPath,
+    configDir: projectConfigInfo.configDir
+  };
+}
+
+/**
+ * @param {string} inputPath
+ * @param {{ force?: boolean }} [options]
+ * @returns {number}
+ */
+export function runTrustTemplateCommand(inputPath, options = {}) {
+  const projectConfigInfo = loadProjectConfig(inputPath);
+  if (!projectConfigInfo) {
+    throw new Error("Cannot trust template files without topogram.project.json.");
+  }
+  const templateManifestPath = path.join(projectConfigInfo.configDir, "topogram-template.json");
+  if (!projectConfigInfo.config.template && fs.existsSync(templateManifestPath) && !options.force) {
+    throw new Error("Cannot write consumer template trust metadata in a template source repo. Template source repos should not contain .topogram-template-files.json or .topogram-template-trust.json. Run this command in a generated project, or pass --force if you intentionally need local trust metadata here.");
+  }
+  if (!projectConfigInfo.config.template && fs.existsSync(templateManifestPath) && options.force) {
+    console.warn("Warning: writing consumer template trust metadata in a template source repo because --force was provided.");
+  }
+  const fileManifest = writeTemplateFilesManifest(projectConfigInfo.configDir, projectConfigInfo.config);
+  console.log(`Wrote .topogram-template-files.json with ${fileManifest.files.length} template-owned file hash(es).`);
+  if (projectConfigInfo.config.implementation) {
+    const implementationInfo = implementationInfoFromProject(projectConfigInfo);
+    if (implementationRequiresTrust(implementationInfo, projectConfigInfo.config)) {
+      const trustRecord = writeTemplateTrustRecord(projectConfigInfo.configDir, projectConfigInfo.config);
+      console.log(`Wrote ${TEMPLATE_TRUST_FILE} for ${trustRecord.implementation.module}.`);
+      if (trustRecord.template.id) {
+        console.log(`Trusted template: ${trustRecord.template.id}@${trustRecord.template.version || "unknown"}`);
+      }
+      console.log(`Trusted implementation digest: ${trustRecord.content.digest}`);
+      return 0;
+    }
+  }
+  console.log("No local implementation trust record needed for this project.");
+  return 0;
+}
+
+/**
+ * @param {string} inputPath
+ * @param {{ json?: boolean }} [options]
+ * @returns {number}
+ */
+export function runTrustStatusCommand(inputPath, options = {}) {
+  const projectConfigInfo = loadProjectConfig(inputPath);
+  if (!projectConfigInfo) {
+    throw new Error("Cannot inspect template trust without topogram.project.json.");
+  }
+  if (!projectConfigInfo.config.implementation) {
+    throw new Error("Cannot inspect template trust because topogram.project.json has no implementation config.");
+  }
+  const status = getTemplateTrustStatus(implementationInfoFromProject(projectConfigInfo), projectConfigInfo.config);
+  if (options.json) {
+    console.log(stableStringify(status));
+  } else if (!status.requiresTrust) {
+    console.log("No local implementation trust record needed for this project.");
+  } else {
+    console.log(status.ok ? "Implementation trust status: trusted" : "Implementation trust status: review required");
+    if (status.template.id) {
+      console.log(`Template: ${status.template.id}@${status.template.version || "unknown"}`);
+    }
+    console.log(`Implementation: ${status.implementation.module}`);
+    if (status.content.trustedDigest) {
+      console.log(`Trusted digest: ${status.content.trustedDigest}`);
+    }
+    if (status.content.currentDigest) {
+      console.log(`Current digest: ${status.content.currentDigest}`);
+    }
+    for (const issue of status.issues) {
+      console.log(`Issue: ${issue}`);
+    }
+    for (const filePath of status.content.changed) {
+      console.log(`Changed: ${filePath}`);
+    }
+    for (const filePath of status.content.added) {
+      console.log(`Added: ${filePath}`);
+    }
+    for (const filePath of status.content.removed) {
+      console.log(`Removed: ${filePath}`);
+    }
+    if (!status.ok) {
+      const guidance = templateTrustRecoveryGuidance(status.issues);
+      if (guidance) {
+        console.log(guidance);
+      }
+    }
+  }
+  return status.ok ? 0 : 1;
+}
+
+/**
+ * @param {string} inputPath
+ * @param {{ json?: boolean }} [options]
+ * @returns {number}
+ */
+export function runTrustDiffCommand(inputPath, options = {}) {
+  const projectConfigInfo = loadProjectConfig(inputPath);
+  if (!projectConfigInfo) {
+    throw new Error("Cannot inspect template trust diff without topogram.project.json.");
+  }
+  if (!projectConfigInfo.config.implementation) {
+    throw new Error("Cannot inspect template trust diff because topogram.project.json has no implementation config.");
+  }
+  const diff = getTemplateTrustDiff(implementationInfoFromProject(projectConfigInfo), projectConfigInfo.config);
+  if (options.json) {
+    console.log(stableStringify(diff));
+  } else if (!diff.requiresTrust) {
+    console.log("No local implementation trust record needed for this project.");
+  } else if (diff.files.length === 0) {
+    console.log(diff.ok ? "Template trust diff: no implementation changes." : "Template trust diff: no file-level diff available.");
+    for (const issue of diff.status.issues) {
+      console.log(`Issue: ${issue}`);
+    }
+    if (!diff.ok) {
+      const guidance = templateTrustRecoveryGuidance(diff.status.issues);
+      if (guidance) {
+        console.log(guidance);
+      }
+    }
+  } else {
+    console.log(diff.ok ? "Template trust diff: no implementation changes." : "Template trust diff: review required");
+    for (const file of diff.files) {
+      console.log("");
+      console.log(`${file.kind.toUpperCase()}: implementation/${file.path}`);
+      if (file.trusted) {
+        console.log(`  trusted sha256: ${file.trusted.sha256}`);
+        console.log(`  trusted size: ${file.trusted.size}`);
+      }
+      if (file.current) {
+        console.log(`  current sha256: ${file.current.sha256}`);
+        console.log(`  current size: ${file.current.size}`);
+      }
+      if (file.binary) {
+        console.log("  diff: binary file");
+      } else if (file.diffOmitted && !file.unifiedDiff) {
+        console.log("  diff: hash-only");
+      }
+      if (file.unifiedDiff) {
+        console.log(file.unifiedDiff.trimEnd());
+      }
+    }
+    if (!diff.ok) {
+      console.log("");
+      const guidance = templateTrustRecoveryGuidance(diff.status.issues);
+      if (guidance) {
+        console.log(guidance);
+      }
+    }
+  }
+  return diff.ok ? 0 : 1;
+}
+
+/**
+ * @param {{
+ *   commandArgs: Record<string, any>,
+ *   inputPath: string|null|undefined,
+ *   json: boolean
+ * }} context
+ * @returns {number}
+ */
+export function runTrustCommand(context) {
+  const inputPath = context.inputPath || "./topogram";
+  if (context.commandArgs.trustCommand === "template") {
+    return runTrustTemplateCommand(inputPath, { force: Boolean(context.commandArgs.force) });
+  }
+  if (context.commandArgs.trustCommand === "status") {
+    return runTrustStatusCommand(inputPath, { json: context.json });
+  }
+  if (context.commandArgs.trustCommand === "diff") {
+    return runTrustDiffCommand(inputPath, { json: context.json });
+  }
+  throw new Error(`Unknown trust command '${context.commandArgs.trustCommand}'`);
+}

package/src/cli/commands/version.js

@@ -0,0 +1,40 @@
+// @ts-check
+
+import fs from "node:fs";
+
+const CLI_PACKAGE_NAME = "@topogram/cli";
+const PACKAGE_JSON_URL = new URL("../../../package.json", import.meta.url);
+
+/**
+ * @returns {string}
+ */
+function readInstalledCliPackageVersion() {
+  if (!fs.existsSync(PACKAGE_JSON_URL)) {
+    return "0.0.0";
+  }
+  const pkg = JSON.parse(fs.readFileSync(PACKAGE_JSON_URL, "utf8"));
+  return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+}
+
+/**
+ * @param {{ executablePath?: string }} [options]
+ * @returns {{ packageName: string, version: string, executablePath: string, nodeVersion: string }}
+ */
+export function buildVersionPayload(options = {}) {
+  return {
+    packageName: CLI_PACKAGE_NAME,
+    version: readInstalledCliPackageVersion(),
+    executablePath: options.executablePath || process.argv[1] || "",
+    nodeVersion: process.version
+  };
+}
+
+/**
+ * @param {ReturnType<typeof buildVersionPayload>} payload
+ * @returns {void}
+ */
+export function printVersion(payload) {
+  console.log(`Topogram CLI: ${payload.packageName}@${payload.version}`);
+  console.log(`Executable: ${payload.executablePath}`);
+  console.log(`Node: ${payload.nodeVersion}`);
+}

package/src/cli/commands/widget.js

@@ -0,0 +1,168 @@
+// @ts-check
+
+import { stableStringify } from "../../format.js";
+import { generateWorkspace } from "../../generator.js";
+import { parsePath } from "../../parser.js";
+import { formatValidationErrors } from "../../validator.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} report
+ * @returns {void}
+ */
+export function printWidgetConformanceReport(report) {
+  const summary = report.summary || {};
+  const ok = (summary.errors || 0) === 0;
+  console.log(ok ? "Widget conformance passed." : "Widget conformance found issues.");
+  console.log(`Usages: ${summary.total_usages || 0} total, ${summary.passed_usages || 0} passed, ${summary.warning_usages || 0} warning, ${summary.error_usages || 0} error`);
+  console.log(`Checks: ${summary.errors || 0} error(s), ${summary.warnings || 0} warning(s)`);
+  if (report.filters?.projection) {
+    console.log(`Projection filter: ${report.filters.projection}`);
+  }
+  if (report.filters?.widget) {
+    console.log(`Widget filter: ${report.filters.widget}`);
+  }
+  if ((summary.affected_projections || []).length > 0) {
+    console.log(`Affected projections: ${summary.affected_projections.join(", ")}`);
+  }
+  if ((summary.affected_widgets || []).length > 0) {
+    console.log(`Affected widgets: ${summary.affected_widgets.join(", ")}`);
+  }
+  if ((report.checks || []).length > 0) {
+    console.log("");
+    console.log("Issues:");
+    for (const check of report.checks) {
+      const context = [
+        check.projection ? `projection ${check.projection}` : null,
+        check.widget ? `widget ${check.widget}` : null,
+        check.screen ? `screen ${check.screen}` : null,
+        check.region ? `region ${check.region}` : null,
+        check.prop ? `prop ${check.prop}` : null,
+        check.event ? `event ${check.event}` : null,
+        check.behavior ? `behavior ${check.behavior}` : null
+      ].filter(Boolean).join(", ");
+      console.log(`- ${check.severity.toUpperCase()} ${check.code}${context ? ` (${context})` : ""}: ${check.message}`);
+      if (check.suggested_fix) {
+        console.log(`  Fix: ${check.suggested_fix}`);
+      }
+    }
+  }
+  const writeScopePaths = report.write_scope?.paths || [];
+  if (writeScopePaths.length > 0) {
+    console.log("");
+    console.log("Write scope:");
+    for (const filePath of writeScopePaths) {
+      console.log(`- ${filePath}`);
+    }
+  }
+}
+
+/**
+ * @param {AnyRecord} report
+ * @returns {void}
+ */
+export function printWidgetBehaviorReport(report) {
+  const summary = report.summary || {};
+  const ok = (summary.errors || 0) === 0;
+  console.log(ok ? "Widget behavior report passed." : "Widget behavior report found issues.");
+  console.log(`Behaviors: ${summary.total_behaviors || 0} total, ${summary.realized || 0} realized, ${summary.partial || 0} partial, ${summary.declared || 0} declared`);
+  console.log(`Checks: ${summary.errors || 0} error(s), ${summary.warnings || 0} warning(s)`);
+  if (report.filters?.projection) {
+    console.log(`Projection filter: ${report.filters.projection}`);
+  }
+  if (report.filters?.widget) {
+    console.log(`Widget filter: ${report.filters.widget}`);
+  }
+  if ((summary.affected_projections || []).length > 0) {
+    console.log(`Affected projections: ${summary.affected_projections.join(", ")}`);
+  }
+  if ((summary.affected_widgets || []).length > 0) {
+    console.log(`Affected widgets: ${summary.affected_widgets.join(", ")}`);
+  }
+  if ((summary.affected_capabilities || []).length > 0) {
+    console.log(`Affected capabilities: ${summary.affected_capabilities.join(", ")}`);
+  }
+  const highlights = report.highlights || [];
+  if (highlights.length > 0) {
+    console.log("");
+    console.log("Behavior highlights:");
+    for (const highlight of highlights) {
+      const context = [
+        highlight.projection ? `projection ${highlight.projection}` : null,
+        highlight.widget ? `widget ${highlight.widget}` : null,
+        highlight.screen ? `screen ${highlight.screen}` : null,
+        highlight.region ? `region ${highlight.region}` : null,
+        highlight.event ? `event ${highlight.event}` : null,
+        highlight.capability ? `capability ${highlight.capability}` : null,
+        highlight.behavior ? `behavior ${highlight.behavior}` : null
+      ].filter(Boolean).join(", ");
+      console.log(`- ${highlight.severity.toUpperCase()} ${highlight.code}${context ? ` (${context})` : ""}: ${highlight.message}`);
+      if (highlight.suggested_fix) {
+        console.log(`  Fix: ${highlight.suggested_fix}`);
+      }
+    }
+  }
+  const groupSummary = report.groups || {};
+  console.log("");
+  console.log(`Groups: ${(groupSummary.widgets || []).length} widget(s), ${(groupSummary.screens || []).length} screen(s), ${(groupSummary.capabilities || []).length} capability group(s), ${(groupSummary.effects || []).length} effect group(s)`);
+}
+
+/**
+ * @param {string} inputPath
+ * @param {{ json?: boolean, projectionId?: string|null, widgetId?: string|null }} [options]
+ * @returns {number}
+ */
+export function runWidgetCheckCommand(inputPath, options = {}) {
+  return runWidgetReportCommand(inputPath, {
+    json: options.json,
+    projectionId: options.projectionId,
+    widgetId: options.widgetId,
+    target: "widget-conformance-report",
+    print: printWidgetConformanceReport
+  });
+}
+
+/**
+ * @param {string} inputPath
+ * @param {{ json?: boolean, projectionId?: string|null, widgetId?: string|null }} [options]
+ * @returns {number}
+ */
+export function runWidgetBehaviorCommand(inputPath, options = {}) {
+  return runWidgetReportCommand(inputPath, {
+    json: options.json,
+    projectionId: options.projectionId,
+    widgetId: options.widgetId,
+    target: "widget-behavior-report",
+    print: printWidgetBehaviorReport
+  });
+}
+
+/**
+ * @param {string} inputPath
+ * @param {{ json?: boolean, projectionId?: string|null, widgetId?: string|null, target: string, print: (report: AnyRecord) => void }} options
+ * @returns {number}
+ */
+function runWidgetReportCommand(inputPath, options) {
+  const ast = parsePath(inputPath);
+  const result = generateWorkspace(ast, {
+    target: options.target,
+    projectionId: options.projectionId,
+    widgetId: options.widgetId,
+    componentId: options.widgetId
+  });
+  if (!result.ok) {
+    console.error(formatValidationErrors(result.validation));
+    return 1;
+  }
+  const report = result.artifact;
+  const ok = (report.summary?.errors || 0) === 0;
+  if (options.json) {
+    console.log(stableStringify(report));
+  } else {
+    options.print(report);
+  }
+  return ok ? 0 : 1;
+}

package/src/cli/commands/workflow.js

@@ -0,0 +1,63 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../../format.js";
+import { parsePath } from "../../parser.js";
+import { formatValidationErrors, validateWorkspace } from "../../validator.js";
+import { runWorkflow } from "../../workflows.js";
+
+/**
+ * @param {string|null|undefined} inputPath
+ * @returns {number}
+ */
+export function runValidateCommand(inputPath) {
+  const ast = parsePath(inputPath || ".");
+  const result = validateWorkspace(ast);
+  if (!result.ok) {
+    console.error(formatValidationErrors(result));
+    return 1;
+  }
+
+  const files = /** @type {Array<{ statements: any[] }>} */ (ast.files || []);
+  const statementCount = files.flatMap((file) => file.statements).length;
+  console.log(`Validated ${files.length} file(s) and ${statementCount} statement(s) with 0 errors.`);
+  return 0;
+}
+
+/**
+ * @param {{
+ *   workflowName: string,
+ *   inputPath: string|null|undefined,
+ *   from: string|null,
+ *   adopt: string|null,
+ *   write: boolean,
+ *   refreshAdopted: boolean,
+ *   outDir: string|null
+ * }} context
+ * @returns {number}
+ */
+export function runLegacyWorkflowCommand(context) {
+  const result = runWorkflow(context.workflowName, context.inputPath || ".", {
+    from: context.from,
+    adopt: context.adopt,
+    write: context.write,
+    refreshAdopted: context.refreshAdopted
+  });
+
+  if (context.write) {
+    const resolvedOutDir = path.resolve(context.outDir || result.defaultOutDir || "artifacts");
+    fs.mkdirSync(resolvedOutDir, { recursive: true });
+    for (const [relativePath, contents] of Object.entries(result.files || {})) {
+      const destination = path.join(resolvedOutDir, relativePath);
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      fs.writeFileSync(destination, typeof contents === "string" ? contents : `${stableStringify(contents)}\n`, "utf8");
+    }
+    console.log(`Wrote ${Object.keys(result.files || {}).length} file(s) to ${resolvedOutDir}`);
+    return 0;
+  }
+
+  console.log(stableStringify(result.summary));
+  return 0;
+}