@topogram/cli 0.3.64 → 0.3.66

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

@@ -0,0 +1,241 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { stableStringify } from "../../../../format.js";
+import { parsePath } from "../../../../parser.js";
+import { resolveWorkspace } from "../../../../resolver.js";
+import {
+  buildImportPlanPayload,
+  buildResolvedWorkflowContextPayload,
+  buildSingleAgentPlanPayload,
+  buildWorkflowPresetActivationPayload,
+  buildWorkflowPresetCustomizationPayload,
+  buildWorkflowPresetDiffPayload,
+  buildWorkflowPresetState
+} from "../../../../agent-ops/query-builders.js";
+import {
+  adoptionPlanPath,
+  artifactOrNull,
+  buildMaintainedBundle,
+  buildSlice,
+  buildTaskMode,
+  generatorTargetsForWorkflowContext,
+  hasSelectors,
+  normalizeTopogramPath,
+  printValidationFailure,
+  readJson,
+  resultOk,
+  selectorOptions,
+  workflowPresetSelectors
+} from "../workspace.js";
+import { resolveRecommendedQueryFamily } from "../workflow-context.js";
+import { printJson } from "./output.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {AnyRecord} context
+ * @returns {number|null}
+ */
+export function runWorkflowQuery(context) {
+  const queryName = context.commandArgs?.queryName;
+  const selectors = selectorOptions(context);
+
+  if (queryName === "next-action") {
+    const result = buildTaskMode(parsePath(context.inputPath), selectors, context.modeId || "import-adopt", context.fromTopogramPath);
+    if (!resultOk(result)) return printValidationFailure(result);
+    return printJson({
+      type: "next_action_query",
+      mode: result.artifact.mode,
+      summary: result.artifact.summary || null,
+      next_action: result.artifact.next_action || null,
+      recommended_query_family: resolveRecommendedQueryFamily(result.artifact.next_action || null, result.artifact.mode),
+      immediate_artifacts: (result.artifact.preferred_context_artifacts || []).slice(0, 2),
+      preferred_context_artifacts: result.artifact.preferred_context_artifacts || [],
+      review_emphasis: result.artifact.review_emphasis || [],
+      write_scope: result.artifact.write_scope || null,
+      verification_targets: result.artifact.verification_targets || null
+    });
+  }
+
+  if (queryName === "single-agent-plan") {
+    return runSingleAgentPlan(context, selectors);
+  }
+
+  if (queryName === "resolved-workflow-context") {
+    return runResolvedWorkflowContext(context, selectors);
+  }
+
+  if (queryName === "workflow-preset-activation") {
+    if (!context.modeId) {
+      throw new Error("query workflow-preset-activation requires --mode <modeling|maintained-app-edit|import-adopt|diff-review|verification>.");
+    }
+    const topogramRoot = normalizeTopogramPath(context.inputPath);
+    const taskModeResult = buildTaskMode(parsePath(context.inputPath), selectors, context.modeId, context.fromTopogramPath);
+    if (!resultOk(taskModeResult)) return printValidationFailure(taskModeResult);
+    let importPlan = null;
+    if (context.modeId === "import-adopt" && fs.existsSync(adoptionPlanPath(topogramRoot))) {
+      const workflowPresets = buildWorkflowPresetState({
+        workspace: topogramRoot,
+        selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, "workflow-preset-activation")
+      });
+      importPlan = buildImportPlanPayload(readJson(adoptionPlanPath(topogramRoot)), taskModeResult.artifact, null, workflowPresets);
+    }
+    return printJson(buildWorkflowPresetActivationPayload({
+      workspace: topogramRoot,
+      taskModeArtifact: taskModeResult.artifact,
+      importPlan,
+      selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, "workflow-preset-activation")
+    }));
+  }
+
+  if (queryName === "workflow-preset-diff") {
+    if (!context.providerId) {
+      throw new Error("query workflow-preset-diff requires --provider <id>.");
+    }
+    return printJson(buildWorkflowPresetDiffPayload({
+      workspace: normalizeTopogramPath(context.inputPath),
+      providerId: context.providerId,
+      presetId: context.presetId
+    }));
+  }
+
+  if (queryName === "workflow-preset-customization" || context.commandArgs?.workflowPresetCommand === "customize") {
+    return runWorkflowPresetCustomization(context, queryName);
+  }
+
+  return null;
+}
+
+/**
+ * @param {AnyRecord} context
+ * @param {AnyRecord} selectors
+ * @returns {number}
+ */
+function runSingleAgentPlan(context, selectors) {
+  if (!context.modeId) {
+    throw new Error("query single-agent-plan requires --mode <modeling|maintained-app-edit|import-adopt|diff-review|verification>.");
+  }
+  const ast = parsePath(context.inputPath);
+  const result = buildTaskMode(ast, selectors, context.modeId, context.fromTopogramPath);
+  if (!resultOk(result)) return printValidationFailure(result);
+  const sliceResult = hasSelectors(context) ? buildSlice(ast, selectors) : null;
+  if (sliceResult && !resultOk(sliceResult)) return printValidationFailure(sliceResult);
+  const resolved = resolveWorkspace(ast);
+  if (!resultOk(resolved)) return printValidationFailure(resolved);
+  const generatorTargets = generatorTargetsForWorkflowContext({
+    graph: resolved.graph,
+    taskModeArtifact: result.artifact,
+    sliceArtifact: artifactOrNull(sliceResult)
+  });
+  const topogramRoot = normalizeTopogramPath(context.inputPath);
+  let importPlan = null;
+  if (context.modeId === "import-adopt" && fs.existsSync(adoptionPlanPath(topogramRoot))) {
+    const workflowPresets = buildWorkflowPresetState({
+      workspace: topogramRoot,
+      selectors: workflowPresetSelectors(result.artifact, context.providerId, context.presetId, "single-agent-plan")
+    });
+    importPlan = buildImportPlanPayload(readJson(adoptionPlanPath(topogramRoot)), result.artifact, null, workflowPresets);
+  }
+  const resolvedWorkflowContext = buildResolvedWorkflowContextPayload({
+    workspace: topogramRoot,
+    taskModeArtifact: result.artifact,
+    generatorTargets,
+    selectors: workflowPresetSelectors(result.artifact, context.providerId, context.presetId, "single-agent-plan"),
+    importPlan
+  });
+  return printJson(buildSingleAgentPlanPayload({
+    workspace: topogramRoot,
+    taskModeArtifact: result.artifact,
+    importPlan,
+    resolvedWorkflowContext
+  }));
+}
+
+/**
+ * @param {AnyRecord} context
+ * @param {AnyRecord} selectors
+ * @returns {number}
+ */
+function runResolvedWorkflowContext(context, selectors) {
+  if (!context.modeId) {
+    throw new Error("query resolved-workflow-context requires --mode <modeling|maintained-app-edit|import-adopt|diff-review|verification>.");
+  }
+  const topogramRoot = normalizeTopogramPath(context.inputPath);
+  const ast = parsePath(context.inputPath);
+  const taskModeResult = buildTaskMode(ast, selectors, context.modeId, context.fromTopogramPath);
+  if (!resultOk(taskModeResult)) return printValidationFailure(taskModeResult);
+  const resolved = resolveWorkspace(ast);
+  if (!resultOk(resolved)) return printValidationFailure(resolved);
+  const sliceResult = hasSelectors(context) ? buildSlice(ast, selectors) : null;
+  if (sliceResult && !resultOk(sliceResult)) return printValidationFailure(sliceResult);
+  const includeMaintainedBoundary =
+    context.modeId === "maintained-app-edit" ||
+    context.surfaceId === "maintained-boundary" ||
+    context.fromTopogramPath;
+  const maintainedBundleResult = includeMaintainedBoundary ? buildMaintainedBundle(ast) : null;
+  if (maintainedBundleResult && !resultOk(maintainedBundleResult)) return printValidationFailure(maintainedBundleResult);
+  const generatorTargets = generatorTargetsForWorkflowContext({
+    graph: resolved.graph,
+    taskModeArtifact: taskModeResult.artifact,
+    sliceArtifact: artifactOrNull(sliceResult),
+    maintainedBoundaryArtifact: maintainedBundleResult?.artifact?.maintained_boundary || null
+  });
+  let importPlan = null;
+  if (context.modeId === "import-adopt" && fs.existsSync(adoptionPlanPath(topogramRoot))) {
+    const workflowPresets = buildWorkflowPresetState({
+      workspace: topogramRoot,
+      selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, "resolved-workflow-context")
+    });
+    importPlan = buildImportPlanPayload(
+      readJson(adoptionPlanPath(topogramRoot)),
+      taskModeResult.artifact,
+      maintainedBundleResult?.artifact?.maintained_boundary || null,
+      workflowPresets
+    );
+  }
+  return printJson(buildResolvedWorkflowContextPayload({
+    workspace: topogramRoot,
+    taskModeArtifact: taskModeResult.artifact,
+    importPlan,
+    reviewBoundary: sliceResult?.artifact?.review_boundary || null,
+    maintainedBoundary: maintainedBundleResult?.artifact?.maintained_boundary || null,
+    generatorTargets,
+    selectors: workflowPresetSelectors(taskModeResult.artifact, context.providerId, context.presetId, "resolved-workflow-context")
+  }));
+}
+
+/**
+ * @param {AnyRecord} context
+ * @param {string|undefined} queryName
+ * @returns {number}
+ */
+function runWorkflowPresetCustomization(context, queryName) {
+  if (!context.providerId || !context.presetId) {
+    throw new Error(`${queryName ? "query workflow-preset-customization" : "workflow-preset customize"} requires --provider <id> and --preset <id>.`);
+  }
+  const topogramRoot = normalizeTopogramPath(context.inputPath);
+  const payload = buildWorkflowPresetCustomizationPayload({
+    workspace: topogramRoot,
+    providerId: context.providerId,
+    presetId: context.presetId
+  });
+  if (queryName === "workflow-preset-customization" || !context.shouldWrite) {
+    return printJson(payload);
+  }
+  const targetPath = path.resolve(topogramRoot, context.outPath || payload.recommended_local_path);
+  if (fs.existsSync(targetPath)) {
+    throw new Error(`Refusing to overwrite existing workflow preset customization at '${targetPath}'.`);
+  }
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  fs.writeFileSync(targetPath, `${stableStringify(payload.customization_template)}\n`);
+  return printJson({
+    ...payload,
+    written: true,
+    written_path: targetPath
+  });
+}

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

@@ -0,0 +1,3 @@
+// @ts-check
+
+export { runQueryCommand } from "./runner/index.js";

package/src/cli/commands/query/workflow-context.js

@@ -0,0 +1,5 @@
+// @ts-check
+
+export { resolveRecommendedQueryFamily } from "./workspace.js";
+
+

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

@@ -0,0 +1,270 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { generateWorkspace } from "../../../generator.js";
+import { formatValidationErrors } from "../../../validator.js";
+import { buildChangePlanPayload } from "../../../agent-ops/query-builders.js";
+import { resolveTopoRoot } from "../../../workspace-paths.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @param {string} inputPath
+ * @returns {string}
+ */
+export function normalizeTopogramPath(inputPath) {
+  return resolveTopoRoot(inputPath);
+}
+
+/**
+ * @param {AnyRecord} taskModeArtifact
+ * @param {string|null} providerId
+ * @param {string|null} presetId
+ * @param {string|null} queryFamily
+ * @returns {AnyRecord}
+ */
+export function workflowPresetSelectors(taskModeArtifact, providerId = null, presetId = null, queryFamily = null) {
+  const categories = [];
+  if (taskModeArtifact?.mode === "import-adopt") categories.push("provider_adoption");
+  if (taskModeArtifact?.mode === "maintained-app-edit") categories.push("maintained_app");
+  if ((taskModeArtifact?.verification_targets?.maintained_app_checks || []).length > 0) categories.push("maintained_boundary");
+  return {
+    mode: taskModeArtifact?.mode || null,
+    task_class: taskModeArtifact?.mode || null,
+    provider_id: providerId,
+    preset_id: presetId,
+    query_family: queryFamily,
+    integration_categories: categories
+  };
+}
+
+/**
+ * @param {AnyRecord} options
+ * @returns {AnyRecord[]}
+ */
+export function generatorTargetsForWorkflowContext(options = {}) {
+  const { graph, taskModeArtifact, sliceArtifact = null, diffArtifact = null, maintainedBoundaryArtifact = null } = options;
+  if (!graph || !taskModeArtifact) {
+    return [];
+  }
+  return buildChangePlanPayload({
+    graph,
+    taskModeArtifact,
+    sliceArtifact,
+    diffArtifact,
+    maintainedBoundaryArtifact
+  }).generator_targets || [];
+}
+
+/**
+ * @param {AnyRecord} options
+ * @returns {boolean}
+ */
+export function importAdoptOnlyRequested(options = {}) {
+  return options.modeId === "import-adopt" && !(
+    options.capabilityId ||
+    options.workflowId ||
+    options.projectionId ||
+    options.componentId ||
+    options.entityId ||
+    options.journeyId ||
+    options.surfaceId ||
+    options.domainId ||
+    options.fromTopogramPath
+  );
+}
+
+/**
+ * @param {AnyRecord} result
+ * @returns {boolean}
+ */
+export function resultOk(result) {
+  return Boolean(result?.ok);
+}
+
+/**
+ * @param {AnyRecord} result
+ * @returns {number}
+ */
+export function printValidationFailure(result) {
+  console.error(formatValidationErrors(result.validation));
+  return 1;
+}
+
+/**
+ * @param {AnyRecord} ast
+ * @param {AnyRecord} selectors
+ * @param {string} modeId
+ * @param {string|null} fromTopogramPath
+ * @returns {AnyRecord}
+ */
+export function buildTaskMode(ast, selectors, modeId, fromTopogramPath = null) {
+  return generateWorkspace(ast, {
+    target: "context-task-mode",
+    modeId,
+    ...selectors,
+    widgetId: selectors.componentId,
+    fromTopogramPath
+  });
+}
+
+/**
+ * @param {AnyRecord} ast
+ * @param {AnyRecord} selectors
+ * @returns {AnyRecord}
+ */
+export function buildSlice(ast, selectors) {
+  return generateWorkspace(ast, {
+    target: "context-slice",
+    ...selectors,
+    widgetId: selectors.componentId
+  });
+}
+
+/**
+ * @param {AnyRecord} ast
+ * @returns {AnyRecord}
+ */
+export function buildMaintainedBundle(ast) {
+  return generateWorkspace(ast, {
+    target: "context-bundle",
+    taskId: "maintained-app"
+  });
+}
+
+/**
+ * @param {AnyRecord} ast
+ * @param {string|null} fromTopogramPath
+ * @returns {AnyRecord|null}
+ */
+export function buildDiff(ast, fromTopogramPath) {
+  return fromTopogramPath
+    ? generateWorkspace(ast, {
+        target: "context-diff",
+        fromTopogramPath
+      })
+    : null;
+}
+
+/**
+ * @param {AnyRecord|null} result
+ * @returns {AnyRecord|null}
+ */
+export function artifactOrNull(result) {
+  return result?.artifact || null;
+}
+
+/**
+ * @param {string} topogramRoot
+ * @returns {string}
+ */
+export function adoptionPlanPath(topogramRoot) {
+  return path.join(topogramRoot, "candidates", "reconcile", "adoption-plan.agent.json");
+}
+
+/**
+ * @param {string} topogramRoot
+ * @param {string} label
+ * @returns {{ reportPath: string, adoptionStatusPath: string, adoptionPlanPath: string }}
+ */
+export function requireReconcileArtifacts(topogramRoot, label) {
+  const reportPath = path.join(topogramRoot, "candidates", "reconcile", "report.json");
+  const adoptionStatusPath = path.join(topogramRoot, "candidates", "reconcile", "adoption-status.json");
+  const planPath = adoptionPlanPath(topogramRoot);
+  if (!fs.existsSync(reportPath) || !fs.existsSync(adoptionStatusPath) || !fs.existsSync(planPath)) {
+    throw new Error(`No reconcile ${label} artifacts found under '${path.join(topogramRoot, "candidates", "reconcile")}'. Run 'node ./src/cli.js reconcile ${topogramRoot}' first.`);
+  }
+  return { reportPath, adoptionStatusPath, adoptionPlanPath: planPath };
+}
+
+/**
+ * @param {string} filePath
+ * @returns {AnyRecord}
+ */
+export function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+/**
+ * @param {AnyRecord} options
+ * @returns {boolean}
+ */
+export function hasSelectors(options) {
+  return Boolean(
+    options.capabilityId ||
+    options.workflowId ||
+    options.projectionId ||
+    options.componentId ||
+    options.entityId ||
+    options.journeyId ||
+    options.surfaceId ||
+    options.domainId
+  );
+}
+
+/**
+ * @param {AnyRecord} options
+ * @returns {boolean}
+ */
+export function shouldUseImportAdoptPath(options) {
+  const selectorOrDiff = hasSelectors(options) || Boolean(options.fromTopogramPath);
+  return importAdoptOnlyRequested(options) || (!selectorOrDiff && !options.modeId);
+}
+
+/**
+ * @param {AnyRecord} options
+ * @returns {AnyRecord}
+ */
+export function selectorOptions(options) {
+  return {
+    capabilityId: options.capabilityId,
+    workflowId: options.workflowId,
+    projectionId: options.projectionId,
+    componentId: options.componentId,
+    entityId: options.entityId,
+    journeyId: options.journeyId,
+    surfaceId: options.surfaceId,
+    domainId: options.domainId
+  };
+}
+
+/**
+ * @param {AnyRecord} nextAction
+ * @param {string|null} mode
+ * @returns {string}
+ */
+export function resolveRecommendedQueryFamily(nextAction, mode) {
+  switch (nextAction?.kind) {
+    case "review_staged":
+    case "review_bundle":
+    case "inspect_review_group":
+    case "inspect_proposal_surface":
+    case "customize_workflow_preset":
+    case "refresh_workflow_preset_customization":
+    case "import_declared_workflow_preset":
+      return "import-plan";
+    case "review_diff_impact":
+    case "inspect_projection":
+    case "inspect_diff":
+    case "review_diff_boundaries":
+      return "change-plan";
+    case "inspect_maintained_impact":
+    case "inspect_boundary_before_edit":
+    case "run_maintained_checks":
+      return "maintained-boundary";
+    case "inspect_verification_targets":
+      return "verification-targets";
+    case "inspect_workspace_digest":
+      return "single-agent-plan";
+    default:
+      break;
+  }
+  if (mode === "import-adopt") return "import-plan";
+  if (mode === "maintained-app-edit") return "maintained-boundary";
+  if (mode === "verification") return "verification-targets";
+  return "change-plan";
+}