@topogram/cli 0.3.65 → 0.3.66

package/src/project-config/index.js

@@ -9,6 +9,7 @@ import {
   validateGeneratorManifest
 } from "../generator/registry.js";
 import { validateProjectGeneratorPolicy } from "../generator-policy.js";
+import { DEFAULT_WORKSPACE_PATH, normalizeWorkspaceConfigPath } from "../workspace-paths.js";
 
 /**
  * @typedef {Object} GeneratorBinding
@@ -32,6 +33,7 @@ import { validateProjectGeneratorPolicy } from "../generator-policy.js";
 /**
  * @typedef {Object} ProjectConfig
  * @property {string} version
+ * @property {string} [workspace]
  * @property {Record<string, { path: string, ownership: "generated"|"maintained" }>} outputs
  * @property {{ runtimes: RuntimeTopologyRuntime[] }} topology
  * @property {{ id?: string, module?: string, export?: string, implementation_module?: string, implementation_export?: string }} [implementation]
@@ -206,6 +208,7 @@ export function defaultProjectConfigForGraph(graph, implementation = null) {
 
   return {
     version: "0.1",
+    workspace: DEFAULT_WORKSPACE_PATH,
     implementation: implementation?.exampleId
       ? {
           id: implementation.exampleId
@@ -223,6 +226,29 @@ export function defaultProjectConfigForGraph(graph, implementation = null) {
   };
 }
 
+/**
+ * @param {ValidationError[]} errors
+ * @param {any} config
+ * @returns {void}
+ */
+function validateWorkspaceConfig(errors, config) {
+  if (Object.prototype.hasOwnProperty.call(config, "workspaces")) {
+    pushError(errors, "topogram.project.json workspaces[] is not supported yet; use workspace instead");
+  }
+  if (!Object.prototype.hasOwnProperty.call(config, "workspace")) {
+    return;
+  }
+  if (typeof config.workspace !== "string") {
+    pushError(errors, "topogram.project.json workspace must be a non-empty relative path");
+    return;
+  }
+  try {
+    normalizeWorkspaceConfigPath(config.workspace);
+  } catch (error) {
+    pushError(errors, error instanceof Error ? error.message : String(error));
+  }
+}
+
 /**
  * @param {string} root
  * @returns {ProjectConfigInfo|null}
@@ -448,6 +474,7 @@ export function validateProjectConfig(config, graph = null, options = {}) {
   if (typeof config.version !== "string" || config.version.length === 0) {
     pushError(errors, "topogram.project.json version must be a non-empty string");
   }
+  validateWorkspaceConfig(errors, config);
   validateOutputConfig(errors, config);
   if (config.topology?.components != null) {
     pushError(errors, `topogram.project.json ${renameDiagnostic("'topology.components'", "'topology.runtimes'", `"topology": { "runtimes": [] }`)}`);

package/src/sdlc/adopt.js

@@ -6,6 +6,7 @@
 
 import { existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
+import { DEFAULT_TOPO_FOLDER_NAME, resolveTopoRoot } from "../workspace-paths.js";
 
 const SDLC_FOLDERS = [
   "pitches",
@@ -17,7 +18,7 @@ const SDLC_FOLDERS = [
 ];
 
 function ensureFolder(root, name) {
-  const dir = path.join(root, "topogram", name);
+  const dir = path.join(resolveTopoRoot(root), name);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
     return { name, created: true };
@@ -29,8 +30,8 @@ function scanPressure(root) {
   // Pressure scan: count statements per kind so the operator knows the
   // workspace's current shape. We do not attempt to backfill — that's the
   // operator's job after they pick a starting point.
-  const tg = path.join(root, "topogram");
-  if (!existsSync(tg)) return { error: `No 'topogram/' directory found at ${root}` };
+  const tg = resolveTopoRoot(root);
+  if (!existsSync(tg)) return { error: `No '${DEFAULT_TOPO_FOLDER_NAME}/' workspace folder found at ${root}` };
   let totalFiles = 0;
   function walk(dir) {
     for (const entry of readdirSync(dir)) {
@@ -50,8 +51,8 @@ function scanPressure(root) {
 
 export function sdlcAdopt(workspaceRoot) {
   const root = path.resolve(workspaceRoot);
-  if (!existsSync(path.join(root, "topogram"))) {
-    return { ok: false, error: `No 'topogram/' directory at ${root}; run 'topogram new' first` };
+  if (!existsSync(resolveTopoRoot(root))) {
+    return { ok: false, error: `No '${DEFAULT_TOPO_FOLDER_NAME}/' workspace folder at ${root}; run 'topogram new' first` };
   }
   const folders = SDLC_FOLDERS.map((name) => ensureFolder(root, name));
   const pressure = scanPressure(root);

package/src/sdlc/paths.js

@@ -1,11 +1,9 @@
-import path from "node:path";
+import { resolveTopoRoot, resolveWorkspaceContext } from "../workspace-paths.js";
 
 export function topogramRootForSdlc(inputPath) {
-  const absolute = path.resolve(inputPath);
-  return path.basename(absolute) === "topogram" ? absolute : path.join(absolute, "topogram");
+  return resolveTopoRoot(inputPath);
 }
 
 export function projectRootForSdlc(inputPath) {
-  const absolute = path.resolve(inputPath);
-  return path.basename(absolute) === "topogram" ? path.dirname(absolute) : absolute;
+  return resolveWorkspaceContext(inputPath).projectRoot;
 }

package/src/sdlc/scaffold.js

@@ -3,6 +3,7 @@
 
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { resolveTopoRoot } from "../workspace-paths.js";
 
 const TEMPLATES = {
   pitch: (slug) => `pitch pitch_${slug} {
@@ -73,7 +74,7 @@ export function scaffoldNew(workspaceRoot, kind, slug) {
   if (!slug || !/^[a-z][a-z0-9_]*$/.test(slug)) {
     return { ok: false, error: `Invalid slug '${slug}' — must match /^[a-z][a-z0-9_]*$/` };
   }
-  const targetDir = path.join(workspaceRoot, "topogram", `${kind === "acceptance_criterion" ? "acceptance_criteria" : kind + "s"}`);
+  const targetDir = path.join(resolveTopoRoot(workspaceRoot), `${kind === "acceptance_criterion" ? "acceptance_criteria" : kind + "s"}`);
   if (!existsSync(targetDir)) mkdirSync(targetDir, { recursive: true });
   const targetFile = path.join(targetDir, `${slug}.tg`);
   if (existsSync(targetFile)) {

package/src/workflows/reconcile/adoption-plan/build.js

@@ -82,8 +82,12 @@ export function buildAdoptionPlan(bundles) {
         target: step.target || null,
         confidence: step.confidence || null,
         inference_summary: step.inference_summary || null,
+        source_kind: step.source_kind || null,
+        widget_id: step.widget_id || null,
+        event_name: step.event_name || null,
         related_docs: step.related_docs || [],
         related_capabilities: step.related_capabilities || [],
+        related_shapes: step.related_shapes || [],
         permission: step.permission || null,
         claim: step.claim || null,
         claim_value: Object.prototype.hasOwnProperty.call(step, "claim_value") ? step.claim_value : null,
@@ -95,7 +99,7 @@ export function buildAdoptionPlan(bundles) {
         canonical_path:
           step.action === "skip_duplicate_shape"
             ? (step.target ? canonicalDisplayPathForItem("shape", step.target) : null)
-            : (step.canonical_rel_path ? `topogram/${step.canonical_rel_path}` : canonicalDisplayPathForItem(itemKind, step.item)),
+            : (step.canonical_rel_path ? `topo/${step.canonical_rel_path}` : canonicalDisplayPathForItem(itemKind, step.item)),
         canonical_rel_path: step.canonical_rel_path || canonicalRelativePathForItem(itemKind, step.item),
         reason: reasonForAdoptionItem(step),
         recommendation: recommendationForAdoptionItem(step),
@@ -155,7 +159,7 @@ export function buildAdoptionPlan(bundles) {
         target: patch.doc_id,
         status: "pending",
         source_path: `candidates/reconcile/model/bundles/${bundle.slug}/${patch.patch_rel_path}`,
-        canonical_path: patch.canonical_rel_path ? `topogram/${patch.canonical_rel_path}` : null,
+        canonical_path: patch.canonical_rel_path ? `topo/${patch.canonical_rel_path}` : null,
         canonical_rel_path: patch.canonical_rel_path || null,
         reason: `Apply suggested related actor/role links to \`${patch.doc_id}\`.`,
         recommendation: recommendationForAdoptionItem({ action: "apply_doc_link_patch", target: patch.doc_id }),
@@ -182,7 +186,7 @@ export function buildAdoptionPlan(bundles) {
         status: "pending",
         confidence: patch.imported_confidence || "low",
         source_path: `candidates/reconcile/model/bundles/${bundle.slug}/${patch.patch_rel_path}`,
-        canonical_path: patch.canonical_rel_path ? `topogram/${patch.canonical_rel_path}` : null,
+        canonical_path: patch.canonical_rel_path ? `topo/${patch.canonical_rel_path}` : null,
         canonical_rel_path: patch.canonical_rel_path || null,
         reason: `Apply suggested safe metadata updates to \`${patch.doc_id}\`.`,
         recommendation: recommendationForAdoptionItem({ action: "apply_doc_metadata_patch", target: patch.doc_id }),

package/src/workflows/reconcile/adoption-plan/outputs.js

@@ -33,8 +33,18 @@ export function buildCanonicalAdoptionOutputs(paths, candidateFiles, planItems,
       .filter((/** @type {any} */ item) => item?.kind === "capability")
       .map((/** @type {any} */ item) => item.bundle)
   );
+  const widgetShapeIdSet = new Set(
+    [...selectedSet]
+      .map((/** @type {any} */ key) => itemMap.get(key))
+      .filter((/** @type {any} */ item) => item?.kind === "widget")
+      .flatMap((/** @type {any} */ item) => item.related_shapes || [])
+  );
   for (const item of planItems) {
-    if (item.kind === "shape" && item.status !== "skipped" && capabilityBundleSet.has(item.bundle)) {
+    if (
+      item.kind === "shape" &&
+      item.status !== "skipped" &&
+      (capabilityBundleSet.has(item.bundle) || widgetShapeIdSet.has(item.item))
+    ) {
       selectedSet.add(adoptionItemKey(item));
     }
   }
@@ -131,7 +141,7 @@ export function buildPromotedCanonicalItems(planItems, selectedItems, writtenCan
       track: item.track || null,
       source_path: item.source_path || null,
       canonical_rel_path: String(item.canonical_rel_path).replaceAll(path.sep, "/"),
-      canonical_path: item.canonical_path || `topogram/${String(item.canonical_rel_path).replaceAll(path.sep, "/")}`,
+      canonical_path: item.canonical_path || `topo/${String(item.canonical_rel_path).replaceAll(path.sep, "/")}`,
       suggested_action: item.suggested_action || null
     }))
     .sort((/** @type {any} */ a, /** @type {any} */ b) =>

package/src/workflows/reconcile/adoption-plan/paths.js

@@ -29,7 +29,7 @@ export function canonicalRelativePathForItem(kind, item) {
 /** @param {string} kind @param {string} item @returns {any} */
 export function canonicalDisplayPathForItem(kind, item) {
   const relativePath = canonicalRelativePathForItem(kind, item);
-  return relativePath ? `topogram/${relativePath}` : null;
+  return relativePath ? `topo/${relativePath}` : null;
 }
 
 /** @param {CandidateBundle} bundle @param {string} kind @param {WorkflowRecord} item @returns {any} */

package/src/workflows/reconcile/candidate-model.js

@@ -82,8 +82,10 @@ export function bestContextBundleForCandidate(bundles, candidate) {
 export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
   const dbCandidates = appImport.candidates.db || { entities: [], enums: [] };
   const apiCandidates = appImport.candidates.api || { capabilities: [] };
-  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [], widgets: [] };
+  const uiCandidates = appImport.candidates.ui || { screens: [], routes: [], actions: [], widgets: [], shapes: [] };
   const uiWidgetCandidates = uiCandidates.widgets || uiCandidates.components || [];
+  const uiShapeCandidates = uiCandidates.shapes || [];
+  const uiShapeCandidatesById = new Map(uiShapeCandidates.map((/** @type {any} */ shape) => [shape.id || shape.id_hint, shape]));
   const workflowCandidates = appImport.candidates.workflows || { workflows: [], workflow_states: [], workflow_transitions: [] };
   const verificationCandidates = appImport.candidates.verification || { verifications: [], scenarios: [], frameworks: [], scripts: [] };
   const docCandidates = appImport.candidates.docs || [];
@@ -210,6 +212,20 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
     }
     const conceptId = widgetConceptId(entry);
     const bundle = getOrCreateCandidateBundle(bundles, conceptId, bundleLabelFromConceptId(conceptId || entry.screen_id || entry.id_hint));
+    for (const event of entry.inferred_events || []) {
+      const shapeId = event.payload_shape || null;
+      const shape = shapeId ? uiShapeCandidatesById.get(shapeId) : null;
+      if (shape && !bundle.shapes.some((/** @type {any} */ candidate) => candidate.id === shapeId)) {
+        bundle.shapes.push({
+          id: shapeId,
+          label: shape.label || `${entry.label || entry.id_hint} ${event.name || "event"} Payload`,
+          fields: shape.fields || event.payload_fields || ["id"],
+          source_kind: shape.source_kind || "ui_widget_event",
+          widget_id: entry.id_hint,
+          event_name: event.name || null
+        });
+      }
+    }
     bundle.widgets.push(entry);
   }
   for (const entry of workflowCandidates.workflows || []) {
@@ -412,7 +428,7 @@ export function buildCandidateModelFiles(graph, appImport, topogramRoot) {
       files[`${bundleRoot}/entities/${entry.id_hint}.tg`] = renderCandidateEntity(entry, knownEnums);
     }
     for (const shape of bundle.shapes) {
-      files[`${bundleRoot}/shapes/${shape.id}.tg`] = renderCandidateShape(shape.id, shape.label, shape.fields);
+      files[`${bundleRoot}/shapes/${shape.id}.tg`] = renderCandidateShape(shape.id, shape.label, shape.fields, shape.source_kind || null);
     }
     for (const entry of bundle.capabilities) {
       const inputShapeId = bundle.shapes.find((/** @type {any} */ shape) => shape.id === shapeIdForCapability(entry, "input")) ? shapeIdForCapability(entry, "input") : null;

package/src/workflows/reconcile/impacts/adoption-plan.js

@@ -65,7 +65,7 @@ export function buildBundleAdoptionPlan(bundle, canonicalShapeIndex) {
   for (const entry of bundle.shapes) {
     const signature = shapeFieldSignature(entry.fields || []);
     const duplicateTargets = canonicalShapeIndex.get(signature) || [];
-    if (duplicateTargets.length > 0) {
+    if (duplicateTargets.length > 0 && entry.source_kind !== "ui_widget_event") {
       steps.push({
         action: "skip_duplicate_shape",
         item: entry.id,
@@ -76,7 +76,10 @@ export function buildBundleAdoptionPlan(bundle, canonicalShapeIndex) {
     steps.push({
       action: "promote_shape",
       item: entry.id,
-      target: bundle.mergeHints?.canonicalEntityTarget || null
+      target: bundle.mergeHints?.canonicalEntityTarget || null,
+      source_kind: entry.source_kind || null,
+      widget_id: entry.widget_id || null,
+      event_name: entry.event_name || null
     });
   }
   for (const entry of bundle.docs) {
@@ -126,6 +129,7 @@ export function buildBundleAdoptionPlan(bundle, canonicalShapeIndex) {
       confidence: entry.confidence || "low",
       inference_summary: entry.inference_summary || null,
       related_capabilities: [entry.data_source].filter(Boolean),
+      related_shapes: [...new Set((entry.inferred_events || []).map((/** @type {any} */ event) => event.payload_shape).filter(Boolean))],
       source_path: `candidates/reconcile/model/bundles/${bundle.slug}/widgets/${entry.id_hint}.tg`,
       canonical_rel_path: `widgets/${dashedTopogramId(entry.id_hint)}.tg`
     });

package/src/workflows/reconcile/impacts/indexes.js

@@ -2,7 +2,11 @@
 
 /** @param {any[]} fields @returns {any} */
 export function shapeFieldSignature(fields) {
-  return [...new Set((fields || []).filter(Boolean))].sort().join("|");
+  return [...new Set((fields || [])
+    .map((field) => typeof field === "string" ? field : field?.name)
+    .filter(Boolean))]
+    .sort()
+    .join("|");
 }
 
 /** @param {ResolvedGraph} graph @returns {any} */

package/src/workflows/reconcile/renderers.js

@@ -113,17 +113,31 @@ export function shapeIdForCapability(record, direction) {
   return direction === "input" ? `shape_input_${stem}` : `shape_output_${stem}`;
 }
 
-/** @param {string} shapeId @param {string} label @param {any[]} fields @returns {any} */
-export function renderCandidateShape(shapeId, label, fields) {
+/** @param {string} shapeId @param {string} label @param {any[]} fields @param {string|null} [sourceKind] @returns {any} */
+export function renderCandidateShape(shapeId, label, fields, sourceKind = null) {
+  /** @param {any} field @returns {{ name: string, fieldType: string, requiredness: string }} */
+  function normalizeField(field) {
+    if (typeof field === "string") {
+      return { name: field, fieldType: "string", requiredness: "optional" };
+    }
+    return {
+      name: field?.name || "id",
+      fieldType: field?.field_type || field?.type || "string",
+      requiredness: field?.required ? "required" : "optional"
+    };
+  }
   const lines = [
     `shape ${shapeId} {`,
     `  name "${label}"`,
-    `  description "Candidate shape imported from brownfield API evidence"`,
+    sourceKind === "ui_widget_event"
+      ? `  description "Candidate event payload shape imported from brownfield UI interaction evidence"`
+      : `  description "Candidate shape imported from brownfield API evidence"`,
     "",
     "  fields {"
   ];
   for (const field of fields) {
-    lines.push(`    ${field} string optional`);
+    const normalized = normalizeField(field);
+    lines.push(`    ${normalized.name} ${normalized.fieldType} ${normalized.requiredness}`);
   }
   lines.push("  }", "", "  status active", "}");
   return ensureTrailingNewline(lines.join("\n"));
@@ -236,7 +250,6 @@ export function renderCandidateUiReportDoc(screen, routes, actions) {
     source_of_truth: "imported",
     confidence: screen.confidence || "medium",
     review_required: true,
-    related_entities: [screen.entity_id].filter(Boolean),
     provenance: screen.provenance || [],
     tags: ["import", "ui"]
   };
@@ -244,11 +257,12 @@ export function renderCandidateUiReportDoc(screen, routes, actions) {
     "Candidate UI surface imported from brownfield route evidence.",
     "",
     `Screen: \`${screen.id_hint}\` (${screen.screen_kind})`,
+    screen.entity_id ? `Inferred entity: \`${screen.entity_id}\`` : null,
     `Routes: ${routes.length ? routes.map((/** @type {any} */ route) => `\`${route.path}\``).join(", ") : "_none_"}`,
     `Actions: ${actions.length ? actions.map((/** @type {any} */ action) => `\`${action.capability_hint}\``).join(", ") : "_none_"}`,
     "",
     "Review this UI surface before promoting it into canonical docs or projections."
-  ].join("\n");
+  ].filter(Boolean).join("\n");
   return renderMarkdownDoc(metadata, body);
 }
 
@@ -257,15 +271,36 @@ export function renderCandidateWidget(widget) {
   const propName = widget.data_prop || "rows";
   const pattern = widget.pattern || "search_results";
   const region = widget.region || "results";
+  const inferredEvents = Array.isArray(widget.inferred_events) ? widget.inferred_events : [];
+  const eventLines = inferredEvents
+    .filter((/** @type {any} */ event) => event.name && event.payload_shape)
+    .map((/** @type {any} */ event) => `    ${event.name} ${event.payload_shape}`);
+  const selectionEvent = inferredEvents.find((/** @type {any} */ event) => event.name);
+  const eventComments = inferredEvents.map((/** @type {any} */ event) =>
+    `  # Inferred event: ${event.name || "event"} ${event.action || "action"} ${event.target_screen || event.target || "target"}.`
+  );
+  const behaviorLines = eventLines.length > 0
+    ? [
+        "  events {",
+        ...eventLines,
+        "  }",
+        "  behavior [selection]",
+        "  behaviors {",
+        `    selection mode single emits ${selectionEvent?.name || "row_select"}`,
+        "  }"
+      ]
+    : [];
   return ensureTrailingNewline(
     [
       `widget ${widget.id_hint} {`,
       `  name "${widget.label || widget.id_hint}"`,
       '  description "Candidate reusable widget inferred from imported UI evidence. Review props, behavior, events, and reuse before adoption."',
       "  category collection",
+      ...eventComments,
       "  props {",
       `    ${propName} array required`,
       "  }",
+      ...behaviorLines,
       `  patterns [${pattern}]`,
       `  regions [${region}]`,
       "  status proposed",

package/src/workflows/shared.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { ensureTrailingNewline, titleCase } from "../text-helpers.js";
+import { resolveWorkspaceContext } from "../workspace-paths.js";
 
 /** @param {string} startDir @returns {any} */
 export function findNearestGitRoot(startDir) {
@@ -21,17 +22,10 @@ export function findNearestGitRoot(startDir) {
 
 /** @param {string} inputPath @returns {any} */
 export function normalizeWorkspacePaths(inputPath) {
+  const context = resolveWorkspaceContext(inputPath);
   const absolute = path.resolve(inputPath);
-  const inputExists = fs.existsSync(absolute);
-  const hasTopogramChild = fs.existsSync(path.join(absolute, "topogram")) && fs.statSync(path.join(absolute, "topogram")).isDirectory();
-  const isTopogramDir = path.basename(absolute) === "topogram" && inputExists;
-  const bootstrapWorkspaceRoot = !isTopogramDir && !hasTopogramChild;
-  const topogramRoot = isTopogramDir
-    ? absolute
-    : hasTopogramChild
-      ? path.join(absolute, "topogram")
-      : path.join(absolute, "topogram");
-  const workspaceRoot = isTopogramDir ? path.dirname(topogramRoot) : absolute;
+  const topogramRoot = context.topoRoot;
+  const workspaceRoot = context.projectRoot;
   const repoRoot = findNearestGitRoot(workspaceRoot);
   return {
     inputRoot: absolute,
@@ -39,7 +33,7 @@ export function normalizeWorkspacePaths(inputPath) {
     workspaceRoot,
     exampleRoot: workspaceRoot,
     repoRoot,
-    bootstrappedTopogramRoot: !fs.existsSync(topogramRoot)
+    bootstrappedTopogramRoot: context.bootstrappedTopoRoot
   };
 }