@topogram/cli 0.3.72 → 0.3.74

package/src/validator/per-kind/task.js

@@ -1,6 +1,7 @@
 // @ts-check
 import {
   TASK_IDENTIFIER_PATTERN,
+  TASK_DISPOSITIONS,
   PRIORITY_VALUES,
   WORK_TYPES
 } from "../kinds.js";
@@ -55,6 +56,23 @@ function validateWorkType(errors, statement, fieldMap) {
   }
 }
 
+/** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap */
+function validateDisposition(errors, statement, fieldMap) {
+  const field = fieldMap.get("disposition")?.[0];
+  if (!field) return;
+  if (field.value.type !== "symbol") {
+    pushError(errors, `Field 'disposition' on task ${statement.id} must be a symbol`, field.loc);
+    return;
+  }
+  if (!TASK_DISPOSITIONS.has(field.value.value)) {
+    pushError(
+      errors,
+      `Invalid disposition '${field.value.value}' on task ${statement.id}`,
+      field.loc
+    );
+  }
+}
+
 /** @param {ValidationErrors} errors @param {TopogramStatement} statement @param {TopogramFieldMap} fieldMap @param {TopogramRegistry} registry */
 function validateBlockingPair(errors, statement, fieldMap, registry) {
   // Self-block guard. Reciprocal `blocks` <-> `blocked_by` resolution is the
@@ -98,6 +116,7 @@ export function validateTask(errors, statement, fieldMap, registry) {
   validateTaskIdentifier(errors, statement);
   validatePriority(errors, statement, fieldMap);
   validateWorkType(errors, statement, fieldMap);
+  validateDisposition(errors, statement, fieldMap);
   validateBlockingPair(errors, statement, fieldMap, registry);
   validateClaimedByPresence(errors, statement, fieldMap);
 }

package/src/validator/projections/cli.js

@@ -0,0 +1,267 @@
+// @ts-check
+
+import {
+  CLI_COMMAND_EFFECTS,
+  CLI_COMMAND_OPTION_TYPES,
+  CLI_COMMAND_OUTPUT_FORMATS,
+  IDENTIFIER_PATTERN
+} from "../kinds.js";
+import {
+  blockEntries,
+  getFieldValue,
+  pushError
+} from "../utils.js";
+
+/**
+ * @param {TopogramToken | null | undefined} token
+ * @returns {string | null}
+ */
+function tokenText(token) {
+  return token?.type === "symbol" || token?.type === "string" ? token.value : null;
+}
+
+/**
+ * @param {TopogramToken | null | undefined} token
+ * @returns {string | null}
+ */
+function tokenDirectiveValue(token) {
+  if (!token) {
+    return null;
+  }
+  if (token.type === "list") {
+    return token.items.map((item) => tokenText(item)).filter((value) => value !== null).join(",");
+  }
+  return tokenText(token);
+}
+
+/**
+ * @param {TopogramBlockEntry} entry
+ * @returns {string[]}
+ */
+function entryTokens(entry) {
+  const values = [];
+  for (const token of entry.items) {
+    const value = tokenDirectiveValue(token);
+    if (value !== null) {
+      values.push(value);
+    }
+  }
+  return values;
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramBlockEntry} entry
+ * @param {string[]} tokens
+ * @param {number} startIndex
+ * @param {string} context
+ * @returns {Map<string, string>}
+ */
+function parseDirectives(errors, statement, entry, tokens, startIndex, context) {
+  const directives = new Map();
+  for (let index = startIndex; index < tokens.length; index += 2) {
+    const key = tokens[index];
+    const value = tokens[index + 1];
+    if (!key) {
+      continue;
+    }
+    if (!value) {
+      pushError(errors, `Projection ${statement.id} ${context} is missing a value for '${key}'`, entry.loc);
+      continue;
+    }
+    directives.set(key, value);
+  }
+  return directives;
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @returns {boolean}
+ */
+function validateCliOwnership(errors, statement, fieldMap) {
+  const cliFields = ["commands", "command_options", "command_outputs", "command_effects", "command_examples"];
+  const hasCliFields = cliFields.some((key) => fieldMap.has(key));
+  if (!hasCliFields) {
+    return false;
+  }
+
+  const typeValue = tokenText(fieldMap.get("type")?.[0]?.value);
+  if (typeValue !== "cli_surface") {
+    for (const key of cliFields) {
+      const field = fieldMap.get(key)?.[0];
+      if (field) {
+        pushError(errors, `Projection ${statement.id} ${key} belongs on cli_surface projections`, field.loc);
+      }
+    }
+    return false;
+  }
+  return true;
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramRegistry} registry
+ * @returns {Set<string>}
+ */
+function validateCommands(errors, statement, registry) {
+  const commandIds = new Set();
+  const entries = blockEntries(getFieldValue(statement, "commands"));
+  for (const entry of entries) {
+    const tokens = entryTokens(entry);
+    if (tokens[0] !== "command") {
+      pushError(errors, `Projection ${statement.id} commands entries must start with 'command'`, entry.loc);
+      continue;
+    }
+    const commandId = tokens[1];
+    if (!commandId || !IDENTIFIER_PATTERN.test(commandId)) {
+      pushError(errors, `Projection ${statement.id} command id '${commandId || ""}' must be a Topogram identifier`, entry.loc);
+      continue;
+    }
+    if (commandIds.has(commandId)) {
+      pushError(errors, `Projection ${statement.id} commands has duplicate command '${commandId}'`, entry.loc);
+    }
+    commandIds.add(commandId);
+
+    const directives = parseDirectives(errors, statement, entry, tokens, 2, `command '${commandId}'`);
+    const capabilityId = directives.get("capability");
+    if (capabilityId) {
+      const capability = registry.get(capabilityId);
+      if (!capability || capability.kind !== "capability") {
+        pushError(errors, `Projection ${statement.id} command '${commandId}' references unknown capability '${capabilityId}'`, entry.loc);
+      }
+    }
+    const mode = directives.get("mode");
+    if (mode && !CLI_COMMAND_EFFECTS.has(mode)) {
+      pushError(errors, `Projection ${statement.id} command '${commandId}' has invalid mode '${mode}'`, entry.loc);
+    }
+  }
+  return commandIds;
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {Set<string>} commandIds
+ * @returns {void}
+ */
+function validateCommandOptions(errors, statement, commandIds) {
+  for (const entry of blockEntries(getFieldValue(statement, "command_options"))) {
+    const tokens = entryTokens(entry);
+    const commandId = tokens[0] === "command" ? tokens[1] : null;
+    if (!commandId || tokens[2] !== "option" || !tokens[3]) {
+      pushError(errors, `Projection ${statement.id} command_options entries must use 'command <id> option <name> type <type>'`, entry.loc);
+      continue;
+    }
+    if (!commandIds.has(commandId)) {
+      pushError(errors, `Projection ${statement.id} command_options references unknown command '${commandId}'`, entry.loc);
+    }
+    const directives = parseDirectives(errors, statement, entry, tokens, 4, `command option '${commandId}.${tokens[3]}'`);
+    const type = directives.get("type");
+    if (!type) {
+      pushError(errors, `Projection ${statement.id} command option '${commandId}.${tokens[3]}' must include type`, entry.loc);
+    } else if (!CLI_COMMAND_OPTION_TYPES.has(type)) {
+      pushError(errors, `Projection ${statement.id} command option '${commandId}.${tokens[3]}' has invalid type '${type}'`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramRegistry} registry
+ * @param {Set<string>} commandIds
+ * @returns {void}
+ */
+function validateCommandOutputs(errors, statement, registry, commandIds) {
+  for (const entry of blockEntries(getFieldValue(statement, "command_outputs"))) {
+    const tokens = entryTokens(entry);
+    const commandId = tokens[0] === "command" ? tokens[1] : null;
+    if (!commandId || tokens[2] !== "format" || !tokens[3]) {
+      pushError(errors, `Projection ${statement.id} command_outputs entries must use 'command <id> format <format>'`, entry.loc);
+      continue;
+    }
+    if (!commandIds.has(commandId)) {
+      pushError(errors, `Projection ${statement.id} command_outputs references unknown command '${commandId}'`, entry.loc);
+    }
+    const format = tokens[3];
+    if (!CLI_COMMAND_OUTPUT_FORMATS.has(format)) {
+      pushError(errors, `Projection ${statement.id} command output '${commandId}' has invalid format '${format}'`, entry.loc);
+    }
+    const directives = parseDirectives(errors, statement, entry, tokens, 4, `command output '${commandId}'`);
+    const schemaId = directives.get("schema");
+    if (schemaId) {
+      const schema = registry.get(schemaId);
+      if (!schema || schema.kind !== "shape") {
+        pushError(errors, `Projection ${statement.id} command output '${commandId}' references unknown shape '${schemaId}'`, entry.loc);
+      }
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {Set<string>} commandIds
+ * @returns {void}
+ */
+function validateCommandEffects(errors, statement, commandIds) {
+  for (const entry of blockEntries(getFieldValue(statement, "command_effects"))) {
+    const tokens = entryTokens(entry);
+    const commandId = tokens[0] === "command" ? tokens[1] : null;
+    if (!commandId || tokens[2] !== "effect" || !tokens[3]) {
+      pushError(errors, `Projection ${statement.id} command_effects entries must use 'command <id> effect <effect>'`, entry.loc);
+      continue;
+    }
+    if (!commandIds.has(commandId)) {
+      pushError(errors, `Projection ${statement.id} command_effects references unknown command '${commandId}'`, entry.loc);
+    }
+    if (!CLI_COMMAND_EFFECTS.has(tokens[3])) {
+      pushError(errors, `Projection ${statement.id} command effect '${commandId}' has invalid effect '${tokens[3]}'`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {Set<string>} commandIds
+ * @returns {void}
+ */
+function validateCommandExamples(errors, statement, commandIds) {
+  for (const entry of blockEntries(getFieldValue(statement, "command_examples"))) {
+    const tokens = entryTokens(entry);
+    const commandId = tokens[0] === "command" ? tokens[1] : null;
+    if (!commandId || tokens[2] !== "example" || !tokens[3]) {
+      pushError(errors, `Projection ${statement.id} command_examples entries must use 'command <id> example <command-line>'`, entry.loc);
+      continue;
+    }
+    if (!commandIds.has(commandId)) {
+      pushError(errors, `Projection ${statement.id} command_examples references unknown command '${commandId}'`, entry.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+export function validateCliProjection(errors, statement, fieldMap, registry) {
+  if (statement.kind !== "projection") {
+    return;
+  }
+  if (!validateCliOwnership(errors, statement, fieldMap)) {
+    return;
+  }
+  const commandIds = validateCommands(errors, statement, registry);
+  validateCommandOptions(errors, statement, commandIds);
+  validateCommandOutputs(errors, statement, registry, commandIds);
+  validateCommandEffects(errors, statement, commandIds);
+  validateCommandExamples(errors, statement, commandIds);
+}

package/src/validator.d.ts

@@ -1,2 +1,3 @@
 export function formatValidationErrors(validation: any, configPath?: string): string;
 export function validateWorkspace(ast: any): any;
+export * from "./validator/index.js";

package/src/workflows/import-app/shared.js

@@ -6,7 +6,7 @@ import { relativeTo } from "../../path-helpers.js";
 import { canonicalCandidateTerm, idHintify } from "../../text-helpers.js";
 import { listFilesRecursive } from "../shared.js";
 
-export const IMPORT_TRACKS = new Set(["db", "api", "ui", "workflows", "verification"]);
+export const IMPORT_TRACKS = new Set(["db", "api", "ui", "cli", "workflows", "verification"]);
 export const SCALAR_FIELD_TYPES = new Set([
   "bigint",
   "boolean",

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

@@ -30,6 +30,7 @@ export function buildAdoptionPlan(bundles) {
         step.action === "apply_projection_permission_patch" ? "projection_permission_patch" :
         step.action === "apply_projection_auth_patch" ? "projection_auth_patch" :
         step.action === "apply_projection_ownership_patch" ? "projection_ownership_patch" :
+        step.action === "promote_cli_surface" ? "projection" :
         step.action.includes("doc") ? "doc" :
         step.action.includes("decision") ? "decision" :
         step.action.includes("verification") ? "verification" :
@@ -70,6 +71,7 @@ export function buildAdoptionPlan(bundles) {
         item: step.item,
         kind: itemKind,
         track:
+          step.track ? step.track :
           step.action.includes("workflow") ? "workflows" :
           step.action.includes("verification") ? "verification" :
           step.action.includes("ui_") ? "ui" :
@@ -209,4 +211,4 @@ export function buildAdoptionPlan(bundles) {
   );
 }
 
-export const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "widgets", "docs", "journeys", "workflows", "verification", "ui"]);
+export const ADOPT_SELECTORS = new Set(["from-plan", "actors", "roles", "enums", "shapes", "entities", "capabilities", "widgets", "docs", "journeys", "workflows", "verification", "cli", "ui"]);

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

@@ -17,6 +17,8 @@ export function reasonForAdoptionItem(step) {
       return "Promote this imported capability into canonical Topogram.";
     case "promote_widget":
       return "Promote this imported reusable UI widget into canonical Topogram.";
+    case "promote_cli_surface":
+      return "Promote this imported CLI surface projection into canonical Topogram.";
     case "merge_capability_into_existing_entity":
       return `Adopt this capability while preserving the existing canonical entity ${step.target}.`;
     case "promote_doc":
@@ -66,6 +68,9 @@ export function recommendationForAdoptionItem(step) {
   if (step.action === "promote_widget") {
     return "Promote this reviewed widget candidate before binding or reusing it from canonical projections.";
   }
+  if (step.action === "promote_cli_surface") {
+    return "Promote this reviewed CLI surface candidate after confirming commands, options, outputs, and side effects.";
+  }
   if (!["promote_actor", "promote_role"].includes(step.action)) {
     return null;
   }

package/src/workflows/reconcile/bundle-core/index.js

@@ -35,6 +35,7 @@ export function getOrCreateCandidateBundle(bundles, conceptId, label) {
       capabilities: [],
       shapes: [],
       widgets: [],
+      cliSurfaces: [],
       screens: [],
       uiRoutes: [],
       uiActions: [],
@@ -332,6 +333,7 @@ export function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
     `Capabilities: ${bundle.capabilities.length}`,
     `Shapes: ${bundle.shapes.length}`,
     `Widgets: ${bundle.widgets.length}`,
+    `CLI surfaces: ${(bundle.cliSurfaces || []).length}`,
     `Screens: ${bundle.screens.length}`,
     `UI routes: ${bundle.uiRoutes.length}`,
     `UI actions: ${bundle.uiActions.length}`,
@@ -350,6 +352,7 @@ export function renderCandidateBundleReadme(bundle, proposalSurfaces = []) {
     `- Participants: ${summary.participants.label}`,
     `- Main capabilities: ${summarizeBundleSurface(bundle, summary.capabilityIds)}`,
     `- Main widgets: ${summarizeBundleSurface(bundle, summary.widgetIds)}`,
+    `- Main CLI surfaces: ${summarizeBundleSurface(bundle, summary.cliSurfaceIds)}`,
     `- Main screens: ${summarizeBundleSurface(bundle, summary.screenIds)}`,
     `- Main routes: ${summarizeBundleSurface(bundle, summary.routePaths)}`,
     `- Main workflows: ${summarizeBundleSurface(bundle, summary.workflowIds)}`,

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

@@ -18,6 +18,7 @@ import { buildTopogramApiCapabilityIndex, buildBundleDocLinkSuggestions, collect
 import { buildBundleAdoptionPlan, buildCanonicalShapeIndex, buildProjectionEntityIndex, buildProjectionImpacts, buildProjectionPatchCandidates, buildUiImpacts, buildWorkflowImpacts } from "./impacts.js";
 import {
   renderCandidateCapability,
+  renderCandidateCliSurface,
   renderCandidateEntity,
   renderCandidateEnum,
   renderCandidateShape,
@@ -88,6 +89,7 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
   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 cliCandidates = appImport.candidates.cli || { commands: [], capabilities: [], surfaces: [] };
   const docCandidates = appImport.candidates.docs || [];
   const actorCandidates = appImport.candidates.actors || [];
   const roleCandidates = appImport.candidates.roles || [];
@@ -174,6 +176,14 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
       });
     }
   }
+  for (const entry of cliCandidates.capabilities || []) {
+    const bundle = getOrCreateCandidateBundle(bundles, "cli", "CLI");
+    bundle.capabilities.push(entry);
+  }
+  for (const entry of cliCandidates.surfaces || []) {
+    const bundle = getOrCreateCandidateBundle(bundles, "cli", "CLI");
+    bundle.cliSurfaces.push(entry);
+  }
   for (const entry of uiCandidates.screens || []) {
     if (canonicalUi.screens.includes(entry.id_hint)) {
       continue;
@@ -316,6 +326,7 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
       bundle.capabilities.length > 0 ||
       bundle.shapes.length > 0 ||
       bundle.widgets.length > 0 ||
+      bundle.cliSurfaces.length > 0 ||
       bundle.screens.length > 0 ||
       bundle.uiRoutes.length > 0 ||
       bundle.uiActions.length > 0 ||
@@ -334,6 +345,7 @@ export function buildCandidateModelBundles(graph, appImport, topogramRoot) {
         capabilities: bundle.capabilities.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         shapes: bundle.shapes.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id.localeCompare(b.id)),
         widgets: bundle.widgets.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
+        cliSurfaces: bundle.cliSurfaces.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         screens: bundle.screens.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         uiRoutes: bundle.uiRoutes.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
         uiActions: bundle.uiActions.sort((/** @type {any} */ a, /** @type {any} */ b) => a.id_hint.localeCompare(b.id_hint)),
@@ -441,6 +453,9 @@ export function buildCandidateModelFiles(graph, appImport, topogramRoot) {
     for (const entry of bundle.widgets || []) {
       files[`${bundleRoot}/widgets/${entry.id_hint}.tg`] = renderCandidateWidget(entry);
     }
+    for (const entry of bundle.cliSurfaces || []) {
+      files[`${bundleRoot}/projections/${entry.id_hint}.tg`] = renderCandidateCliSurface(entry);
+    }
     for (const entry of bundle.docs) {
       if (entry.existing_canonical) {
         continue;

package/src/workflows/reconcile/gap-report.js

@@ -22,10 +22,11 @@ export function loadImportArtifacts(paths, inputPath) {
   const dbCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "db", "candidates.json"));
   const apiCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "api", "candidates.json"));
   const uiCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "ui", "candidates.json"));
+  const cliCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "cli", "candidates.json"));
   const workflowCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "workflows", "candidates.json"));
   const verificationCandidates = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "app", "verification", "candidates.json"));
   const docsReport = readJsonIfExists(path.join(paths.topogramRoot, "candidates", "docs", "import-report.json"));
-  if (dbCandidates || apiCandidates || uiCandidates || workflowCandidates || verificationCandidates || docsReport) {
+  if (dbCandidates || apiCandidates || uiCandidates || cliCandidates || workflowCandidates || verificationCandidates || docsReport) {
     return {
       type: "import_app_report",
       workspace: paths.workspaceRoot,
@@ -33,6 +34,7 @@ export function loadImportArtifacts(paths, inputPath) {
         db: dbCandidates || { entities: [], enums: [], relations: [], indexes: [] },
         api: apiCandidates || { capabilities: [], routes: [], stacks: [] },
         ui: uiCandidates || { screens: [], routes: [], actions: [], stacks: [] },
+        cli: cliCandidates || { commands: [], capabilities: [], surfaces: [] },
         workflows: workflowCandidates || { workflows: [], workflow_states: [], workflow_transitions: [] },
         verification: verificationCandidates || { verifications: [], scenarios: [], frameworks: [], scripts: [] },
         docs: docsReport?.candidate_docs || [],
@@ -41,7 +43,7 @@ export function loadImportArtifacts(paths, inputPath) {
       }
     };
   }
-  const imported = importAppWorkflow(inputPath, { from: "db,api,ui,workflows,verification" }).summary;
+  const imported = importAppWorkflow(inputPath, { from: "db,api,ui,cli,workflows,verification" }).summary;
   const docsSummary = scanDocsWorkflow(inputPath).summary;
   imported.candidates.docs = docsSummary.candidate_docs || [];
   imported.candidates.actors = docsSummary.candidate_actors || [];

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

@@ -134,6 +134,19 @@ export function buildBundleAdoptionPlan(bundle, canonicalShapeIndex) {
       canonical_rel_path: `widgets/${dashedTopogramId(entry.id_hint)}.tg`
     });
   }
+  for (const entry of bundle.cliSurfaces || []) {
+    steps.push({
+      action: "promote_cli_surface",
+      item: entry.id_hint,
+      target: null,
+      confidence: entry.confidence || "low",
+      inference_summary: entry.inference_summary || null,
+      related_capabilities: [...new Set((entry.command_records || []).map((/** @type {any} */ command) => command.capability_id).filter(Boolean))].sort(),
+      source_path: `candidates/reconcile/model/bundles/${bundle.slug}/projections/${entry.id_hint}.tg`,
+      canonical_rel_path: `projections/${dashedTopogramId(entry.id_hint)}.tg`,
+      track: "cli"
+    });
+  }
   for (const screen of bundle.screens) {
     steps.push({
       action: "promote_ui_report",

package/src/workflows/reconcile/renderers.js

@@ -11,6 +11,11 @@ import {
   formatAuthPermissionHintInline
 } from "./auth.js";
 
+/** @param {string|null|undefined} value @returns {string} */
+function quoteString(value) {
+  return String(value || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
 /** @param {string} fieldType @param {Set<any>} knownEnums @returns {any} */
 export function normalizeCandidateFieldType(fieldType, knownEnums = new Set()) {
   const normalized = idHintify(fieldType);
@@ -145,6 +150,18 @@ export function renderCandidateShape(shapeId, label, fields, sourceKind = null)
 
 /** @param {WorkflowRecord} record @param {any} inputShapeId @param {any} outputShapeId @returns {any} */
 export function renderCandidateCapability(record, inputShapeId, outputShapeId) {
+  if (record.track === "cli" || record.source_kind === "cli_command") {
+    const lines = [
+      `capability ${record.id_hint} {`,
+      `  name "${record.label}"`,
+      `  description "Candidate capability imported from brownfield CLI command evidence"`,
+      "",
+      "  status active",
+      "}"
+    ];
+    return ensureTrailingNewline(`${renderCandidateMetadataComments(record)}\n${lines.join("\n")}`);
+  }
+
   const operationKind = inferCapabilityVerb(record);
   const entityId = inferCapabilityEntityId(record);
   const lines = [
@@ -309,6 +326,71 @@ export function renderCandidateWidget(widget) {
   );
 }
 
+/** @param {WorkflowRecord} surface @returns {any} */
+export function renderCandidateCliSurface(surface) {
+  const commandRecords = surface.command_records || [];
+  const commands = commandRecords.map((/** @type {any} */ command) =>
+    `    command ${command.command_id} capability ${command.capability_id} usage "${quoteString(command.usage)}" mode ${command.mode || "read_only"}`
+  );
+  const options = (surface.options || []).map((/** @type {any} */ option) => {
+    const parts = [
+      `    command ${option.command_id} option ${option.name}`,
+      `type ${option.type || "boolean"}`
+    ];
+    if (option.flag) parts.push(`flag ${option.flag}`);
+    if (option.description) parts.push(`description "${quoteString(option.description)}"`);
+    return parts.join(" ");
+  });
+  const outputs = (surface.outputs || []).map((/** @type {any} */ output) => {
+    const parts = [`    command ${output.command_id} format ${output.format || "human"}`];
+    if (output.schema_id) parts.push(`schema ${output.schema_id}`);
+    if (output.description) parts.push(`description "${quoteString(output.description)}"`);
+    return parts.join(" ");
+  });
+  const effects = (surface.effects || []).map((/** @type {any} */ effect) => {
+    const parts = [`    command ${effect.command_id} effect ${effect.effect || "read_only"}`];
+    if (effect.target) parts.push(`target ${effect.target}`);
+    return parts.join(" ");
+  });
+  const examples = (surface.examples || []).map((/** @type {any} */ example) =>
+    `    command ${example.command_id} example "${quoteString(example.example)}"`
+  );
+  const realizedCapabilities = [...new Set(commandRecords.map((/** @type {any} */ command) => command.capability_id).filter(Boolean))].sort();
+  return ensureTrailingNewline(
+    `${renderCandidateMetadataComments(surface)}\n${[
+      `projection ${surface.id_hint} {`,
+      `  name "${quoteString(surface.label || "CLI Surface")}"`,
+      '  description "Candidate CLI surface inferred from imported command usage. Review commands, options, outputs, and side effects before adoption."',
+      "  type cli_surface",
+      `  realizes [${realizedCapabilities.join(", ")}]`,
+      "  outputs [maintained_app]",
+      "",
+      "  commands {",
+      ...commands,
+      "  }",
+      "",
+      "  command_options {",
+      ...options,
+      "  }",
+      "",
+      "  command_outputs {",
+      ...outputs,
+      "  }",
+      "",
+      "  command_effects {",
+      ...effects,
+      "  }",
+      "",
+      "  command_examples {",
+      ...examples,
+      "  }",
+      "",
+      "  status proposed",
+      "}"
+    ].join("\n")}`
+  );
+}
+
 /** @param {WorkflowRecord} patch @returns {any} */
 export function renderProjectionPatchDoc(patch) {
   const lines = [

package/src/workflows/reconcile/summary.js

@@ -33,6 +33,7 @@ export function buildBundleOperatorSummary(bundle) {
   const primaryConcept =
     primaryEntityId ||
     bundle.capabilities?.[0]?.id_hint ||
+    bundle.cliSurfaces?.[0]?.id_hint ||
     bundle.workflows?.[0]?.id_hint ||
     bundle.screens?.[0]?.id_hint ||
     bundle.enums?.[0]?.id_hint ||
@@ -40,6 +41,7 @@ export function buildBundleOperatorSummary(bundle) {
   const participants = summarizeBundleParticipants(bundle);
   const capabilityIds = [...new Set((bundle.capabilities || []).map((/** @type {any} */ entry) => entry.id_hint))].slice(0, 4);
   const widgetIds = [...new Set((bundle.widgets || []).map((/** @type {any} */ entry) => entry.id_hint))].slice(0, 4);
+  const cliSurfaceIds = [...new Set((bundle.cliSurfaces || []).map((/** @type {any} */ entry) => entry.id_hint))].slice(0, 4);
   const screenIds = [...new Set((bundle.screens || []).map((/** @type {any} */ entry) => entry.id_hint))].slice(0, 4);
   const routePaths = [...new Set((bundle.uiRoutes || []).map((/** @type {any} */ entry) => entry.path).filter(Boolean))].slice(0, 4);
   const workflowIds = [...new Set((bundle.workflows || []).map((/** @type {any} */ entry) => entry.id_hint))].slice(0, 4);
@@ -55,6 +57,7 @@ export function buildBundleOperatorSummary(bundle) {
   const evidenceKinds = [
     (bundle.entities || []).length > 0 ? "entity evidence" : null,
     (bundle.capabilities || []).length > 0 ? "API capability evidence" : null,
+    (bundle.cliSurfaces || []).length > 0 ? "CLI surface evidence" : null,
     (bundle.widgets || []).length > 0 ? "UI widget evidence" : null,
     (bundle.screens || []).length > 0 || (bundle.uiRoutes || []).length > 0 ? "UI screen/route evidence" : null,
     (bundle.workflows || []).length > 0 ? "workflow evidence" : null,
@@ -72,6 +75,7 @@ export function buildBundleOperatorSummary(bundle) {
     participants,
     capabilityIds,
     widgetIds,
+    cliSurfaceIds,
     screenIds,
     routePaths,
     workflowIds,

package/src/workflows/reconcile/workflow.js

@@ -259,6 +259,7 @@ export function reconcileWorkflow(inputPath, options = {}) {
       capabilities: bundle.capabilities.map((/** @type {any} */ entry) => entry.id_hint),
       shapes: bundle.shapes.map((/** @type {any} */ entry) => entry.id),
       widgets: bundle.widgets.map((/** @type {any} */ entry) => entry.id_hint),
+      cli_surfaces: (bundle.cliSurfaces || []).map((/** @type {any} */ entry) => entry.id_hint),
       screens: bundle.screens.map((/** @type {any} */ entry) => entry.id_hint),
       workflows: bundle.workflows.map((/** @type {any} */ entry) => entry.id_hint),
       docs: bundle.docs.map((/** @type {any} */ entry) => entry.id),
@@ -282,7 +283,7 @@ export function reconcileWorkflow(inputPath, options = {}) {
     : "## Promoted Canonical Items";
   files["candidates/reconcile/report.json"] = `${stableStringify(report)}\n`;
   const candidateModelBundlesMarkdown = report.candidate_model_bundles.length
-    ? report.candidate_model_bundles.map((/** @type {any} */ bundle) => `- \`${bundle.slug}\` (${bundle.actors.length} actors, ${bundle.roles.length} roles, ${bundle.entities.length} entities, ${bundle.enums.length} enums, ${bundle.capabilities.length} capabilities, ${bundle.shapes.length} shapes, ${bundle.widgets.length} widgets, ${bundle.screens.length} screens, ${bundle.workflows.length} workflows, ${bundle.docs.length} docs)
+    ? report.candidate_model_bundles.map((/** @type {any} */ bundle) => `- \`${bundle.slug}\` (${bundle.actors.length} actors, ${bundle.roles.length} roles, ${bundle.entities.length} entities, ${bundle.enums.length} enums, ${bundle.capabilities.length} capabilities, ${bundle.shapes.length} shapes, ${bundle.widgets.length} widgets, ${bundle.cli_surfaces.length} CLI surfaces, ${bundle.screens.length} screens, ${bundle.workflows.length} workflows, ${bundle.docs.length} docs)
   - primary concept \`${bundle.operator_summary.primaryConcept}\`${bundle.operator_summary.primaryEntityId ? `, primary entity \`${bundle.operator_summary.primaryEntityId}\`` : ""}
   - participants ${bundle.operator_summary.participants.label}
   - main capabilities ${summarizeBundleSurface(bundle, bundle.operator_summary.capabilityIds)}