@topogram/cli 0.3.63 → 0.3.65

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

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

@@ -0,0 +1,211 @@
+// @ts-check
+
+import { recommendedVerificationTargets } from "../../../../generator/context/shared.js";
+import { parsePath } from "../../../../parser.js";
+import { resolveWorkspace } from "../../../../resolver.js";
+import {
+  buildMaintainedConformancePayload,
+  buildMaintainedDriftPayload,
+  buildSeamCheckPayload
+} from "../../../../agent-ops/query-builders.js";
+import {
+  artifactOrNull,
+  buildDiff,
+  buildMaintainedBundle,
+  buildSlice,
+  buildTaskMode,
+  hasSelectors,
+  printValidationFailure,
+  resultOk,
+  selectorOptions
+} from "../workspace.js";
+import { printJson } from "./output.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} context
+ * @returns {number|null}
+ */
+export function runBoundaryQuery(context) {
+  const queryName = context.commandArgs?.queryName;
+  const selectors = selectorOptions(context);
+
+  if (queryName === "maintained-drift") {
+    if (!context.fromTopogramPath) {
+      throw new Error("query maintained-drift requires --from-topogram <path>.");
+    }
+    const ast = parsePath(context.inputPath);
+    const diffResult = buildDiff(ast, context.fromTopogramPath);
+    if (diffResult && !resultOk(diffResult)) return printValidationFailure(diffResult);
+    const maintainedBundleResult = buildMaintainedBundle(ast);
+    if (!resultOk(maintainedBundleResult)) return printValidationFailure(maintainedBundleResult);
+    const taskModeResult = buildTaskMode(ast, {}, "diff-review", context.fromTopogramPath);
+    if (!resultOk(taskModeResult)) return printValidationFailure(taskModeResult);
+    return printJson(buildMaintainedDriftPayload({
+      diffArtifact: diffResult?.artifact || null,
+      maintainedBoundaryArtifact: maintainedBundleResult.artifact.maintained_boundary || null,
+      verificationTargets: maintainedBundleResult.artifact.verification_targets || taskModeResult.artifact.verification_targets || null,
+      nextAction: taskModeResult.artifact.next_action || null
+    }));
+  }
+
+  if (queryName === "maintained-conformance") {
+    const ast = parsePath(context.inputPath);
+    const resolved = resolveWorkspace(ast);
+    if (!resultOk(resolved)) return printValidationFailure(resolved);
+    const diffResult = buildDiff(ast, context.fromTopogramPath);
+    if (diffResult && !resultOk(diffResult)) return printValidationFailure(diffResult);
+    const maintainedBundleResult = buildMaintainedBundle(ast);
+    if (!resultOk(maintainedBundleResult)) return printValidationFailure(maintainedBundleResult);
+    const taskModeResult = buildTaskMode(ast, {}, context.fromTopogramPath ? "diff-review" : "verification", context.fromTopogramPath);
+    if (!resultOk(taskModeResult)) return printValidationFailure(taskModeResult);
+    return printJson(buildMaintainedConformancePayload({
+      graph: resolved.graph,
+      diffArtifact: artifactOrNull(diffResult),
+      maintainedBoundaryArtifact: maintainedBundleResult.artifact.maintained_boundary || null,
+      verificationTargets: maintainedBundleResult.artifact.verification_targets || taskModeResult.artifact.verification_targets || null,
+      nextAction: taskModeResult.artifact.next_action || null
+    }));
+  }
+
+  if (queryName === "seam-check") {
+    const ast = parsePath(context.inputPath);
+    const resolved = resolveWorkspace(ast);
+    if (!resultOk(resolved)) return printValidationFailure(resolved);
+    const diffResult = buildDiff(ast, context.fromTopogramPath);
+    if (diffResult && !resultOk(diffResult)) return printValidationFailure(diffResult);
+    const maintainedBundleResult = buildMaintainedBundle(ast);
+    if (!resultOk(maintainedBundleResult)) return printValidationFailure(maintainedBundleResult);
+    const taskModeResult = buildTaskMode(ast, {}, context.fromTopogramPath ? "diff-review" : "verification", context.fromTopogramPath);
+    if (!resultOk(taskModeResult)) return printValidationFailure(taskModeResult);
+    return printJson(buildSeamCheckPayload({
+      graph: resolved.graph,
+      maintainedBoundaryArtifact: maintainedBundleResult.artifact.maintained_boundary || null,
+      diffArtifact: artifactOrNull(diffResult),
+      verificationTargets: maintainedBundleResult.artifact.verification_targets || taskModeResult.artifact.verification_targets || null,
+      nextAction: taskModeResult.artifact.next_action || null,
+      seamId: context.seamId
+    }));
+  }
+
+  if (queryName === "review-boundary") {
+    const result = buildSlice(parsePath(context.inputPath), selectors);
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson({
+      type: "review_boundary_query",
+      focus: result.artifact.focus,
+      review_boundary: result.artifact.review_boundary,
+      ownership_boundary: result.artifact.ownership_boundary,
+      write_scope: result.artifact.write_scope || null,
+      verification_targets: result.artifact.verification_targets || null
+    });
+  }
+
+  if (queryName === "write-scope") {
+    return runWriteScopeQuery(context, selectors);
+  }
+
+  if (queryName === "verification-targets") {
+    return runVerificationTargetsQuery(context, selectors);
+  }
+
+  return null;
+}
+
+/**
+ * @param {AnyRecord} context
+ * @param {AnyRecord} selectors
+ * @returns {number}
+ */
+function runWriteScopeQuery(context, selectors) {
+  const ast = parsePath(context.inputPath);
+  if (context.modeId || (!hasSelectors(context) && !context.fromTopogramPath)) {
+    const result = buildTaskMode(ast, selectors, context.modeId || "verification", context.fromTopogramPath);
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson({
+      type: "write_scope_query",
+      source: "context-task-mode",
+      mode: result.artifact.mode,
+      summary: result.artifact.summary || null,
+      rationale: "Task mode write scope is the safest file-boundary contract for the selected operating mode.",
+      write_scope: result.artifact.write_scope || null
+    });
+  }
+  if (context.surfaceId === "maintained-boundary") {
+    const result = buildMaintainedBundle(ast);
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson({
+      type: "write_scope_query",
+      source: "maintained-boundary",
+      summary: {
+        maintained_file_count: (result.artifact.maintained_boundary?.maintained_files_in_scope || []).length
+      },
+      rationale: "Maintained-boundary write scope isolates the human-owned application files currently in scope.",
+      write_scope: result.artifact.write_scope || null
+    });
+  }
+  const result = buildSlice(ast, selectors);
+  if (!resultOk(result)) return printValidationFailure(result);
+  return printJson({
+    type: "write_scope_query",
+    source: "context-slice",
+    focus: result.artifact.focus,
+    summary: result.artifact.summary || null,
+    rationale: "Slice write scope is the narrowest file-boundary contract attached to the selected semantic surface.",
+    write_scope: result.artifact.write_scope || null
+  });
+}
+
+/**
+ * @param {AnyRecord} context
+ * @param {AnyRecord} selectors
+ * @returns {number}
+ */
+function runVerificationTargetsQuery(context, selectors) {
+  const ast = parsePath(context.inputPath);
+  if (context.modeId || (!hasSelectors(context) && !context.fromTopogramPath)) {
+    const result = buildTaskMode(ast, selectors, context.modeId || "verification", context.fromTopogramPath);
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson({
+      type: "verification_targets_query",
+      source: "context-task-mode",
+      mode: result.artifact.mode,
+      summary: result.artifact.summary || null,
+      verification_targets: result.artifact.verification_targets || null
+    });
+  }
+  if (context.fromTopogramPath) {
+    const resolved = resolveWorkspace(ast);
+    if (!resultOk(resolved)) return printValidationFailure(resolved);
+    const result = buildDiff(ast, context.fromTopogramPath);
+    if (result && !resultOk(result)) return printValidationFailure(result);
+    const affectedVerificationIds = (result?.artifact?.affected_verifications || []).map((/** @type {AnyRecord} */ item) => item.id);
+    const verificationTargets = recommendedVerificationTargets(resolved.graph, affectedVerificationIds, {
+      includeMaintainedApp: Boolean(result?.artifact?.affected_maintained_surfaces?.ownership_interpretation?.maintained_code_impact),
+      rationale: "Diff verification targets should cover the affected semantic proof set and any maintained-app proof gates."
+    });
+    return printJson({
+      type: "verification_targets_query",
+      source: "context-diff",
+      summary: {
+        baseline_root: result?.artifact?.baseline_root,
+        affected_verification_count: affectedVerificationIds.length,
+        maintained_code_impact: Boolean(result?.artifact?.affected_maintained_surfaces?.ownership_interpretation?.maintained_code_impact)
+      },
+      verification_targets: verificationTargets,
+      affected_verifications: result?.artifact?.affected_verifications || []
+    });
+  }
+  const result = buildSlice(ast, selectors);
+  if (!resultOk(result)) return printValidationFailure(result);
+  return printJson({
+    type: "verification_targets_query",
+    source: "context-slice",
+    focus: result.artifact.focus,
+    summary: result.artifact.summary || null,
+    verification_targets: result.artifact.verification_targets || null
+  });
+}

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

@@ -0,0 +1,182 @@
+// @ts-check
+
+import fs from "node:fs";
+
+import {
+  buildCanonicalWritesPayloadForChangePlan,
+  buildCanonicalWritesPayloadForImportPlan,
+  buildResolvedWorkflowContextPayload,
+  buildReviewPacketPayloadForChangePlan,
+  buildReviewPacketPayloadForImportPlan,
+  buildRiskSummaryPayload,
+  classifyRisk,
+  proceedDecisionFromRisk
+} from "../../../../agent-ops/query-builders.js";
+import { parsePath } from "../../../../parser.js";
+import { buildChangePlanContext } from "../change-plan.js";
+import { buildImportPlanForContext } from "../import-adopt.js";
+import {
+  adoptionPlanPath,
+  buildTaskMode,
+  normalizeTopogramPath,
+  printValidationFailure,
+  readJson,
+  resultOk,
+  selectorOptions,
+  shouldUseImportAdoptPath,
+  workflowPresetSelectors
+} from "../workspace.js";
+import { printJson } from "./output.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} context
+ * @returns {number|null}
+ */
+export function runChangeQuery(context) {
+  const queryName = context.commandArgs?.queryName;
+  const selectors = selectorOptions(context);
+
+  if (queryName === "change-plan") {
+    const built = buildChangePlanContext(context, "modeling");
+    const failure = validateChangePlanBuild(built);
+    if (failure !== null) return failure;
+    return printJson(built.changePlan);
+  }
+
+  if (queryName === "risk-summary") {
+    if (hasImportPlan(context)) {
+      const built = buildImportPlanForContext(context, "risk-summary");
+      if (!resultOk(built)) return printValidationFailure(built);
+      const risk = classifyRisk({
+        importPlan: built.importPlan,
+        verificationTargets: built.importPlan.verification_targets,
+        maintainedRisk: built.importPlan.maintained_risk || null
+      });
+      return printJson(buildRiskSummaryPayload({
+        source: "import-plan",
+        risk,
+        nextAction: built.importPlan.next_action || null,
+        maintainedRisk: built.importPlan.maintained_risk || null
+      }));
+    }
+    const built = buildChangePlanContext(context, "modeling");
+    const failure = validateChangePlanBuild(built);
+    if (failure !== null) return failure;
+    const risk = riskFromChangePlanBuild(built);
+    return printJson(buildRiskSummaryPayload({
+      source: "change-plan",
+      risk,
+      nextAction: built.changePlan.next_action || null,
+      maintainedRisk: built.maintainedRisk
+    }));
+  }
+
+  if (queryName === "canonical-writes") {
+    if (hasImportPlan(context)) {
+      const adoptionPlan = readJson(adoptionPlanPath(normalizeTopogramPath(context.inputPath)));
+      return printJson(buildCanonicalWritesPayloadForImportPlan(adoptionPlan.imported_proposal_surfaces || []));
+    }
+    const result = buildTaskMode(parsePath(context.inputPath), selectors, context.modeId || "modeling", context.fromTopogramPath);
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson(buildCanonicalWritesPayloadForChangePlan(result.artifact.write_scope));
+  }
+
+  if (queryName === "proceed-decision") {
+    if (hasImportPlan(context)) {
+      const built = buildImportPlanForContext(context, "proceed-decision");
+      if (!resultOk(built)) return printValidationFailure(built);
+      const risk = classifyRisk({
+        importPlan: built.importPlan,
+        verificationTargets: built.importPlan.verification_targets,
+        maintainedRisk: built.importPlan.maintained_risk || null
+      });
+      const resolvedWorkflowContext = buildResolvedWorkflowContextPayload({
+        workspace: built.topogramRoot,
+        taskModeArtifact: built.taskModeResult.artifact,
+        importPlan: built.importPlan,
+        selectors: workflowPresetSelectors(built.taskModeResult.artifact, context.providerId, context.presetId, "proceed-decision")
+      });
+      return printJson(proceedDecisionFromRisk(
+        risk,
+        built.importPlan.next_action,
+        built.importPlan.write_scope,
+        built.importPlan.verification_targets,
+        built.importPlan.maintained_risk || null,
+        built.importPlan.workflow_presets || null,
+        resolvedWorkflowContext
+      ));
+    }
+    const built = buildChangePlanContext(context, "modeling");
+    const failure = validateChangePlanBuild(built);
+    if (failure !== null) return failure;
+    const risk = riskFromChangePlanBuild(built);
+    return printJson(proceedDecisionFromRisk(
+      risk,
+      built.changePlan.next_action || null,
+      built.changePlan.write_scope || null,
+      built.changePlan.verification_targets || null,
+      built.maintainedRisk,
+      null,
+      null
+    ));
+  }
+
+  if (queryName === "review-packet") {
+    if (hasImportPlan(context)) {
+      const built = buildImportPlanForContext(context, "review-packet");
+      if (!resultOk(built)) return printValidationFailure(built);
+      const risk = classifyRisk({
+        importPlan: built.importPlan,
+        verificationTargets: built.importPlan.verification_targets,
+        maintainedRisk: built.importPlan.maintained_risk || null
+      });
+      return printJson(buildReviewPacketPayloadForImportPlan({ importPlan: built.importPlan, risk }));
+    }
+    const built = buildChangePlanContext(context, "modeling");
+    const failure = validateChangePlanBuild(built);
+    if (failure !== null) return failure;
+    const risk = riskFromChangePlanBuild(built);
+    return printJson(buildReviewPacketPayloadForChangePlan({ changePlan: built.changePlan, risk }));
+  }
+
+  return null;
+}
+
+/**
+ * @param {AnyRecord} context
+ * @returns {boolean}
+ */
+function hasImportPlan(context) {
+  return shouldUseImportAdoptPath(context) && fs.existsSync(adoptionPlanPath(normalizeTopogramPath(context.inputPath)));
+}
+
+/**
+ * @param {AnyRecord} built
+ * @returns {number|null}
+ */
+function validateChangePlanBuild(built) {
+  if (!resultOk(built.resolved)) return printValidationFailure(built.resolved);
+  if (!resultOk(built.taskModeResult)) return printValidationFailure(built.taskModeResult);
+  if (built.sliceResult && !resultOk(built.sliceResult)) return printValidationFailure(built.sliceResult);
+  if (built.diffResult && !resultOk(built.diffResult)) return printValidationFailure(built.diffResult);
+  if (built.maintainedBundleResult && !resultOk(built.maintainedBundleResult)) return printValidationFailure(built.maintainedBundleResult);
+  return null;
+}
+
+/**
+ * @param {AnyRecord} built
+ * @returns {AnyRecord}
+ */
+function riskFromChangePlanBuild(built) {
+  return classifyRisk({
+    reviewBoundary: built.changePlan.review_boundary,
+    maintainedBoundary: built.changePlan.maintained_boundary,
+    diffSummary: built.diffSummary,
+    verificationTargets: built.changePlan.verification_targets,
+    maintainedRisk: built.maintainedRisk
+  });
+}