heximon 0.9.0 → 0.10.0

package/README.md

@@ -16,6 +16,8 @@ after your last `pnpm build`.
   token, so two copies of one package bind two different sets of classes. `doctor` names both directories.
 - **`heximon deploy` ships with the platform's own tool.** It builds your app, then runs `wrangler`,
   `vercel`, `netlify`, or `deployctl` for you, with the right flags for your environment.
+- **Agents and CI read one JSON document.** Every command takes `--json`: stdout gets one document with
+  `ok` and `diagnostics`, logs go to stderr, and the command never prompts.
 - **Shell completion is built in.** `heximon complete zsh` (or `bash`, `fish`, `powershell`, `fig`) sets
   up tab completion for every command and flag.
 
@@ -78,10 +80,58 @@ const main = defineCommand({
 | `heximon provision` | Creates a resource your build needs an identifier for, before the build runs. |
 | `heximon migrations` | Runs `generate`, `migrate`, `status`, or `push` against your database, with no hand-written `drizzle-kit` config. |
 | `heximon workflows` | Compares a durable workflow's current shape against its committed upgrade baseline. |
-| `heximon task run <Module> <Task>` | Runs one task against the production graph of the app, prints its result as JSON, and exits. It starts no HTTP listener, no schedule timer, no polling loop, and no outbox relay (`--with-outbox-relay` starts it). It refuses a graph that needs platform bindings. The module can be a packed library module: the command runs the tasks that the module exports. `--payload` sets the event payload, and `--env-file` loads variables. Exit status: `0` when the task returned, `2` when the task itself threw (stdout then holds one `{"error":{"name":…,"message":…}}` line), `1` for every other failure. |
+| `heximon task run <Module> <Task>` | Runs one task against the production graph of the app, prints its result as JSON, and exits. It starts no HTTP listener, no schedule timer, no polling loop, and no outbox relay (`--with-outbox-relay` starts it). It refuses a graph that needs platform bindings. The module can be a packed library module: the command runs the tasks that the module exports. `--payload` sets the event payload, and `--env-file` loads variables. Exit status: `0` when the task returned, `2` when the task itself threw (stdout then holds one `{"error":{"name":…,"message":…}}` line), `1` for every other failure. `--json` prints one document for every outcome, with the same exit status. |
 | `heximon skills` | `add <url>` records an agent-skill source in `package.json` (`heximon.skills`) and installs it. `sync` re-installs every recorded source. |
 | `heximon complete <shell>` | Installs shell completion for `zsh`, `bash`, `fish`, `powershell`, or `fig`. |
 
+## Machine-readable output
+
+Pass `--json` to any command except `complete`. The command then follows one contract:
+
+- stdout holds one JSON document, written when the command ends, and nothing else;
+- progress, app logs and the output of `vp build`, `drizzle-kit` or a vendor tool go to stderr;
+- the command never prompts: a question it would ask fails the run with a `cli.option-required` diagnostic
+  that names the option (or environment variable) that answers it;
+- `ok` is `false` exactly when the exit status is not `0`.
+
+Each document has `ok` and `diagnostics` at the top level, beside the fields of the command. A diagnostic has
+`severity`, `message`, `code`, `hint`, `file`, `line`, `column` and `option` where they apply. A run that
+stops before it has its own fields (a `heximon.config.ts` that throws, an invalid option, arguments the
+command cannot parse) prints `{ ok: false, diagnostics }` only. `check` and `workflows` also accept `--format json`.
+
+```json
+{"ok":false,"diagnostics":[{"severity":"error","code":"cli.config-unreadable","message":"heximon.config.ts could not be loaded: DATABASE_URL is not set","hint":"Fix the error in the config file, then run the command again.","file":"/tmp/shop/heximon.config.ts"}]}
+```
+
+The document types are exported as types from the package root:
+
+| Command | Document type | Its own codes |
+| :-- | :-- | :-- |
+| every command | `CliJsonDocument`, `CliFailureDocument`, `CliDiagnostic` | `CliDiagnosticCode` |
+| `create` | `CreateJsonDocument` | `CreateDiagnosticCode` |
+| `check` | `CheckJsonDocument` | the compiler codes |
+| `workflows` | `WorkflowsJsonDocument` | `WorkflowsDiagnosticCode` |
+| `routes` | `RoutesJsonDocument` | `RoutesDiagnosticCode` |
+| `graph` | `GraphJsonDocument` | `GraphDiagnosticCode` |
+| `doctor` | `DoctorJsonDocument` | `DoctorDiagnosticCode` |
+| `skills add`, `skills sync` | `SkillsAddJsonDocument`, `SkillsSyncJsonDocument` | `SkillsDiagnosticCode` |
+| `task run` | `TaskRunJsonDocument` | `TaskDiagnosticCode` |
+| `migrations generate`, `migrate`, `push`, `status` | `MigrationsGenerateJsonDocument`, `MigrationsMigrateJsonDocument`, `MigrationsPushJsonDocument`, `MigrationsStatusJsonDocument` | `MigrationsDiagnosticCode` |
+| `deploy` | `DeployJsonDocument` | `DeployDiagnosticCode` |
+| `provision` | `ProvisionJsonDocument` | `ProvisionDiagnosticCode` |
+
+```ts
+import type { CheckJsonDocument, CliFailureDocument } from "heximon";
+```
+
+`CliEntry.run(command, rawArgs)` starts a command tree with the same contract: under `--json`, an argument
+error is a document too, and stdout stays on stderr after the document until the process exits.
+`create-heximon` starts `heximon create` this way. A command that you call in your own code, such as
+`createCommand`, gives stdout back when it ends.
+
+The fields, the codes and the exit status of each command are in the
+[CLI reference of the agent skill](../../../docs/skills/heximon/references/tooling-cli.md#machine-readable-output).
+
 ## Works with
 
 - [`@heximon/deploy`](../deploy) supplies the `deploy` command's logic. This package adds the interactive
@@ -130,7 +180,7 @@ the fix instructions plus a non-zero exit code.
 - **`heximon check` writes no wiring unless you ask.** Pass `--emit`, or set `debug: true` in
   `heximon.config.ts`, and the generated files land in `.heximon/` — prettified in place, and the command
   prints where. This applies to an app. In a published module package, `--emit` and `debug: true` write
-  nothing, and the pretty output prints a notice (`--format json` omits the notice and `emittedTo`). `vp pack` regenerates the `create<Module>` factory in
+  nothing, and the pretty output prints a notice (`--json` omits the notice and `emittedTo`). `vp pack` regenerates the `create<Module>` factory in
   `.heximon/library/`.
 - **`heximon skills add` records only what it installed.** A source it could not fetch stays out of
   `heximon.skills`, so `heximon skills sync` never retries a URL that never worked.
@@ -147,6 +197,8 @@ the fix instructions plus a non-zero exit code.
 
 - [The CLI](https://heximon.dev/docs/cli/overview) — every command, every flag.
 - [Deploy from the CLI](https://heximon.dev/docs/cli/deploy) — the `deploy` command in depth.
+- [Machine-readable output](https://heximon.dev/docs/cli/json-output) — the `--json` contract, for tool
+  authors.
 - [The Heximon agent skill](../../../docs/skills/heximon) — the technical reference for coding agents.
 
 ## License