@xemahq/repo-build-tooling 0.10.1 → 0.10.2

package/README.md

@@ -1,138 +1,46 @@
-# `@xemahq/repo-build-tooling`
-
-This package belongs to Layer 1 — dev-time build tooling shared by every Xema
-repository. Nothing here ever ships inside a service image; every consumer
-declares it as a `devDependency`.
-
-## Why it is a package and not a file
-
-It used to be a file — five byte-identical copies of one 700-line script, one
-per repository that needed it, kept honest by a boundary check that ran each
-copy's `--self-test`.
-
-That arrangement could not hold the invariant it existed for. A defect found in
-one copy is fixed in one copy; the other four keep shipping it until someone
-remembers. Exactly that happened: three of the five copies deliberately carried
-*less* behaviour than the other two (they detected a leak shape without
-rewriting it), which was a reasonable decision at the time and then became a
-permanent, undocumented divergence nobody re-examined. A parity check on N
-copies is a workaround for not having one artifact.
-
-## How the two resolution modes work
-
-This is the standard shape in this fleet, and getting it wrong is the single
-most common source of "green locally, red in CI":
-
-- **Inside the `xema-monorepo` aggregator**, the root `package.json`'s
-  `pnpm.overrides` maps `@xemahq/repo-build-tooling` to `workspace:*`, so it
-  resolves to this directory. Editing the tool and rebuilding a service in the
-  same checkout needs no publish, no version bump and no registry round-trip.
-- **Inside each independent repository's own CI**, there is no aggregator and no
-  sibling checkout. The declared semver range is what resolves, from npm.
-
-So the range in a consumer's `package.json` is the real contract, and the local
-link is a development convenience layered on top. A symbol added here is not
-available to a consumer until this package is published AND that consumer's
-range admits the new version — the aggregator will happily compile against the
-local source and tell you nothing.
-
-## Contents
-
-### `xema-scrub-swagger-paths <dist-dir> [<dist-dir>…]`
-
-Post-build sanitizer for `@nestjs/swagger` plugin output, and the verification
-step for the same property. The plugin writes `require()` literals into
-`_OPENAPI_METADATA_FACTORY()` at `nest build` time — they exist in no source
-file — so this is the only thing in the fleet that can see them, and it runs
-immediately after `nest build` in all 54 services that use the plugin.
-
-It rewrites specifiers that name the builder's private install layout into the
-target package's public specifier, then re-reads the output from disk and fails
-the build if any leak survives.
-
-The rewrite is **derived and proved**, never tabled: the replacement comes from
-the target package's own `exports` map, and is accepted only if the emitted
-re-export chain (read statically — package code is never executed) reaches the
-same module. It refuses rather than guesses. That matters because the two
-packages that leak most are opposites — `@xemahq/kernel-contracts` exports only
-`./*` and has no root export, so rewriting to the bare name would swap one crash
-for another, while `@xemahq/platform-common` exports both `.` and `./dist/*`.
-
-`--self-test` proves, on a scratch tree with no build and no fixtures, that a
-missing/empty/no-`.js` directory each FAIL, that the detector matches every leak
-shape and no clean literal, and that a residual leak fails the run. This step's
-failure mode is silence, so "0 leaks" and "0 files read" must never be
-indistinguishable.
-
-### `xema-composed-image <command>`
-
-The build-time half of a repository's composed-process image (the runtime half,
-the `xema-composed-process` host, is `@xemahq/xema-service-nest`'s). One image per
-build carries every composable platform service of the repository at one commit.
-
-- `members --write|--check` derives that set from the tracked biome manifests and
-  writes or verifies `infra/composed-process/image-build-inputs.json`. A member is a
-  `kind: service` with `scheduler: platform`; workers, jobs and runtime-scheduled
-  services never are. A service is left out, with its reason printed, when its
-  `src/main.ts` is not one top-level `void bootstrapXemaService(…)`, it has its own
-  `Dockerfile`, it bakes cross-repository inputs, or the canonical Dockerfile
-  installs a toolchain for it. Options say where the repository keeps those facts:
-  `--manifests <glob>` (repeatable, default `**/xema-biome.json`),
-  `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>` (both optional).
-- Inside the image build: `filters` and `dirs` name the members' closures,
-  `pins <committed-lockfile>` refuses a re-resolution that moves a registry pin,
-  `index <commit> --build-source <repo>` writes the member index the host reads
-  (graded by `@xemahq/contracts/process-topology`, resolved from the members) and
-  links the host bin, and `load` evaluates every member's entry through the host's
-  `readServiceEntry`. `--build-source` is the `repo` the repository's subjects carry
-  in an edition's image lock.
-
-- `coordinate --image-name <name>` is the image's release coordinate: the content tag
-  and whether GHCR already serves it (only 200 and 404 are answers). The tag is computed
-  ONLY by the repository's own `@xemahq/distribution-source-hash` (`xema-compute-image-tag`,
-  resolved from the repository root); the command refuses when it is not installed, and never
-  hashes anything itself. Environment: `SHA`, `REGISTRY`, `REGISTRY_ORG`, `REGISTRY_USER`,
-  `REGISTRY_TOKEN`, optional `TAG_ARGS_FILE`, `GITHUB_OUTPUT`. Outputs `image`, `content_tag`,
-  `exists`, `entry`. The registry check is also exported as `./ghcr-manifest`
-  (`ghcrManifestExists`, `acquireGhcrPullToken`).
-- `load-image <image>` runs the member-load check inside the shipped image (`docker run`), as its own user and `NODE_ENV`; `load` runs in the builder and cannot prove that.
-- `smoke-refusal <image> [--member <biomeId>/<componentKey>]x2` boots the pushed image
-  with two members on one port and fails unless the host refuses at the declaration, names
-  the collision, and constructs no member. Needs only `docker`.
-- `dockerfile --write|--check --tooling-version <x.y.z> --copy <dir>… --cache-id <id> --build-source <repo>`
-  renders `infra/composed-process/Dockerfile` from one template. The builder stage installs
-  this tool at the EXACT version (so the hashed image directory moves when the tool does),
-  runs every step above, and runs `load` last as `node` with `NODE_ENV=production`. Nothing here
-  ships in an image: the final stage copies `/monorepo` only.
-
-Every step refuses rather than skips. The tool has no dependencies: the host and
-the kernel schema are resolved from the members being built.
-
-### `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]`
-
-Generates the descriptors `@xemahq/xema-service-nest` boots from, out of the
-repository's own `xema-biome.json` manifests. For every `kind: service` component
-it writes `src/generated/<name>.bootstrap.generated.ts` (a `BiomeServiceDescriptor`),
-and for every `kind: worker` component `src/generated/<key>.worker-descriptor.generated.ts`
-(a `XemaWorkerDescriptor`; a `shared-oci-image` worker lands in the package of the
-component whose image it shares). Only packages that declare
-`@xemahq/xema-service-nest` are written to.
-
-`requirements.scaling.concurrency.maximumPerInstance` becomes
-`maximumConcurrentRequests` on a service and `maximumConcurrentActivities` on a
-worker. A component without a positive integer there is refused, naming the
-manifest and the component.
-
-`--check` writes nothing and fails on any drift. A run that finds no manifest, or no
-service or worker to generate, fails rather than reporting success. Run it from the
-repository root, or pass `--root`.
-
-## Scope boundary
-
-Dev-time tooling that **more than one repository** runs. Two rules keep it from
-becoming a junk drawer:
-
-- Nothing with a runtime consumer. If a service imports it at run time it is not
-  build tooling and belongs in an SDK package.
-- Nothing with a single consumer. A tool used by one repository stays in that
-  repository until a second one needs it.
+# @xemahq/repo-build-tooling
+
+> Dev-time build tooling shared by every Xema repository
+
+## Overview
+
+Command-line tools that more than one Xema repository runs at build or check time. Nothing here ships in a service image; consumers declare it as a `devDependency`.
+
+## When to use it
+
+- To run the shared build and readiness checks in a repository, locally or in CI.
+
+## Installation
+
+```bash
+pnpm add -D @xemahq/repo-build-tooling
+```
+
+## Usage
+
+```bash
+pnpm exec xema-readiness
+pnpm exec xema-service-bootstrap --check
+pnpm exec xema-scrub-swagger-paths dist
+```
+
+| Bin | What it does |
+| --- | --- |
+| `xema-readiness` | Runs the ordered checks between a source change and a push |
+| `xema-service-bootstrap [--check] [--filter <key>] [--root <dir>]` | Generates `src/generated/*.generated.ts` service and worker descriptors from the repository's `xema-biome.json` manifests; `--check` fails on drift |
+| `xema-scrub-swagger-paths <dist-dir>...` | Rewrites `@nestjs/swagger` plugin output that names a private install path, then fails the build if any leak remains (`--self-test` available) |
+| `xema-composed-image <command>` | Build-time half of a composed-process image: `members`, `filters`, `dirs`, `pins`, `index`, `load`, `coordinate`, `load-image`, `smoke-refusal`, `dockerfile` |
+| `xema-check-no-vendored-deps` | Fails on a `workspace:` range for a package the repository does not own |
+| `xema-check-workspace-ranges` | Fails on a `workspace:` range the local package does not satisfy |
+
+`xema-composed-image members --write|--check` accepts `--manifests <glob>` (repeatable, default `**/xema-biome.json`), `--canonical-dockerfile <path>` and `--cross-repo-manifest <path>`. `xema-composed-image dockerfile` requires `--tooling-version`, `--copy`, `--cache-id` and `--build-source`. Run `xema-composed-image` with no arguments for the full usage.
+
+Every step refuses rather than skips. The package has no dependencies.
+
+## Resolution
+
+Inside the `xema-monorepo` aggregator, `@xemahq/repo-build-tooling` resolves to this directory through a workspace override. In an independent repository's CI it resolves from npm by the declared range, so a change here reaches a consumer only after it is published and the consumer's range admits it.
+
+## License
+
+Apache-2.0 &copy; Xema — [xema.dev](https://xema.dev)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/repo-build-tooling",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Dev-time build tooling shared by every Xema repository. Ships as plain ESM with zero dependencies so the published artifact is the reviewed source.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -42,6 +42,6 @@
     "test": "node src/scrub-swagger-plugin-paths.mjs --self-test && node --test src/check-workspace-range-matches-local.test.mjs && node --test src/check-no-vendored-deps.test.mjs && node --test src/readiness.test.mjs && node --test src/composed-image.test.mjs && node --test src/ghcr-manifest.test.mjs && node --test src/declaration-refusal.test.mjs && node --test src/smoke-refusal.test.mjs && node --test src/load-image.test.mjs && node --test src/composed-image-coordinate.test.mjs && node --test src/composed-image-dockerfile.test.mjs && node --test src/registry-fetch.test.mjs && node --test src/service-bootstrap.test.mjs && node --test src/service-bootstrap-protocols.test.mjs"
   },
   "xemaRelease": {
-    "sourceDigest": "sha256:35b4aafd2345b2d892fff707b22790985f6ae1e20f75d0f7467f3401f8b583d2"
+    "sourceDigest": "sha256:6e85c2039576c5febe254e42d36eef92248dd33a88a8f86416ff654ff36a2765"
   }
 }