@topogram/cli 0.3.63 → 0.3.65

package/src/cli/commands/package/update-cli.js

@@ -0,0 +1,252 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { assertSafeNpmSpec } from "../../../npm-safety.js";
+import {
+  CLI_PACKAGE_NAME,
+  NPMJS_REGISTRY,
+  PACKAGE_UPDATE_CLI_INFO_SCRIPTS,
+  PACKAGE_UPDATE_CLI_VERIFICATION_SCRIPTS
+} from "./constants.js";
+import { sanitizeTopogramLockForPackageUpdate } from "./lockfile.js";
+import { formatPackageUpdateNpmError, latestTopogramCliVersion, runNpmForPackageUpdate } from "./npm.js";
+import { messageFromError } from "./shared.js";
+import { isPackageVersion } from "./versions.js";
+
+/**
+ * @typedef {{
+ *   ok: boolean,
+ *   packageName: string,
+ *   requestedVersion: string,
+ *   requestedLatest: boolean,
+ *   dependencySpec: string,
+ *   checkedVersion: string,
+ *   packageCheckSource: "npm",
+ *   dependencyUpdatedBy: "npm-install"|"manifest-lockfile"|"version-convention",
+ *   lockfileSanitized: boolean,
+ *   versionConventionUpdated: boolean,
+ *   versionConventionPath: string|null,
+ *   scriptsRun: string[],
+ *   skippedScripts: string[],
+ *   diagnostics: Array<Record<string, any>>,
+ *   errors: string[]
+ * }} PackageUpdateCliPayload
+ */
+
+/**
+ * @param {string} requested
+ * @param {{ cwd?: string }} [options]
+ * @returns {PackageUpdateCliPayload}
+ */
+export function buildPackageUpdateCliPayload(requested, options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const requestedLatest = requested === "latest" || requested === "--latest";
+  /** @type {Array<Record<string, any>>} */
+  const diagnostics = [];
+  const version = requestedLatest
+    ? resolveLatestTopogramCliVersionForPackageUpdate(cwd, diagnostics)
+    : requested;
+  if (!isPackageVersion(version)) {
+    throw new Error("topogram package update-cli requires <version> or --latest.");
+  }
+  const exactSpec = `${CLI_PACKAGE_NAME}@${version}`;
+  const dependencySpec = `${CLI_PACKAGE_NAME}@^${version}`;
+  assertSafeNpmSpec(exactSpec);
+  assertSafeNpmSpec(dependencySpec);
+  const view = runNpmForPackageUpdate(["view", `--registry=${NPMJS_REGISTRY}`, "--", exactSpec, "version"], cwd);
+  let checkedVersion = null;
+  const packageCheckSource = "npm";
+  if (view.status !== 0) {
+    throw new Error(formatPackageUpdateNpmError(exactSpec, "inspect", view));
+  } else {
+    checkedVersion = String(view.stdout || "").trim().replace(/^"|"$/g, "");
+    if (checkedVersion !== version) {
+      throw new Error(`Expected ${exactSpec}, but npm returned version '${checkedVersion || "(empty)"}'.`);
+    }
+  }
+  const lockfileSanitized = sanitizeTopogramLockForPackageUpdate(cwd, version);
+  const dependencyUpdatedBy = "npm-install";
+  const install = runNpmForPackageUpdate(["install", "--save-dev", `--registry=${NPMJS_REGISTRY}`, "--", dependencySpec], cwd);
+  if (install.status !== 0) {
+    throw new Error(formatPackageUpdateNpmError(dependencySpec, "install", install));
+  }
+  const versionConvention = writeTopogramCliVersionConventionIfPresent(cwd, version);
+  const packageJson = readPackageJsonForUpdate(cwd);
+  const scripts = packageJson.scripts && typeof packageJson.scripts === "object" ? packageJson.scripts : {};
+  const scriptsRun = [];
+  const skippedScripts = [];
+  const scriptsToRun = packageUpdateCliScriptsToRun(scripts);
+  for (const scriptName of PACKAGE_UPDATE_CLI_INFO_SCRIPTS) {
+    if (!Object.prototype.hasOwnProperty.call(scripts, scriptName)) {
+      skippedScripts.push(scriptName);
+    }
+  }
+  for (const scriptName of PACKAGE_UPDATE_CLI_VERIFICATION_SCRIPTS) {
+    if (!Object.prototype.hasOwnProperty.call(scripts, scriptName)) {
+      skippedScripts.push(scriptName);
+    } else if (!scriptsToRun.includes(scriptName)) {
+      const coveringScript = scriptsToRun.find((candidate) =>
+        PACKAGE_UPDATE_CLI_VERIFICATION_SCRIPTS.includes(candidate)
+      );
+      skippedScripts.push(`${scriptName} (covered by ${coveringScript})`);
+    }
+  }
+  for (const scriptName of scriptsToRun) {
+    const result = runNpmForPackageUpdate(["run", scriptName], cwd);
+    if (result.status !== 0) {
+      throw new Error(formatPackageUpdateNpmError(`npm run ${scriptName}`, "check", result));
+    }
+    scriptsRun.push(scriptName);
+  }
+  return {
+    ok: true,
+    packageName: CLI_PACKAGE_NAME,
+    requestedVersion: version,
+    requestedLatest,
+    dependencySpec,
+    checkedVersion,
+    packageCheckSource,
+    dependencyUpdatedBy,
+    lockfileSanitized,
+    versionConventionUpdated: versionConvention.updated,
+    versionConventionPath: versionConvention.path,
+    scriptsRun,
+    skippedScripts,
+    diagnostics,
+    errors: []
+  };
+}
+
+/**
+ * @param {Record<string, any>} scripts
+ * @returns {string[]}
+ */
+function packageUpdateCliScriptsToRun(scripts) {
+  const selected = [];
+  for (const scriptName of PACKAGE_UPDATE_CLI_INFO_SCRIPTS) {
+    if (Object.prototype.hasOwnProperty.call(scripts, scriptName)) {
+      selected.push(scriptName);
+    }
+  }
+  const verificationScript = PACKAGE_UPDATE_CLI_VERIFICATION_SCRIPTS.find((scriptName) =>
+    Object.prototype.hasOwnProperty.call(scripts, scriptName)
+  );
+  if (verificationScript) {
+    selected.push(verificationScript);
+  }
+  return selected;
+}
+
+/**
+ * @param {string} cwd
+ * @param {Array<Record<string, any>>} diagnostics
+ * @returns {string}
+ */
+function resolveLatestTopogramCliVersionForPackageUpdate(cwd, diagnostics) {
+  try {
+    return latestTopogramCliVersion(cwd);
+  } catch (error) {
+    throw new Error(messageFromError(error));
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} version
+ * @returns {{ updated: boolean, path: string|null }}
+ */
+function writeTopogramCliVersionConventionIfPresent(cwd, version) {
+  const versionPath = path.join(cwd, "topogram-cli.version");
+  if (!fs.existsSync(versionPath)) {
+    return { updated: false, path: null };
+  }
+  fs.writeFileSync(versionPath, `${version}\n`, "utf8");
+  return { updated: true, path: versionPath };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Record<string, any>}
+ */
+function readPackageJsonForUpdate(cwd) {
+  const packagePath = path.join(cwd, "package.json");
+  if (!fs.existsSync(packagePath)) {
+    throw new Error("topogram package update-cli must be run from a package directory with package.json.");
+  }
+  return JSON.parse(fs.readFileSync(packagePath, "utf8"));
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} version
+ * @param {string} dependencySpec
+ * @returns {{ packageJsonUpdated: boolean, lockfileUpdated: boolean }}
+ */
+function updateTopogramCliDependencyFiles(cwd, version, dependencySpec) {
+  const packagePath = path.join(cwd, "package.json");
+  const packageJson = readPackageJsonForUpdate(cwd);
+  const hasDevDependency = packageJson.devDependencies &&
+    typeof packageJson.devDependencies === "object" &&
+    Object.prototype.hasOwnProperty.call(packageJson.devDependencies, CLI_PACKAGE_NAME);
+  const hasDependency = packageJson.dependencies &&
+    typeof packageJson.dependencies === "object" &&
+    Object.prototype.hasOwnProperty.call(packageJson.dependencies, CLI_PACKAGE_NAME);
+  const hasVersionConvention = fs.existsSync(path.join(cwd, "topogram-cli.version"));
+  const shouldUpdatePackageJson = hasDevDependency || hasDependency || !hasVersionConvention;
+  if (!shouldUpdatePackageJson) {
+    return { packageJsonUpdated: false, lockfileUpdated: false };
+  }
+  if (hasDependency && !hasDevDependency) {
+    packageJson.dependencies[CLI_PACKAGE_NAME] = dependencySpec.slice(`${CLI_PACKAGE_NAME}@`.length);
+  } else {
+    packageJson.devDependencies = packageJson.devDependencies && typeof packageJson.devDependencies === "object"
+      ? packageJson.devDependencies
+      : {};
+    packageJson.devDependencies[CLI_PACKAGE_NAME] = dependencySpec.slice(`${CLI_PACKAGE_NAME}@`.length);
+  }
+  if (hasDevDependency && packageJson.dependencies && typeof packageJson.dependencies === "object") {
+    delete packageJson.dependencies[CLI_PACKAGE_NAME];
+  }
+  fs.writeFileSync(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
+
+  const lockPath = path.join(cwd, "package-lock.json");
+  if (!fs.existsSync(lockPath)) {
+    return { packageJsonUpdated: true, lockfileUpdated: false };
+  }
+  const lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+  lock.packages = lock.packages && typeof lock.packages === "object" ? lock.packages : {};
+  lock.packages[""] = lock.packages[""] && typeof lock.packages[""] === "object" ? lock.packages[""] : {};
+  const rootEntry = lock.packages[""];
+  const lockHasDependency = rootEntry.dependencies &&
+    typeof rootEntry.dependencies === "object" &&
+    Object.prototype.hasOwnProperty.call(rootEntry.dependencies, CLI_PACKAGE_NAME);
+  if (lockHasDependency && !hasDevDependency) {
+    rootEntry.dependencies[CLI_PACKAGE_NAME] = dependencySpec.slice(`${CLI_PACKAGE_NAME}@`.length);
+  } else {
+    rootEntry.devDependencies = rootEntry.devDependencies && typeof rootEntry.devDependencies === "object"
+      ? rootEntry.devDependencies
+      : {};
+    rootEntry.devDependencies[CLI_PACKAGE_NAME] = dependencySpec.slice(`${CLI_PACKAGE_NAME}@`.length);
+  }
+  if ((hasDevDependency || !lockHasDependency) && rootEntry.dependencies && typeof rootEntry.dependencies === "object") {
+    delete lock.packages[""].dependencies[CLI_PACKAGE_NAME];
+  }
+  const entryPath = `node_modules/${CLI_PACKAGE_NAME}`;
+  const existingEntry = lock.packages[entryPath] && typeof lock.packages[entryPath] === "object"
+    ? lock.packages[entryPath]
+    : {};
+  lock.packages[entryPath] = {
+    ...existingEntry,
+    version,
+    dev: true,
+    license: existingEntry.license || "Apache-2.0",
+    bin: existingEntry.bin || { topogram: "src/cli.js" },
+    engines: existingEntry.engines || { node: ">=20" }
+  };
+  delete lock.packages[entryPath].resolved;
+  delete lock.packages[entryPath].integrity;
+  fs.writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+  return { packageJsonUpdated: true, lockfileUpdated: true };
+}

package/src/cli/commands/package/versions.js

@@ -0,0 +1,35 @@
+// @ts-check
+
+/**
+ * @param {string} left
+ * @param {string} right
+ * @returns {number}
+ */
+export function compareSemver(left, right) {
+  const leftParts = left.split(/[.-]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+  const rightParts = right.split(/[.-]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] > rightParts[index]) return 1;
+    if (leftParts[index] < rightParts[index]) return -1;
+  }
+  return 0;
+}
+
+/**
+ * @param {string|null} value
+ * @returns {string|null}
+ */
+export function normalizeRegistryUrl(value) {
+  if (!value) {
+    return null;
+  }
+  return value.trim().replace(/\/+$/, "");
+}
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isPackageVersion(value) {
+  return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(value);
+}

package/src/cli/commands/package.js

@@ -0,0 +1,31 @@
+// @ts-check
+
+export {
+  CLI_PACKAGE_NAME,
+  NPMJS_REGISTRY
+} from "./package/constants.js";
+export {
+  checkDoctorNode,
+  checkDoctorNpm,
+  checkDoctorPackageAccess,
+  checkTemplatePackageStatus,
+  isLocalCliDependencySpec,
+  localTemplatePackageStatus,
+  npmConfigGet,
+  readInstalledCliPackageVersion,
+  readProjectCliDependencySpec,
+  registryPackageNameFromSpec
+} from "./package/doctor.js";
+export { printPackageHelp } from "./package/help.js";
+export { inspectTopogramCliLockfile } from "./package/lockfile.js";
+export {
+  latestTopogramCliVersion,
+  runNpmForPackageUpdate
+} from "./package/npm.js";
+export { printPackageUpdateCli } from "./package/reporting.js";
+export { runPackageCommand } from "./package/runner.js";
+export { buildPackageUpdateCliPayload } from "./package/update-cli.js";
+export {
+  isPackageVersion,
+  normalizeRegistryUrl
+} from "./package/versions.js";

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