@topogram/cli 0.3.63 → 0.3.65

package/src/cli/commands/check.js

@@ -0,0 +1,268 @@
+// @ts-check
+
+import { loadImplementationProvider } from "../../example-implementation.js";
+import { stableStringify } from "../../format.js";
+import { parsePath } from "../../parser.js";
+import {
+  formatProjectConfigErrors,
+  loadProjectConfig,
+  projectConfigOrDefault,
+  validateProjectConfig,
+  validateProjectOutputOwnership
+} from "../../project-config.js";
+import { resolveWorkspace } from "../../resolver.js";
+import { validateProjectImplementationTrust } from "../../template-trust.js";
+import { formatValidationErrors } from "../../validator.js";
+
+/**
+ * @typedef {Record<string, any>} AnyRecord
+ */
+
+/**
+ * @typedef {{ message: string, loc: any }} ValidationError
+ */
+
+/**
+ * @returns {void}
+ */
+export function printCheckHelp() {
+  console.log("Usage: topogram check [path] [--json]");
+  console.log("");
+  console.log("Validates Topogram files, project configuration, topology, generator compatibility, generator policy, output ownership, and template policy.");
+  console.log("");
+  console.log("Defaults: path is ./topogram.");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram check");
+  console.log("  topogram check --json");
+  console.log("  topogram check ./topogram");
+}
+
+/**
+ * @param {AnyRecord} component
+ * @returns {{ uses_api: string|null, uses_database: string|null }}
+ */
+function topologyComponentReferences(component) {
+  return {
+    uses_api: component.uses_api || null,
+    uses_database: component.uses_database || null
+  };
+}
+
+/**
+ * @param {AnyRecord} component
+ * @returns {unknown}
+ */
+function topologyComponentPort(component) {
+  return Object.prototype.hasOwnProperty.call(component, "port") ? component.port : null;
+}
+
+/**
+ * @param {AnyRecord|null|undefined} config
+ * @returns {{ outputs: Array<AnyRecord>, runtimes: Array<AnyRecord>, edges: Array<AnyRecord> }}
+ */
+function summarizeProjectTopology(config) {
+  const outputs = Object.entries(config?.outputs || {})
+    .map(([name, output]) => ({
+      name,
+      path: /** @type {AnyRecord} */ (output)?.path || null,
+      ownership: /** @type {AnyRecord} */ (output)?.ownership || null
+    }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+  const runtimeInputs = /** @type {Array<AnyRecord>} */ (config?.topology?.runtimes || []);
+  const runtimes = runtimeInputs
+    .map((component) => ({
+      id: component.id,
+      kind: component.kind,
+      projection: component.projection,
+      generator: {
+        id: component.generator?.id || null,
+        version: component.generator?.version || null
+      },
+      port: topologyComponentPort(component),
+      references: topologyComponentReferences(component)
+    }))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  /** @type {Array<AnyRecord>} */
+  const edges = runtimes.flatMap((component) => {
+    const references = [];
+    if (component.references.uses_api) {
+      references.push({
+        from: component.id,
+        to: component.references.uses_api,
+        type: "calls_api"
+      });
+    }
+    if (component.references.uses_database) {
+      references.push({
+        from: component.id,
+        to: component.references.uses_database,
+        type: "uses_database"
+      });
+    }
+    return references;
+  }).sort((left, right) => `${left.from}:${left.type}:${left.to}`.localeCompare(`${right.from}:${right.type}:${right.to}`));
+  return {
+    outputs,
+    runtimes,
+    edges
+  };
+}
+
+/**
+ * @param {AnyRecord|null|undefined} topology
+ * @returns {AnyRecord|null}
+ */
+function publicProjectTopology(topology) {
+  if (!topology || typeof topology !== "object") {
+    return topology || null;
+  }
+  return {
+    ...Object.fromEntries(Object.entries(topology).filter(([key]) => key !== "components")),
+    runtimes: topology.runtimes || []
+  };
+}
+
+/**
+ * @param {AnyRecord} component
+ * @returns {string}
+ */
+function formatTopologyComponent(component) {
+  const generator = component.generator.id
+    ? `${component.generator.id}${component.generator.version ? `@${component.generator.version}` : ""}`
+    : "unbound generator";
+  const port = component.port == null ? "no port" : `port ${component.port}`;
+  const refs = Object.entries(component.references)
+    .filter(([, value]) => Boolean(value))
+    .map(([key, value]) => `${key} ${value}`);
+  const suffix = refs.length ? ` -> ${refs.join(", ")}` : "";
+  return `  - ${component.id}: ${component.kind} ${component.projection} via ${generator} (${port})${suffix}`;
+}
+
+/**
+ * @param {{ outputs: Array<AnyRecord>, runtimes: Array<AnyRecord>, edges: Array<AnyRecord> }} topology
+ * @returns {void}
+ */
+export function printTopologySummary(topology) {
+  console.log("Project topology:");
+  if (topology.outputs.length > 0) {
+    console.log("  Outputs:");
+    for (const output of topology.outputs) {
+      console.log(`  - ${output.name}: ${output.path || "unset"} (${output.ownership || "unknown"})`);
+    }
+  }
+  if (topology.runtimes.length > 0) {
+    console.log("  Runtimes:");
+    for (const component of topology.runtimes) {
+      console.log(formatTopologyComponent(component));
+    }
+  }
+  if (topology.edges.length > 0) {
+    console.log("  Edges:");
+    for (const edge of topology.edges) {
+      console.log(`  - ${edge.from} ${edge.type} ${edge.to}`);
+    }
+  }
+}
+
+/**
+ * @param {{ inputPath: string, ast: AnyRecord, resolved: AnyRecord, projectConfigInfo: AnyRecord|null|undefined, projectValidation: AnyRecord }} input
+ * @returns {AnyRecord}
+ */
+export function checkSummaryPayload({ inputPath, ast, resolved, projectConfigInfo, projectValidation }) {
+  const files = /** @type {Array<AnyRecord>} */ (ast.files || []);
+  const statementCount = files.flatMap((file) => file.statements).length;
+  const projectInfo = projectConfigInfo || {
+    configPath: null,
+    compatibility: false,
+    config: { topology: null }
+  };
+  const topogramErrors = resolved.ok
+    ? []
+    : /** @type {Array<AnyRecord>} */ (resolved.validation.errors || []);
+  const projectErrors = /** @type {Array<AnyRecord>} */ (projectValidation.errors || []);
+  const resolvedTopology = summarizeProjectTopology(projectInfo.config);
+  return {
+    ok: resolved.ok && projectValidation.ok,
+    inputPath,
+    topogram: {
+      files: files.length,
+      statements: statementCount,
+      valid: resolved.ok
+    },
+    project: {
+      configPath: projectInfo.configPath,
+      compatibility: Boolean(projectInfo.compatibility),
+      valid: projectValidation.ok,
+      topology: publicProjectTopology(projectInfo.config.topology),
+      resolvedTopology
+    },
+    errors: [
+      ...topogramErrors.map((error) => ({
+        source: "topogram",
+        message: error.message,
+        loc: error.loc
+      })),
+      ...projectErrors.map((error) => ({
+        source: "project",
+        message: error.message,
+        loc: error.loc
+      }))
+    ]
+  };
+}
+
+/**
+ * @param {...{ ok?: boolean, errors?: ValidationError[] }|null|undefined} results
+ * @returns {{ ok: boolean, errors: ValidationError[] }}
+ */
+export function combineProjectValidationResults(...results) {
+  /** @type {ValidationError[]} */
+  const errors = [];
+  for (const result of results) {
+    errors.push(...(result?.errors || []));
+  }
+  return {
+    ok: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * @param {string|null|undefined} inputPath
+ * @param {{ json?: boolean }} [options]
+ * @returns {Promise<number>}
+ */
+export async function runCheckCommand(inputPath, options = {}) {
+  const topogramPath = inputPath || "./topogram";
+  const ast = parsePath(topogramPath);
+  const resolved = resolveWorkspace(ast);
+  const implementation = await loadImplementationProvider(topogramPath).catch(() => null);
+  const explicitProjectConfig = loadProjectConfig(topogramPath);
+  const projectConfigInfo = explicitProjectConfig ||
+    (implementation ? projectConfigOrDefault(topogramPath, resolved.ok ? resolved.graph : null, implementation) : null);
+  const projectValidation = projectConfigInfo
+    ? combineProjectValidationResults(
+        validateProjectConfig(projectConfigInfo.config, resolved.ok ? resolved.graph : null, { configDir: projectConfigInfo.configDir }),
+        validateProjectOutputOwnership(projectConfigInfo),
+        validateProjectImplementationTrust(projectConfigInfo)
+      )
+    : { ok: false, errors: [{ message: "Missing topogram.project.json or compatible topogram.implementation.json", loc: null }] };
+  const payload = checkSummaryPayload({ inputPath: topogramPath, ast, resolved, projectConfigInfo, projectValidation });
+  if (options.json) {
+    console.log(stableStringify(payload));
+  } else if (payload.ok) {
+    console.log(`Topogram check passed for ${topogramPath}.`);
+    console.log(`Validated ${payload.topogram.files} file(s) and ${payload.topogram.statements} statement(s).`);
+    console.log(`Project config: ${payload.project.configPath || "compatibility defaults"}`);
+    printTopologySummary(payload.project.resolvedTopology);
+  } else {
+    if (!resolved.ok) {
+      console.error(formatValidationErrors(resolved.validation));
+    }
+    if (!projectValidation.ok) {
+      console.error(formatProjectConfigErrors(projectValidation, projectConfigInfo?.configPath || "topogram.project.json"));
+    }
+  }
+  return payload.ok ? 0 : 1;
+}

package/src/cli/commands/doctor.js

@@ -0,0 +1,268 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  catalogSourceOrDefault,
+  isCatalogSourceDisabled
+} from "../../catalog.js";
+import { LOCAL_NPMRC_ENV, localNpmrcStatus } from "../../npm-safety.js";
+import { loadProjectConfig } from "../../project-config.js";
+import {
+  buildCatalogDoctorAuth,
+  buildCatalogDoctorPayload
+} from "./catalog.js";
+import {
+  checkDoctorNode,
+  checkDoctorNpm,
+  checkDoctorPackageAccess,
+  CLI_PACKAGE_NAME,
+  inspectTopogramCliLockfile,
+  isLocalCliDependencySpec,
+  normalizeRegistryUrl,
+  NPMJS_REGISTRY,
+  npmConfigGet,
+  readInstalledCliPackageVersion,
+  readProjectCliDependencySpec
+} from "./package.js";
+
+/**
+ * @returns {void}
+ */
+export function printDoctorHelp() {
+  console.log("Usage: topogram doctor [--json] [--catalog <path-or-source>]");
+  console.log("");
+  console.log("Checks local runtime, npm, public package access, CLI lockfile metadata, and catalog access.");
+  console.log("");
+  console.log("Fresh install check:");
+  console.log("  npm install --save-dev @topogram/cli");
+  console.log("  npx topogram doctor");
+  console.log("  npx topogram template list");
+  console.log("  npx topogram new ./my-app --template hello-web");
+  console.log("");
+  console.log("Related setup commands:");
+  console.log("  topogram setup package-auth");
+  console.log("  topogram setup catalog-auth");
+  console.log("");
+  console.log("Examples:");
+  console.log("  topogram doctor");
+  console.log("  topogram doctor --json");
+  console.log("  topogram doctor --catalog ./topograms.catalog.json");
+  console.log("  topogram catalog doctor");
+  console.log("");
+  console.log("Use `catalog doctor` when you only want catalog/package-access diagnostics. Use `doctor --catalog` for the full environment check plus catalog diagnostics.");
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function messageFromError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * @param {string} inputPath
+ * @returns {string}
+ */
+function normalizeTopogramPath(inputPath) {
+  const absolute = path.resolve(inputPath);
+  if (path.basename(absolute) === "topogram") {
+    return absolute;
+  }
+  const candidate = path.join(absolute, "topogram");
+  return fs.existsSync(candidate) ? candidate : absolute;
+}
+
+/**
+ * @param {string|null} source
+ * @returns {{ ok: boolean, node: ReturnType<typeof checkDoctorNode>, npm: ReturnType<typeof checkDoctorNpm>, localNpmrc: ReturnType<typeof localNpmrcStatus>, packageRegistry: { required: boolean, reason: string|null, registry: string, configuredRegistry: string|null, registryConfigured: boolean, nodeAuthTokenEnv: boolean, packageName: string, packageSpec: string|null, packageAccess: { ok: boolean, checkedVersion: string|null, diagnostics: any[] } }, lockfile: ReturnType<typeof inspectTopogramCliLockfile>, catalog: ReturnType<typeof buildCatalogDoctorPayload>, diagnostics: any[], errors: string[] }}
+ */
+export function buildDoctorPayload(source) {
+  const projectCliDependency = readProjectCliDependencySpec(process.cwd());
+  const packageRegistryRequired = !isLocalCliDependencySpec(projectCliDependency);
+  const node = checkDoctorNode();
+  const npm = checkDoctorNpm();
+  const configuredRegistry = npm.available ? npmConfigGet("@topogram:registry") : null;
+  const registryConfigured = !configuredRegistry ||
+    normalizeRegistryUrl(configuredRegistry) === normalizeRegistryUrl(NPMJS_REGISTRY);
+  const registryDiagnostics = [];
+  if (packageRegistryRequired && npm.available && !registryConfigured) {
+    registryDiagnostics.push({
+      code: "package_registry_registry_not_configured",
+      severity: "error",
+      message: `npm is configured to resolve @topogram packages from '${configuredRegistry}', not ${NPMJS_REGISTRY}.`,
+      path: ".npmrc",
+      suggestedFix: "Remove the custom @topogram registry config or set it to https://registry.npmjs.org, then rerun `topogram doctor`."
+    });
+  }
+  const packageSpec = packageRegistryRequired ? `${CLI_PACKAGE_NAME}@${readInstalledCliPackageVersion()}` : null;
+  const packageAccess = packageRegistryRequired && npm.available
+    ? checkDoctorPackageAccess(packageSpec || CLI_PACKAGE_NAME)
+    : packageRegistryRequired ? {
+        ok: false,
+        checkedVersion: null,
+        diagnostics: [{
+          code: "npm_not_found",
+          severity: "error",
+          message: "npm is required to inspect the Topogram CLI package.",
+          path: null,
+          suggestedFix: "Install Node.js/npm, then rerun `topogram doctor`."
+        }]
+      } : {
+        ok: true,
+        checkedVersion: null,
+        diagnostics: []
+      };
+  const catalog = buildDoctorCatalogPayload(source);
+  const lockfile = inspectTopogramCliLockfile(process.cwd());
+  const diagnostics = [
+    ...node.diagnostics,
+    ...npm.diagnostics,
+    ...registryDiagnostics,
+    ...packageAccess.diagnostics,
+    ...lockfile.diagnostics,
+    ...catalog.diagnostics
+  ];
+  const errors = diagnostics
+    .filter((diagnostic) => diagnostic.severity === "error")
+    .map((diagnostic) => diagnostic.message);
+  return {
+    ok: errors.length === 0,
+    node,
+    npm,
+    localNpmrc: localNpmrcStatus(process.cwd()),
+    packageRegistry: {
+      required: packageRegistryRequired,
+      reason: packageRegistryRequired ? null : `Project uses local CLI dependency '${projectCliDependency}'.`,
+      registry: NPMJS_REGISTRY,
+      configuredRegistry,
+      registryConfigured,
+      nodeAuthTokenEnv: Boolean(process.env.NODE_AUTH_TOKEN),
+      packageName: CLI_PACKAGE_NAME,
+      packageSpec,
+      packageAccess
+    },
+    lockfile,
+    catalog,
+    diagnostics,
+    errors
+  };
+}
+
+/**
+ * @param {string|null} source
+ * @returns {ReturnType<typeof buildCatalogDoctorPayload>}
+ */
+function buildDoctorCatalogPayload(source) {
+  const resolvedSource = resolveDoctorCatalogSource(source);
+  if (isCatalogSourceDisabled(resolvedSource)) {
+    return {
+      ok: true,
+      source: resolvedSource,
+      auth: buildCatalogDoctorAuth(resolvedSource),
+      catalog: {
+        reachable: false,
+        version: null,
+        entries: 0
+      },
+      packages: [],
+      diagnostics: [{
+        code: "catalog_check_skipped",
+        severity: "warning",
+        message: "Catalog access check was skipped for this project.",
+        path: null,
+        suggestedFix: "Pass --catalog <source> to check a catalog explicitly."
+      }],
+      errors: []
+    };
+  }
+  return buildCatalogDoctorPayload(resolvedSource);
+}
+
+/**
+ * @param {string|null} source
+ * @returns {string}
+ */
+function resolveDoctorCatalogSource(source) {
+  if (source) {
+    return source;
+  }
+  const projectConfigInfo = loadProjectConfig(normalizeTopogramPath(process.cwd()));
+  if (projectConfigInfo) {
+    const catalog = projectConfigInfo.config?.template?.catalog;
+    if (catalog && typeof catalog.source === "string" && catalog.source) {
+      return catalog.source;
+    }
+    return "none";
+  }
+  return catalogSourceOrDefault(null);
+}
+
+/**
+ * @param {ReturnType<typeof buildDoctorPayload>} payload
+ * @returns {void}
+ */
+function printDoctorSetupGuidance(payload) {
+  console.log("Setup guidance:");
+  if (payload.packageRegistry.required) {
+    console.log(`- CLI package access: public @topogram packages should install from ${payload.packageRegistry.registry} without auth.`);
+  } else {
+    console.log("- CLI package auth: skipped because this project uses a local Topogram CLI dependency.");
+  }
+  if (isCatalogSourceDisabled(payload.catalog.source)) {
+    console.log("- Catalog auth: skipped because catalog discovery is disabled for this project.");
+  } else {
+    console.log("- Catalog auth: the default catalog is public; private catalogs should use GITHUB_TOKEN or GH_TOKEN. Local `gh auth login` is only a no-token fallback.");
+  }
+  console.log("- Template package auth: private template packages may need registry-specific npm auth during npm install.");
+  console.log(`- Local .npmrc: ignored by default. Use --allow-local-npmrc or ${LOCAL_NPMRC_ENV}=1 only after reviewing the file.`);
+  console.log("- Catalog disabled mode: TOPOGRAM_CATALOG_SOURCE=none skips catalog aliases, including the default hello-web starter.");
+}
+
+/**
+ * @param {ReturnType<typeof buildDoctorPayload>} payload
+ * @returns {void}
+ */
+export function printDoctor(payload) {
+  console.log(payload.ok ? "Topogram doctor passed." : "Topogram doctor found issues.");
+  console.log(`Node: ${payload.node.version} (${payload.node.ok ? "ok" : `requires ${payload.node.minimum}`})`);
+  console.log(`npm: ${payload.npm.available ? `${payload.npm.version || "available"} (ok)` : "not found"}`);
+  console.log(`local .npmrc: ${payload.localNpmrc.exists ? (payload.localNpmrc.enabled ? "enabled" : "ignored") : "not found"}`);
+  if (payload.localNpmrc.exists) {
+    console.log(`local .npmrc reason: ${payload.localNpmrc.reason}`);
+  }
+  console.log(`npm registry: ${payload.packageRegistry.required ? (payload.packageRegistry.registryConfigured ? "ok" : "misconfigured") : "not required"}`);
+  if (payload.packageRegistry.reason) {
+    console.log(`npm registry reason: ${payload.packageRegistry.reason}`);
+  }
+  if (payload.packageRegistry.configuredRegistry) {
+    console.log(`Configured @topogram registry: ${payload.packageRegistry.configuredRegistry}`);
+  }
+  console.log(`CLI package access: ${payload.packageRegistry.required ? (payload.packageRegistry.packageAccess.ok ? `${payload.packageRegistry.packageSpec} ok` : `${payload.packageRegistry.packageSpec} failed`) : "not checked"}`);
+  if (payload.lockfile.checked && payload.lockfile.packageVersion) {
+    console.log(`CLI lockfile: ${payload.lockfile.packageVersion}${payload.lockfile.refreshRecommended ? " (refresh recommended)" : " (ok)"}`);
+  }
+  console.log(`Catalog source: ${payload.catalog.source}`);
+  console.log(`Catalog reachable: ${payload.catalog.catalog.reachable ? "yes" : "no"}`);
+  if (payload.catalog.catalog.reachable) {
+    console.log(`Catalog entries: ${payload.catalog.catalog.entries}`);
+    const failedPackages = payload.catalog.packages.filter((item) => !item.ok).length;
+    console.log(`Catalog package access: ${failedPackages === 0 ? "ok" : `${failedPackages} failed`}`);
+  }
+  if (payload.catalog.source !== "none" || payload.catalog.catalog.reachable || payload.packageRegistry.required) {
+    console.log("Project provenance: run `topogram source status --local` for catalog, template, trust, and baseline details.");
+  }
+  printDoctorSetupGuidance(payload);
+  if (payload.diagnostics.length > 0) {
+    console.log("Diagnostics:");
+    for (const diagnostic of payload.diagnostics) {
+      const label = diagnostic.severity === "warning" ? "Warning" : "Error";
+      console.log(`- ${label}: ${diagnostic.message}`);
+      if (diagnostic.suggestedFix) {
+        console.log(`  Fix: ${diagnostic.suggestedFix}`);
+      }
+    }
+  }
+}

package/src/cli/commands/emit.js

@@ -0,0 +1,149 @@
+// @ts-check
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { loadImplementationProvider } from "../../example-implementation.js";
+import { stableStringify } from "../../format.js";
+import { buildOutputFiles, generateWorkspace } from "../../generator.js";
+import { parsePath } from "../../parser.js";
+import {
+  formatProjectConfigErrors,
+  loadProjectConfig,
+  projectConfigOrDefault,
+  validateProjectConfig
+} from "../../project-config.js";
+import { resolveWorkspace } from "../../resolver.js";
+import { formatValidationErrors } from "../../validator.js";
+import {
+  assertProjectOutputAllowsWrite,
+  assertSafeGeneratedOutputDir,
+  GENERATED_OUTPUT_SENTINEL,
+  generatedOutputSentinel,
+  topogramInputPathForGeneration
+} from "../output-safety.js";
+
+const IMPLEMENTATION_PROVIDER_TARGETS = new Set([
+  "persistence-scaffold",
+  "hono-server",
+  "express-server",
+  "sveltekit-app",
+  "environment-plan",
+  "environment-bundle",
+  "deployment-plan",
+  "deployment-bundle",
+  "runtime-smoke-plan",
+  "runtime-smoke-bundle",
+  "runtime-check-plan",
+  "runtime-check-bundle",
+  "compile-check-plan",
+  "compile-check-bundle",
+  "app-bundle-plan",
+  "app-bundle",
+  "native-parity-plan",
+  "native-parity-bundle"
+]);
+
+const IMPLEMENTATION_OPTIONAL_TARGETS = new Set([
+  "app-bundle-plan",
+  "app-bundle",
+  "environment-plan",
+  "environment-bundle",
+  "compile-check-plan",
+  "compile-check-bundle"
+]);
+
+/**
+ * @param {string} target
+ * @returns {boolean}
+ */
+function targetRequiresImplementationProvider(target) {
+  return IMPLEMENTATION_PROVIDER_TARGETS.has(target);
+}
+
+/**
+ * @param {{
+ *   inputPath: string,
+ *   projectRoot: string,
+ *   target: string,
+ *   write?: boolean,
+ *   outDir?: string|null,
+ *   selectors?: Record<string, any>,
+ *   outputSelectors?: Record<string, any>,
+ *   profileId?: string|null,
+ *   fromSnapshotPath?: string|null,
+ *   fromTopogramPath?: string|null
+ * }} options
+ * @returns {Promise<number>}
+ */
+export async function runEmitCommand(options) {
+  const ast = parsePath(options.inputPath);
+  const explicitProjectConfig = loadProjectConfig(options.projectRoot) || loadProjectConfig(options.inputPath);
+  const shouldLoadImplementation = targetRequiresImplementationProvider(options.target) &&
+    (!IMPLEMENTATION_OPTIONAL_TARGETS.has(options.target) || Boolean(explicitProjectConfig?.config?.implementation));
+  const implementation = shouldLoadImplementation
+    ? await loadImplementationProvider(explicitProjectConfig?.configDir || options.projectRoot)
+    : null;
+  const resolvedForConfig = targetRequiresImplementationProvider(options.target) || explicitProjectConfig
+    ? resolveWorkspace(ast)
+    : null;
+  if (resolvedForConfig && !resolvedForConfig.ok) {
+    console.error(formatValidationErrors(resolvedForConfig.validation));
+    return 1;
+  }
+  const projectConfigInfo = resolvedForConfig
+    ? (explicitProjectConfig || projectConfigOrDefault(options.projectRoot, resolvedForConfig.graph, implementation))
+    : null;
+  const projectConfigValidation = projectConfigInfo
+    ? validateProjectConfig(projectConfigInfo.config, resolvedForConfig?.graph || null, { configDir: projectConfigInfo.configDir })
+    : { ok: true, errors: [] };
+  if (!projectConfigValidation.ok) {
+    console.error(formatProjectConfigErrors(projectConfigValidation, projectConfigInfo?.configPath || "topogram.project.json"));
+    return 1;
+  }
+
+  const result = generateWorkspace(ast, {
+    target: options.target,
+    ...(options.selectors || {}),
+    profileId: options.profileId,
+    fromSnapshot: options.fromSnapshotPath ? JSON.parse(fs.readFileSync(options.fromSnapshotPath, "utf8")) : null,
+    fromSnapshotPath: options.fromSnapshotPath,
+    fromTopogramPath: options.fromTopogramPath,
+    topogramInputPath: topogramInputPathForGeneration(options.inputPath),
+    implementation,
+    projectConfig: projectConfigInfo?.config || null,
+    configDir: projectConfigInfo?.configDir || options.projectRoot,
+    projectRoot: projectConfigInfo?.configDir || options.projectRoot
+  });
+  if (!result.ok) {
+    console.error(formatValidationErrors(result.validation));
+    return 1;
+  }
+
+  if (options.write) {
+    const resolvedOutDir = path.resolve(options.outDir || "artifacts");
+    assertProjectOutputAllowsWrite(projectConfigInfo, resolvedOutDir);
+    assertSafeGeneratedOutputDir(resolvedOutDir, options.inputPath);
+    const outputFiles = buildOutputFiles(result, options.outputSelectors || {});
+    outputFiles.unshift({
+      path: GENERATED_OUTPUT_SENTINEL,
+      contents: generatedOutputSentinel(options.target)
+    });
+    fs.rmSync(resolvedOutDir, { recursive: true, force: true });
+    fs.mkdirSync(resolvedOutDir, { recursive: true });
+
+    for (const file of outputFiles) {
+      const destination = path.join(resolvedOutDir, file.path);
+      fs.mkdirSync(path.dirname(destination), { recursive: true });
+      const contents =
+        typeof file.contents === "string" ? file.contents : `${stableStringify(file.contents)}\n`;
+      fs.writeFileSync(destination, contents, "utf8");
+    }
+
+    console.log(`Wrote ${outputFiles.length} file(s) to ${resolvedOutDir}`);
+    return 0;
+  }
+
+  console.log(typeof result.artifact === "string" ? result.artifact : stableStringify(result.artifact));
+  return 0;
+}