heximon 0.1.1 → 0.3.0

package/README.md

@@ -69,7 +69,7 @@ const main = defineCommand({
 | 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 check` | Compiles the app, reports every diagnostic, and refreshes the editor's type hints. `--emit` also writes the generated app 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. |
@@ -127,7 +127,9 @@ the fix instructions plus a non-zero exit code.
   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.
+  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
+  `.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.
 - **Adding a durable record is silent until you look for it.** A new queue channel, saga slot, workflow, or

package/dist/bin.mjs

@@ -431,7 +431,7 @@ var UpgradeBaseline = class UpgradeBaseline {
 *
 * Two opt-in passes ride the same compile. `--emit` (and the sidecar's own `debug: true`) writes the generated
 * wiring to `.heximon/` and reformats it in place, so what the compiler produced can be read; a bare run writes
-* only the verdict mirror. `--verify-baseline` makes every durable concept ALSO report the records the
+* only the verdict mirror. Both apply to the app leg only: a library run writes no wiring and says so. `--verify-baseline` makes every durable concept ALSO report the records the
 * committed `heximon.upgrade.json` never acknowledged — the direction the diff does not walk, since adding a
 * record is safe to deploy. It writes nothing, and is refused alongside `--update`, which acknowledges exactly
 * what it exists to show.
@@ -487,7 +487,7 @@ const checkCommand = defineCommand({
 		},
 		emit: {
 			type: "boolean",
-			description: "Write the generated wiring to `.heximon/` and prettify it, for inspection. The sidecar's `debug: true` turns this on for every run.",
+			description: "Write the generated app wiring to `.heximon/` and prettify it, for inspection. A library compile writes nothing: run `vp pack` to regenerate its factory. The sidecar's `debug: true` turns this on for every app-mode run.",
 			default: false
 		}
 	},
@@ -563,6 +563,7 @@ const checkCommand = defineCommand({
 		} else {
 			if (checked.emittedTo !== void 0) log.info(`Wrote the generated wiring to ${checked.emittedTo}`);
 			if (checked.prunedVerdicts !== void 0) log.info(`Removed the stale DI verdict mirror ${checked.prunedVerdicts} — it was written by an app-mode compile of this package, and a library compile emits none to replace it.`);
+			if (mode === CompileMode.Library && (args.emit === true || session.config?.debug === true)) log.warn(`${args.emit === true ? "`--emit`" : "`debug: true`"} writes app wiring only. A library's generated factory is written by \`vp pack\`.`);
 			if (mode === CompileMode.Library && verifyBaseline) log.warn(`${UpgradeBaselineFile.fileName} is an app-level artifact — a library's durable surface is verified by each app that composes it, so there is nothing here to verify.`);
 			if (mode === CompileMode.Library && args.update === true) log.warn(`${UpgradeBaselineFile.fileName} is an app-level artifact — a library's durable surface is baselined by each app that composes it, so there is nothing here to update.`);
 			else if (rebaselined !== void 0) log.success(rebaselined.changed ? `Updated ${UpgradeBaselineFile.fileName} — commit it to acknowledge the durable-surface changes.` : `${UpgradeBaselineFile.fileName} already up to date.`);

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { CommandDef } from "citty";
 //#region src/prompter.d.ts
 /** Thrown when the operator cancels an interactive prompt (Ctrl-C). */
-declare class PromptCancelledError extends Error {
+export declare class PromptCancelledError extends Error {
   constructor();
 }
 /**
@@ -23,7 +23,7 @@ interface Prompter {
  * prompt (clack's sentinel symbol) is normalized to a thrown {@link PromptCancelledError} so the credential
  * resolver handles one cancel failure mode.
  */
-declare class ClackPrompter implements Prompter {
+export declare class ClackPrompter implements Prompter {
   /** @throws PromptCancelledError when cancelled. */
   secret(message: string): Promise<string>;
   /** @throws PromptCancelledError when cancelled. */
@@ -32,7 +32,7 @@ declare class ClackPrompter implements Prompter {
 //#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. */
-declare class CliEnvironment {
+export declare class CliEnvironment {
   /**
    * Whether this is an interactive session a prompt may block on: a real TTY on stdin AND not a CI runner. In CI
    * (or a piped/non-TTY invocation) the deploy credential ladder must fail fast on a missing value rather than
@@ -46,7 +46,7 @@ declare class CliEnvironment {
  * A template fetch that failed — the giget ref could not be downloaded. Distinct from every local failure so a
  * caller may retry another ref without also retrying (or cleaning up after) a validation or manifest error.
  */
-declare class TemplateDownloadError extends Error {
+export declare class TemplateDownloadError extends Error {
   /** The giget source string that could not be fetched. */
   readonly gigetSource: string;
   constructor(gigetSource: string, cause: unknown);
@@ -102,7 +102,7 @@ interface ScaffoldResult {
  * the `@heximon/*` dependency ranges onto the fetched `package.json`. Pure filesystem work — prompting,
  * git, and dependency installation live with the CLI command.
  */
-declare class ProjectScaffolder {
+export declare class ProjectScaffolder {
   /** A project/directory name: lowercase npm-safe segments (no scopes — the directory is the name). */
   private static readonly projectNamePattern;
   /**
@@ -177,12 +177,12 @@ interface StartersScaffoldRequest {
   readonly templateName: string;
 }
 /** The `heximon create` verb: scaffold a new Heximon app from the starters templates. */
-declare const createCommand: CommandDef;
+export declare const createCommand: CommandDef;
 /**
  * The `create` command's defaults + environment glue: package-manager detection, the CLI's own lockstep
  * version, the starters giget refs (version branch → main fallback), git init, and the install spawn.
  */
-declare class CreateDefaults {
+export declare class CreateDefaults {
   /** The default project (directory + package) name when none is given. */
   static readonly projectName: string;
   /** The GitHub repository the published templates are fetched from. */
@@ -249,7 +249,7 @@ interface ProcessRunResult {
 /** Spawns a command and resolves its captured result. Injected so a test never spawns a real process. */
 type ProcessRunner = (command: string, commandArguments: readonly string[]) => Promise<ProcessRunResult>;
 /** The verdict {@link RegistryAccess.probe} classifies an `npm view` attempt into. */
-declare const RegistryAccessStatus: {
+export declare const RegistryAccessStatus: {
   /** The probe package resolved — the registry is reachable and authorized. */
   readonly Ok: "ok";
   /** The registry rejected the request for lacking (or holding invalid) credentials. */
@@ -260,7 +260,7 @@ declare const RegistryAccessStatus: {
   readonly NotFound: "not-found";
 };
 /** One of {@link RegistryAccessStatus}. */
-type RegistryAccessStatus = (typeof RegistryAccessStatus)[keyof typeof RegistryAccessStatus];
+export type RegistryAccessStatus = (typeof RegistryAccessStatus)[keyof typeof RegistryAccessStatus];
 /** What {@link RegistryAccess.probe} reports. */
 interface RegistryAccessReport {
   /** The classified verdict. */
@@ -274,7 +274,7 @@ interface RegistryAccessReport {
  * `.npmrc` scope line plus a token in the user's `~/.npmrc`; this probe reuses npm's own config
  * resolution — the same files npm itself reads — so the verdict matches what an install would do.
  */
-declare class RegistryAccess {
+export declare class RegistryAccess {
   /** The private registry `@heximon/*` packages publish to. */
   static readonly gitHubPackagesRegistry: string;
   /** The package probed to decide reachability — small, always published, always current. */
@@ -316,7 +316,7 @@ interface InstalledSkill {
  * directory there natively). Best-effort by contract: the caller treats a throw as a skippable step with
  * a printed hint, never a scaffold failure.
  */
-declare class SkillInstaller {
+export declare class SkillInstaller {
   private readonly sourceUrl;
   /** The published docs site serving the skill. */
   static readonly defaultSourceUrl = "https://heximon.dev";
@@ -357,7 +357,7 @@ declare class SkillInstaller {
  * before an app exists to compile, and a tool reads the list without evaluating any TypeScript. Every entry
  * is a base URL {@link SkillInstaller} can install from — the same value `npx skills add <url>` takes.
  */
-declare abstract class SkillSources {
+export declare abstract class SkillSources {
   /** The `package.json` member holding the framework's own manifest block. */
   private static readonly manifestKey;
   /** The member of that block holding the source list. */
@@ -400,6 +400,6 @@ declare abstract class SkillSources {
  * `heximon create` already installs the default source and records it, so an existing project's first use of
  * this command is usually `sync` after a clone, or `add` for a second, private skill site.
  */
-declare const skillsCommand: CommandDef;
+export declare const skillsCommand: CommandDef;
 //#endregion
-export { ClackPrompter, CliEnvironment, CreateDefaults, type InstalledSkill, type PreparedTarget, type ProcessRunResult, type ProcessRunner, ProjectScaffolder, PromptCancelledError, type Prompter, RegistryAccess, type RegistryAccessReport, RegistryAccessStatus, type ScaffoldRequest, type ScaffoldResult, SkillInstaller, SkillSources, type StartersScaffoldRequest, TemplateDownloadError, type TemplateSelection, type TemplateSource, createCommand, skillsCommand };
+export type { InstalledSkill, PreparedTarget, ProcessRunResult, ProcessRunner, Prompter, RegistryAccessReport, ScaffoldRequest, ScaffoldResult, StartersScaffoldRequest, TemplateSelection, TemplateSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heximon",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "The Heximon CLI: create, develop, build, migrate, and deploy Heximon apps.",
   "keywords": [
     "cli",
@@ -37,23 +37,23 @@
   },
   "dependencies": {
     "@bomb.sh/tab": "^0.0.22",
-    "@clack/prompts": "^1.8.0",
-    "@heximon/compiler": "0.1.1",
-    "@heximon/cqrs": "0.1.1",
-    "@heximon/deploy": "0.1.1",
-    "@heximon/http": "0.1.1",
-    "@heximon/node": "0.1.1",
-    "@heximon/testing": "0.1.1",
+    "@clack/prompts": "^1.8.1",
+    "@heximon/compiler": "0.3.0",
+    "@heximon/cqrs": "0.3.0",
+    "@heximon/deploy": "0.3.0",
+    "@heximon/http": "0.3.0",
+    "@heximon/node": "0.3.0",
+    "@heximon/testing": "0.3.0",
     "citty": "^0.2.2",
     "giget": "^3.3.1",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@types/node": "^24.13.3",
+    "@types/node": "^24.19.0",
     "@typescript/native-preview": "^7.0.0-dev.20260707.2",
-    "@vitest/coverage-v8": "^5.0.0",
+    "@vitest/coverage-v8": "5.0.1",
     "typescript": "^6.0.3",
-    "vitest": "^5.0.0"
+    "vitest": "5.0.1"
   },
   "engines": {
     "node": ">=24"