heximon 0.9.0 → 0.10.0

package/dist/index.d.mts

@@ -1,4 +1,122 @@
 import { CommandDef } from "citty";
+import { CompileMode, DiagnosticLabel, DiagnosticSeverity, DiagnosticSpan, ModuleGraphView } from "@heximon/compiler";
+import { TransactionCensusDocument } from "@heximon/cqrs/compiler";
+import { DatabaseApplyModeValue, DeployPhaseValue, PlatformTracingStatusValue } from "@heximon/deploy";
+import { RouteCensusGap, RouteCensusRow, RouteCensusScopeEnforcement } from "@heximon/http/compiler";
+//#region src/cli-json-document.d.ts
+/**
+ * The stable codes of the failures the CLI itself raises in a `--json` document. A compiler diagnostic keeps
+ * its own compiler code; these cover what happens around the compile.
+ */
+declare const CliDiagnosticCode: {
+  /** The command threw an error it does not expect. The message is the error message; stderr has the stack. */
+  readonly UnexpectedError: "cli.unexpected-error";
+  /** The command needs an answer that it would ask for in a prompt, and `--json` never prompts. */
+  readonly OptionRequired: "cli.option-required";
+  /** The options of the run contradict each other, or an option has a value the command cannot use. */
+  readonly InvalidOptions: "cli.invalid-options";
+  /** The `heximon.config.ts` sidecar threw when it was loaded. `file` names the sidecar. */
+  readonly ConfigUnreadable: "cli.config-unreadable";
+  /** The command could not start the child process that runs the app's TypeScript source. */
+  readonly ReexecFailed: "cli.reexec-failed";
+  /** The arguments do not fit the command: a missing positional, an unknown subcommand. stderr has the usage. */
+  readonly UsageError: "cli.usage-error";
+};
+/** One of the {@link CliDiagnosticCode} values. */
+type CliDiagnosticCode = (typeof CliDiagnosticCode)[keyof typeof CliDiagnosticCode];
+/**
+ * One finding in a `--json` document: a compiler diagnostic, or a failure the CLI raised. It has every field
+ * of the compiler's `Diagnostic`, plus the flat `file` / `line` / `column` of its primary source position.
+ */
+interface CliDiagnostic {
+  /** `error` fails the command; `warning` is advisory. */
+  readonly severity: DiagnosticSeverity;
+  /** The sentence that names the problem. */
+  readonly message: string;
+  /** A stable code to branch on: a compiler code, or a {@link CliDiagnosticCode}. */
+  readonly code?: string;
+  /** How to fix the problem. */
+  readonly hint?: string;
+  /** The absolute path of the source file the diagnostic points at. */
+  readonly file?: string;
+  /** The 1-based line in {@link file}, when the file could be read. */
+  readonly line?: number;
+  /** The 1-based column in {@link file}, when the file could be read. */
+  readonly column?: number;
+  /**
+   * The command-line option or environment variable the diagnostic is about: the one that answers a refused
+   * prompt, or the one whose value the command cannot use.
+   */
+  readonly option?: string;
+  /** A text location, used when there is no {@link span}. */
+  readonly location?: string;
+  /** The source offsets the compiler recorded. */
+  readonly span?: DiagnosticSpan;
+  /** Every span the compiler underlines, primary first. */
+  readonly labels?: readonly DiagnosticLabel[];
+  /** The original severity, when the project's `strictDiagnostics` escalated a warning. */
+  readonly escalatedFrom?: DiagnosticSeverity;
+}
+/**
+ * The fields every `--json` document shares. A command adds its own fields next to them. A failure is a
+ * document with `ok: false` and at least one error diagnostic.
+ */
+interface CliJsonDocument {
+  /** Whether the command succeeded. `false` always comes with a non-zero exit status. */
+  readonly ok: boolean;
+  /** Every diagnostic of the run, empty when there is none. */
+  readonly diagnostics: readonly CliDiagnostic[];
+}
+/**
+ * The document of a run that stopped before it had the fields of its command: an invalid option, a refused
+ * prompt, a config sidecar that threw, an unexpected error. Every command can print it in place of its own
+ * document, so a tool reads `ok` and `diagnostics` first and the command fields only when they are present.
+ */
+interface CliFailureDocument extends CliJsonDocument {
+  /** Always `false`. */
+  readonly ok: false;
+}
+//#endregion
+//#region src/check-json-document.d.ts
+/** The stable codes of the failures `heximon check` raises itself, beside the compiler's own. */
+declare const CheckDiagnosticCode: {
+  /** A consumed workspace library changed since its last `vp pack`, so the compile read an old manifest. */
+  readonly StaleLibrary: "check.stale-library";
+};
+/** One of the {@link CheckDiagnosticCode} values. */
+type CheckDiagnosticCode = (typeof CheckDiagnosticCode)[keyof typeof CheckDiagnosticCode];
+/** What `heximon check --update` did with the committed upgrade-safety baseline. */
+type CheckUpgradeBaselineResult = {
+  /** The baseline was not written: the compile has errors that leave its durable surface partly read. */
+  readonly written: false;
+  /** How many of those errors there are. */
+  readonly blockingErrors: number;
+} | {
+  /** The baseline was written or confirmed. */
+  readonly written: true;
+  /** Whether the file content changed, so there is something to commit. */
+  readonly changed: boolean;
+  /** The absolute path of the baseline file. */
+  readonly path: string;
+};
+/** The `heximon check --json` document. */
+interface CheckJsonDocument extends CliJsonDocument {
+  /** Which compile ran: `app`, or `library` for a published module package. */
+  readonly mode: CompileMode;
+  /** How many error diagnostics the run has. */
+  readonly errors: number;
+  /** How many warning diagnostics the run has. */
+  readonly warnings: number;
+  /** The transaction census of the compile, when the app declares command handlers. */
+  readonly transactionCensus?: TransactionCensusDocument;
+  /** The stale DI verdict mirror the library compile deleted. */
+  readonly prunedVerdicts?: string;
+  /** Where `--emit` wrote the generated wiring. */
+  readonly emittedTo?: string;
+  /** The `--update` outcome, present only with `--update`. */
+  readonly upgradeBaseline?: CheckUpgradeBaselineResult;
+}
+//#endregion
 //#region src/prompter.d.ts
 /** Thrown when the operator cancels an interactive prompt (Ctrl-C). */
 export declare class PromptCancelledError extends Error {
@@ -30,6 +148,48 @@ export declare class ClackPrompter implements Prompter {
   text(message: string): Promise<string>;
 }
 //#endregion
+//#region src/cli-entry.d.ts
+/**
+ * Starts the `heximon` command tree. Without a JSON flag it is citty's own `runMain`. With one, an argument
+ * error that citty raises before a command runs (a missing positional, an unknown subcommand) is printed as one
+ * {@link CliFailureDocument} on stdout, and the usage text goes to stderr. Any other error there is a
+ * `cli.unexpected-error` document, with the stack on stderr. Under a JSON request, stdout is on stderr from the
+ * start of the command until the process exits, and the documents reach the true stdout.
+ */
+export declare class CliEntry {
+  /** The flags that print usage; they keep citty's own output, JSON flag or not. */
+  private static readonly helpFlags;
+  /** The name citty gives its argument and command errors. */
+  private static readonly usageErrorName;
+  /** The output flags as every command declares them, so the entry reads them as the command's parser does. */
+  private static readonly outputFlags;
+  /**
+   * Run the command tree.
+   *
+   * @param main - The root command.
+   * @param rawArgs - The arguments after the binary name.
+   */
+  static run(main: CommandDef, rawArgs?: readonly string[]): Promise<void>;
+  /** Print an error raised before a command ran as a failure document. */
+  private static reportEntryError;
+  /** Print a {@link CliFailureDocument} with one diagnostic on the true stdout, and set exit status 1. */
+  private static fail;
+  /**
+   * Whether the arguments ask for JSON output: `--json`, or `--format json`. citty's own parser reads them,
+   * so `--no-json`, `--json=false`, a repeated `--format` and a `--` separator count as the command sees them.
+   *
+   * @param rawArgs - The arguments after the binary name.
+   * @returns Whether the run prints a JSON document.
+   */
+  static isJsonRequest(rawArgs: readonly string[]): boolean;
+  /** Whether a thrown value is a citty argument or command error. */
+  private static isUsageError;
+  /** The deepest subcommand the arguments name, with its parent, for the usage text. */
+  private static commandOf;
+  /** A citty `Resolvable`: the value, or what its function returns. */
+  private static resolve;
+}
+//#endregion
 //#region src/cli-environment.d.ts
 /** Detects how the CLI is being run, so the deploy credential ladder knows whether interactive prompting is safe. */
 export declare class CliEnvironment {
@@ -51,6 +211,14 @@ export declare class TemplateDownloadError extends Error {
   readonly gigetSource: string;
   constructor(gigetSource: string, cause: unknown);
 }
+/** A target directory that already holds content. `create` never overwrites, so it refuses the target. */
+export declare class ProjectDirectoryOccupiedError extends Error {
+  readonly projectDirectory: string;
+  /**
+   * @param projectDirectory - The absolute directory that is not empty.
+   */
+  constructor(projectDirectory: string);
+}
 /** The template axes `heximon create` offers: the app shape and the request-body validator. */
 interface TemplateSelection {
   /** The base template: the smallest real app, or the Drizzle/libsql CRUD app. */
@@ -95,6 +263,8 @@ interface ScaffoldResult {
   readonly projectDirectory: string;
   /** The resolved template directory name (e.g. `"minimal-zod"`). */
   readonly templateName: string;
+  /** Where the template content came from. */
+  readonly source: TemplateSource;
 }
 /**
  * Materializes a new Heximon project from a starters template: resolves the template directory name from
@@ -208,6 +378,7 @@ export declare class CreateDefaults {
    * @param validator - The `--validator` flag value, if any.
    * @param options - Whether prompting is allowed.
    * @returns The resolved selection, or `undefined` when the user cancelled a prompt.
+   * @throws CommandFailure when a flag names an unknown template or validator.
    */
   static resolveSelection(template: string | undefined, validator: string | undefined, options: {
     readonly interactive: boolean;
@@ -226,8 +397,16 @@ export declare class CreateDefaults {
    * @returns Whether a repository was initialized.
    */
   static initializeGit(projectDirectory: string): Promise<boolean>;
-  /** Run `<pm> install` in the project directory with inherited stdio (the user sees the real output). */
-  static runInstall(packageManager: string, projectDirectory: string): Promise<void>;
+  /**
+   * Run `<pm> install` in the project directory with inherited stdio (the user sees the real output).
+   *
+   * @param packageManager - The package manager binary.
+   * @param projectDirectory - The directory to install in.
+   * @param options - `stdoutToStderr` sends the child's stdout to stderr and gives it no stdin, for `--json`.
+   */
+  static runInstall(packageManager: string, projectDirectory: string, options?: {
+    readonly stdoutToStderr?: boolean;
+  }): Promise<void>;
   /** Run one starters attempt against a single giget ref. */
   private static attemptScaffold;
   /** Narrow a raw flag value to one of the allowed literals, or `undefined`. */
@@ -303,10 +482,698 @@ export declare class RegistryAccess {
   private static spawnProcess;
 }
 //#endregion
+//#region src/skills-json-document.d.ts
+/** The codes of the failures `heximon skills` raises in a `--json` document. */
+declare const SkillsDiagnosticCode: {
+  /** A source could not be installed: its index or one of its files did not download. */
+  readonly InstallFailed: "skills.install-failed";
+  /** The project's `package.json` is missing, or is not a JSON object. */
+  readonly ManifestUnreadable: "skills.manifest-unreadable";
+};
+/** One of the {@link SkillsDiagnosticCode} values. */
+type SkillsDiagnosticCode = (typeof SkillsDiagnosticCode)[keyof typeof SkillsDiagnosticCode];
+/** What `heximon skills add` did with the `heximon.skills` list in `package.json`. */
+declare const SkillSourceRecording: {
+  /** The source was not in the list, and the run added it. */
+  readonly Added: "added";
+  /** The source was in the list already; the run installed it again. */
+  readonly AlreadyRecorded: "already-recorded";
+  /** The install failed, so the run did not record the source. */
+  readonly NotRecorded: "not-recorded";
+};
+/** One of the {@link SkillSourceRecording} values. */
+type SkillSourceRecording = (typeof SkillSourceRecording)[keyof typeof SkillSourceRecording];
+/** One agent skill that a run installed into the project. */
+interface SkillJsonEntry {
+  /** The skill name from the index of the source. */
+  readonly name: string;
+  /** The base URL of the site the skill came from. */
+  readonly source: string;
+  /** The absolute directory the skill was written to, `<project>/.agents/skills/<name>`. */
+  readonly directory: string;
+  /** How many files of the skill were written. */
+  readonly fileCount: number;
+}
+/** The result of one recorded source in `heximon skills sync`. */
+interface SkillSourceJsonEntry {
+  /** The base URL from `heximon.skills`. */
+  readonly source: string;
+  /** Whether the install of this source succeeded. A failure has a diagnostic with the reason. */
+  readonly installed: boolean;
+}
+/** The `heximon skills add --json` document. */
+interface SkillsAddJsonDocument extends CliJsonDocument {
+  /** The absolute project root. */
+  readonly rootDir: string;
+  /** The source URL, without a trailing slash. */
+  readonly source: string;
+  /** What the run did with the `heximon.skills` list. */
+  readonly recording: SkillSourceRecording;
+  /** The skills the run installed; empty when the install failed. */
+  readonly skills: readonly SkillJsonEntry[];
+}
+/** The `heximon skills sync --json` document. */
+interface SkillsSyncJsonDocument extends CliJsonDocument {
+  /** The absolute project root. */
+  readonly rootDir: string;
+  /** Each recorded source in list order, with the result of its install. Empty when none is recorded. */
+  readonly sources: readonly SkillSourceJsonEntry[];
+  /** The skills of every source that installed, in list order. */
+  readonly skills: readonly SkillJsonEntry[];
+}
+//#endregion
+//#region src/create-json-document.d.ts
+/** The codes of the failures `heximon create` raises in a `--json` document. */
+declare const CreateDiagnosticCode: {
+  /** The target directory already holds files. `create` never overwrites. */
+  readonly TargetNotEmpty: "create.target-not-empty";
+  /** The starter template could not be downloaded, from the version branch or from `main`. */
+  readonly TemplateDownloadFailed: "create.template-download-failed";
+  /** The scaffold failed for another reason, for example a template without a `package.json`. */
+  readonly ScaffoldFailed: "create.scaffold-failed";
+  /** The registry check before the install failed, so the command did not install. The project stays. */
+  readonly RegistryAccessFailed: "create.registry-access-failed";
+  /** The dependency install exited with a non-zero status. The project stays. */
+  readonly InstallFailed: "create.install-failed";
+  /** A warning: the agent skill could not be fetched. The project is complete without it. */
+  readonly SkillsUnavailable: "create.skills-unavailable";
+};
+/** One of the {@link CreateDiagnosticCode} values. */
+type CreateDiagnosticCode = (typeof CreateDiagnosticCode)[keyof typeof CreateDiagnosticCode];
+/**
+ * The `heximon create --json` document. A failure before the project directory exists prints a
+ * {@link CliFailureDocument}; a failure after it has every field, so a tool knows what is on disk.
+ */
+interface CreateJsonDocument extends CliJsonDocument {
+  /** The project name: the directory name and the `package.json` name. */
+  readonly projectName: string;
+  /** The absolute root directory of the new project. */
+  readonly rootDir: string;
+  /** The base template. */
+  readonly template: TemplateSelection["template"];
+  /** The request-body validator of the template. */
+  readonly validator: TemplateSelection["validator"];
+  /** The starters directory name, for example `minimal-zod`. */
+  readonly templateName: string;
+  /** Where the template came from: the giget ref that succeeded, or the `--local` starters directory. */
+  readonly templateSource: TemplateSource;
+  /** The version stamped onto every `@heximon/*` range, or `workspace` for `workspace:*`. */
+  readonly heximonVersion: string;
+  /** The package manager of the install step and of {@link nextSteps}. */
+  readonly packageManager: string;
+  /** Whether the run created a git repository in the project. */
+  readonly gitInitialized: boolean;
+  /** Whether the run installed the dependencies. */
+  readonly dependenciesInstalled: boolean;
+  /** The registry check before the install. Present only when the check ran. */
+  readonly registryAccess?: RegistryAccessReport;
+  /** The agent skills installed into `.agents/skills`; empty with `--no-skills` or when the fetch failed. */
+  readonly skills: readonly SkillJsonEntry[];
+  /** The shell commands that start the app, in order. */
+  readonly nextSteps: readonly string[];
+}
+//#endregion
+//#region src/deploy-json-document.d.ts
+/**
+ * The stable codes of the `heximon deploy --json` diagnostics. A flag conflict uses
+ * `cli.invalid-options`, and a missing answer (`--yes`, a credential variable) uses `cli.option-required`.
+ */
+declare const DeployDiagnosticCode: {
+  /**
+   * A finding of the deploy run (preflight, migrations, build, infrastructure, provisioning, ship), at its own
+   * severity. A dry run that goes on past an error finding reports it as a warning, so `ok` stays `true`.
+   */
+  readonly Finding: "deploy.finding";
+  /** The run stopped before the upload. Work that ran before the stop is not rolled back. */
+  readonly Halted: "deploy.halted";
+  /** The vendor rejected the upload, so the artifact is not live. */
+  readonly ShipFailed: "deploy.ship-failed";
+  /** The app shipped, but the `--verify` liveness probe got no 2xx answer. */
+  readonly NotLive: "deploy.not-live";
+  /** The app shipped, but a migration after the ship failed to apply. */
+  readonly MigrationFailed: "deploy.migration-failed";
+  /** `--migrate` found no database config to apply. */
+  readonly NoMigrationConfig: "deploy.no-migration-config";
+  /** `--destroy` on a platform that has no teardown step. */
+  readonly DestroyUnsupported: "deploy.destroy-unsupported";
+  /** No deploy strategy is installed for the platform. */
+  readonly StrategyUnavailable: "deploy.strategy-unavailable";
+  /** The `--env-file` file cannot be read. */
+  readonly EnvFileUnreadable: "deploy.env-file-unreadable";
+  /** A Nitro or Nuxt build uses a preset that the deploy cannot ship. */
+  readonly HostManagedUnsupported: "deploy.host-managed-unsupported";
+};
+/** One of the {@link DeployDiagnosticCode} values. */
+type DeployDiagnosticCode = (typeof DeployDiagnosticCode)[keyof typeof DeployDiagnosticCode];
+/** What a `heximon deploy` run does: ship the app, or remove it with `--destroy`. */
+type DeployAction = "ship" | "destroy";
+/** The deploy target that `heximon deploy` and `heximon provision` resolved. */
+interface DeployJsonTarget {
+  /** The platform name; `node` for the default target. */
+  readonly platform: string;
+  /** The build target class, `node` or `edge`. */
+  readonly targetClass: string;
+  /** Whether a Nitro or Nuxt build made the artifact, so the run ships it without `vp build`. */
+  readonly hostManaged: boolean;
+  /** The directory of the artifact a host-managed build made. */
+  readonly artifactDir?: string;
+}
+/** A credential the platform requires and the run did not have. */
+interface DeployJsonCredential {
+  /** The human name, for example `Cloudflare API token`. */
+  readonly name: string;
+  /** The environment variable that supplies it. */
+  readonly envVar: string;
+}
+/** The resources one phase created, found, or failed to create. */
+interface DeployJsonResources {
+  /** The resources this run created. */
+  readonly created: readonly string[];
+  /** The resources that already existed. */
+  readonly existing: readonly string[];
+  /** The resources whose creation failed. */
+  readonly failed: readonly string[];
+  /** The summary lines of the platform. */
+  readonly messages: readonly string[];
+}
+/** The migrations one database applied during the run. */
+interface DeployJsonMigration {
+  /** The database name. */
+  readonly target: string;
+  /** When the apply ran: `pre-ship` or `post-ship`. */
+  readonly phase: string;
+  /** The migration ids the applier reported. drizzle-kit reports none. */
+  readonly applied: readonly string[];
+  /** Whether the apply failed. */
+  readonly failed: boolean;
+}
+/** The upload step of a deploy. */
+interface DeployJsonShipResult {
+  /** The platform that handled the upload. */
+  readonly platform: string;
+  /** Whether an artifact was uploaded. `false` on a dry run and on the Node target. */
+  readonly shipped: boolean;
+  /** Whether the vendor rejected the upload. */
+  readonly failed: boolean;
+  /** The deployed URL, when the platform reported one. */
+  readonly url?: string;
+  /** The summary lines of the platform, for example the ship command of a dry run. */
+  readonly messages: readonly string[];
+}
+/** What the ship action did, or would do on a dry run. */
+interface DeployJsonShip {
+  /** Whether the run ended without a successful ship. */
+  readonly halted: boolean;
+  /** The phases that started, in order (`preflight`, `build`, `provision`, `ship`, …). */
+  readonly phases: readonly DeployPhaseValue[];
+  /** Whether the run skipped `vp build` (`--skip-build`, or a host-managed build). */
+  readonly buildSkipped: boolean;
+  /** The deploy-ledger names the run injected into the build (from `heximon provision --save-ids`). */
+  readonly ledgerValues: readonly string[];
+  /** The databases `--migrate` applies, by name. */
+  readonly migrationTargets: readonly string[];
+  /** The required credentials the run did not have. A real run stops on them; a dry run reports them. */
+  readonly missingCredentials: readonly DeployJsonCredential[];
+  /** The `--create` target bootstrap, when it ran. */
+  readonly targetBootstrap?: DeployJsonResources;
+  /** The `--provision` phase, when it ran. */
+  readonly provision?: DeployJsonResources;
+  /** The migrations each database applied. */
+  readonly migrations: readonly DeployJsonMigration[];
+  /** The upload step, absent when the run stopped before it. */
+  readonly result?: DeployJsonShipResult;
+  /** The `--verify` liveness probe, when it ran. */
+  readonly verification?: {
+    readonly url: string;
+    readonly live: boolean;
+  };
+  /** The work that finished before a stop and was not rolled back. Empty when nothing ran. */
+  readonly completedBeforeHalt: readonly string[];
+}
+/** What the `--destroy` action did. */
+interface DeployJsonDestroy {
+  /** The platform of the teardown. */
+  readonly platform: string;
+  /** Whether the platform has no teardown step. */
+  readonly unsupported: boolean;
+  /** Whether the app was removed. `false` on a dry run. */
+  readonly destroyed: boolean;
+  /** The summary lines of the platform. */
+  readonly messages: readonly string[];
+}
+/**
+ * The `heximon deploy --json` document. The command sets the run fields on every document it writes; each
+ * section is present once the run reached it.
+ */
+interface DeployJsonDocument extends CliJsonDocument {
+  /** `ship` for a deploy, `destroy` for `--destroy`. */
+  readonly action: DeployAction;
+  /** The deploy environment (`--env`). */
+  readonly environment: string;
+  /** Whether the run was a dry run: nothing was uploaded or removed. */
+  readonly dryRun: boolean;
+  /** The resolved target, absent when the run stopped before it resolved. */
+  readonly target?: DeployJsonTarget;
+  /** The credential variables the run resolved, by name. Values never appear. */
+  readonly credentials?: readonly string[];
+  /** The ship action, when it ran. */
+  readonly ship?: DeployJsonShip;
+  /** The `--destroy` action, when it ran. */
+  readonly destroy?: DeployJsonDestroy;
+}
+//#endregion
+//#region src/doctor-json-document.d.ts
+/** Which audit set one `heximon doctor` run ran. */
+declare const DoctorMode: {
+  /** The default run: the audits of an app and the libraries it consumes. */
+  readonly App: "app";
+  /** `--self`: the pre-publish check of the current library package. */
+  readonly Self: "self";
+};
+/** One of the {@link DoctorMode} values. */
+type DoctorMode = (typeof DoctorMode)[keyof typeof DoctorMode];
+/** The verdict on one audited package in a {@link DoctorJsonDocument}. */
+declare const DoctorPackageStatus: {
+  /** The packed manifest matches the local source of the package. */
+  readonly Fresh: "fresh";
+  /**
+   * The local source changed since the last pack, some recorded source is gone, or a file the bundle read outside
+   * the source changed or is gone.
+   */
+  readonly Stale: "stale";
+  /** The packed manifest has no provenance stamp, so nothing was compared. */
+  readonly NoProvenance: "no-provenance";
+  /** The package has no local source (a published package), so nothing was compared. */
+  readonly NoSource: "no-source";
+  /** The package resolves to more than one physical copy. */
+  readonly Fork: "fork";
+};
+/** One of the {@link DoctorPackageStatus} values. */
+type DoctorPackageStatus = (typeof DoctorPackageStatus)[keyof typeof DoctorPackageStatus];
+/** The outcome of the physical-copy census in a {@link DoctorJsonDocument}. */
+declare const DoctorCopyCensusStatus: {
+  /** Every probed package resolves to one copy. */
+  readonly SingleCopies: "single-copies";
+  /** At least one probed package resolves to more than one copy. */
+  readonly Forked: "forked";
+  /** The census ran but found no `node_modules` to resolve from, so it could not look. */
+  readonly NothingProbed: "nothing-probed";
+  /** `--self` found no pnpm workspace, so the census did not run. */
+  readonly NotRun: "not-run";
+};
+/** One of the {@link DoctorCopyCensusStatus} values. */
+type DoctorCopyCensusStatus = (typeof DoctorCopyCensusStatus)[keyof typeof DoctorCopyCensusStatus];
+/**
+ * The stable codes of the `heximon doctor` diagnostics. A `heximon.config.ts` that `--self` cannot load is the
+ * shared `cli.config-unreadable`, as a warning: the run goes on without its `expectedOpenPeers`.
+ */
+declare const DoctorDiagnosticCode: {
+  /** `@heximon/*` cannot be read from GitHub Packages. Error. */
+  readonly RegistryAccessFailed: "doctor.registry-access-failed";
+  /** A packed library no longer matches its local source. Error. */
+  readonly StalePackage: "doctor.stale-package";
+  /** A package resolves to more than one physical copy. Error when it fails the run, else warning. */
+  readonly PackageFork: "doctor.package-fork";
+  /** The copy census found nothing to resolve from. Warning. */
+  readonly CopiesNotProbed: "doctor.copies-not-probed";
+  /** The deployed wrangler config does not carry the tracing directives. Warning. */
+  readonly PlatformTracingNotCarried: "doctor.platform-tracing-not-carried";
+  /** A `@heximon/*` peer of the dependency closure is declared nowhere in `package.json`. Warning. */
+  readonly PeerPivotUndeclared: "doctor.peer-pivot-undeclared";
+  /** An `expectedOpenPeers` name matches no undeclared peer. Warning. */
+  readonly StalePeerAcknowledgement: "doctor.stale-peer-acknowledgement";
+};
+/** One of the {@link DoctorDiagnosticCode} values. */
+type DoctorDiagnosticCode = (typeof DoctorDiagnosticCode)[keyof typeof DoctorDiagnosticCode];
+/** The registry-access probe of a {@link DoctorJsonDocument}. */
+interface DoctorRegistryResult {
+  /** The registry the probe read from. */
+  readonly registry: string;
+  /** The package the probe asked for. */
+  readonly probePackage: string;
+  /** The verdict of the probe. */
+  readonly status: RegistryAccessStatus;
+  /** The raw `npm view` output behind the verdict, when there is any. */
+  readonly detail?: string;
+  /** The steps that fix the access, as text lines. Absent when the status is `ok`. */
+  readonly instructions?: string;
+}
+/** One physical copy of a forked package. */
+interface DoctorPackageCopy {
+  /** The real package directory of the copy. */
+  readonly directory: string;
+  /** The `version` of the copy, when its `package.json` can be read. */
+  readonly version?: string;
+  /** Who resolves to this copy (`the app`, `this package`, or a package name). */
+  readonly origins: readonly string[];
+}
+/**
+ * One audited package. A staleness verdict and a fork are separate entries, so a stale library that also forks
+ * appears twice: once with its staleness status and once with `fork`.
+ */
+interface DoctorPackageResult {
+  /** The package name, or the bare specifier the app imports a consumed library under. */
+  readonly name: string;
+  /** The verdict. */
+  readonly status: DoctorPackageStatus;
+  /** Why the package has this status. */
+  readonly reason: string;
+  /** How to fix the package, as text. Absent when there is nothing to fix. */
+  readonly hint?: string;
+  /** The shell command that fixes the package. Absent when no single command fixes it. */
+  readonly fix?: string;
+  /** Whether this entry is the package `--self` audits. */
+  readonly self: boolean;
+  /** Whether this entry fails the run. */
+  readonly failing: boolean;
+  /** The packed `package.json` version, for a staleness entry. */
+  readonly version?: string;
+  /** The real package directory, for a staleness entry. */
+  readonly directory?: string;
+  /** The source fingerprint the packed manifest recorded. */
+  readonly manifestSourceHash?: string;
+  /** The source fingerprint computed from the local source now. */
+  readonly recomputedSourceHash?: string;
+  /** The recorded source folders and files that are no longer on disk. */
+  readonly missingSource?: readonly string[];
+  /** The current source directory, when the source moved since the pack. */
+  readonly currentSource?: string;
+  /** The hash of the files the bundle read outside the source, as the packed manifest recorded it. */
+  readonly manifestBundleInputHash?: string;
+  /** That hash recomputed from the files now, when the source matched and every file is on disk. */
+  readonly recomputedBundleInputHash?: string;
+  /** The recorded bundle inputs (package-relative) that are no longer on disk. */
+  readonly missingBundleInputs?: readonly string[];
+  /** Every physical copy, for a `fork` entry. */
+  readonly copies?: readonly DoctorPackageCopy[];
+}
+/** The physical-copy census of a {@link DoctorJsonDocument}. */
+interface DoctorCopyCensusResult {
+  /** The outcome. */
+  readonly status: DoctorCopyCensusStatus;
+  /** How many origins the census resolved from. Zero means it could not look. */
+  readonly originsProbed: number;
+  /** How many package names the census probed. */
+  readonly packagesProbed: number;
+  /** How many probed packages resolve to more than one copy. Each one is a `fork` entry in `packages`. */
+  readonly forkedPackages: number;
+  /** The pnpm workspace root, with `--self` when one was found. */
+  readonly workspaceRoot?: string;
+  /** The names of the in-workspace consumers, with `--self` when a workspace was found. */
+  readonly consumers?: readonly string[];
+}
+/** The platform-tracing check of a {@link DoctorJsonDocument}. */
+interface DoctorPlatformTracingResult {
+  /** `not-applicable` when there is nothing to check, `carried` when the config is correct, else `not-carried`. */
+  readonly status: PlatformTracingStatusValue;
+  /** The committed wrangler config that wrangler reads, when the project commits one. */
+  readonly wranglerConfigPath?: string;
+  /** Whether that config does not set `observability.traces.enabled` to `true`. */
+  readonly tracingNotEnabled: boolean;
+  /** The configured `otel.samplerRatio` that no `head_sampling_rate` in that config carries. */
+  readonly droppedSamplerRatio?: number;
+}
+/** One `@heximon/*` peer that some package of the dependency closure declares. */
+interface DoctorPeerPivot {
+  /** The peer package name. */
+  readonly packageName: string;
+  /** The closure packages that declare it as a peer. */
+  readonly declaredBy: readonly string[];
+}
+/** The `--self` peer-closure roster of a {@link DoctorJsonDocument}. Advisory: it never fails the run. */
+interface DoctorPeerClosureResult {
+  /** Every `@heximon/*` package of the installed dependency closure. */
+  readonly closurePackages: readonly string[];
+  /** Every `@heximon/*` peer that a closure package declares. */
+  readonly pivots: readonly DoctorPeerPivot[];
+  /** The pivots that `package.json` declares nowhere and `expectedOpenPeers` does not name. */
+  readonly uncovered: readonly DoctorPeerPivot[];
+  /** The pivots that `expectedOpenPeers` names. */
+  readonly expectedOpen: readonly DoctorPeerPivot[];
+  /** The `expectedOpenPeers` names that match no undeclared pivot. */
+  readonly staleExpectedOpen: readonly string[];
+}
+/** The `heximon doctor --json` document. `ok` is `false` exactly when the run exits 1. */
+interface DoctorJsonDocument extends CliJsonDocument {
+  /** Which audit set ran. */
+  readonly mode: DoctorMode;
+  /** The absolute project root the audits read. */
+  readonly rootDir: string;
+  /** The registry-access probe. */
+  readonly registry: DoctorRegistryResult;
+  /** Every audited package: each staleness verdict and each fork. */
+  readonly packages: readonly DoctorPackageResult[];
+  /** The physical-copy census. */
+  readonly packageCopies: DoctorCopyCensusResult;
+  /** The platform-tracing check. Present only in the `app` mode. */
+  readonly platformTracing?: DoctorPlatformTracingResult;
+  /** The peer-closure roster. Present only in the `self` mode, when `package.json` can be read. */
+  readonly peerClosure?: DoctorPeerClosureResult;
+  /** Whether the package has a packed manifest to compare. Present only in the `self` mode. */
+  readonly packed?: boolean;
+  /** The closing sentence of the text report. */
+  readonly summary: string;
+}
+//#endregion
+//#region src/module-graph-report.d.ts
+/** A cross-package boundary node summarized for the graph report — its factory plus its `requires`/`exports` tokens. */
+interface BoundarySummary {
+  /** The package's bare specifier (e.g. `@acme/billing`). */
+  readonly specifier: string;
+  /** The `create<Module>` factory export the app calls. */
+  readonly factory: string;
+  /** The tokens the boundary requires the host to supply, by name. */
+  readonly requires: readonly string[];
+  /** The tokens the boundary exposes to the host, by name. */
+  readonly exports: readonly string[];
+}
+//#endregion
+//#region src/graph-json-document.d.ts
+/** The stable codes of the failures `heximon graph` raises itself. */
+declare const GraphDiagnosticCode: {
+  /** The compile threw before the command could read a module graph. */
+  readonly ReadFailed: "graph.read-failed";
+  /** The `--out` file could not be written. */
+  readonly OutWriteFailed: "graph.out-write-failed";
+};
+/** One of the {@link GraphDiagnosticCode} values. */
+type GraphDiagnosticCode = (typeof GraphDiagnosticCode)[keyof typeof GraphDiagnosticCode];
+/**
+ * The `heximon graph --json` document, and the content of its `--out` file. A compile with errors keeps the
+ * graph it could build, with `ok: false`. A run that read no graph at all prints a {@link CliFailureDocument}.
+ */
+interface GraphJsonDocument extends CliJsonDocument {
+  /** Each module of the app (or each published root of a package) over its providers and their dependencies. */
+  readonly modules: ModuleGraphView["modules"];
+  /** The cross-package boundary nodes the app composes. Present only with `--boundaries` and at least one node. */
+  readonly boundaries?: readonly BoundarySummary[];
+  /** How many error diagnostics the compile has. More than zero means the graph can be incomplete. */
+  readonly errors: number;
+}
+//#endregion
+//#region src/migrations-json-document.d.ts
+/** The stable codes of the failures and warnings `heximon migrations` raises itself. */
+declare const MigrationsDiagnosticCode: {
+  /** No drizzle-kit config was detected, and `--config` was not given. */
+  readonly NoConfig: "migrations.no-config";
+  /** A candidate config file could not be loaded. A warning beside {@link NoConfig}; `file` names it. */
+  readonly ConfigLoadFailed: "migrations.config-load-failed";
+  /** The `--env-file` cannot be read. */
+  readonly EnvFileUnreadable: "migrations.env-file-unreadable";
+  /** `drizzle-kit` exited with a non-zero status for one database. */
+  readonly DrizzleKitFailed: "migrations.drizzle-kit-failed";
+  /** `drizzle-kit` could not start, for example because it is not installed. The run stops there. */
+  readonly DrizzleKitNotStarted: "migrations.drizzle-kit-not-started";
+  /** A Cloudflare D1 database was not migrated: `wrangler d1 migrations apply` applies it. A warning. */
+  readonly D1ApplySkipped: "migrations.d1-apply-skipped";
+};
+/** One of the {@link MigrationsDiagnosticCode} values. */
+type MigrationsDiagnosticCode = (typeof MigrationsDiagnosticCode)[keyof typeof MigrationsDiagnosticCode];
+/** What happened to one database in a `generate`, `migrate` or `push` run. */
+declare const MigrationsStepStatus: {
+  /** `drizzle-kit` exited 0. */
+  readonly Succeeded: "succeeded";
+  /** `drizzle-kit` exited with a non-zero status. */
+  readonly Failed: "failed";
+  /** `drizzle-kit` could not start. The run stopped, and the databases after this one have no entry. */
+  readonly NotStarted: "not-started";
+  /** The command did not run `drizzle-kit` for this database; {@link MigrationsStepEntry.reason} says why. */
+  readonly Skipped: "skipped";
+};
+/** One of the {@link MigrationsStepStatus} values. */
+type MigrationsStepStatus = (typeof MigrationsStepStatus)[keyof typeof MigrationsStepStatus];
+/** One drizzle-kit config the command acted on. */
+interface MigrationsDatabaseView {
+  /** The basename of the config file, for example `database.config.ts`. */
+  readonly name: string;
+  /** The absolute path of the config file, the `drizzle-kit --config` target. */
+  readonly configPath: string;
+  /** The drizzle-kit dialect of the config, or `unknown` for a `--config` file that could not be loaded. */
+  readonly dialect: string;
+  /** The drizzle-kit driver, when the config sets one (`d1-http`, `durable-sqlite`, …). */
+  readonly driver?: string;
+  /** How `migrate` applies this database: `drizzle-kit`, `wrangler-d1` or `skip`. */
+  readonly applyMode: DatabaseApplyModeValue;
+  /** The migrations folder of the config (its `out`, else `drizzle`), relative to the project root. */
+  readonly migrationsDirectory: string;
+}
+/**
+ * The captured result of one `drizzle-kit` run. The password of any URL with userinfo, any `password=` query
+ * parameter, each `dbCredentials` secret of the configs, and each `--env-file` value of 8 characters or more are
+ * replaced with `***`.
+ */
+interface MigrationsDrizzleKitResult {
+  /** The exit status of `drizzle-kit`; `-1` when a signal stopped it. */
+  readonly exitCode: number;
+  /** What `drizzle-kit` wrote to its stdout. */
+  readonly stdout: string;
+  /** What `drizzle-kit` wrote to its stderr. */
+  readonly stderr: string;
+}
+/** One database of a `generate`, `migrate` or `push` run. */
+interface MigrationsStepEntry extends MigrationsDatabaseView {
+  /** What happened to the database. */
+  readonly status: MigrationsStepStatus;
+  /** Why the database was skipped, or why `drizzle-kit` could not start. */
+  readonly reason?: string;
+  /** The `drizzle-kit` result, when it ran. */
+  readonly drizzleKit?: MigrationsDrizzleKitResult;
+}
+/** One database of a `generate` run. */
+interface MigrationsGenerateEntry extends MigrationsStepEntry {
+  /** The `.sql` files the run added to {@link migrationsDirectory}, relative to it, sorted. */
+  readonly generatedFiles: readonly string[];
+}
+/** One database of a `status` run. */
+interface MigrationsStatusEntry extends MigrationsDatabaseView {
+  /** Every `.sql` file in {@link migrationsDirectory}, relative to it, sorted. Applied or not is unknown. */
+  readonly migrations: readonly string[];
+}
+/** The `heximon migrations generate --json` document. */
+interface MigrationsGenerateJsonDocument extends CliJsonDocument {
+  /** The absolute project root. */
+  readonly rootDir: string;
+  /** One entry for each database the run acted on, in run order. */
+  readonly databases: readonly MigrationsGenerateEntry[];
+}
+/** The `heximon migrations migrate --json` document. */
+interface MigrationsMigrateJsonDocument extends CliJsonDocument {
+  /** The absolute project root. */
+  readonly rootDir: string;
+  /** One entry for each database the run acted on, in run order. */
+  readonly databases: readonly MigrationsStepEntry[];
+}
+/** The `heximon migrations push --json` document. */
+interface MigrationsPushJsonDocument extends CliJsonDocument {
+  /** The absolute project root. */
+  readonly rootDir: string;
+  /** One entry for each database the run pushed to, in run order. */
+  readonly databases: readonly MigrationsStepEntry[];
+}
+/** The `heximon migrations status --json` document. It reads the files on disk only, never the database. */
+interface MigrationsStatusJsonDocument extends CliJsonDocument {
+  /** The absolute project root. */
+  readonly rootDir: string;
+  /** One entry for each selected database. */
+  readonly databases: readonly MigrationsStatusEntry[];
+}
+//#endregion
+//#region src/provision-json-document.d.ts
+/**
+ * The stable codes of the `heximon provision --json` diagnostics. `--profile` uses `cli.invalid-options`,
+ * and a missing credential uses `cli.option-required`.
+ */
+declare const ProvisionDiagnosticCode: {
+  /** The platform has no foundational resources to provision. */
+  readonly Unsupported: "provision.unsupported";
+  /** One or more resources failed to provision; `result.failed` names them. */
+  readonly Failed: "provision.failed";
+  /** No deploy strategy is installed for the platform. */
+  readonly StrategyUnavailable: "provision.strategy-unavailable";
+  /** A Nitro or Nuxt build uses a preset that the deploy cannot ship. */
+  readonly HostManagedUnsupported: "provision.host-managed-unsupported";
+};
+/** One of the {@link ProvisionDiagnosticCode} values. */
+type ProvisionDiagnosticCode = (typeof ProvisionDiagnosticCode)[keyof typeof ProvisionDiagnosticCode];
+/** A resource the run created, with the id the app records. */
+interface ProvisionJsonResource {
+  /** The app-facing name, for example the Hyperdrive binding `HYPERDRIVE`. */
+  readonly resource: string;
+  /** The id the platform returned. */
+  readonly id: string;
+  /** The environment variable the build reads the id from, when the resource has one. */
+  readonly envVar?: string;
+}
+/** What the provisioning did, or would do on a dry run. */
+interface ProvisionJsonResult {
+  /** The platform that handled it. */
+  readonly platform: string;
+  /** The resources this run created. Empty on a dry run. */
+  readonly provisioned: readonly ProvisionJsonResource[];
+  /** The resources that already have an id. */
+  readonly existing: readonly string[];
+  /** The resources whose creation failed. */
+  readonly failed: readonly string[];
+  /** The summary lines of the platform; a dry run names each resource it would create here. */
+  readonly messages: readonly string[];
+}
+/** The `heximon provision --json` document. */
+interface ProvisionJsonDocument extends CliJsonDocument {
+  /** The deploy environment (`--env`). */
+  readonly environment: string;
+  /** Whether the run was a dry run: nothing was created. */
+  readonly dryRun: boolean;
+  /** The resolved target, absent when the run stopped before it resolved. */
+  readonly target?: DeployJsonTarget;
+  /** The credential variables the run resolved, by name. Values never appear. */
+  readonly credentials?: readonly string[];
+  /** The provisioning result, absent when the platform has nothing to provision. */
+  readonly result?: ProvisionJsonResult;
+  /** Where `--save-ids` recorded the created ids, and their variable names. */
+  readonly savedIds?: {
+    readonly path: string;
+    readonly names: readonly string[];
+  };
+}
+//#endregion
+//#region src/routes-json-document.d.ts
+/** The stable codes of the failures `heximon routes` raises itself. */
+declare const RoutesDiagnosticCode: {
+  /** The compile threw before the command could read a route census. */
+  readonly ReadFailed: "routes.read-failed";
+  /** `--boot` could not load or boot the app. A compile error of the boot gives the compiler diagnostics instead. */
+  readonly BootFailed: "routes.boot-failed";
+  /** `--boot` booted the app, but its live route table could not be read. */
+  readonly TableUnreadable: "routes.table-unreadable";
+  /** `--boot` read the route table, but the booted app did not dispose cleanly; a client can still be open. */
+  readonly DisposeFailed: "routes.dispose-failed";
+  /** The `--out` file could not be written. */
+  readonly OutWriteFailed: "routes.out-write-failed";
+};
+/** One of the {@link RoutesDiagnosticCode} values. */
+type RoutesDiagnosticCode = (typeof RoutesDiagnosticCode)[keyof typeof RoutesDiagnosticCode];
+/**
+ * The `heximon routes --json` document (also with `--boot`), and the content of its `--out` file. A run that
+ * read no route table prints a {@link CliFailureDocument}. A successful compile-time read lists no compile warning,
+ * so the document stays free of file paths and two runs of the same source give the same bytes.
+ */
+interface RoutesJsonDocument extends CliJsonDocument {
+  /** Every route the app serves, with the authorization scopes it enforces. */
+  readonly routes: readonly RouteCensusRow[];
+  /** The controllers or packages whose routes the compile-time census could not name; `[]` under `--boot`. */
+  readonly unresolved: readonly RouteCensusGap[];
+  /** Which scope enforcer checks each module's routes. Absent when nothing checks any route's scopes. */
+  readonly scopeEnforcement?: RouteCensusScopeEnforcement;
+}
+//#endregion
 //#region src/skill-installer.d.ts
-/** One installed skill: its name and how many files were written. */
+/** One installed skill: its name, where it was written, and how many files were written. */
 interface InstalledSkill {
+  /** The skill name from the source's index. */
   readonly name: string;
+  /** The absolute directory of the skill, `<project>/.agents/skills/<name>`. */
+  readonly directory: string;
+  /** How many files of the skill were written. */
   readonly fileCount: number;
 }
 /**
@@ -402,4 +1269,130 @@ export declare abstract class SkillSources {
  */
 export declare const skillsCommand: CommandDef;
 //#endregion
-export type { InstalledSkill, PreparedTarget, ProcessRunResult, ProcessRunner, Prompter, RegistryAccessReport, ScaffoldRequest, ScaffoldResult, StartersScaffoldRequest, TemplateSelection, TemplateSource };
+//#region src/task-run-json-document.d.ts
+/** The stable codes of the failures `heximon task run --json` reports. */
+declare const TaskDiagnosticCode: {
+  /** The `run()` of the task threw. The run exits 2, and the document names the error. */
+  readonly TaskFailed: "task.failed";
+  /** No module or no task of the compiled graph has the name, or the source file does not export the class. */
+  readonly TargetNotFound: "task.target-not-found";
+  /** More than one module, or more than one task of the module, has the name. */
+  readonly TargetAmbiguous: "task.target-ambiguous";
+  /** The named class has no `run()` method. */
+  readonly NotATask: "task.not-a-task";
+  /** The production compile failed. The compiler diagnostics are in the same document. */
+  readonly CompileFailed: "task.compile-failed";
+  /** The project has no app: the compile gave no module graph, or no wiring file. */
+  readonly AppNotFound: "task.app-not-found";
+  /** A Nitro option is computed, so the command cannot read the preset or the source directories. */
+  readonly NitroConfigComputed: "task.nitro-config-computed";
+  /** A packed library that the app imports does not have the factories a production build needs. */
+  readonly LibraryPreflightFailed: "task.library-preflight-failed";
+  /** The graph needs bindings that only its platform has, so nothing was booted. */
+  readonly PlatformBindingsRequired: "task.platform-bindings-required";
+  /** The `@heximon/runtime` of the project is older than the command. */
+  readonly RuntimeOutdated: "task.runtime-outdated";
+  /** The app did not boot. The stack is on stderr. */
+  readonly BootFailed: "task.boot-failed";
+  /** The app could not create the task. */
+  readonly CreateFailed: "task.create-failed";
+  /** The frame of the task did not open, or a context seed threw before `run()`. */
+  readonly StartFailed: "task.start-failed";
+  /** The task returned a value that is not JSON. */
+  readonly ResultNotJson: "task.result-not-json";
+  /** The app did not shut down cleanly after the run. */
+  readonly ShutdownFailed: "task.shutdown-failed";
+};
+/** One of the {@link TaskDiagnosticCode} values. */
+type TaskDiagnosticCode = (typeof TaskDiagnosticCode)[keyof typeof TaskDiagnosticCode];
+/** The error a task threw, named as the text error line of `heximon task run` names it. */
+interface TaskRunError {
+  /** The error name, or the class name when the class keeps the generic `Error` name. */
+  readonly name: string;
+  /** The error message. */
+  readonly message: string;
+}
+/**
+ * The `heximon task run --json` document. A run that stops before the compile (a bad `--payload` or
+ * `--env-file`, a child process that did not start, an unexpected error) prints a {@link CliFailureDocument}.
+ */
+interface TaskRunJsonDocument extends CliJsonDocument {
+  /** The module class name the run named. */
+  readonly module: string;
+  /** The task class name the run named. */
+  readonly task: string;
+  /** The `result` of the `TaskResult` the task returned; absent when the task returned none. */
+  readonly result?: unknown;
+  /** The error the task threw; present only with {@link TaskDiagnosticCode.TaskFailed}. */
+  readonly error?: TaskRunError;
+}
+//#endregion
+//#region src/workflow-status-report.d.ts
+/** How one workflow's current step graph relates to the committed baseline gate. */
+declare const WorkflowBaselineState: {
+  /** The committed snapshot matches the current graph — the gate is armed and clean. */
+  readonly InSync: "in-sync";
+  /**
+   * The committed sites are an exact prefix of the current ones — the append-only change the upgrade check
+   * accepts. In-flight runs replay through the recorded prefix unchanged.
+   */
+  readonly Appended: "appended";
+  /** The committed snapshot differs — `heximon check` gates the deploy until the change is re-acknowledged. */
+  readonly Diverged: "diverged";
+  /** No committed snapshot for this workflow — the gate is unarmed until `heximon check --update` runs. */
+  readonly Unarmed: "unarmed";
+};
+type WorkflowBaselineState = (typeof WorkflowBaselineState)[keyof typeof WorkflowBaselineState];
+/** One workflow's row in the report: identity, current graph, and its baseline state. */
+interface WorkflowStatusEntry {
+  readonly resourceName: string;
+  readonly fingerprint: string;
+  readonly stepCount: number;
+  readonly state: WorkflowBaselineState;
+}
+/** One live instance observed on the platform, with the fingerprint it was stamped with at create. */
+interface WorkflowInstanceView {
+  readonly id: string;
+  readonly status: string;
+  readonly createdOn: string;
+  readonly stampedFingerprint: string;
+}
+/** The per-workflow live-fleet inventory — a structural mirror of `WorkflowUpgradeInventory`. */
+interface WorkflowInstanceInventory {
+  readonly workflowName: string;
+  readonly currentFingerprint: string;
+  readonly comparable: boolean;
+  readonly liveInstanceCount: number;
+  readonly staleInstances: readonly WorkflowInstanceView[];
+}
+/** One workflow's row in the `heximon workflows --json` document. */
+interface WorkflowStatusJsonEntry extends WorkflowStatusEntry {
+  /** The Cloudflare live-fleet inventory, or `null` when enumeration was skipped or failed. */
+  readonly inventory: WorkflowInstanceInventory | null;
+  readonly enumerationError?: string;
+}
+/** The stable codes of the failures `heximon workflows` raises itself, beside the compiler's own. */
+declare const WorkflowsDiagnosticCode: {
+  /** The committed `heximon.upgrade.json` exists but cannot be read, so no workflow state is known. */
+  readonly BaselineUnreadable: "workflows.baseline-unreadable";
+  /** The Cloudflare live instances of one workflow could not be listed, so the fleet picture is incomplete. */
+  readonly EnumerationFailed: "workflows.enumeration-failed";
+};
+/** One of the {@link WorkflowsDiagnosticCode} values. */
+type WorkflowsDiagnosticCode = (typeof WorkflowsDiagnosticCode)[keyof typeof WorkflowsDiagnosticCode];
+/**
+ * The `heximon workflows --json` document. A run that produced no per-workflow report (a failed compile, an
+ * unreadable committed baseline, an app without workflows) keeps the same keys with `workflows: []`, and its
+ * diagnostics say why. A run that stopped before the compile prints a {@link CliFailureDocument}.
+ */
+interface WorkflowsJsonDocument extends CliJsonDocument {
+  /** One row for each workflow of the app. */
+  readonly workflows: readonly WorkflowStatusJsonEntry[];
+  /** Whether the Cloudflare live fleet was enumerated, and why not when it was skipped. */
+  readonly cloudflare: {
+    readonly enumerated: boolean;
+    readonly skipped?: string;
+  };
+}
+//#endregion
+export type { BoundarySummary, CheckDiagnosticCode, CheckJsonDocument, CheckUpgradeBaselineResult, CliDiagnostic, CliDiagnosticCode, CliFailureDocument, CliJsonDocument, CreateDiagnosticCode, CreateJsonDocument, DeployAction, DeployDiagnosticCode, DeployJsonCredential, DeployJsonDestroy, DeployJsonDocument, DeployJsonMigration, DeployJsonResources, DeployJsonShip, DeployJsonShipResult, DeployJsonTarget, DoctorCopyCensusResult, DoctorCopyCensusStatus, DoctorDiagnosticCode, DoctorJsonDocument, DoctorMode, DoctorPackageCopy, DoctorPackageResult, DoctorPackageStatus, DoctorPeerClosureResult, DoctorPeerPivot, DoctorPlatformTracingResult, DoctorRegistryResult, GraphDiagnosticCode, GraphJsonDocument, InstalledSkill, MigrationsDatabaseView, MigrationsDiagnosticCode, MigrationsDrizzleKitResult, MigrationsGenerateEntry, MigrationsGenerateJsonDocument, MigrationsMigrateJsonDocument, MigrationsPushJsonDocument, MigrationsStatusEntry, MigrationsStatusJsonDocument, MigrationsStepEntry, MigrationsStepStatus, PreparedTarget, ProcessRunResult, ProcessRunner, Prompter, ProvisionDiagnosticCode, ProvisionJsonDocument, ProvisionJsonResource, ProvisionJsonResult, RegistryAccessReport, RoutesDiagnosticCode, RoutesJsonDocument, ScaffoldRequest, ScaffoldResult, SkillJsonEntry, SkillSourceJsonEntry, SkillSourceRecording, SkillsAddJsonDocument, SkillsDiagnosticCode, SkillsSyncJsonDocument, StartersScaffoldRequest, TaskDiagnosticCode, TaskRunError, TaskRunJsonDocument, TemplateSelection, TemplateSource, WorkflowBaselineState, WorkflowInstanceInventory, WorkflowInstanceView, WorkflowStatusEntry, WorkflowStatusJsonEntry, WorkflowsDiagnosticCode, WorkflowsJsonDocument };