@topogram/cli 0.3.78 → 0.3.80

package/src/package-adapters/spec.js

@@ -0,0 +1,51 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} spec
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function isPathSpec(spec, cwd) {
+  return spec.startsWith(".") || spec.startsWith("/") || fs.existsSync(path.resolve(cwd, spec));
+}
+
+/**
+ * @param {string} spec
+ * @returns {string}
+ */
+export function packageNameFromSpec(spec) {
+  if (spec.startsWith("@")) {
+    const versionIndex = spec.indexOf("@", 1);
+    return versionIndex > 0 ? spec.slice(0, versionIndex) : spec;
+  }
+  const versionIndex = spec.indexOf("@");
+  return versionIndex > 0 ? spec.slice(0, versionIndex) : spec;
+}
+
+/**
+ * @param {string|null|undefined} rootDir
+ * @returns {string}
+ */
+export function packageResolutionBase(rootDir) {
+  return path.join(rootDir || process.cwd(), "package.json");
+}
+
+/**
+ * @param {string|null|undefined} packageName
+ * @returns {string|null}
+ */
+export function packageInstallCommand(packageName) {
+  return packageName ? `npm install -D ${packageName}` : null;
+}
+
+/**
+ * @param {string|null|undefined} packageName
+ * @returns {string|null}
+ */
+export function packageInstallHint(packageName) {
+  const command = packageInstallCommand(packageName);
+  return command ? `Install it from the project root with: ${command}` : null;
+}

package/src/reconcile/journeys.js

@@ -28,9 +28,11 @@ function primaryEntityIdForBundle(bundle) {
 
 function canonicalJourneyCoverage(graph) {
   const journeyDocs = (graph?.docs || []).filter((doc) => doc.kind === "journey");
+  const journeyStatements = graph?.byKind?.journey || [];
+  const journeys = [...journeyStatements, ...journeyDocs];
   return {
-    byEntityId: new Set(journeyDocs.flatMap((doc) => doc.relatedEntities || [])),
-    byCapabilityId: new Set(journeyDocs.flatMap((doc) => doc.relatedCapabilities || []))
+    byEntityId: new Set(journeys.flatMap((journey) => journey.relatedEntities || [])),
+    byCapabilityId: new Set(journeys.flatMap((journey) => journey.relatedCapabilities || []))
   };
 }
 
@@ -42,7 +44,10 @@ function collectJourneyGenerationContext(graph) {
   const uiSharedScreens = projections
     .filter((projection) => projection.type === "ui_contract")
     .flatMap((projection) => (projection.uiScreens || []).map((screen) => ({ ...screen, projectionId: projection.id })));
-  const canonicalJourneys = (graph.docs || []).filter((doc) => doc.kind === "journey");
+  const canonicalJourneys = [
+    ...(graph.byKind?.journey || []),
+    ...(graph.docs || []).filter((doc) => doc.kind === "journey")
+  ];
   const coveredEntityIds = new Set(canonicalJourneys.flatMap((doc) => doc.relatedEntities || []));
 
   return entities

package/src/record-blocks.js

@@ -0,0 +1,125 @@
+// @ts-check
+
+/**
+ * @typedef {{
+ *   key: string,
+ *   value: import("./parser.js").AstValue | null,
+ *   values: import("./parser.js").AstValue[],
+ *   loc: import("./parser.js").AstLocation
+ * }} TopogramRecordField
+ *
+ * @typedef {{
+ *   fields: Map<string, TopogramRecordField[]>,
+ *   fieldOrder: TopogramRecordField[],
+ *   loc: import("./parser.js").AstLocation
+ * }} TopogramRecordBlock
+ */
+
+/**
+ * @param {import("./parser.js").AstValue[]} values
+ * @param {import("./parser.js").AstLocation} loc
+ * @returns {import("./parser.js").AstValue | null}
+ */
+function valuesToRecordValue(values, loc) {
+  if (values.length === 0) {
+    return null;
+  }
+  if (values.length === 1) {
+    return values[0];
+  }
+  return {
+    type: "sequence",
+    items: values,
+    loc
+  };
+}
+
+/**
+ * @param {import("./parser.js").AstBlock} block
+ * @returns {TopogramRecordBlock}
+ */
+export function parseRecordBlock(block) {
+  /** @type {Map<string, TopogramRecordField[]>} */
+  const fields = new Map();
+  /** @type {TopogramRecordField[]} */
+  const fieldOrder = [];
+
+  for (const entry of block.entries || []) {
+    const [keyToken, ...values] = entry.items || [];
+    const key = keyToken?.type === "symbol" ? keyToken.value : "";
+    const field = {
+      key,
+      value: valuesToRecordValue(values, entry.loc),
+      values,
+      loc: entry.loc
+    };
+    if (!fields.has(key)) {
+      fields.set(key, []);
+    }
+    fields.get(key)?.push(field);
+    fieldOrder.push(field);
+  }
+
+  return {
+    fields,
+    fieldOrder,
+    loc: block.loc
+  };
+}
+
+/**
+ * @param {TopogramRecordBlock} record
+ * @param {string} key
+ * @returns {TopogramRecordField | null}
+ */
+export function recordField(record, key) {
+  return record.fields.get(key)?.[0] || null;
+}
+
+/**
+ * @param {TopogramRecordBlock} record
+ * @param {string} key
+ * @returns {string | null}
+ */
+export function recordSymbol(record, key) {
+  const value = recordField(record, key)?.value;
+  return value?.type === "symbol" ? value.value : null;
+}
+
+/**
+ * @param {TopogramRecordBlock} record
+ * @param {string} key
+ * @returns {string | null}
+ */
+export function recordString(record, key) {
+  const value = recordField(record, key)?.value;
+  return value?.type === "string" ? value.value : null;
+}
+
+/**
+ * @param {TopogramRecordBlock} record
+ * @param {string} key
+ * @returns {string[]}
+ */
+export function recordStringList(record, key) {
+  const value = recordField(record, key)?.value;
+  if (!value) return [];
+  const items = value.type === "list" ? value.items : value.type === "sequence" ? value.items : [value];
+  return items
+    .map((item) => item.type === "string" ? item.value : null)
+    .filter(/** @param {string | null} value */ (value) => value !== null);
+}
+
+/**
+ * @param {TopogramRecordBlock} record
+ * @param {string} key
+ * @returns {string[]}
+ */
+export function recordSymbolList(record, key) {
+  const value = recordField(record, key)?.value;
+  if (!value) return [];
+  const items = value.type === "list" ? value.items : value.type === "sequence" ? value.items : [value];
+  return items
+    .map((item) => item.type === "symbol" ? item.value : null)
+    .filter(/** @param {string | null} value */ (value) => value !== null);
+}

package/src/resolver/index.js

@@ -111,6 +111,7 @@ export function resolveWorkspace(workspaceAst) {
         orchestrations: [],
         operations: [],
         decisions: [],
+        journeys: [],
         pitches: [],
         requirements: [],
         tasks: [],
@@ -128,6 +129,7 @@ export function resolveWorkspace(workspaceAst) {
     orchestration: "orchestrations",
     operation: "operations",
     decision: "decisions",
+    journey: "journeys",
     pitch: "pitches",
     requirement: "requirements",
     task: "tasks",
@@ -321,6 +323,7 @@ export function resolveWorkspace(workspaceAst) {
             orchestrations: [],
             operations: [],
             decisions: [],
+            journeys: [],
             pitches: [],
             requirements: [],
             tasks: [],

package/src/resolver/journeys.js

@@ -0,0 +1,74 @@
+// @ts-check
+
+import {
+  parseRecordBlock,
+  recordString,
+  recordStringList,
+  recordSymbol,
+  recordSymbolList
+} from "../record-blocks.js";
+
+/**
+ * @param {import("../parser.js").AstStatement} statement
+ * @param {string} key
+ * @returns {import("../parser.js").AstField[]}
+ */
+function fieldsByKey(statement, key) {
+  return statement.fields.filter((field) => field.key === key);
+}
+
+/**
+ * @param {import("../parser.js").AstField} field
+ * @returns {any}
+ */
+function parseStepField(field) {
+  if (field.value.type !== "block") {
+    return null;
+  }
+  const record = parseRecordBlock(field.value);
+  return {
+    id: recordSymbol(record, "id"),
+    intent: recordString(record, "intent"),
+    commands: recordStringList(record, "commands"),
+    expects: recordStringList(record, "expects"),
+    after: recordSymbolList(record, "after"),
+    notes: recordString(record, "notes"),
+    loc: field.loc
+  };
+}
+
+/**
+ * @param {import("../parser.js").AstField} field
+ * @returns {any}
+ */
+function parseAlternateField(field) {
+  if (field.value.type !== "block") {
+    return null;
+  }
+  const record = parseRecordBlock(field.value);
+  return {
+    id: recordSymbol(record, "id"),
+    from: recordSymbol(record, "from"),
+    condition: recordString(record, "condition"),
+    commands: recordStringList(record, "commands"),
+    expects: recordStringList(record, "expects"),
+    notes: recordString(record, "notes"),
+    loc: field.loc
+  };
+}
+
+/**
+ * @param {import("../parser.js").AstStatement} statement
+ * @returns {any[]}
+ */
+export function parseJourneySteps(statement) {
+  return fieldsByKey(statement, "step").map(parseStepField).filter(Boolean);
+}
+
+/**
+ * @param {import("../parser.js").AstStatement} statement
+ * @returns {any[]}
+ */
+export function parseJourneyAlternates(statement) {
+  return fieldsByKey(statement, "alternate").map(parseAlternateField).filter(Boolean);
+}

package/src/resolver/normalize.js

@@ -75,6 +75,7 @@ import {
   parseProjectionGeneratorDefaultsBlock
 } from "./projections-db.js";
 import { parsePlanSteps } from "../sdlc/plan-steps.js";
+import { parseJourneyAlternates, parseJourneySteps } from "./journeys.js";
 
 export function normalizeStatement(statement, registry) {
   const fieldMap = collectFieldMap(statement);
@@ -308,6 +309,30 @@ export function normalizeStatement(statement, registry) {
           : null,
         aliases: normalizeDomainScopeList(statement, "aliases")
       };
+    case "journey":
+      return {
+        ...base,
+        actors: symbolValues(getFieldValue(statement, "actors")),
+        roles: symbolValues(getFieldValue(statement, "roles")),
+        goal: stringValue(getFieldValue(statement, "goal")),
+        trigger: stringValue(getFieldValue(statement, "trigger")),
+        steps: parseJourneySteps(statement),
+        alternates: parseJourneyAlternates(statement),
+        successSignals: normalizeDomainScopeList(statement, "success_signals"),
+        failureSignals: normalizeDomainScopeList(statement, "failure_signals"),
+        relatedCapabilities: symbolValues(getFieldValue(statement, "related_capabilities")),
+        relatedEntities: symbolValues(getFieldValue(statement, "related_entities")),
+        relatedRules: symbolValues(getFieldValue(statement, "related_rules")),
+        relatedWorkflows: symbolValues(getFieldValue(statement, "related_workflows")),
+        relatedProjections: symbolValues(getFieldValue(statement, "related_projections")),
+        relatedWidgets: symbolValues(getFieldValue(statement, "related_widgets")),
+        relatedVerifications: symbolValues(getFieldValue(statement, "related_verifications")),
+        relatedDecisions: symbolValues(getFieldValue(statement, "related_decisions")),
+        relatedDocs: symbolValues(getFieldValue(statement, "related_docs")),
+        tags: normalizeDomainScopeList(statement, "tags"),
+        updated: stringValue(getFieldValue(statement, "updated")),
+        resolvedDomain: resolveDomainTag(statement, registry)
+      };
     case "pitch":
       return {
         ...base,

package/src/sdlc/adopt.js

@@ -55,7 +55,7 @@ function scanPressure(root) {
 export function sdlcAdopt(workspaceRoot) {
   const root = path.resolve(workspaceRoot);
   if (!existsSync(resolveTopoRoot(root))) {
-    return { ok: false, error: `No '${DEFAULT_TOPO_FOLDER_NAME}/' workspace folder at ${root}; run 'topogram new' first` };
+    return { ok: false, error: `No '${DEFAULT_TOPO_FOLDER_NAME}/' workspace folder at ${root}; run 'topogram init' or 'topogram copy' first` };
   }
   const folders = SDLC_FOLDERS.map((name) => ensureFolder(root, name));
   const pressure = scanPressure(root);

package/src/validator/common.js

@@ -205,6 +205,8 @@ function validateFieldShapes(errors, statement, fieldMap) {
   ensureSingleValueField(errors, statement, fieldMap, "updated", ["string"]);
   ensureSingleValueField(errors, statement, fieldMap, "notes", ["string"]);
   ensureSingleValueField(errors, statement, fieldMap, "outcome", ["string"]);
+  ensureSingleValueField(errors, statement, fieldMap, "goal", ["string"]);
+  ensureSingleValueField(errors, statement, fieldMap, "trigger", ["string"]);
 
   const listFields = [
     "aliases",
@@ -238,7 +240,19 @@ function validateFieldShapes(errors, statement, fieldMap) {
     "regions",
     "lookups",
     "dependencies",
-    "approvals"
+    "approvals",
+    "success_signals",
+    "failure_signals",
+    "tags",
+    "related_capabilities",
+    "related_entities",
+    "related_rules",
+    "related_workflows",
+    "related_projections",
+    "related_widgets",
+    "related_verifications",
+    "related_decisions",
+    "related_docs"
   ];
   if (statement.kind === "orchestration") {
     listFields.push("steps");
@@ -251,6 +265,16 @@ function validateFieldShapes(errors, statement, fieldMap) {
   if (statement.kind === "plan") {
     blockFields.push("steps");
   }
+  if (statement.kind === "journey") {
+    for (const key of ["step", "alternate"]) {
+      const fields = fieldMap.get(key) || [];
+      for (const field of fields) {
+        if (field.value.type !== "block") {
+          pushError(errors, `Field '${key}' on ${statement.kind} ${statement.id} must be block, found ${field.value.type}`, field.loc);
+        }
+      }
+    }
+  }
   for (const key of blockFields) {
     ensureSingleValueField(errors, statement, fieldMap, key, ["block"]);
   }
@@ -429,6 +453,15 @@ function validateReferenceKinds(errors, statement, fieldMap, registry) {
     requirement: null,
     from_requirement: ["requirement"],
     affects: ["capability", "entity", "rule", "projection", "widget", "orchestration", "operation"],
+    related_capabilities: ["capability"],
+    related_entities: ["entity"],
+    related_rules: ["rule"],
+    related_workflows: null,
+    related_projections: ["projection"],
+    related_widgets: ["widget"],
+    related_verifications: ["verification"],
+    related_decisions: ["decision"],
+    related_docs: null,
     introduces_rules: ["rule"],
     respects_rules: ["rule"],
     decisions: ["decision"],

package/src/validator/index.js

@@ -20,6 +20,7 @@ import { validateAcceptanceCriterion } from "./per-kind/acceptance-criterion.js"
 import { validateTask } from "./per-kind/task.js";
 import { validatePlan } from "./per-kind/plan.js";
 import { validateBug } from "./per-kind/bug.js";
+import { validateJourney } from "./per-kind/journey.js";
 
 export {
   STATEMENT_KINDS,
@@ -32,6 +33,7 @@ export {
   TASK_IDENTIFIER_PATTERN,
   PLAN_IDENTIFIER_PATTERN,
   BUG_IDENTIFIER_PATTERN,
+  JOURNEY_IDENTIFIER_PATTERN,
   DOCUMENT_IDENTIFIER_PATTERN,
   GLOBAL_STATUSES,
   DECISION_STATUSES,
@@ -48,6 +50,7 @@ export {
   PLAN_STATUSES,
   PLAN_STEP_STATUSES,
   BUG_STATUSES,
+  JOURNEY_STATUSES,
   PRIORITY_VALUES,
   WORK_TYPES,
   BUG_SEVERITIES,
@@ -112,6 +115,7 @@ export function validateWorkspace(workspaceAst) {
       validateTask(errors, statement, fieldMap, registry);
       validatePlan(errors, statement, fieldMap, registry);
       validateBug(errors, statement, fieldMap, registry);
+      validateJourney(errors, statement, fieldMap, registry);
       validateExpressions(errors, statement, fieldMap);
     }
   }

package/src/validator/kinds.d.ts

@@ -8,6 +8,7 @@ export const ACCEPTANCE_CRITERION_IDENTIFIER_PATTERN: RegExp;
 export const TASK_IDENTIFIER_PATTERN: RegExp;
 export const PLAN_IDENTIFIER_PATTERN: RegExp;
 export const BUG_IDENTIFIER_PATTERN: RegExp;
+export const JOURNEY_IDENTIFIER_PATTERN: RegExp;
 export const DOCUMENT_IDENTIFIER_PATTERN: RegExp;
 export const GLOBAL_STATUSES: Set<string>;
 export const DECISION_STATUSES: Set<string>;
@@ -25,6 +26,7 @@ export const TASK_DISPOSITIONS: Set<string>;
 export const PLAN_STATUSES: Set<string>;
 export const PLAN_STEP_STATUSES: Set<string>;
 export const BUG_STATUSES: Set<string>;
+export const JOURNEY_STATUSES: Set<string>;
 export const PRIORITY_VALUES: Set<string>;
 export const WORK_TYPES: Set<string>;
 export const BUG_SEVERITIES: Set<string>;

package/src/validator/kinds.js

@@ -16,6 +16,7 @@ export const STATEMENT_KINDS = new Set([
   "verification",
   "operation",
   "domain",
+  "journey",
   "pitch",
   "requirement",
   "acceptance_criterion",
@@ -32,6 +33,7 @@ export const ACCEPTANCE_CRITERION_IDENTIFIER_PATTERN = /^ac_[a-z][a-z0-9_]*$/;
 export const TASK_IDENTIFIER_PATTERN = /^task_[a-z][a-z0-9_]*$/;
 export const PLAN_IDENTIFIER_PATTERN = /^plan_[a-z][a-z0-9_]*$/;
 export const BUG_IDENTIFIER_PATTERN = /^bug_[a-z][a-z0-9_]*$/;
+export const JOURNEY_IDENTIFIER_PATTERN = /^journey_[a-z][a-z0-9_]*$/;
 export const DOCUMENT_IDENTIFIER_PATTERN = /^doc_[a-z][a-z0-9_]*$/;
 
 export const GLOBAL_STATUSES = new Set(["draft", "proposed", "active", "deprecated"]);
@@ -46,6 +48,7 @@ export const TASK_STATUSES = new Set(["unclaimed", "claimed", "in-progress", "do
 export const PLAN_STATUSES = new Set(["draft", "active", "complete", "superseded"]);
 export const PLAN_STEP_STATUSES = new Set(["pending", "in-progress", "blocked", "done", "skipped"]);
 export const BUG_STATUSES = new Set(["open", "in-progress", "fixed", "verified", "wont-fix"]);
+export const JOURNEY_STATUSES = new Set(["draft", "canonical", "active", "deprecated"]);
 export const TASK_DISPOSITIONS = new Set(["active", "follow_up", "deferred", "backlog", "blocker"]);
 
 export const PRIORITY_VALUES = new Set(["critical", "high", "medium", "low"]);
@@ -79,7 +82,8 @@ export const STATUS_SETS_BY_KIND = {
   acceptance_criterion: ACCEPTANCE_CRITERION_STATUSES,
   task: TASK_STATUSES,
   plan: PLAN_STATUSES,
-  bug: BUG_STATUSES
+  bug: BUG_STATUSES,
+  journey: JOURNEY_STATUSES
 };
 export const VERIFICATION_METHODS = new Set(["smoke", "runtime", "contract", "journey", "manual"]);
 export const CLI_COMMAND_EFFECTS = new Set(["read_only", "writes_workspace", "writes_app", "network", "package_install", "git", "filesystem"]);
@@ -120,6 +124,7 @@ export const DOMAIN_TAGGABLE_KINDS = new Set([
   "orchestration",
   "operation",
   "decision",
+  "journey",
   "pitch",
   "requirement",
   "task",
@@ -244,6 +249,34 @@ export const FIELD_SPECS = {
     required: ["name", "description", "status"],
     allowed: ["name", "description", "in_scope", "out_of_scope", "owners", "parent_domain", "aliases", "status"]
   },
+  journey: {
+    required: ["name", "description", "status", "actors", "goal", "step"],
+    allowed: [
+      "name",
+      "description",
+      "status",
+      "actors",
+      "roles",
+      "goal",
+      "trigger",
+      "step",
+      "alternate",
+      "success_signals",
+      "failure_signals",
+      "related_capabilities",
+      "related_entities",
+      "related_rules",
+      "related_workflows",
+      "related_projections",
+      "related_widgets",
+      "related_verifications",
+      "related_decisions",
+      "related_docs",
+      "tags",
+      "domain",
+      "updated"
+    ]
+  },
   pitch: {
     required: ["name", "description", "status", "priority"],
     allowed: [