@topogram/cli 0.3.64 → 0.3.66

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

package/src/workspace-docs.d.ts

@@ -0,0 +1,29 @@
+import type { TopogramLocation } from "./topogram-types.js";
+
+export const DOC_KINDS: Set<string>;
+export const DOC_STATUSES: Set<string>;
+export const DOC_CONFIDENCE: Set<string>;
+export const DOC_AUDIENCES: Set<string>;
+export const DOC_PRIORITIES: Set<string>;
+export const DOC_ARRAY_FIELDS: Set<string>;
+export const DOC_REFERENCE_FIELDS: Record<string, string>;
+export const DOC_SCALAR_FIELDS: Set<string>;
+
+export interface TopogramDocParseError {
+  message: string;
+  loc: TopogramLocation;
+}
+
+export interface TopogramDoc {
+  type: "doc";
+  file: string;
+  relativePath: string;
+  metadata: Record<string, any>;
+  body: string;
+  loc: TopogramLocation;
+  parseError: TopogramDocParseError | null;
+}
+
+export function collectTopogramDocFiles(inputPath: string): string[];
+export function parseDocFile(filePath: string, workspaceRoot: string): TopogramDoc;
+export function parseDocsPath(inputPath: string): TopogramDoc[];

package/src/workspace-paths.js

@@ -0,0 +1,328 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const DEFAULT_TOPO_FOLDER_NAME = "topo";
+export const LEGACY_TOPOGRAM_FOLDER_NAME = "topogram";
+export const DEFAULT_WORKSPACE_PATH = `./${DEFAULT_TOPO_FOLDER_NAME}`;
+export const PROJECT_CONFIG_FILE = "topogram.project.json";
+
+const SIGNAL_SCAN_IGNORED_DIRS = new Set([
+  ".git",
+  ".next",
+  ".tmp",
+  ".turbo",
+  ".yarn",
+  "app",
+  "build",
+  "coverage",
+  "dist",
+  "expected",
+  "node_modules",
+  "tmp"
+]);
+const WORKSPACE_SIGNAL_DIRS = new Set([
+  "_archive",
+  "acceptance_criteria",
+  "actors",
+  "bugs",
+  "capabilities",
+  "decisions",
+  "domains",
+  "entities",
+  "enums",
+  "operations",
+  "pitches",
+  "projections",
+  "requirements",
+  "rules",
+  "shapes",
+  "tasks",
+  "terms",
+  "verifications",
+  "widgets",
+  "workflows"
+]);
+
+/**
+ * @typedef {Object} WorkspaceResolution
+ * @property {string} inputRoot
+ * @property {string} topoRoot
+ * @property {string} projectRoot
+ * @property {string|null} configPath
+ * @property {boolean} fromConfig
+ * @property {boolean} fromSignal
+ * @property {boolean} bootstrappedTopoRoot
+ */
+
+/**
+ * @param {string} candidatePath
+ * @returns {boolean}
+ */
+function isDirectory(candidatePath) {
+  try {
+    return fs.existsSync(candidatePath) && fs.statSync(candidatePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} filePath
+ * @returns {any}
+ */
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * @param {string} startPath
+ * @returns {string}
+ */
+function searchStartDirectory(startPath) {
+  const absolute = path.resolve(startPath || ".");
+  if (fs.existsSync(absolute) && fs.statSync(absolute).isFile()) {
+    return path.dirname(absolute);
+  }
+  if (!fs.existsSync(absolute) && path.basename(absolute) === DEFAULT_TOPO_FOLDER_NAME) {
+    return path.dirname(absolute);
+  }
+  return absolute;
+}
+
+/**
+ * @param {string} startPath
+ * @returns {{ config: any, configPath: string, configDir: string }|null}
+ */
+export function findProjectRoot(startPath) {
+  let current = searchStartDirectory(startPath);
+  while (current && current !== path.dirname(current)) {
+    const candidate = path.join(current, PROJECT_CONFIG_FILE);
+    if (fs.existsSync(candidate)) {
+      return {
+        config: readJson(candidate),
+        configPath: candidate,
+        configDir: current
+      };
+    }
+    current = path.dirname(current);
+  }
+  return null;
+}
+
+/**
+ * @param {string} workspacePath
+ * @returns {string}
+ */
+export function normalizeWorkspaceConfigPath(workspacePath) {
+  const value = String(workspacePath || "").trim();
+  if (!value) {
+    throw new Error("topogram.project.json workspace must be a non-empty relative path.");
+  }
+  if (path.isAbsolute(value)) {
+    throw new Error("topogram.project.json workspace must be relative to the project root.");
+  }
+  const normalized = value.replace(/\\/g, "/");
+  const resolved = path.posix.normalize(normalized);
+  if (resolved === ".." || resolved.startsWith("../")) {
+    throw new Error("topogram.project.json workspace must not escape the project root.");
+  }
+  return normalized;
+}
+
+/**
+ * @param {any} config
+ * @param {string} configDir
+ * @returns {string}
+ */
+export function resolveProjectWorkspace(config, configDir) {
+  if (config && Object.prototype.hasOwnProperty.call(config, "workspaces")) {
+    throw new Error("topogram.project.json workspaces[] is not supported yet; use single workspace instead.");
+  }
+  const configured = config?.workspace == null ? DEFAULT_WORKSPACE_PATH : config.workspace;
+  const normalized = normalizeWorkspaceConfigPath(configured);
+  return path.resolve(configDir, normalized);
+}
+
+/**
+ * @param {string} root
+ * @param {number} [maxDepth]
+ * @returns {boolean}
+ */
+export function workspaceHasTgFiles(root, maxDepth = 3) {
+  if (!isDirectory(root)) {
+    return false;
+  }
+  const walk = (/** @type {string} */ current, /** @type {number} */ depth) => {
+    if (depth > maxDepth) {
+      return false;
+    }
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (SIGNAL_SCAN_IGNORED_DIRS.has(entry.name)) {
+        continue;
+      }
+      const child = path.join(current, entry.name);
+      if (entry.isFile() && entry.name.endsWith(".tg")) {
+        return true;
+      }
+      if (entry.isDirectory() && walk(child, depth + 1)) {
+        return true;
+      }
+    }
+    return false;
+  };
+  return walk(root, 0);
+}
+
+/**
+ * @param {string} root
+ * @returns {boolean}
+ */
+function isWorkspaceSignalRoot(root) {
+  if (!isDirectory(root)) {
+    return false;
+  }
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith(".tg")) {
+      return true;
+    }
+    if (entry.isDirectory() && WORKSPACE_SIGNAL_DIRS.has(entry.name) && workspaceHasTgFiles(path.join(root, entry.name), 2)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {string} root
+ * @returns {string[]}
+ */
+function signalWorkspaceCandidates(root) {
+  if (!isDirectory(root)) {
+    return [];
+  }
+  /** @type {string[]} */
+  const candidates = [];
+  if (isWorkspaceSignalRoot(root)) {
+    candidates.push(root);
+  }
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || SIGNAL_SCAN_IGNORED_DIRS.has(entry.name)) {
+      continue;
+    }
+    const child = path.join(root, entry.name);
+    if (isWorkspaceSignalRoot(child)) {
+      candidates.push(child);
+    }
+  }
+  return [...new Set(candidates.map((candidate) => path.resolve(candidate)))].sort();
+}
+
+/**
+ * @param {string} inputPath
+ * @returns {WorkspaceResolution}
+ */
+export function resolveWorkspaceContext(inputPath = ".") {
+  const absolute = path.resolve(inputPath || ".");
+  if (
+    isDirectory(absolute) &&
+    (
+      path.basename(absolute) === DEFAULT_TOPO_FOLDER_NAME ||
+      (isWorkspaceSignalRoot(absolute) && !isDirectory(path.join(absolute, DEFAULT_TOPO_FOLDER_NAME)))
+    )
+  ) {
+    return {
+      inputRoot: absolute,
+      topoRoot: absolute,
+      projectRoot: path.basename(absolute) === DEFAULT_TOPO_FOLDER_NAME ? path.dirname(absolute) : absolute,
+      configPath: null,
+      fromConfig: false,
+      fromSignal: false,
+      bootstrappedTopoRoot: false
+    };
+  }
+
+  const configInfo = findProjectRoot(absolute);
+  if (configInfo) {
+    const topoRoot = resolveProjectWorkspace(configInfo.config, configInfo.configDir);
+    return {
+      inputRoot: absolute,
+      topoRoot,
+      projectRoot: configInfo.configDir,
+      configPath: configInfo.configPath,
+      fromConfig: true,
+      fromSignal: false,
+      bootstrappedTopoRoot: !fs.existsSync(topoRoot)
+    };
+  }
+
+  const searchBase = !fs.existsSync(absolute) && path.basename(absolute) === DEFAULT_TOPO_FOLDER_NAME
+    ? path.dirname(absolute)
+    : absolute;
+  const defaultCandidate = path.join(searchBase, DEFAULT_TOPO_FOLDER_NAME);
+  if (isDirectory(defaultCandidate)) {
+    return {
+      inputRoot: absolute,
+      topoRoot: defaultCandidate,
+      projectRoot: searchBase,
+      configPath: null,
+      fromConfig: false,
+      fromSignal: false,
+      bootstrappedTopoRoot: false
+    };
+  }
+
+  const signalCandidates = signalWorkspaceCandidates(searchBase);
+  if (signalCandidates.length === 1) {
+    const topoRoot = signalCandidates[0];
+    return {
+      inputRoot: absolute,
+      topoRoot,
+      projectRoot: topoRoot,
+      configPath: null,
+      fromConfig: false,
+      fromSignal: true,
+      bootstrappedTopoRoot: false
+    };
+  }
+  if (signalCandidates.length > 1) {
+    throw new Error(
+      `Multiple Topogram workspace candidates found. Pass one explicitly: ${signalCandidates.join(", ")}`
+    );
+  }
+
+  return {
+    inputRoot: absolute,
+    topoRoot: defaultCandidate,
+    projectRoot: searchBase,
+    configPath: null,
+    fromConfig: false,
+    fromSignal: false,
+    bootstrappedTopoRoot: true
+  };
+}
+
+/**
+ * @param {string} inputPath
+ * @returns {string}
+ */
+export function resolveTopoRoot(inputPath = ".") {
+  return resolveWorkspaceContext(inputPath).topoRoot;
+}
+
+/**
+ * @param {string} packageRoot
+ * @returns {{ root: string, legacy: boolean }}
+ */
+export function resolvePackageWorkspace(packageRoot) {
+  const topoRoot = path.join(packageRoot, DEFAULT_TOPO_FOLDER_NAME);
+  if (isDirectory(topoRoot)) {
+    return { root: topoRoot, legacy: false };
+  }
+  const legacyRoot = path.join(packageRoot, LEGACY_TOPOGRAM_FOLDER_NAME);
+  if (isDirectory(legacyRoot)) {
+    return { root: legacyRoot, legacy: true };
+  }
+  throw new Error(`Package is missing ${DEFAULT_TOPO_FOLDER_NAME}/.`);
+}