heximon 0.11.1 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -75,7 +75,7 @@ const main = defineCommand({
75
75
  | Command | What it does |
76
76
  | :-- | :-- |
77
77
  | `heximon create` | Scaffolds a new app from a starter template. Also reachable as `pnpm create heximon`. |
78
- | `heximon check` | Compiles the app, reports every diagnostic, and refreshes the editor's type hints. A consumed workspace library that changed since its last `vp pack` fails the run with the `STALE` line of `heximon doctor`. `--emit` also writes the generated app wiring to `.heximon/`; `--verify-baseline` names every durable record the committed `heximon.upgrade.json` has not acknowledged. |
78
+ | `heximon check` | Compiles the app, reports every diagnostic, and refreshes the editor's type hints. When the config declares `crossService`, it reads the cross-service subscription topology, as the build does. A consumed workspace library that changed since its last `vp pack` fails the run with the `STALE` line of `heximon doctor`. `--emit` also writes the generated app wiring to `.heximon/`; `--verify-baseline` names every durable record the committed `heximon.upgrade.json` has not acknowledged, with the code `<axis>.upgrade-unacknowledged`. `--update --dry-run` names the sections that `--update` would change, carries the whole would-be file in `upgradeBaseline.baseline` with `--json`, and writes no project file. |
79
79
  | `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. |
80
80
  | `heximon graph` | Prints the resolved module dependency graph: modules, providers, and dependencies. |
81
81
  | `heximon doctor` | Reports a package installed twice, an untraced deploy target, and a stale published module. |
@@ -189,11 +189,19 @@ the fix instructions plus a non-zero exit code.
189
189
  `.heximon/library/`.
190
190
  - **`heximon skills add` records only what it installed.** A source it could not fetch stays out of
191
191
  `heximon.skills`, so `heximon skills sync` never retries a URL that never worked.
192
- - **Adding a durable record is silent until you look for it.** A new queue channel, saga slot, workflow, or
193
- integration subscription is safe to deploy, so the upgrade check says nothing. `heximon check
194
- --verify-baseline` names every one the committed baseline has not acknowledged; add `--strict` to fail CI
195
- on them, then `heximon check --update` to accept them. That acceptance also refreshes the DI verdict
196
- mirror, so a bare `tsgo` on unchanged source passes right away.
192
+ - **A safe durable change is silent until you look for it.** A new queue channel, saga slot, workflow, or
193
+ integration subscription, a step appended to a workflow, or a widened payload is safe to deploy, so the
194
+ upgrade check says nothing. `heximon check --verify-baseline` names every record that `heximon check
195
+ --update` would write differently, with its own code, `<axis>.upgrade-unacknowledged`. A warning that the
196
+ check cannot compare a record keeps the code `<axis>.upgrade-review`, so one compile tells the two apart.
197
+ A committed section that no registered plugin records any more is reported too, because `--update` would
198
+ drop it.
199
+ Add `--strict` to fail CI on them, then `heximon check --update` to accept them. That acceptance also
200
+ refreshes the DI verdict mirror, so a bare `tsgo` on unchanged source passes right away.
201
+ - **`heximon check --update --dry-run` writes no project file.** It composes the file that `--update` would
202
+ write and says which sections would change. It writes no baseline, no verdict mirror and no wiring, and it
203
+ does not change `tsconfig.json`, so `--emit` with `--dry-run` is refused and a sidecar `debug: true` emits nothing. With `--json`, `upgradeBaseline.baseline` holds the whole file. A dry run
204
+ acknowledges nothing, so a breaking error still fails it, and it may run with `--verify-baseline`.
197
205
  - **`heximon workflows` still reports a breaking upgrade verdict per workflow.** The verdict comes out of a
198
206
  complete graph analysis, so the rows stay and the command exits non-zero. Only a genuine compile failure
199
207
  refuses the report. A workflow that only gained steps at the end reads as `appended`, not `diverged`.
package/dist/bin.mjs CHANGED
@@ -9,7 +9,7 @@ import { AstNodeType, CompileEnvironment, CompileMode, DeployPlatform, Diagnosti
9
9
  import { spawn } from "node:child_process";
10
10
  import { basename, dirname, isAbsolute, join, relative, resolve } from "pathe";
11
11
  import tab from "@bomb.sh/tab/citty";
12
- import { ConfigLoader, LibraryEmitter, LibraryFactoryPreflight, LibraryFreshness, LibraryFreshnessStatus, PnpmWorkspaceManifest, ProjectCompiler, RuntimeConfigLoader, SourceModuleResolution, SourceParser, WorkspaceTopologyReader } from "@heximon/compiler/project";
12
+ import { ConfigLoader, LibraryEmitter, LibraryFactoryPreflight, LibraryFreshness, LibraryFreshnessStatus, PnpmWorkspaceManifest, ProjectCompiler, RuntimeConfigLoader, SourceModuleResolution, SourceParser, TsconfigAliases, WorkspaceTopologyReader } from "@heximon/compiler/project";
13
13
  import { NodeCompileSeam } from "@heximon/node/compiler";
14
14
  import { TransactionCensus, TransactionCensusPolicy } from "@heximon/cqrs/compiler";
15
15
  import { BoundaryProvenanceAuditor, BoundaryProvenanceStatus, CredentialSelection, DatabaseConfigDetector, DeployDiagnosticSeverity, DeployLedger, DeployManifestStore, DeployRunner, DeployStrategyUnavailableError, DeployTargetResolver, DeployableServiceReader, DotenvCascade, DrizzleKitRunner, EnvFileReader, EnvFileUnreadableError, HostManagedDeployUnsupportedError, ImportScanner, MigrationInspector, MigrationTargetComposer, PackageCopyAuditor, PeerClosureAuditor, PlatformTracingAuditor, PlatformTracingStatus, SecretMask, WorkspaceConsumerLocator } from "@heximon/deploy";
@@ -19,9 +19,15 @@ import { pathToFileURL } from "node:url";
19
19
  import { homedir } from "node:os";
20
20
  //#region src/check-json-document.ts
21
21
  /** The stable codes of the failures `heximon check` raises itself, beside the compiler's own. */
22
- const CheckDiagnosticCode = {
23
- /** A consumed workspace library changed since its last `vp pack`, so the compile read an old manifest. */
24
- StaleLibrary: "check.stale-library" };
22
+ const CheckDiagnosticCode = {
23
+ /** A consumed workspace library changed since its last `vp pack`, so the compile read an old manifest. */
24
+ StaleLibrary: "check.stale-library",
25
+ /**
26
+ * Only under `--verify-baseline`: the committed `heximon.upgrade.json` has a section that no plugin of this
27
+ * build records and whose name is not one of the four durable concepts, so `--update` would drop it.
28
+ */
29
+ BaselineSectionUnacknowledged: "check.baseline-section-unacknowledged"
30
+ };
25
31
  //#endregion
26
32
  //#region src/compile-diagnostics.ts
27
33
  /**
@@ -167,6 +173,8 @@ var ConfigSidecar = class ConfigSidecar {
167
173
  var ProjectCompileSession = class ProjectCompileSession {
168
174
  /** The gitignored directory the compile anchors its generated paths at. */
169
175
  static outputDirectoryName = ".heximon";
176
+ /** Why a check reports a topology failure: the build of the same project fails on it too. */
177
+ static topologyFailureHint = "The sidecar declares `crossService`, so the build reads the cross-service subscription topology of the workspace and fails on the same error.";
170
178
  /** The absolute project root the compile runs against. */
171
179
  rootDir;
172
180
  /** The warm compiler — reused by a caller that also prunes or writes type verdicts. */
@@ -220,8 +228,8 @@ var ProjectCompileSession = class ProjectCompileSession {
220
228
  * Run the app-mode compile.
221
229
  *
222
230
  * @param typeVerdicts - Whether to emit the editor-verdict typegen file (only `heximon check` writes it).
223
- * @param options - `verifyBaseline` makes every durable concept also report the records the committed
224
- * `heximon.upgrade.json` never acknowledged. Nothing is written either way.
231
+ * @param options - The baseline verification pass, and the cross-service topology the fan-out
232
+ * diagnostics read.
225
233
  * @returns The compile output, diagnostics included.
226
234
  */
227
235
  compile(typeVerdicts = false, options = {}) {
@@ -235,16 +243,38 @@ var ProjectCompileSession = class ProjectCompileSession {
235
243
  ...this.runtimeConfig === void 0 ? {} : { runtimeConfig: this.runtimeConfig },
236
244
  ...this.config?.root === void 0 ? {} : { apps: { main: this.config.root } },
237
245
  ...typeVerdicts ? { typeVerdicts: true } : {},
238
- ...options.verifyBaseline === true ? { verifyBaseline: true } : {}
246
+ ...options.verifyBaseline === true ? { verifyBaseline: true } : {},
247
+ ...options.workspaceSubscribers === void 0 ? {} : { workspaceSubscribers: options.workspaceSubscribers }
239
248
  });
240
249
  }
250
+ /**
251
+ * Read the cross-service subscription topology for {@link compile}: only when the sidecar declares
252
+ * `crossService`, with the plugins and the `$env` name of this session, over the production graph that
253
+ * {@link compile} builds.
254
+ *
255
+ * @returns The topology, or one error diagnostic in place of the error the read threw.
256
+ */
257
+ async readWorkspaceTopology() {
258
+ try {
259
+ return {
260
+ topology: await WorkspaceTopologyReader.resolveFromConfig(this.rootDir, this.plugins, this.config, this.environment, CompileEnvironment.Production),
261
+ diagnostics: []
262
+ };
263
+ } catch (error) {
264
+ return {
265
+ topology: void 0,
266
+ diagnostics: [this.topologyFailure(error)]
267
+ };
268
+ }
269
+ }
241
270
  /** The platform the session compiles for, or `undefined` for the zero-config Node default. */
242
271
  platformName() {
243
272
  return this.strategy.platformName;
244
273
  }
245
274
  /**
246
275
  * Run the compile `vp build` runs, into a chosen directory: the production graph with the sidecar's wiring
247
- * mode, diagnostic dials and cross-service topology, which {@link compile} leaves out.
276
+ * mode, diagnostic dials and cross-service topology. {@link compile} leaves out the first two, and reads the
277
+ * topology only when its caller passes it.
248
278
  *
249
279
  * @param outputDirectory - The directory the generated files will be written to. It must sit directly
250
280
  * under the project root, because the generated imports of the app source are relative to it.
@@ -346,6 +376,22 @@ var ProjectCompileSession = class ProjectCompileSession {
346
376
  ...this.sourceDirectories === void 0 ? {} : { sourceDirectories: this.sourceDirectories }
347
377
  };
348
378
  }
379
+ /**
380
+ * The diagnostic for a topology read that threw. The reader puts the code of a known failure on the error
381
+ * and at the start of its message; the diagnostic carries the code once, in its own field.
382
+ */
383
+ topologyFailure(error) {
384
+ const message = error instanceof Error ? error.message : String(error);
385
+ const code = error?.code;
386
+ const knownCode = Object.values(DiagnosticCode).find((candidate) => candidate === code);
387
+ return {
388
+ severity: DiagnosticSeverity.Error,
389
+ message: knownCode !== void 0 && message.startsWith(`[${knownCode}] `) ? message.slice(knownCode.length + 3) : message,
390
+ location: this.rootDir,
391
+ hint: ProjectCompileSession.topologyFailureHint,
392
+ ...knownCode === void 0 ? {} : { code: knownCode }
393
+ };
394
+ }
349
395
  };
350
396
  //#endregion
351
397
  //#region src/source-directories.ts
@@ -484,6 +530,8 @@ var TransactionCensusReport = class TransactionCensusReport {
484
530
  * concept's gate half-wired — unacknowledgeable by `--update`, or unarmed with no nudge.
485
531
  */
486
532
  var UpgradeBaseline = class UpgradeBaseline {
533
+ /** The envelope key that names no section. */
534
+ static versionKey = "version";
487
535
  /**
488
536
  * The breaking-verdict codes `--update` acknowledges. Each concept contributes one; a code missing here would
489
537
  * survive its own acknowledgement and fail the command that just rewrote the baseline.
@@ -494,6 +542,48 @@ var UpgradeBaseline = class UpgradeBaseline {
494
542
  DiagnosticCode.IntegrationUpgradeBreaking,
495
543
  DiagnosticCode.SagaUpgradeBreaking
496
544
  ]);
545
+ /** The unacknowledged-record code of each durable concept section, keyed by section name. */
546
+ static unacknowledgedCodes = /* @__PURE__ */ new Map([
547
+ ["workflow", DiagnosticCode.WorkflowUpgradeUnacknowledged],
548
+ ["queue", DiagnosticCode.QueueUpgradeUnacknowledged],
549
+ ["integration", DiagnosticCode.IntegrationUpgradeUnacknowledged],
550
+ ["saga", DiagnosticCode.SagaUpgradeUnacknowledged]
551
+ ]);
552
+ /**
553
+ * `--verify-baseline`: one warning per committed section that no plugin of this compile emitted, because no
554
+ * plugin that records it is registered any more. `--update` drops such a section, and no plugin can say so.
555
+ *
556
+ * @param rootDir - The app root that holds the committed file.
557
+ * @param files - The files the compile generated.
558
+ * @param diagnostics - The compile's own diagnostics; a section a plugin already reported on is skipped.
559
+ * @param strictDiagnostics - The project's escalated codes, applied as the compiler applies them.
560
+ * @returns The warnings (errors when the project escalates their code), and the CLI code of each warning
561
+ * whose section is not one of the four durable concepts, so it has no compiler code.
562
+ */
563
+ static droppedSections(rootDir, files, diagnostics, strictDiagnostics) {
564
+ const committed = UpgradeBaseline.readCommitted(join(rootDir, UpgradeBaselineFile.fileName))?.document;
565
+ const cliCodes = /* @__PURE__ */ new Map();
566
+ if (typeof committed !== "object" || committed === null || Array.isArray(committed)) return {
567
+ diagnostics: [],
568
+ cliCodes
569
+ };
570
+ const emitted = new Set(files.map((file) => UpgradeBaselineFile.sectionOfGeneratedPath(file.path)));
571
+ return {
572
+ diagnostics: Object.keys(committed).filter((section) => section !== UpgradeBaseline.versionKey && !emitted.has(section) && !diagnostics.some((diagnostic) => diagnostic.code?.startsWith(`${section}.upgrade-`) === true)).sort().map((section) => {
573
+ const code = UpgradeBaseline.unacknowledgedCodes.get(section);
574
+ const escalated = code !== void 0 && strictDiagnostics.includes(code);
575
+ const diagnostic = {
576
+ severity: escalated ? DiagnosticSeverity.Error : DiagnosticSeverity.Warning,
577
+ ...code === void 0 ? {} : { code },
578
+ message: `the committed '${section}' section of ${UpgradeBaselineFile.fileName} has no plugin in this build that records it, so \`heximon check --update\` would drop it. Register the plugin again, or run \`heximon check --update\` and commit the result.`,
579
+ ...escalated ? { escalatedFrom: DiagnosticSeverity.Warning } : {}
580
+ };
581
+ if (code === void 0) cliCodes.set(diagnostic, CheckDiagnosticCode.BaselineSectionUnacknowledged);
582
+ return diagnostic;
583
+ }),
584
+ cliCodes
585
+ };
586
+ }
497
587
  /** Whether a diagnostic is a breaking upgrade verdict that `--update` acknowledges. */
498
588
  static isBreaking(code) {
499
589
  return code !== void 0 && UpgradeBaseline.breakingCodes.has(code);
@@ -503,14 +593,18 @@ var UpgradeBaseline = class UpgradeBaseline {
503
593
  return files.some((file) => UpgradeBaselineFile.sectionOfGeneratedPath(file.path) !== void 0);
504
594
  }
505
595
  /**
506
- * `--update`: recompose the committed baseline from every concept section this compile emitted
507
- * (write-if-changed) — the explicit acknowledgement that clears the breaking-change gate. Returns the target +
508
- * whether it changed, or `undefined` when the project has no durable surface to baseline.
596
+ * `--update --dry-run`: recompose the committed baseline from every concept section this compile emitted, and
597
+ * compare it with the committed file, without writing. With no section emitted, the file is the bare envelope
598
+ * when the committed file still holds sections (so `--update` drops them), and `undefined` otherwise.
509
599
  *
510
600
  * Composing rather than copying is what lets a further concept join the file without touching this command:
511
601
  * each plugin emits its own section, and the envelope is assembled here from whatever was emitted.
602
+ *
603
+ * @param rootDir - The app root that holds the committed file.
604
+ * @param files - The files the compile generated.
605
+ * @returns The would-be file, or `undefined` when there is nothing durable and nothing committed to drop.
512
606
  */
513
- static update(rootDir, files) {
607
+ static preview(rootDir, files) {
514
608
  const sections = /* @__PURE__ */ new Map();
515
609
  for (const file of files) {
516
610
  const section = UpgradeBaselineFile.sectionOfGeneratedPath(file.path);
@@ -521,21 +615,98 @@ var UpgradeBaseline = class UpgradeBaseline {
521
615
  continue;
522
616
  }
523
617
  }
524
- if (sections.size === 0) return;
525
- const content = UpgradeBaselineFile.compose(sections);
526
618
  const target = join(rootDir, UpgradeBaselineFile.fileName);
527
- let changed = true;
528
- try {
529
- changed = readFileSync(target, "utf8") !== content;
530
- } catch {
531
- changed = true;
532
- }
533
- if (changed) writeFileSync(target, content);
619
+ const committed = UpgradeBaseline.readCommitted(target);
620
+ if (sections.size === 0 && UpgradeBaseline.committedSections(committed?.document).length === 0) return;
621
+ const content = UpgradeBaselineFile.compose(sections);
622
+ const document = JSON.parse(content);
534
623
  return {
535
624
  target,
536
- changed
625
+ content,
626
+ document,
627
+ changed: committed?.content !== content,
628
+ changedSections: UpgradeBaseline.changedSections(document, committed?.document)
629
+ };
630
+ }
631
+ /**
632
+ * `--update`: write the file {@link preview} composes when it differs from the committed one — the explicit
633
+ * acknowledgement that clears the breaking-change errors. Returns the target + whether it changed, or
634
+ * `undefined` when there is nothing durable and no committed section to drop.
635
+ */
636
+ static update(rootDir, files) {
637
+ const preview = UpgradeBaseline.preview(rootDir, files);
638
+ if (preview === void 0) return;
639
+ if (preview.changed) writeFileSync(preview.target, preview.content);
640
+ return {
641
+ target: preview.target,
642
+ changed: preview.changed
643
+ };
644
+ }
645
+ /**
646
+ * The `--update --dry-run` outcome for the `--json` document.
647
+ *
648
+ * @param rootDir - The app root that holds the committed file.
649
+ * @param composed - Whether the run composed the file: an app compile with no blocking error.
650
+ * @param blockingErrors - The errors that would make `--update` refuse.
651
+ * @param preview - What {@link preview} returned, when the run composed the file.
652
+ * @returns The would-be file and its difference, or the reason `--update` would write nothing.
653
+ */
654
+ static dryRunResult(rootDir, composed, blockingErrors, preview) {
655
+ if (!composed) return {
656
+ written: false,
657
+ dryRun: true,
658
+ blockingErrors
659
+ };
660
+ if (preview === void 0) return {
661
+ written: false,
662
+ dryRun: true,
663
+ changed: false,
664
+ path: join(rootDir, UpgradeBaselineFile.fileName),
665
+ changedSections: []
666
+ };
667
+ return {
668
+ written: false,
669
+ dryRun: true,
670
+ changed: preview.changed,
671
+ path: preview.target,
672
+ baseline: preview.document,
673
+ changedSections: preview.changedSections
537
674
  };
538
675
  }
676
+ /** The committed file's text and its parsed form (`undefined` when it does not parse), or `undefined` when absent. */
677
+ static readCommitted(target) {
678
+ let content;
679
+ try {
680
+ content = readFileSync(target, "utf8");
681
+ } catch {
682
+ return;
683
+ }
684
+ try {
685
+ return {
686
+ content,
687
+ document: JSON.parse(content)
688
+ };
689
+ } catch {
690
+ return {
691
+ content,
692
+ document: void 0
693
+ };
694
+ }
695
+ }
696
+ /** The section names of a parsed committed file; none when it is not an object. */
697
+ static committedSections(committed) {
698
+ return typeof committed === "object" && committed !== null && !Array.isArray(committed) ? Object.keys(committed).filter((name) => name !== UpgradeBaseline.versionKey) : [];
699
+ }
700
+ /**
701
+ * The sections whose content differs between the would-be file and the committed one, sorted: a section only
702
+ * one side has counts too. An unreadable committed file has no sections, so each would-be section counts.
703
+ */
704
+ static changedSections(document, committed) {
705
+ const committedSections = typeof committed === "object" && committed !== null && !Array.isArray(committed) ? committed : {};
706
+ const names = /* @__PURE__ */ new Set([...Object.keys(document), ...Object.keys(committedSections)]);
707
+ names.delete(UpgradeBaseline.versionKey);
708
+ return [...names].filter((name) => !UpgradeBaselineFile.sameSection(document[name], committedSections[name])).sort();
709
+ }
539
710
  };
540
711
  //#endregion
541
712
  //#region src/check-command.ts
@@ -549,10 +720,17 @@ var UpgradeBaseline = class UpgradeBaseline {
549
720
  *
550
721
  * Two opt-in passes ride the same compile. `--emit` (and the sidecar's own `debug: true`) writes the generated
551
722
  * wiring to `.heximon/` and reformats it in place, so what the compiler produced can be read; a bare run writes
552
- * 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
553
- * committed `heximon.upgrade.json` never acknowledged — the direction the diff does not walk, since adding a
554
- * record is safe to deploy. It writes nothing, and is refused alongside `--update`, which acknowledges exactly
555
- * what it exists to show.
723
+ * 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, as
724
+ * `<axis>.upgrade-unacknowledged`, each record that `--update` would write differently from the committed
725
+ * `heximon.upgrade.json` — changes the diff does not report because they are safe to deploy. It writes no
726
+ * baseline, and is refused alongside a plain `--update`, which acknowledges exactly what it exists to show.
727
+ * `--update --dry-run` composes the file `--update` would write and reports it, and writes no project file: no
728
+ * baseline, no verdict mirror, no wiring, no tsconfig change. So it may run with `--verify-baseline`, and it is
729
+ * refused with `--emit`.
730
+ *
731
+ * When the sidecar declares `crossService`, the app leg reads the cross-service subscription topology of the
732
+ * workspace, as the build does, so the fan-out diagnostics of the build reach the check. A topology the build
733
+ * cannot read is a check error.
556
734
  *
557
735
  * A consumed workspace library whose source changed since its last `vp pack` fails the run before anything is
558
736
  * reported or written: the compile read its old manifest, so its verdicts are not trustworthy. The failure is the
@@ -598,14 +776,19 @@ const checkCommand = defineCommand({
598
776
  },
599
777
  update: {
600
778
  type: "boolean",
601
- description: "Regenerate + write the committed `heximon.upgrade.json` upgrade-safety baseline — the acknowledgement that clears a breaking durable-surface change (drain the in-flight work first).",
779
+ description: "Regenerate + write the committed `heximon.upgrade.json` upgrade-safety baseline — the acknowledgement that clears a breaking durable-surface change (drain the in-flight work first). Add --dry-run to see the file without writing it.",
602
780
  default: false
603
781
  },
604
782
  library: CompileModeResolver.flags.library,
605
783
  app: CompileModeResolver.flags.app,
606
784
  "verify-baseline": {
607
785
  type: "boolean",
608
- description: "Also report every durable record the committed `heximon.upgrade.json` never acknowledged (workflows, saga timeouts, queue channels, integration subscriptions). Writes nothing; pair with --strict to fail on them.",
786
+ description: "Also report every durable record that `--update` would write differently in the committed `heximon.upgrade.json` (workflows, saga timeouts, queue channels, integration subscriptions), as `<axis>.upgrade-unacknowledged`. Writes no baseline; pair with --strict to fail on them.",
787
+ default: false
788
+ },
789
+ "dry-run": {
790
+ type: "boolean",
791
+ description: "With --update: compose the baseline that --update would write and report whether it differs from the committed file. Writes no project file (no baseline, no verdict mirror, no wiring). `--json` carries the whole would-be file.",
609
792
  default: false
610
793
  },
611
794
  emit: {
@@ -622,7 +805,11 @@ const checkCommand = defineCommand({
622
805
  const resolved = CompileModeResolver.resolve(rootDir, args, sourceDirectories);
623
806
  const { mode } = resolved;
624
807
  const verifyBaseline = args["verify-baseline"] === true;
625
- if (verifyBaseline && args.update === true) throw CommandFailure.of(CliDiagnosticCode.InvalidOptions, "--verify-baseline reports what the committed baseline has not acknowledged, and --update acknowledges everything — pass one or the other.");
808
+ const update = args.update === true;
809
+ const dryRun = args["dry-run"] === true;
810
+ if (dryRun && !update) throw CommandFailure.of(CliDiagnosticCode.InvalidOptions, "--dry-run previews what --update would write — pass it together with --update.");
811
+ if (dryRun && args.emit === true) throw CommandFailure.of(CliDiagnosticCode.InvalidOptions, "--dry-run writes no project file, and --emit writes the generated wiring — pass one or the other.");
812
+ if (verifyBaseline && update && !dryRun) throw CommandFailure.of(CliDiagnosticCode.InvalidOptions, "--verify-baseline reports what the committed baseline has not acknowledged, and --update acknowledges everything — pass one or the other, or add --dry-run to --update.");
626
813
  if (!commandOutput.isJson()) intro(`heximon check — ${basename(rootDir)} · ${CompileModeResolver.stamp(resolved)}`);
627
814
  const session = await ProjectCompileSession.open({
628
815
  rootDir,
@@ -630,8 +817,9 @@ const checkCommand = defineCommand({
630
817
  ...sourceDirectories === void 0 ? {} : { sourceDirectories }
631
818
  });
632
819
  let checked;
820
+ let appCompileOptions = { verifyBaseline };
633
821
  if (mode === CompileMode.Library) {
634
- const emitted = session.compileLibrary({ pruneVerdicts: true });
822
+ const emitted = session.compileLibrary({ pruneVerdicts: !dryRun });
635
823
  const staleLibraries = await session.staleLibraryDiagnostics();
636
824
  checked = staleLibraries.length > 0 ? {
637
825
  diagnostics: staleLibraries,
@@ -644,7 +832,12 @@ const checkCommand = defineCommand({
644
832
  ...emitted.prunedVerdicts === void 0 ? {} : { prunedVerdicts: emitted.prunedVerdicts }
645
833
  };
646
834
  } else {
647
- const output = session.compile(true, { verifyBaseline });
835
+ const topology = await session.readWorkspaceTopology();
836
+ if (topology.topology !== void 0) appCompileOptions = {
837
+ verifyBaseline,
838
+ workspaceSubscribers: topology.topology
839
+ };
840
+ const output = session.compile(true, appCompileOptions);
648
841
  const staleLibraries = await session.staleLibraryDiagnostics();
649
842
  if (staleLibraries.length > 0) checked = {
650
843
  diagnostics: staleLibraries,
@@ -652,23 +845,33 @@ const checkCommand = defineCommand({
652
845
  staleLibraries: true
653
846
  };
654
847
  else {
655
- session.compiler.writeTypeVerdicts(output);
656
- session.compiler.healTsconfigInclude(session.typeVerdictTarget());
657
- const emitted = args.emit || session.config?.debug === true;
848
+ if (!dryRun) {
849
+ session.compiler.writeTypeVerdicts(output);
850
+ session.compiler.healTsconfigInclude(session.typeVerdictTarget());
851
+ }
852
+ const emitted = !dryRun && (args.emit || session.config?.debug === true);
658
853
  if (emitted) {
659
854
  session.compiler.write(session.outputDirectory, output.files);
660
855
  await session.compiler.formatOnDisk(rootDir, session.outputDirectory, output.files);
661
856
  }
857
+ const dropped = verifyBaseline ? UpgradeBaseline.droppedSections(rootDir, output.files, output.diagnostics, session.config?.strictDiagnostics ?? []) : void 0;
662
858
  checked = {
663
- diagnostics: output.diagnostics,
859
+ diagnostics: [
860
+ ...topology.diagnostics,
861
+ ...output.diagnostics,
862
+ ...dropped?.diagnostics ?? []
863
+ ],
664
864
  files: output.files,
865
+ ...dropped === void 0 ? {} : { cliCodes: dropped.cliCodes },
665
866
  ...emitted ? { emittedTo: session.outputDirectory } : {}
666
867
  };
667
868
  }
668
869
  }
669
870
  const blockingErrors = checked.diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error && diagnostic.escalatedFrom === void 0 && !UpgradeBaseline.isBreaking(diagnostic.code)).length;
670
- const rebaselined = mode === CompileMode.App && args.update && blockingErrors === 0 ? UpgradeBaseline.update(rootDir, checked.files) : void 0;
671
- if (rebaselined?.changed === true && checked.diagnostics.some((diagnostic) => UpgradeBaseline.isBreaking(diagnostic.code))) session.compiler.writeTypeVerdicts(session.compile(true, { verifyBaseline }));
871
+ const baselined = mode === CompileMode.App && update && blockingErrors === 0;
872
+ const rebaselined = baselined && !dryRun ? UpgradeBaseline.update(rootDir, checked.files) : void 0;
873
+ const previewed = baselined && dryRun ? UpgradeBaseline.preview(rootDir, checked.files) : void 0;
874
+ if (rebaselined?.changed === true && checked.diagnostics.some((diagnostic) => UpgradeBaseline.isBreaking(diagnostic.code))) session.compiler.writeTypeVerdicts(session.compile(true, appCompileOptions));
672
875
  const diagnostics = rebaselined !== void 0 ? checked.diagnostics.filter((diagnostic) => !UpgradeBaseline.isBreaking(diagnostic.code)) : checked.diagnostics;
673
876
  const errorCount = diagnostics.filter((diagnostic) => diagnostic.severity === DiagnosticSeverity.Error).length;
674
877
  const warningCount = diagnostics.length - errorCount;
@@ -680,14 +883,20 @@ const checkCommand = defineCommand({
680
883
  mode,
681
884
  errors: errorCount,
682
885
  warnings: warningCount,
683
- diagnostics: CliDiagnostics.fromCompiler(diagnostics).map((diagnostic) => checked.staleLibraries === true ? {
684
- ...diagnostic,
685
- code: CheckDiagnosticCode.StaleLibrary
686
- } : diagnostic),
886
+ diagnostics: CliDiagnostics.fromCompiler(diagnostics).map((diagnostic, index) => {
887
+ const cliCode = checked.cliCodes?.get(diagnostics[index]);
888
+ return checked.staleLibraries === true ? {
889
+ ...diagnostic,
890
+ code: CheckDiagnosticCode.StaleLibrary
891
+ } : cliCode === void 0 ? diagnostic : {
892
+ ...diagnostic,
893
+ code: cliCode
894
+ };
895
+ }),
687
896
  ...census === void 0 ? {} : { transactionCensus: census },
688
897
  ...checked.prunedVerdicts === void 0 ? {} : { prunedVerdicts: checked.prunedVerdicts },
689
898
  ...checked.emittedTo === void 0 ? {} : { emittedTo: checked.emittedTo },
690
- ...args.update === true ? { upgradeBaseline: rebaselined === void 0 ? {
899
+ ...update ? { upgradeBaseline: dryRun ? UpgradeBaseline.dryRunResult(rootDir, baselined, blockingErrors, previewed) : rebaselined === void 0 ? {
691
900
  written: false,
692
901
  blockingErrors
693
902
  } : {
@@ -700,12 +909,15 @@ const checkCommand = defineCommand({
700
909
  } else {
701
910
  if (checked.emittedTo !== void 0) log.info(`Wrote the generated wiring to ${checked.emittedTo}`);
702
911
  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.`);
703
- 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\`.`);
912
+ if (mode === CompileMode.Library && !dryRun && (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\`.`);
704
913
  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.`);
705
- 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.`);
706
- 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.`);
707
- else if (args.update === true && blockingErrors > 0) log.warn(`${UpgradeBaselineFile.fileName} NOT updated — this compile has ${blockingErrors} unrelated error${blockingErrors === 1 ? "" : "s"}, so its durable surface is only partly analyzed and baselining it would acknowledge less than the app really has. Fix those first, then re-run.`);
708
- else if (args.update === true) log.info("Nothing durable to baseline — no workflows, queue channels or other durable surface found.");
914
+ if (mode === CompileMode.Library && update) 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.`);
915
+ else if (previewed !== void 0) {
916
+ if (previewed.changed) log.info(`--update would change ${UpgradeBaselineFile.fileName} — ` + (previewed.changedSections.length > 0 ? `sections: ${previewed.changedSections.join(", ")}.` : "its format only.") + " Nothing written (--dry-run); `--json` carries the whole file.");
917
+ else log.success(`${UpgradeBaselineFile.fileName} already up to date — nothing written (--dry-run).`);
918
+ } 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.`);
919
+ else if (update && blockingErrors > 0) log.warn(`${UpgradeBaselineFile.fileName} NOT ${dryRun ? "composed" : "updated"} — this compile has ${blockingErrors} unrelated error${blockingErrors === 1 ? "" : "s"}, so its durable surface is only partly analyzed and baselining it would acknowledge less than the app really has. Fix those first, then re-run.`);
920
+ else if (update) log.info("Nothing durable to baseline — no workflows, queue channels or other durable surface found.");
709
921
  const census = TransactionCensusReport.read(checked.files);
710
922
  const censusSummary = census === void 0 ? void 0 : TransactionCensusReport.summarize(census);
711
923
  if (census !== void 0 && censusSummary !== void 0) {
@@ -723,7 +935,7 @@ const checkCommand = defineCommand({
723
935
  if (warningCount > 0) parts.push(`${warningCount} warning${warningCount === 1 ? "" : "s"}`);
724
936
  outro(`Check failed — ${parts.join(", ")}.`);
725
937
  } else {
726
- const closing = mode === CompileMode.Library ? "Library compiled." : "Verdicts refreshed.";
938
+ const closing = dryRun ? "Dry run, nothing written." : mode === CompileMode.Library ? "Library compiled." : "Verdicts refreshed.";
727
939
  if (warningCount > 0) {
728
940
  log.warn(`${warningCount} warning${warningCount === 1 ? "" : "s"} — not failing (pass --strict to fail on warnings too).`);
729
941
  outro(closing);
@@ -5205,111 +5417,6 @@ var TaskTargetResolver = class TaskTargetResolver {
5205
5417
  }
5206
5418
  };
5207
5419
  //#endregion
5208
- //#region src/tsconfig-aliases.ts
5209
- /**
5210
- * Reads the module aliases of a Nitro project from the `paths` of its tsconfig files. Nitro writes the aliases
5211
- * of a project into a generated tsconfig, and the project's tsconfig extends it and adds its own. The
5212
- * files are read as they are on disk: nothing is generated, and no config of the project runs.
5213
- *
5214
- * TypeScript's rules apply. A `paths` of a config replaces the `paths` of what it extends. `baseUrl` is the
5215
- * nearest one in the chain, and a target is relative to it; without one, a target is relative to the directory
5216
- * of the config that sets `paths`. An exact pattern wins over a wildcard one, and a longer wildcard prefix wins
5217
- * over a shorter one.
5218
- */
5219
- var TsconfigAliases = class TsconfigAliases {
5220
- /** Where Nitro writes its generated tsconfig, below the build directory. */
5221
- static generatedFiles = ["node_modules/.nitro/types/tsconfig.json", ".nitro/types/tsconfig.json"];
5222
- /** The longest `extends` chain followed. */
5223
- static maximumDepth = 8;
5224
- /**
5225
- * The aliases of the project. The project's tsconfig wins over the generated one that it does not extend.
5226
- *
5227
- * @param rootDir - The project root.
5228
- */
5229
- static read(rootDir) {
5230
- const exact = {};
5231
- const prefixes = {};
5232
- for (const file of [...TsconfigAliases.generatedFiles.map((name) => join(rootDir, name)), join(rootDir, "tsconfig.json")]) {
5233
- const options = TsconfigAliases.optionsOf(file, 0);
5234
- if (options.paths === void 0) continue;
5235
- const base = options.baseUrl ?? options.paths.directory;
5236
- for (const [pattern, targets] of Object.entries(options.paths.entries)) {
5237
- const target = targets[0];
5238
- if (target === void 0) continue;
5239
- if (pattern.endsWith("/*") && target.endsWith("/*")) prefixes[pattern.slice(0, -2)] = resolve(base, target.slice(0, -2));
5240
- else if (!pattern.includes("*") && !target.includes("*")) exact[pattern] = resolve(base, target);
5241
- }
5242
- }
5243
- return {
5244
- exact,
5245
- prefixes
5246
- };
5247
- }
5248
- /** The effective options of one tsconfig, after the files it extends. */
5249
- static optionsOf(file, depth) {
5250
- if (!existsSync(file) || depth > TsconfigAliases.maximumDepth) return {};
5251
- let config;
5252
- try {
5253
- config = JSON.parse(TsconfigAliases.toJson(readFileSync(file, "utf8")));
5254
- } catch {
5255
- return {};
5256
- }
5257
- const options = {};
5258
- const parents = typeof config.extends === "string" ? [config.extends] : [...config.extends ?? []];
5259
- for (const parent of parents) if (parent.startsWith(".") || isAbsolute(parent)) {
5260
- const path = resolve(dirname(file), parent);
5261
- const inherited = TsconfigAliases.optionsOf(path.endsWith(".json") ? path : `${path}.json`, depth + 1);
5262
- Object.assign(options, inherited);
5263
- }
5264
- if (config.compilerOptions?.baseUrl !== void 0) options.baseUrl = resolve(dirname(file), config.compilerOptions.baseUrl);
5265
- if (config.compilerOptions?.paths !== void 0) options.paths = {
5266
- entries: config.compilerOptions.paths,
5267
- directory: dirname(file)
5268
- };
5269
- return options;
5270
- }
5271
- /**
5272
- * A tsconfig is JSON with comments and trailing commas. This removes both and leaves every string as it is,
5273
- * so `JSON.parse` can read the text.
5274
- */
5275
- static toJson(text) {
5276
- let withoutComments = "";
5277
- let inString = false;
5278
- for (let index = 0; index < text.length; index += 1) {
5279
- const character = text[index];
5280
- if (inString) {
5281
- withoutComments += character;
5282
- if (character === "\\") withoutComments += text[++index] ?? "";
5283
- else if (character === "\"") inString = false;
5284
- } else if (character === "\"") {
5285
- inString = true;
5286
- withoutComments += character;
5287
- } else if (character === "/" && text[index + 1] === "/") {
5288
- while (index < text.length && text[index] !== "\n") index += 1;
5289
- withoutComments += "\n";
5290
- } else if (character === "/" && text[index + 1] === "*") {
5291
- index = text.indexOf("*/", index + 2);
5292
- index = index === -1 ? text.length : index + 1;
5293
- } else withoutComments += character;
5294
- }
5295
- let json = "";
5296
- inString = false;
5297
- for (let index = 0; index < withoutComments.length; index += 1) {
5298
- const character = withoutComments[index];
5299
- if (inString) {
5300
- json += character;
5301
- if (character === "\\") json += withoutComments[++index] ?? "";
5302
- else if (character === "\"") inString = false;
5303
- } else if (character === "\"") {
5304
- inString = true;
5305
- json += character;
5306
- } else if (character === "," && /^\s*[}\]]/.test(withoutComments.slice(index + 1))) continue;
5307
- else json += character;
5308
- }
5309
- return json;
5310
- }
5311
- };
5312
- //#endregion
5313
5420
  //#region src/task-runner.ts
5314
5421
  /** The in-process client of a run. A run serves no HTTP, so every call fails with the reason. */
5315
5422
  var RefusingInternalClient = class {
package/dist/index.d.mts CHANGED
@@ -82,6 +82,11 @@ interface CliFailureDocument extends CliJsonDocument {
82
82
  declare const CheckDiagnosticCode: {
83
83
  /** A consumed workspace library changed since its last `vp pack`, so the compile read an old manifest. */
84
84
  readonly StaleLibrary: "check.stale-library";
85
+ /**
86
+ * Only under `--verify-baseline`: the committed `heximon.upgrade.json` has a section that no plugin of this
87
+ * build records and whose name is not one of the four durable concepts, so `--update` would drop it.
88
+ */
89
+ readonly BaselineSectionUnacknowledged: "check.baseline-section-unacknowledged";
85
90
  };
86
91
  /** One of the {@link CheckDiagnosticCode} values. */
87
92
  type CheckDiagnosticCode = (typeof CheckDiagnosticCode)[keyof typeof CheckDiagnosticCode];
@@ -91,6 +96,8 @@ type CheckUpgradeBaselineResult = {
91
96
  readonly written: false;
92
97
  /** How many of those errors there are. */
93
98
  readonly blockingErrors: number;
99
+ /** Present on a `--dry-run`, which would not have written the file for the same reason. */
100
+ readonly dryRun?: true;
94
101
  } | {
95
102
  /** The baseline was written or confirmed. */
96
103
  readonly written: true;
@@ -98,6 +105,22 @@ type CheckUpgradeBaselineResult = {
98
105
  readonly changed: boolean;
99
106
  /** The absolute path of the baseline file. */
100
107
  readonly path: string;
108
+ } | {
109
+ /** A `--dry-run` writes no project file. */
110
+ readonly written: false;
111
+ /** The run was `--update --dry-run`. */
112
+ readonly dryRun: true;
113
+ /** Whether `--update` would change the committed file, byte for byte. An absent file would change. */
114
+ readonly changed: boolean;
115
+ /** The absolute path of the baseline file. */
116
+ readonly path: string;
117
+ /**
118
+ * The whole file `--update` would write, parsed. Absent when nothing is durable and the committed file
119
+ * holds no section, so `--update` would write nothing.
120
+ */
121
+ readonly baseline?: Readonly<Record<string, unknown>>;
122
+ /** The sections whose content differs from the committed file, sorted. A section only one side has counts. */
123
+ readonly changedSections: readonly string[];
101
124
  };
102
125
  /** The `heximon check --json` document. */
103
126
  interface CheckJsonDocument extends CliJsonDocument {
@@ -113,7 +136,7 @@ interface CheckJsonDocument extends CliJsonDocument {
113
136
  readonly prunedVerdicts?: string;
114
137
  /** Where `--emit` wrote the generated wiring. */
115
138
  readonly emittedTo?: string;
116
- /** The `--update` outcome, present only with `--update`. */
139
+ /** The `--update` outcome (or its `--dry-run` preview), present only with `--update`. */
117
140
  readonly upgradeBaseline?: CheckUpgradeBaselineResult;
118
141
  }
119
142
  //#endregion
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "heximon",
3
- "version": "0.11.1",
3
+ "version": "0.12.0",
4
4
  "description": "The Heximon CLI: create, develop, build, migrate, and deploy Heximon apps.",
5
5
  "keywords": [
6
6
  "cli",
@@ -38,26 +38,26 @@
38
38
  "dependencies": {
39
39
  "@bomb.sh/tab": "^0.0.22",
40
40
  "@clack/prompts": "^1.8.1",
41
- "@heximon/compiler": "0.11.1",
42
- "@heximon/cqrs": "0.11.1",
43
- "@heximon/deploy": "0.11.1",
44
- "@heximon/http": "0.11.1",
45
- "@heximon/node": "0.11.1",
46
- "@heximon/runtime": "0.11.1",
47
- "@heximon/testing": "0.11.1",
41
+ "@heximon/compiler": "0.12.0",
42
+ "@heximon/cqrs": "0.12.0",
43
+ "@heximon/deploy": "0.12.0",
44
+ "@heximon/http": "0.12.0",
45
+ "@heximon/node": "0.12.0",
46
+ "@heximon/runtime": "0.12.0",
47
+ "@heximon/testing": "0.12.0",
48
48
  "citty": "^0.2.2",
49
49
  "giget": "^3.3.1",
50
50
  "pathe": "^2.0.3"
51
51
  },
52
52
  "devDependencies": {
53
- "@heximon/cloudflare": "0.11.1",
54
- "@heximon/durable": "0.11.1",
55
- "@heximon/integration": "0.11.1",
56
- "@heximon/library": "0.11.1",
57
- "@heximon/nitro": "0.11.1",
58
- "@heximon/queue": "0.11.1",
59
- "@heximon/schedule": "0.11.1",
60
- "@heximon/schema": "0.11.1",
53
+ "@heximon/cloudflare": "0.12.0",
54
+ "@heximon/durable": "0.12.0",
55
+ "@heximon/integration": "0.12.0",
56
+ "@heximon/library": "0.12.0",
57
+ "@heximon/nitro": "0.12.0",
58
+ "@heximon/queue": "0.12.0",
59
+ "@heximon/schedule": "0.12.0",
60
+ "@heximon/schema": "0.12.0",
61
61
  "@heximon/test-support": "0.0.1",
62
62
  "@types/node": "^24.19.0",
63
63
  "@typescript/native-preview": "^7.0.0-dev.20260707.2",