heximon 0.0.1 → 0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 heximon@heximon.dev
+Copyright (c) 2026 WP Online Magyarország Kft.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,17 +1,150 @@
-# heximon
+# ⏣ Heximon CLI
 
-> ⚠️ **Placeholder package.** This name is reserved for future development and currently has no functionality.
+The `heximon` command bundles the tasks that sit around everyday development: scaffolding a new app,
+inspecting its routes and dependency graph, shipping a build, and running migrations.
 
-## Status
+`pnpm dev` and `pnpm build` stay Vite tasks. `heximon` handles what comes before your first `pnpm dev` and
+after your last `pnpm build`.
 
-This package exists to reserve the `heximon` name on npm. Real functionality will land in a future release. Until then, installing it does nothing useful.
+## Why you want it
+
+- **One binary for the whole surface.** `create`, `check`, `routes`, `graph`, `doctor`, `deploy`,
+  `provision`, `migrations`, 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 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.
+- **Shell completion is built in.** `heximon complete zsh` (or `bash`, `fish`, `powershell`, `fig`) sets
+  up tab completion for every command and flag.
 
 ## Install
 
 ```sh
-npm install heximon
+pnpm add -D heximon
 ```
 
+You need no extra configuration. `heximon` reads the same `heximon.config.ts` sidecar your build
+already uses.
+
+## Your first command
+
+Most starters wire `heximon check` in front of the type check, so a dependency-injection error surfaces
+before the type checker runs.
+
+```json [starters/minimal/package.json]
+{
+  "scripts": {
+    "dev": "vp dev",
+    "build": "vp build",
+    "check": "heximon check && vp check",
+    "test": "vitest --run"
+  }
+}
+```
+
+The full command surface is ten subcommands, each its own file, registered once.
+
+```ts [src/bin.ts]
+const main = defineCommand({
+  meta: { name: "heximon", description: "The Heximon CLI." },
+  subCommands: {
+    create: createCommand,
+    deploy: deployCommand,
+    check: checkCommand,
+    routes: routesCommand,
+    graph: graphCommand,
+    doctor: doctorCommand,
+    provision: provisionCommand,
+    migrations: migrationsCommand,
+    workflows: workflowsCommand,
+    skills: skillsCommand,
+  },
+});
+```
+
+## What is included
+
+| Command | What it does |
+| :-- | :-- |
+| `heximon create` | Scaffolds a new app from a starter template. Also reachable as `pnpm create heximon`. |
+| `heximon check` | Compiles the app, reports every diagnostic, and refreshes the editor's type hints. `--emit` also writes the generated wiring to `.heximon/`; `--verify-baseline` names every durable record the committed `heximon.upgrade.json` has not acknowledged. |
+| `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 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 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`. |
+
+## Works with
+
+- [`@heximon/deploy`](../deploy) supplies the `deploy` command's logic. This package adds the interactive
+  prompts on top.
+- [`@heximon/compiler`](../../kernel/compiler) supplies `check`, `routes`, and `graph`.
+- [`create-heximon`](../create-heximon) is a separate, smaller package that forwards `npm create heximon`
+  to this package's `create` command.
+
+## Registry access
+
+`@heximon/*` packages publish to GitHub Packages, a private registry. The `heximon` CLI itself stays on
+public npm, so it installs with no extra setup — but a scaffolded app's `@heximon/*` dependencies need
+two things in place:
+
+1. A `.npmrc` in the project, with the scope line:
+
+   ```
+   @heximon:registry=https://npm.pkg.github.com
+   ```
+
+   `heximon create` writes this file for you. It does not overwrite a `.npmrc` your template already
+   ships, and it skips the file in `--workspace` mode, where the `@heximon/*` ranges are workspace links.
+
+2. A GitHub token with the `read:packages` scope, in your **user-level** `~/.npmrc`:
+
+   ```
+   //npm.pkg.github.com/:_authToken=<your token>
+   ```
+
+Before it installs, `heximon create` checks that `@heximon/*` is readable. On failure it prints the fix
+above, skips the install, and keeps the scaffolded project so you can install by hand once the token is in
+place. Pass `--skip-registry-check` to skip this check (for example, when a proxy or mirror answers the
+install another way).
+
+`heximon doctor` reports the same check as its first line: `✔ GitHub Packages — @heximon/* readable`, or
+the fix instructions plus a non-zero exit code.
+
+## Good to know
+
+- **`heximon deploy` needs the platform's own command-line tool installed and logged in.** It checks
+  this first and stops with the exact command to run, before it builds anything.
+- **`heximon doctor` reports. It does not fix.** A duplicate package copy needs a change to your lockfile
+  or your dependency versions.
+- **Run `heximon check` before you trust a red `pnpm check`.** The type checker cannot see a missing
+  provider on its own. `heximon check` reports that error with the line that is wrong.
+- **`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.
+- **`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.
+- **Adding a durable record is silent until you look for it.** A new queue channel, saga slot, workflow, or
+  integration subscription is safe to deploy, so the upgrade check says nothing. `heximon check
+  --verify-baseline` names every one the committed baseline has not acknowledged; add `--strict` to fail CI
+  on them, then `heximon check --update` to accept them. That acceptance also refreshes the DI verdict
+  mirror, so a bare `tsgo` on unchanged source passes right away.
+- **`heximon workflows` still reports a breaking upgrade verdict per workflow.** The verdict comes out of a
+  complete graph analysis, so the rows stay and the command exits non-zero. Only a genuine compile failure
+  refuses the report. A workflow that only gained steps at the end reads as `appended`, not `diverged`.
+
+## Learn more
+
+- [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.
+- [The Heximon agent skill](../../../docs/skills/heximon) — the technical reference for coding agents.
+
 ## License
 
-[MIT](./LICENSE)
+MIT — see [LICENSE](./LICENSE).

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export {}