@topogram/cli 0.3.64 → 0.3.65

package/src/cli/commands/query/change-plan.js

@@ -0,0 +1,68 @@
+// @ts-check
+
+import { buildMaintainedRiskSummary, buildChangePlanPayload, summarizeDiffArtifact } from "../../../agent-ops/query-builders.js";
+import { parsePath } from "../../../parser.js";
+import { resolveWorkspace } from "../../../resolver.js";
+import {
+  artifactOrNull,
+  buildDiff,
+  buildMaintainedBundle,
+  buildSlice,
+  buildTaskMode,
+  hasSelectors,
+  resultOk,
+  selectorOptions
+} from "./workspace.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} context
+ * @param {string} defaultMode
+ * @returns {{ ast: AnyRecord, resolved: AnyRecord, taskModeResult: AnyRecord, sliceResult: AnyRecord|null, diffResult: AnyRecord|null, maintainedBundleResult: AnyRecord|null, changePlan: AnyRecord, diffSummary: AnyRecord|null, maintainedRisk: AnyRecord }}
+ */
+export function buildChangePlanContext(context, defaultMode = "modeling") {
+  const ast = parsePath(context.inputPath);
+  const resolved = resolveWorkspace(ast);
+  if (!resultOk(resolved)) {
+    return /** @type {any} */ ({ ast, resolved });
+  }
+  const selectors = selectorOptions(context);
+  const effectiveModeId = context.modeId || defaultMode;
+  const taskModeResult = buildTaskMode(ast, selectors, effectiveModeId, context.fromTopogramPath);
+  if (!resultOk(taskModeResult)) {
+    return /** @type {any} */ ({ ast, resolved, taskModeResult });
+  }
+  const sliceResult = hasSelectors(context) ? buildSlice(ast, selectors) : null;
+  if (sliceResult && !resultOk(sliceResult)) {
+    return /** @type {any} */ ({ ast, resolved, taskModeResult, sliceResult });
+  }
+  const diffResult = buildDiff(ast, context.fromTopogramPath);
+  if (diffResult && !resultOk(diffResult)) {
+    return /** @type {any} */ ({ ast, resolved, taskModeResult, sliceResult, diffResult });
+  }
+  const includeMaintainedBoundary =
+    effectiveModeId === "maintained-app-edit" ||
+    context.surfaceId === "maintained-boundary" ||
+    Boolean(diffResult?.artifact?.affected_maintained_surfaces?.ownership_interpretation?.maintained_code_impact);
+  const maintainedBundleResult = includeMaintainedBoundary ? buildMaintainedBundle(ast) : null;
+  if (maintainedBundleResult && !resultOk(maintainedBundleResult)) {
+    return /** @type {any} */ ({ ast, resolved, taskModeResult, sliceResult, diffResult, maintainedBundleResult });
+  }
+  const changePlan = buildChangePlanPayload({
+    graph: resolved.graph,
+    taskModeArtifact: taskModeResult.artifact,
+    sliceArtifact: artifactOrNull(sliceResult),
+    diffArtifact: artifactOrNull(diffResult),
+    maintainedBoundaryArtifact: maintainedBundleResult?.artifact?.maintained_boundary || null
+  });
+  const diffSummary = changePlan.diff_summary || summarizeDiffArtifact(diffResult?.artifact || null);
+  const maintainedRisk = buildMaintainedRiskSummary({
+    maintainedImpacts: changePlan.maintained_impacts,
+    maintainedBoundary: changePlan.maintained_boundary,
+    diffSummary
+  });
+  return { ast, resolved, taskModeResult, sliceResult, diffResult, maintainedBundleResult, changePlan, diffSummary, maintainedRisk };
+}

package/src/cli/commands/query/definitions.js

@@ -0,0 +1,202 @@
+// @ts-check
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   purpose: string,
+ *   description: string,
+ *   selectors: string[],
+ *   args: string[],
+ *   output: string,
+ *   example: string
+ * }} QueryDefinition
+ *
+ * @typedef {{
+ *   type: "query_list",
+ *   version: 1,
+ *   queries: QueryDefinition[]
+ * }} QueryListPayload
+ *
+ * @typedef {{
+ *   type: "query_definition",
+ *   version: 1,
+ *   query: QueryDefinition
+ * }} QueryDefinitionPayload
+ */
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @returns {QueryDefinition[]}
+ */
+export function queryDefinitions() {
+  return [
+    {
+      name: "slice",
+      purpose: "Give an agent the smallest graph slice needed to reason about one selected semantic surface.",
+      description: "Return a focused semantic context slice for one selected surface.",
+      selectors: ["capability", "workflow", "projection", "widget", "entity", "journey", "domain"],
+      args: ["[path]", "[selectors]", "[--json]"],
+      output: "context_slice",
+      example: "topogram query slice ./topogram --widget widget_data_grid"
+    },
+    {
+      name: "verification-targets",
+      purpose: "Map a selected change or mode to the smallest verification set worth running.",
+      description: "Return the smallest verification target set for a mode, selector, or diff.",
+      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "from-topogram"],
+      args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
+      output: "verification_targets",
+      example: "topogram query verification-targets ./topogram --widget widget_data_grid"
+    },
+    {
+      name: "widget-behavior",
+      purpose: "Show how reusable widget behavior is realized by projection usage.",
+      description: "Return widget behavior realization data grouped by widget, screen, capability, and effect.",
+      selectors: ["projection", "widget"],
+      args: ["[path]", "[--projection <id>]", "[--widget <id>]", "[--json]"],
+      output: "widget_behavior_report",
+      example: "topogram query widget-behavior ./topogram --projection proj_web_surface --widget widget_data_grid --json"
+    },
+    {
+      name: "change-plan",
+      purpose: "Summarize what a selected change affects before code or Topogram edits start.",
+      description: "Return the semantic change plan, generator targets, risk, and alignment recommendations.",
+      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
+      output: "change_plan_query",
+      example: "topogram query change-plan ./topogram --widget widget_data_grid"
+    },
+    {
+      name: "review-packet",
+      purpose: "Bundle the context a human or agent needs to review a selected semantic change.",
+      description: "Return the review packet for a selected change or diff.",
+      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
+      output: "review_packet_query",
+      example: "topogram query review-packet ./topogram --widget widget_data_grid"
+    },
+    {
+      name: "resolved-workflow-context",
+      purpose: "Resolve workflow guidance and artifact load order for a selected mode or change.",
+      description: "Return resolved workflow guidance, artifact load order, preset policy, and recommended artifact queries.",
+      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "provider", "preset", "from-topogram"],
+      args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
+      output: "resolved_workflow_context_query",
+      example: "topogram query resolved-workflow-context ./topogram --mode modeling --widget widget_data_grid --json"
+    },
+    {
+      name: "single-agent-plan",
+      purpose: "Give one coding agent a bounded plan, artifact set, and write guidance.",
+      description: "Return a single-agent operating plan for a mode and optional selector.",
+      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
+      output: "single_agent_plan_query",
+      example: "topogram query single-agent-plan ./topogram --mode modeling --widget widget_data_grid --json"
+    },
+    {
+      name: "risk-summary",
+      purpose: "Surface behavioral, ownership, and verification risks for a selected change.",
+      description: "Return the risk summary for a selected change, mode, or diff.",
+      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
+      output: "risk_summary_query",
+      example: "topogram query risk-summary ./topogram --widget widget_data_grid"
+    },
+    {
+      name: "proceed-decision",
+      purpose: "Tell a human or agent whether enough context and proof exist to proceed.",
+      description: "Return a proceed/no-go decision for the current selected work.",
+      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
+      output: "proceed_decision_query",
+      example: "topogram query proceed-decision ./topogram --mode verification"
+    },
+    {
+      name: "write-scope",
+      purpose: "Define where an agent may edit for a selected semantic surface.",
+      description: "Return safe edit boundaries for a selected mode or semantic surface.",
+      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "from-topogram"],
+      args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
+      output: "write_scope_query",
+      example: "topogram query write-scope ./topogram --widget widget_data_grid"
+    }
+  ];
+}
+
+/**
+ * @returns {QueryListPayload}
+ */
+export function buildQueryListPayload() {
+  return {
+    type: "query_list",
+    version: 1,
+    queries: queryDefinitions()
+  };
+}
+
+/**
+ * @param {string} name
+ * @returns {QueryDefinitionPayload}
+ */
+export function buildQueryShowPayload(name) {
+  const query = queryDefinitions().find((entry) => entry.name === name);
+  if (!query) {
+    const known = queryDefinitions().map((entry) => entry.name).join(", ");
+    throw new Error(`Unknown query '${name}'. Run 'topogram query list' to inspect available queries. Known queries: ${known}`);
+  }
+  return {
+    type: "query_definition",
+    version: 1,
+    query
+  };
+}
+
+/**
+ * @returns {void}
+ */
+export function printQueryHelp() {
+  console.log("Usage: topogram query list [--json]");
+  console.log("   or: topogram query show <name> [--json]");
+  console.log("   or: topogram query widget-behavior [path] [--projection <id>] [--widget <id>] [--json]");
+  console.log("   or: topogram query <name> [path] [selectors] [--json]");
+  console.log("");
+  console.log("Agent-facing queries return focused JSON packets for context, review, verification, and generation follow-up.");
+  console.log("");
+  console.log("Common queries:");
+  for (const query of queryDefinitions()) {
+    console.log(`  ${query.name}`);
+    console.log(`    ${query.description}`);
+    console.log(`    example: ${query.example}`);
+  }
+}
+
+/**
+ * @param {QueryDefinitionPayload} payload
+ * @returns {void}
+ */
+export function printQueryDefinition(payload) {
+  const query = payload.query;
+  console.log(`Query: ${query.name}`);
+  console.log(`Purpose: ${query.purpose}`);
+  console.log(`Description: ${query.description}`);
+  console.log(`Output: ${query.output}`);
+  console.log(`Arguments: ${query.args.join(" ")}`);
+  console.log(`Selectors: ${query.selectors.join(", ") || "none"}`);
+  console.log(`Example: ${query.example}`);
+}
+
+/**
+ * @param {QueryListPayload} payload
+ * @returns {void}
+ */
+export function printQueryList(payload) {
+  console.log("Topogram queries:");
+  for (const query of payload.queries) {
+    console.log(`- ${query.name}: ${query.description}`);
+    console.log(`  selectors: ${query.selectors.join(", ") || "none"}`);
+    console.log(`  example: ${query.example}`);
+  }
+}

package/src/cli/commands/query/import-adopt.js

@@ -0,0 +1,121 @@
+// @ts-check
+
+import fs from "node:fs";
+
+import {
+  buildImportPlanPayload,
+  buildMultiAgentPlanPayload,
+  buildResolvedWorkflowContextPayload,
+  buildSingleAgentPlanPayload,
+  buildWorkflowPresetState
+} from "../../../agent-ops/query-builders.js";
+import { parsePath } from "../../../parser.js";
+import {
+  adoptionPlanPath,
+  buildMaintainedBundle,
+  buildTaskMode,
+  normalizeTopogramPath,
+  readJson,
+  requireReconcileArtifacts,
+  resultOk,
+  workflowPresetSelectors
+} from "./workspace.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} context
+ * @param {string} queryFamily
+ * @returns {AnyRecord}
+ */
+export function buildImportPlanForContext(context, queryFamily) {
+  const topogramRoot = normalizeTopogramPath(context.inputPath);
+  const planPath = adoptionPlanPath(topogramRoot);
+  if (!fs.existsSync(planPath)) {
+    throw new Error(`No agent adoption plan found at '${planPath}'`);
+  }
+  const adoptionPlan = readJson(planPath);
+  const ast = parsePath(context.inputPath);
+  const taskModeResult = buildTaskMode(ast, {}, "import-adopt");
+  if (!resultOk(taskModeResult)) {
+    return taskModeResult;
+  }
+  const maintainedBundleResult = buildMaintainedBundle(ast);
+  if (!resultOk(maintainedBundleResult)) {
+    return maintainedBundleResult;
+  }
+  const workflowPresets = buildWorkflowPresetState({
+    workspace: topogramRoot,
+    selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, queryFamily)
+  });
+  return {
+    ok: true,
+    topogramRoot,
+    taskModeResult,
+    maintainedBundleResult,
+    adoptionPlan,
+    importPlan: buildImportPlanPayload(
+      adoptionPlan,
+      taskModeResult.artifact,
+      maintainedBundleResult.artifact.maintained_boundary || null,
+      workflowPresets
+    )
+  };
+}
+
+/**
+ * @param {AnyRecord} context
+ * @param {string} queryFamily
+ * @returns {AnyRecord}
+ */
+export function buildImportAdoptAgentContext(context, queryFamily) {
+  const topogramRoot = normalizeTopogramPath(context.inputPath);
+  const artifacts = requireReconcileArtifacts(topogramRoot, queryFamily);
+  const ast = parsePath(context.inputPath);
+  const taskModeResult = buildTaskMode(ast, {}, "import-adopt");
+  if (!resultOk(taskModeResult)) {
+    return taskModeResult;
+  }
+  const adoptionPlanArtifact = readJson(artifacts.adoptionPlanPath);
+  const reconcileReport = readJson(artifacts.reportPath);
+  const adoptionStatus = readJson(artifacts.adoptionStatusPath);
+  const workflowPresets = buildWorkflowPresetState({
+    workspace: topogramRoot,
+    selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, queryFamily)
+  });
+  const importPlan = buildImportPlanPayload(adoptionPlanArtifact, taskModeResult.artifact, null, workflowPresets);
+  const resolvedWorkflowContext = buildResolvedWorkflowContextPayload({
+    workspace: topogramRoot,
+    taskModeArtifact: taskModeResult.artifact,
+    importPlan,
+    selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, queryFamily)
+  });
+  const singleAgentPlan = buildSingleAgentPlanPayload({
+    workspace: topogramRoot,
+    taskModeArtifact: taskModeResult.artifact,
+    importPlan,
+    resolvedWorkflowContext
+  });
+  const multiAgentPlan = buildMultiAgentPlanPayload({
+    workspace: topogramRoot,
+    singleAgentPlan,
+    importPlan,
+    report: reconcileReport,
+    adoptionStatus,
+    resolvedWorkflowContext
+  });
+  return {
+    ok: true,
+    topogramRoot,
+    taskModeResult,
+    adoptionPlanArtifact,
+    reconcileReport,
+    adoptionStatus,
+    importPlan,
+    resolvedWorkflowContext,
+    singleAgentPlan,
+    multiAgentPlan
+  };
+}

package/src/cli/commands/query/runner/artifacts.js

@@ -0,0 +1,102 @@
+// @ts-check
+
+import fs from "node:fs";
+
+import { generateWorkspace } from "../../../../generator.js";
+import { parsePath } from "../../../../parser.js";
+import {
+  adoptionPlanPath,
+  buildMaintainedBundle,
+  buildSlice,
+  normalizeTopogramPath,
+  printValidationFailure,
+  readJson,
+  resultOk,
+  selectorOptions
+} from "../workspace.js";
+import { printJson } from "./output.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} context
+ * @returns {number|null}
+ */
+export function runArtifactQuery(context) {
+  const queryName = context.commandArgs?.queryName;
+  const selectors = selectorOptions(context);
+  const selectedWidgetId = context["componentId"];
+
+  if (queryName === "task-mode") {
+    const result = generateWorkspace(parsePath(context.inputPath), {
+      target: "context-task-mode",
+      modeId: context.modeId,
+      ...selectors,
+      widgetId: selectedWidgetId,
+      fromTopogramPath: context.fromTopogramPath
+    });
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson(result.artifact);
+  }
+
+  if (queryName === "diff") {
+    const result = generateWorkspace(parsePath(context.inputPath), {
+      target: "context-diff",
+      fromTopogramPath: context.fromTopogramPath
+    });
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson(result.artifact);
+  }
+
+  if (queryName === "slice") {
+    const result = buildSlice(parsePath(context.inputPath), selectors);
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson(result.artifact);
+  }
+
+  if (queryName === "adoption-plan") {
+    const topogramRoot = normalizeTopogramPath(context.inputPath);
+    const planPath = adoptionPlanPath(topogramRoot);
+    if (!fs.existsSync(planPath)) {
+      throw new Error(`No agent adoption plan found at '${planPath}'`);
+    }
+    return printJson(readJson(planPath));
+  }
+
+  if (queryName === "maintained-boundary") {
+    const result = buildMaintainedBundle(parsePath(context.inputPath));
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson(result.artifact.maintained_boundary);
+  }
+
+  if (queryName === "domain-list") {
+    const result = generateWorkspace(parsePath(context.inputPath), { target: "domain-list" });
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson(result.artifact);
+  }
+
+  if (queryName === "domain-coverage") {
+    if (!context.domainId) {
+      console.error("query domain-coverage requires --domain <id>");
+      return 2;
+    }
+    const result = generateWorkspace(parsePath(context.inputPath), { target: "domain-coverage", domainId: context.domainId });
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson(result.artifact);
+  }
+
+  if (queryName === "widget-behavior") {
+    const result = generateWorkspace(parsePath(normalizeTopogramPath(context.inputPath)), {
+      target: "widget-behavior-report",
+      projectionId: context.projectionId,
+      componentId: selectedWidgetId
+    });
+    if (!resultOk(result)) return printValidationFailure(result);
+    printJson(result.artifact);
+    return (result.artifact.summary?.errors || 0) === 0 ? 0 : 1;
+  }
+
+  return null;
+}