@topogram/cli 0.3.63 → 0.3.65

package/src/cli/dispatcher.js

@@ -0,0 +1,392 @@
+// @ts-check
+
+import { buildDoctorPayload, printDoctor } from "./commands/doctor.js";
+import { buildVersionPayload, printVersion } from "./commands/version.js";
+import { runAgentBriefCommand } from "./commands/agent.js";
+import { runCatalogCommand } from "./commands/catalog.js";
+import { runCheckCommand } from "./commands/check.js";
+import { runEmitCommand } from "./commands/emit.js";
+import { runGenerateAppCommand } from "./commands/generate.js";
+import { runGeneratorCommand } from "./commands/generator.js";
+import { runGeneratorPolicyCommand } from "./commands/generator-policy.js";
+import { runImportCommand } from "./commands/import-runner.js";
+import { runNewProjectCommand } from "./commands/new.js";
+import { runPackageCommand } from "./commands/package.js";
+import { runParseCommand, runResolveCommand } from "./commands/inspect.js";
+import {
+  buildQueryListPayload,
+  buildQueryShowPayload,
+  printQueryDefinition,
+  printQueryList,
+  runQueryCommand
+} from "./commands/query.js";
+import { runReleaseCommand } from "./commands/release.js";
+import { runSdlcCommand } from "./commands/sdlc.js";
+import { runSourceCommand } from "./commands/source.js";
+import { runTemplateCommand } from "./commands/template-runner.js";
+import { runTrustCommand } from "./commands/trust.js";
+import {
+  runWidgetBehaviorCommand,
+  runWidgetCheckCommand
+} from "./commands/widget.js";
+import {
+  runLegacyWorkflowCommand,
+  runValidateCommand
+} from "./commands/workflow.js";
+import { artifactTargetMigrationError } from "./migration-guidance.js";
+import {
+  normalizeProjectRoot,
+  normalizeTopogramPath
+} from "./path-normalization.js";
+import { printQueryHelp, printUsage } from "./help-dispatch.js";
+import { stableStringify } from "../format.js";
+
+/**
+ * @typedef {Record<string, any>} CommandArgs
+ * @typedef {Record<string, any>} CliOptions
+ */
+
+/**
+ * Preserve legacy runtime behavior while satisfying the checked JS boundary.
+ * Some command paths intentionally let downstream commands produce the missing
+ * argument diagnostic.
+ *
+ * @param {string|null|undefined} value
+ * @returns {string}
+ */
+function commandInputPath(value) {
+  return /** @type {string} */ (value);
+}
+
+/**
+ * @param {{
+ *   args: string[],
+ *   commandArgs: CommandArgs|null,
+ *   inputPath: string|null|undefined,
+ *   cliOptions: CliOptions,
+ *   executablePath: string
+ * }} context
+ * @returns {Promise<number>}
+ */
+export async function runCliDispatch(context) {
+  const { args, commandArgs, cliOptions, executablePath } = context;
+  let inputPath = context.inputPath;
+  const {
+    emitJson,
+    shouldForce,
+    shouldValidate,
+    shouldResolve,
+    generateTarget,
+    workflowName,
+    workflowId,
+    fromValue,
+    adoptValue,
+    reasonValue,
+    modeId,
+    profileId,
+    providerId,
+    presetId,
+    templateName,
+    catalogSource,
+    requestedVersion,
+    bundleSlug,
+    laneId,
+    fromSnapshotPath,
+    fromTopogramPath,
+    shouldWrite,
+    refreshAdopted,
+    outPath,
+    effectiveOutDir
+  } = cliOptions;
+  const {
+    shapeId,
+    capabilityId,
+    projectionId,
+    widgetId: componentId,
+    entityId,
+    journeyId,
+    surfaceId,
+    domainId,
+    seamId,
+    taskId,
+    pitchId,
+    requirementId,
+    acceptanceId,
+    bugId,
+    documentId,
+    kind: sdlcKind,
+    appVersion: sdlcAppVersion,
+    sinceTag: sdlcSinceTag,
+    includeArchived: sdlcIncludeArchived
+  } = cliOptions.selectors;
+  const shouldVersion = Boolean(commandArgs?.version);
+  const shouldDoctor = Boolean(commandArgs?.doctor);
+  const shouldCheck = Boolean(commandArgs?.check);
+  const shouldWidgetCheck = Boolean(commandArgs?.widgetCheck);
+  const shouldWidgetBehavior = Boolean(commandArgs?.widgetBehavior);
+  const shouldAgentBrief = Boolean(commandArgs?.agentBrief);
+  const shouldQueryList = Boolean(commandArgs?.queryList);
+  const shouldQueryShow = Boolean(commandArgs?.queryShow);
+  const targetMigrationError = artifactTargetMigrationError(generateTarget);
+  if (targetMigrationError) {
+    console.error(targetMigrationError);
+    return 1;
+  }
+
+  if ((shouldCheck || shouldWidgetCheck || shouldWidgetBehavior || commandArgs?.generatorPolicyCommand || shouldValidate || commandArgs?.trustCommand || commandArgs?.sourceCommand || generateTarget === "app-bundle") && !inputPath) {
+    console.error("Missing required <path>.");
+    printUsage();
+    return 1;
+  }
+
+  if (shouldQueryShow && !commandArgs?.queryShowName) {
+    console.error("Missing required <name>.");
+    printQueryHelp();
+    return 1;
+  }
+
+  if ((shouldCheck || shouldWidgetCheck || shouldWidgetBehavior || shouldAgentBrief || shouldValidate || commandArgs?.generatorPolicyCommand || commandArgs?.trustCommand || generateTarget === "app-bundle") && inputPath) {
+    inputPath = normalizeTopogramPath(inputPath);
+  }
+  const effectiveInputPath = commandInputPath(inputPath);
+
+  if (shouldVersion) {
+    const payload = buildVersionPayload({ executablePath });
+    if (emitJson) {
+      console.log(stableStringify(payload));
+    } else {
+      printVersion(payload);
+    }
+    return 0;
+  }
+
+  if (shouldDoctor) {
+    const payload = buildDoctorPayload(catalogSource || inputPath || null);
+    if (emitJson) {
+      console.log(stableStringify(payload));
+    } else {
+      printDoctor(payload);
+    }
+    return payload.ok ? 0 : 1;
+  }
+
+  if (shouldAgentBrief) {
+    return runAgentBriefCommand(effectiveInputPath, { json: emitJson });
+  }
+
+  if (commandArgs?.releaseCommand) {
+    return runReleaseCommand({ commandArgs, args, json: emitJson });
+  }
+
+  if (shouldQueryList) {
+    const payload = buildQueryListPayload();
+    if (emitJson) {
+      console.log(stableStringify(payload));
+    } else {
+      printQueryList(payload);
+    }
+    return 0;
+  }
+
+  if (shouldQueryShow) {
+    const payload = buildQueryShowPayload(/** @type {string} */ (commandArgs?.queryShowName));
+    if (emitJson) {
+      console.log(stableStringify(payload));
+    } else {
+      printQueryDefinition(payload);
+    }
+    return 0;
+  }
+
+  if (shouldWidgetCheck) {
+    return runWidgetCheckCommand(effectiveInputPath, {
+      json: emitJson,
+      projectionId,
+      widgetId: componentId
+    });
+  }
+
+  if (shouldWidgetBehavior) {
+    return runWidgetBehaviorCommand(effectiveInputPath, {
+      json: emitJson,
+      projectionId,
+      widgetId: componentId
+    });
+  }
+
+  if (commandArgs?.generatorCommand) {
+    return runGeneratorCommand({
+      commandArgs,
+      inputPath,
+      json: emitJson,
+      cwd: process.cwd()
+    });
+  }
+
+  if (commandArgs?.generatorPolicyCommand) {
+    return runGeneratorPolicyCommand({ commandArgs, inputPath, json: emitJson });
+  }
+
+  if (commandArgs?.catalogCommand) {
+    return runCatalogCommand({
+      commandArgs,
+      inputPath,
+      catalogSource,
+      requestedVersion,
+      json: emitJson
+    });
+  }
+
+  if (commandArgs?.packageCommand) {
+    return runPackageCommand({ commandArgs, inputPath, json: emitJson });
+  }
+
+  if (commandArgs?.importCommand) {
+    return runImportCommand({
+      commandArgs,
+      inputPath,
+      outPath,
+      fromValue,
+      reasonValue,
+      refreshAdopted,
+      dryRun: args.includes("--dry-run"),
+      write: shouldWrite,
+      force: shouldForce,
+      json: emitJson
+    });
+  }
+
+  if (commandArgs?.sourceCommand) {
+    return runSourceCommand({ commandArgs, inputPath, args, json: emitJson });
+  }
+
+  if (commandArgs?.newProject) {
+    return runNewProjectCommand(effectiveInputPath, { templateName, catalogSource, cwd: process.cwd() });
+  }
+
+  if (commandArgs?.templateCommand) {
+    return runTemplateCommand({
+      commandArgs,
+      args,
+      inputPath,
+      catalogSource,
+      templateName,
+      outPath,
+      json: emitJson
+    });
+  }
+
+  if (commandArgs?.trustCommand) {
+    return runTrustCommand({ commandArgs, inputPath, json: emitJson });
+  }
+
+  if (shouldCheck) {
+    return runCheckCommand(effectiveInputPath, { json: emitJson });
+  }
+
+  if (commandArgs?.queryName || commandArgs?.workflowPresetCommand) {
+    return (await runQueryCommand({
+      commandArgs,
+      inputPath,
+      capabilityId,
+      workflowId,
+      projectionId,
+      componentId,
+      entityId,
+      journeyId,
+      surfaceId,
+      domainId,
+      seamId,
+      modeId,
+      providerId,
+      presetId,
+      bundleSlug,
+      laneId,
+      fromTopogramPath,
+      shouldWrite,
+      outPath
+    })) || 0;
+  }
+
+  if (commandArgs?.sdlcCommand) {
+    return runSdlcCommand({ commandArgs, args, inputPath });
+  }
+
+  if (workflowName) {
+    return runLegacyWorkflowCommand({
+      workflowName,
+      inputPath,
+      from: fromValue,
+      adopt: adoptValue,
+      write: shouldWrite,
+      refreshAdopted,
+      outDir: effectiveOutDir
+    });
+  }
+
+  if (generateTarget === "app-bundle" && shouldWrite && !commandArgs?.emitArtifact) {
+    return runGenerateAppCommand({
+      inputPath: effectiveInputPath,
+      projectRoot: normalizeProjectRoot(effectiveInputPath),
+      outDir: effectiveOutDir,
+      profileId
+    });
+  }
+
+  if (generateTarget) {
+    return runEmitCommand({
+      inputPath: effectiveInputPath,
+      projectRoot: normalizeProjectRoot(effectiveInputPath),
+      target: generateTarget,
+      write: shouldWrite,
+      outDir: effectiveOutDir,
+      profileId,
+      fromSnapshotPath,
+      fromTopogramPath,
+      selectors: {
+        shapeId,
+        capabilityId,
+        workflowId,
+        projectionId,
+        widgetId: componentId,
+        componentId,
+        entityId,
+        journeyId,
+        surfaceId,
+        domainId,
+        taskId,
+        pitchId,
+        requirementId,
+        acceptanceId,
+        bugId,
+        documentId,
+        kind: sdlcKind,
+        appVersion: sdlcAppVersion,
+        sinceTag: sdlcSinceTag,
+        includeArchived: sdlcIncludeArchived,
+        modeId
+      },
+      outputSelectors: {
+        shapeId,
+        capabilityId,
+        workflowId,
+        projectionId,
+        componentId,
+        entityId,
+        journeyId,
+        taskId,
+        modeId
+      }
+    });
+  }
+
+  if (shouldResolve) {
+    return runResolveCommand(inputPath);
+  }
+
+  if (shouldValidate) {
+    return runValidateCommand(inputPath);
+  }
+
+  return runParseCommand(inputPath, { json: emitJson });
+}

package/src/cli/help-dispatch.js

@@ -0,0 +1,188 @@
+// @ts-check
+
+import {
+  printAgentHelp
+} from "./commands/agent.js";
+import {
+  printCatalogHelp
+} from "./commands/catalog.js";
+import {
+  printCheckHelp
+} from "./commands/check.js";
+import {
+  printDoctorHelp
+} from "./commands/doctor.js";
+import {
+  printGeneratorHelp
+} from "./commands/generator.js";
+import {
+  printImportHelp
+} from "./commands/import.js";
+import {
+  printPackageHelp
+} from "./commands/package.js";
+import {
+  printQueryHelp
+} from "./commands/query.js";
+import {
+  printReleaseHelp
+} from "./commands/release.js";
+import {
+  printSetupHelp
+} from "./commands/setup.js";
+import {
+  printSourceHelp
+} from "./commands/source.js";
+import {
+  printTemplateHelp
+} from "./commands/template.js";
+import {
+  printTrustHelp
+} from "./commands/trust.js";
+import {
+  printEmitHelp,
+  printGenerateHelp,
+  printNewHelp,
+  printUsage,
+  printWidgetHelp
+} from "./help.js";
+
+/**
+ * @param {string|undefined} command
+ * @returns {boolean}
+ */
+export function printCommandHelp(command) {
+  if (command === "new" || command === "create") {
+    printNewHelp();
+    return true;
+  }
+  if (command === "generate") {
+    printGenerateHelp();
+    return true;
+  }
+  if (command === "emit") {
+    printEmitHelp();
+    return true;
+  }
+  if (command === "widget") {
+    printWidgetHelp();
+    return true;
+  }
+  if (command === "query") {
+    printQueryHelp();
+    return true;
+  }
+  if (command === "agent") {
+    printAgentHelp();
+    return true;
+  }
+  if (command === "generator") {
+    printGeneratorHelp();
+    return true;
+  }
+  if (command === "template") {
+    printTemplateHelp();
+    return true;
+  }
+  if (command === "catalog") {
+    printCatalogHelp();
+    return true;
+  }
+  if (command === "doctor") {
+    printDoctorHelp();
+    return true;
+  }
+  if (command === "setup") {
+    printSetupHelp();
+    return true;
+  }
+  if (command === "package") {
+    printPackageHelp();
+    return true;
+  }
+  if (command === "release") {
+    printReleaseHelp();
+    return true;
+  }
+  if (command === "source") {
+    printSourceHelp();
+    return true;
+  }
+  if (command === "trust") {
+    printTrustHelp();
+    return true;
+  }
+  if (command === "import") {
+    printImportHelp();
+    return true;
+  }
+  if (command === "check") {
+    printCheckHelp();
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @param {string[]} args
+ * @returns {number|null}
+ */
+export function handleGlobalHelp(args) {
+  if (args[0] === "help" && args[1] && args[1] !== "all" && printCommandHelp(args[1])) {
+    return 0;
+  }
+
+  if (args[0] !== "version" && (args.includes("--help") || args.includes("-h")) && printCommandHelp(args[0])) {
+    return 0;
+  }
+
+  if (args.length === 0 || (args[0] !== "version" && args.includes("--help")) || args.includes("-h") || args[0] === "help") {
+    printUsage({ all: args[1] === "all" || args.includes("--all") });
+    return args.length === 0 ? 1 : 0;
+  }
+
+  if (args[0] === "help-all") {
+    printUsage({ all: true });
+    return 0;
+  }
+
+  return null;
+}
+
+/**
+ * @param {string[]} args
+ * @returns {number|null}
+ */
+export function handleUnparsedCommandHelp(args) {
+  if (args[0] === "widget") {
+    printWidgetHelp();
+    return args[1] ? 1 : 0;
+  }
+  if (args[0] === "agent") {
+    printAgentHelp();
+    return args[1] ? 1 : 0;
+  }
+  if (args[0] === "generator") {
+    printGeneratorHelp();
+    return args[1] ? 1 : 0;
+  }
+  if (args[0] === "template") {
+    printTemplateHelp();
+    return args[1] ? 1 : 0;
+  }
+  if (args[0] === "import") {
+    printImportHelp();
+    return args[1] ? 1 : 0;
+  }
+  if (args[0] === "query") {
+    printQueryHelp();
+    return args[1] ? 1 : 0;
+  }
+  return null;
+}
+
+export {
+  printEmitHelp,
+  printQueryHelp,
+  printUsage
+};