heximon 0.9.0 → 0.11.0

package/README.md

@@ -8,14 +8,18 @@ after your last `pnpm build`.
 
 ## Why you want it
 
-- **One binary for the whole surface.** `create`, `check`, `routes`, `graph`, `doctor`, `deploy`,
-  `provision`, `migrations`, `task`, and `workflows` are one command each.
+- **One binary for the whole surface.** `create`, `check`, `routes`, `graph`, `doctor`, `freshness`,
+  `deploy`, `provision`, `migrations`, `task`, and `workflows` are one command each.
 - **`heximon check` catches a dependency-injection error before `tsgo` does.** It compiles your app
   headlessly and reports every compile error with its position and a fix.
 - **`heximon doctor` finds a package installed twice.** Class identity is the only dependency-injection
   token, so two copies of one package bind two different sets of classes. `doctor` names both directories.
+- **`heximon freshness` finds the packages that need a new `vp pack`.** It runs from any folder of a
+  workspace, lists every package that has a pack record, and names the file that made a package stale.
 - **`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.
 
@@ -56,6 +60,7 @@ const main = defineCommand({
     routes: routesCommand,
     graph: graphCommand,
     doctor: doctorCommand,
+    freshness: freshnessCommand,
     provision: provisionCommand,
     migrations: migrationsCommand,
     workflows: workflowsCommand,
@@ -74,14 +79,64 @@ const main = defineCommand({
 | `heximon routes` | Prints one table for every path the app answers — routes, SSE streams, and WebSocket upgrades — read from the compiler, with no boot required. |
 | `heximon graph` | Prints the resolved module dependency graph: modules, providers, and dependencies. |
 | `heximon doctor` | Reports a package installed twice, an untraced deploy target, and a stale published module. |
+| `heximon freshness` | Lists every workspace package that has a pack record (`dist/heximon.manifest.json` or `dist/heximon.inputs.json`), with its status and the input that made it stale. It finds the workspace root from any folder (`pnpm-workspace.yaml`, or a `workspaces` field in `package.json`), compiles nothing, and exits `1` when a package is stale or its check failed. A record file that exists but cannot be read is a failed check, not a missing record. `--stale` lists only those packages. |
 | `heximon deploy` | Builds the app, then ships it with the target platform's own command-line tool. |
 | `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` |
+| `freshness` | `FreshnessJsonDocument` | `FreshnessDiagnosticCode` |
+| `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 +185,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 +202,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