@topogram/cli 0.3.77 → 0.3.79

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: [

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

@@ -0,0 +1,233 @@
+// @ts-check
+
+import {
+  JOURNEY_IDENTIFIER_PATTERN
+} from "../kinds.js";
+import {
+  pushError
+} from "../utils.js";
+import {
+  parseRecordBlock,
+  recordField,
+  recordString,
+  recordStringList,
+  recordSymbol,
+  recordSymbolList
+} from "../../record-blocks.js";
+
+const STEP_FIELDS = new Set(["id", "intent", "commands", "expects", "after", "notes"]);
+const ALTERNATE_FIELDS = new Set(["id", "from", "condition", "commands", "expects", "notes"]);
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @returns {void}
+ */
+function validateJourneyIdentifier(errors, statement) {
+  if (!JOURNEY_IDENTIFIER_PATTERN.test(statement.id)) {
+    pushError(
+      errors,
+      `Journey identifier '${statement.id}' must match ${JOURNEY_IDENTIFIER_PATTERN.source}`,
+      statement.loc
+    );
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramField} field
+ * @param {Set<string>} allowedFields
+ * @param {string[]} requiredFields
+ * @returns {import("../../record-blocks.js").TopogramRecordBlock | null}
+ */
+function validateRecordBlock(errors, statement, field, allowedFields, requiredFields) {
+  if (field.value.type !== "block") {
+    pushError(errors, `Field '${field.key}' on journey ${statement.id} must be a block`, field.loc);
+    return null;
+  }
+
+  const record = parseRecordBlock(/** @type {import("../../parser.js").AstBlock} */ (/** @type {unknown} */ (field.value)));
+  for (const recordFieldEntry of record.fieldOrder) {
+    if (!recordFieldEntry.key) {
+      pushError(errors, `Each '${field.key}' record entry on journey ${statement.id} must start with a field name`, recordFieldEntry.loc);
+      continue;
+    }
+    if (!allowedFields.has(recordFieldEntry.key)) {
+      pushError(errors, `Unsupported '${field.key}' field '${recordFieldEntry.key}' on journey ${statement.id}`, recordFieldEntry.loc);
+    }
+    const entries = record.fields.get(recordFieldEntry.key) || [];
+    if (entries.length > 1 && entries[1] === recordFieldEntry) {
+      pushError(errors, `Duplicate '${field.key}' field '${recordFieldEntry.key}' on journey ${statement.id}`, recordFieldEntry.loc);
+    }
+  }
+
+  for (const required of requiredFields) {
+    if (!record.fields.has(required)) {
+      pushError(errors, `Journey ${statement.id} ${field.key} record requires '${required}'`, field.loc);
+    }
+  }
+
+  return record;
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {import("../../record-blocks.js").TopogramRecordBlock} record
+ * @param {string} fieldName
+ * @param {"symbol" | "string" | "symbol_list" | "string_list"} expected
+ * @returns {void}
+ */
+function validateRecordFieldShape(errors, statement, record, fieldName, expected) {
+  const field = recordField(record, fieldName);
+  if (!field || !field.value) return;
+  if (expected === "symbol" && field.value.type !== "symbol") {
+    pushError(errors, `Journey ${statement.id} record field '${fieldName}' must be a symbol`, field.loc);
+  }
+  if (expected === "string" && field.value.type !== "string") {
+    pushError(errors, `Journey ${statement.id} record field '${fieldName}' must be a string`, field.loc);
+  }
+  if (expected === "symbol_list" && field.value.type !== "list") {
+    pushError(errors, `Journey ${statement.id} record field '${fieldName}' must be a list of symbols`, field.loc);
+  }
+  if (expected === "string_list" && field.value.type !== "list") {
+    pushError(errors, `Journey ${statement.id} record field '${fieldName}' must be a list of strings`, field.loc);
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @returns {Set<string>}
+ */
+function validateStepRecords(errors, statement, fieldMap) {
+  const fields = fieldMap.get("step") || [];
+  /** @type {Set<string>} */
+  const stepIds = new Set();
+  if (fields.length === 0) {
+    pushError(errors, `Journey ${statement.id} must include at least one step`, statement.loc);
+    return stepIds;
+  }
+
+  for (const field of fields) {
+    const record = validateRecordBlock(errors, statement, field, STEP_FIELDS, ["id", "intent"]);
+    if (!record) continue;
+    validateRecordFieldShape(errors, statement, record, "id", "symbol");
+    validateRecordFieldShape(errors, statement, record, "intent", "string");
+    validateRecordFieldShape(errors, statement, record, "commands", "string_list");
+    validateRecordFieldShape(errors, statement, record, "expects", "string_list");
+    validateRecordFieldShape(errors, statement, record, "after", "symbol_list");
+    validateRecordFieldShape(errors, statement, record, "notes", "string");
+
+    const stepId = recordSymbol(record, "id");
+    if (!stepId) continue;
+    if (!/^[a-z][a-z0-9_]*$/.test(stepId)) {
+      pushError(errors, `Journey ${statement.id} step id must match /^[a-z][a-z0-9_]*$/`, recordField(record, "id")?.loc || field.loc);
+    }
+    if (stepIds.has(stepId)) {
+      pushError(errors, `Journey ${statement.id} has duplicate step '${stepId}'`, recordField(record, "id")?.loc || field.loc);
+    }
+    stepIds.add(stepId);
+  }
+
+  for (const field of fields) {
+    if (field.value.type !== "block") continue;
+    const record = parseRecordBlock(/** @type {import("../../parser.js").AstBlock} */ (/** @type {unknown} */ (field.value)));
+    const stepId = recordSymbol(record, "id") || "unknown";
+    for (const afterId of recordSymbolList(record, "after")) {
+      if (!stepIds.has(afterId)) {
+        pushError(errors, `Journey ${statement.id} step '${stepId}' after references missing step '${afterId}'`, recordField(record, "after")?.loc || field.loc);
+      }
+    }
+  }
+
+  return stepIds;
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {Set<string>} stepIds
+ * @returns {void}
+ */
+function validateAlternateRecords(errors, statement, fieldMap, stepIds) {
+  const fields = fieldMap.get("alternate") || [];
+  /** @type {Set<string>} */
+  const alternateIds = new Set();
+  for (const field of fields) {
+    const record = validateRecordBlock(errors, statement, field, ALTERNATE_FIELDS, ["id", "from", "condition"]);
+    if (!record) continue;
+    validateRecordFieldShape(errors, statement, record, "id", "symbol");
+    validateRecordFieldShape(errors, statement, record, "from", "symbol");
+    validateRecordFieldShape(errors, statement, record, "condition", "string");
+    validateRecordFieldShape(errors, statement, record, "commands", "string_list");
+    validateRecordFieldShape(errors, statement, record, "expects", "string_list");
+    validateRecordFieldShape(errors, statement, record, "notes", "string");
+
+    const alternateId = recordSymbol(record, "id");
+    if (alternateId) {
+      if (!/^[a-z][a-z0-9_]*$/.test(alternateId)) {
+        pushError(errors, `Journey ${statement.id} alternate id must match /^[a-z][a-z0-9_]*$/`, recordField(record, "id")?.loc || field.loc);
+      }
+      if (alternateIds.has(alternateId)) {
+        pushError(errors, `Journey ${statement.id} has duplicate alternate '${alternateId}'`, recordField(record, "id")?.loc || field.loc);
+      }
+      alternateIds.add(alternateId);
+    }
+
+    const fromStep = recordSymbol(record, "from");
+    if (fromStep && !stepIds.has(fromStep)) {
+      pushError(errors, `Journey ${statement.id} alternate '${alternateId || "unknown"}' from references missing step '${fromStep}'`, recordField(record, "from")?.loc || field.loc);
+    }
+  }
+}
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @returns {void}
+ */
+function validateTopLevelListShapes(errors, statement, fieldMap) {
+  const stringListFields = ["success_signals", "failure_signals", "tags"];
+  for (const key of stringListFields) {
+    const field = fieldMap.get(key)?.[0];
+    if (!field || field.value.type !== "list") continue;
+    for (const item of field.value.items) {
+      if (item.type !== "string" && key !== "tags") {
+        pushError(errors, `Journey ${statement.id} field '${key}' must contain strings`, item.loc);
+      }
+      if (key === "tags" && item.type !== "symbol" && item.type !== "string") {
+        pushError(errors, `Journey ${statement.id} field '${key}' must contain symbols or strings`, item.loc);
+      }
+    }
+  }
+}
+
+/**
+ * Keep referenced imports used by checkJs while making the expected record
+ * helper vocabulary obvious to future validators.
+ */
+void recordString;
+void recordStringList;
+
+/**
+ * @param {ValidationErrors} errors
+ * @param {TopogramStatement} statement
+ * @param {TopogramFieldMap} fieldMap
+ * @param {TopogramRegistry} registry
+ * @returns {void}
+ */
+export function validateJourney(errors, statement, fieldMap, registry) {
+  void registry;
+  if (statement.kind !== "journey") {
+    return;
+  }
+  validateJourneyIdentifier(errors, statement);
+  validateTopLevelListShapes(errors, statement, fieldMap);
+  const stepIds = validateStepRecords(errors, statement, fieldMap);
+  validateAlternateRecords(errors, statement, fieldMap, stepIds);
+}

package/src/workflows/docs-generate.js

@@ -215,7 +215,10 @@ export function generateDocsWorkflow(inputPath) {
 export function generateJourneyDraftsWorkflow(inputPath) {
   const paths = normalizeWorkspacePaths(inputPath);
   const graph = loadResolvedGraph(paths.topogramRoot);
-  const canonicalJourneys = (graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "journey");
+  const canonicalJourneys = [
+    ...(graph.byKind?.journey || []),
+    ...(graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "journey")
+  ];
   const { drafts, skippedEntities } = buildJourneyDraftsReconcile(graph);
   /** @type {WorkflowFiles} */
   /** @type {WorkflowFiles} */

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

@@ -62,9 +62,11 @@ export function bundleLabelFromConceptId(conceptId) {
 /** @param {ResolvedGraph} graph @returns {any} */
 export function canonicalJourneyCoverage(graph) {
   const journeyDocs = (graph?.docs || []).filter((/** @type {any} */ doc) => doc.kind === "journey");
+  const journeyStatements = graph?.byKind?.journey || [];
+  const journeys = [...journeyStatements, ...journeyDocs];
   return {
-    byEntityId: new Set(journeyDocs.flatMap((/** @type {any} */ doc) => doc.relatedEntities || [])),
-    byCapabilityId: new Set(journeyDocs.flatMap((/** @type {any} */ doc) => doc.relatedCapabilities || []))
+    byEntityId: new Set(journeys.flatMap((/** @type {any} */ journey) => journey.relatedEntities || [])),
+    byCapabilityId: new Set(journeys.flatMap((/** @type {any} */ journey) => journey.relatedCapabilities || []))
   };
 }
 

package/src/workflows/reconcile/canonical-surface.js

@@ -133,7 +133,10 @@ export function collectCanonicalWorkflowSurface(graph) {
 
 /** @param {ResolvedGraph} graph @returns {any} */
 export function collectCanonicalActorRoleSurface(graph) {
-  const journeyDocs = (graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "journey");
+  const journeyDocs = [
+    ...(graph.byKind?.journey || []),
+    ...(graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "journey")
+  ];
   const workflowDocs = (graph.docs || []).filter((/** @type {any} */ doc) => doc.kind === "workflow");
   return {
     actor_ids: ((graph.byKind.actor || []).map((/** @type {any} */ entry) => entry.id)).sort(),

package/src/cli/commands/new.js

@@ -1,94 +0,0 @@
-// @ts-check
-
-import path from "node:path";
-
-import { resolveCatalogTemplateAlias } from "../catalog-alias.js";
-import { GENERATOR_POLICY_FILE } from "../../generator-policy.js";
-import { createNewProject } from "../../new-project.js";
-
-const ENGINE_ROOT = path.resolve(decodeURIComponent(new URL("../../../", import.meta.url).pathname));
-const TEMPLATES_ROOT = path.join(ENGINE_ROOT, "templates");
-
-/**
- * @param {ReturnType<typeof createNewProject>} result
- * @param {string} cwd
- * @returns {string}
- */
-function displayProjectRootForNewProject(result, cwd) {
-  const relativeProjectRoot = path.relative(cwd, result.projectRoot);
-  return !relativeProjectRoot || relativeProjectRoot.startsWith("..")
-    ? result.projectRoot
-    : relativeProjectRoot;
-}
-
-/**
- * @param {ReturnType<typeof createNewProject>} result
- * @param {string} cwd
- * @returns {void}
- */
-export function printNewProjectResult(result, cwd) {
-  const template = result.template || {};
-  console.log(`Created Topogram project at ${result.projectRoot}.`);
-  console.log(`Template: ${result.templateName}`);
-  console.log(`Source: ${template.source || "unknown"}`);
-  if (template.sourceSpec) {
-    console.log(`Source spec: ${template.sourceSpec}`);
-  }
-  if (template.catalog) {
-    console.log(`Catalog: ${template.catalog.id} from ${template.catalog.source}`);
-    console.log(`Package: ${template.catalog.packageSpec}`);
-  }
-  console.log(`Executable implementation: ${template.includesExecutableImplementation ? "yes" : "no"}`);
-  console.log("Policy: topogram.template-policy.json");
-  console.log(`Generator policy: ${GENERATOR_POLICY_FILE}`);
-  console.log("Template files: .topogram-template-files.json");
-  if (template.includesExecutableImplementation) {
-    console.log("Trust: .topogram-template-trust.json");
-  }
-  for (const warning of result.warnings) {
-    console.warn(`Warning: ${warning}`);
-  }
-  console.log("");
-  console.log("Next steps:");
-  console.log(`  cd ${displayProjectRootForNewProject(result, cwd)}`);
-  console.log("  npm install");
-  console.log("  npm run agent:brief");
-  console.log("  npm run doctor");
-  console.log("  npm run source:status");
-  console.log("  npm run template:explain");
-  console.log("  npm run check");
-  console.log("  npm run generator:policy:status");
-  console.log("  npm run generator:policy:check");
-  if (template.includesExecutableImplementation) {
-    console.log("  npm run template:policy:explain");
-    console.log("  npm run trust:status");
-  }
-  console.log("  npm run generate");
-  console.log("  npm run verify");
-}
-
-/**
- * @param {string} inputPath
- * @param {{ templateName: string, catalogSource?: string|null, cwd?: string }} options
- * @returns {number}
- */
-export function runNewProjectCommand(inputPath, options) {
-  const cwd = options.cwd || process.cwd();
-  const projectRoot = path.resolve(inputPath);
-  const relativeToEngine = path.relative(ENGINE_ROOT, projectRoot);
-  if (relativeToEngine === "" || (!relativeToEngine.startsWith("..") && !path.isAbsolute(relativeToEngine))) {
-    throw new Error(
-      `Refusing to create a generated project inside the engine directory. Use a path outside engine, for example '../${path.basename(projectRoot)}'.`
-    );
-  }
-  const resolvedTemplate = resolveCatalogTemplateAlias(options.templateName, options.catalogSource || null);
-  const result = createNewProject({
-    targetPath: inputPath,
-    templateName: resolvedTemplate.templateName,
-    templateProvenance: resolvedTemplate.provenance,
-    engineRoot: ENGINE_ROOT,
-    templatesRoot: TEMPLATES_ROOT
-  });
-  printNewProjectResult(result, cwd);
-  return 0;
-}