@topogram/cli 0.3.64 → 0.3.66

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

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

@@ -0,0 +1,111 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  buildAuthHintsQueryPayload,
+  buildAuthReviewPacketPayload,
+  buildHandoffStatusPayload,
+  buildLaneStatusPayload,
+  buildWorkPacketPayload
+} from "../../../../agent-ops/query-builders.js";
+import { buildImportAdoptAgentContext, buildImportPlanForContext } from "../import-adopt.js";
+import { normalizeTopogramPath, printValidationFailure, readJson, resultOk } from "../workspace.js";
+import { printJson } from "./output.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} context
+ * @returns {number|null}
+ */
+export function runImportAdoptQuery(context) {
+  const queryName = context.commandArgs?.queryName;
+
+  if (queryName === "import-plan") {
+    const built = buildImportPlanForContext(context, "import-plan");
+    if (!resultOk(built)) return printValidationFailure(built);
+    return printJson(built.importPlan);
+  }
+
+  if (queryName === "multi-agent-plan") {
+    if (context.modeId !== "import-adopt") {
+      throw new Error("query multi-agent-plan currently supports only --mode import-adopt.");
+    }
+    const built = buildImportAdoptAgentContext(context, "multi-agent-plan");
+    if (!resultOk(built)) return printValidationFailure(built);
+    return printJson(built.multiAgentPlan);
+  }
+
+  if (queryName === "work-packet") {
+    if (context.modeId !== "import-adopt") {
+      throw new Error("query work-packet currently supports only --mode import-adopt.");
+    }
+    if (!context.laneId) {
+      throw new Error("query work-packet requires --lane <id>.");
+    }
+    const built = buildImportAdoptAgentContext(context, "work-packet");
+    if (!resultOk(built)) return printValidationFailure(built);
+    return printJson(buildWorkPacketPayload({
+      workspace: built.topogramRoot,
+      multiAgentPlan: built.multiAgentPlan,
+      laneId: context.laneId
+    }));
+  }
+
+  if (queryName === "lane-status" || queryName === "handoff-status") {
+    if (context.modeId !== "import-adopt") {
+      throw new Error(`query ${queryName} currently supports only --mode import-adopt.`);
+    }
+    const built = buildImportAdoptAgentContext(context, queryName);
+    if (!resultOk(built)) return printValidationFailure(built);
+    const payload = queryName === "lane-status"
+      ? buildLaneStatusPayload({
+          workspace: built.topogramRoot,
+          multiAgentPlan: built.multiAgentPlan,
+          report: built.reconcileReport,
+          adoptionStatus: built.adoptionStatus
+        })
+      : buildHandoffStatusPayload({
+          workspace: built.topogramRoot,
+          multiAgentPlan: built.multiAgentPlan,
+          report: built.reconcileReport,
+          adoptionStatus: built.adoptionStatus
+        });
+    return printJson(payload);
+  }
+
+  if (queryName === "auth-hints") {
+    const topogramRoot = normalizeTopogramPath(context.inputPath);
+    const reportPath = path.join(topogramRoot, "candidates", "reconcile", "report.json");
+    const adoptionStatusPath = path.join(topogramRoot, "candidates", "reconcile", "adoption-status.json");
+    if (!fs.existsSync(reportPath) || !fs.existsSync(adoptionStatusPath)) {
+      throw new Error(`No reconcile auth-hint artifacts found under '${path.join(topogramRoot, "candidates", "reconcile")}'. Run 'node ./src/cli.js reconcile ${topogramRoot}' first.`);
+    }
+    return printJson(buildAuthHintsQueryPayload(readJson(reportPath), readJson(adoptionStatusPath)));
+  }
+
+  if (queryName === "auth-review-packet") {
+    if (!context.bundleSlug) {
+      throw new Error("query auth-review-packet requires --bundle <slug>.");
+    }
+    const topogramRoot = normalizeTopogramPath(context.inputPath);
+    const reportPath = path.join(topogramRoot, "candidates", "reconcile", "report.json");
+    const adoptionStatusPath = path.join(topogramRoot, "candidates", "reconcile", "adoption-status.json");
+    if (!fs.existsSync(reportPath) || !fs.existsSync(adoptionStatusPath)) {
+      throw new Error(`No reconcile auth-review artifacts found under '${path.join(topogramRoot, "candidates", "reconcile")}'. Run 'node ./src/cli.js reconcile ${topogramRoot}' first.`);
+    }
+    const reconcileReport = readJson(reportPath);
+    const packet = buildAuthReviewPacketPayload(reconcileReport, readJson(adoptionStatusPath), context.bundleSlug);
+    if (!packet) {
+      const knownBundles = (reconcileReport.candidate_model_bundles || []).map((/** @type {AnyRecord} */ bundle) => bundle.slug).sort();
+      throw new Error(`No auth review bundle '${context.bundleSlug}' found in '${path.join(topogramRoot, "candidates", "reconcile")}'. Known bundles: ${knownBundles.length ? knownBundles.join(", ") : "none"}.`);
+    }
+    return printJson(packet);
+  }
+
+  return null;
+}

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

@@ -0,0 +1,31 @@
+// @ts-check
+
+import { runArtifactQuery } from "./artifacts.js";
+import { runBoundaryQuery } from "./boundaries.js";
+import { runChangeQuery } from "./change.js";
+import { runImportAdoptQuery } from "./import-adopt.js";
+import { runWorkflowQuery } from "./workflow.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} context
+ * @returns {Promise<number|null>}
+ */
+export async function runQueryCommand(context) {
+  for (const handler of [
+    runArtifactQuery,
+    runBoundaryQuery,
+    runChangeQuery,
+    runWorkflowQuery,
+    runImportAdoptQuery
+  ]) {
+    const result = handler(context);
+    if (result !== null) {
+      return result;
+    }
+  }
+  return null;
+}

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

@@ -0,0 +1,12 @@
+// @ts-check
+
+import { stableStringify } from "../../../../format.js";
+
+/**
+ * @param {any} payload
+ * @returns {0}
+ */
+export function printJson(payload) {
+  console.log(stableStringify(payload));
+  return 0;
+}