ansiblings/packages/nopy/docs/CUBE-PACKAGES.md

Cube bundles as npm packages

Status: All six phases have landed. This document is now a record, not a plan. The one thing still unproven is the publish lane against a real registry — see Risks. cubePackages resolves and loads end to end, @bitsquare/nopy-cube exists and the publish lane can ship a linked package. What is missing is a bundle to point cubePackages at.

Distributing cubes as npm packages so a project can pnpm add @acme/cubes-net and have its cubes show up in nopy alongside local ones.

Goals

• A cube bundle is an ordinary npm package, publishable to npmjs or Gitea through the existing release lanes.
• A consuming project opts into a bundle explicitly, by name, in .nopyrc.json.
• Existing manifests, dependency specs (dependencies: () => ['apt:essentials']) and stored session history keep working untouched.
• The in-repo cubes/ tree becomes the first published bundle, proving the path.

Non-goals

• Automatic discovery of bundles from the dependency tree. Cubes run privileged deploy scripts against real hosts; a transitive dependency contributing one silently is a supply-chain hole. Opt-in per package, always.
• Namespacing or id rewriting. Ids stay flat and global (see Decisions).
• Version compatibility checks between a bundle and the nopy running it. Noted as a risk, deferred.

Decisions

Question	Decision
Duplicate cube ids across sources	Hard error. No precedence, no shadowing. Mitigation is a good error message, not a fallback.
Id format	Unchanged, flat. The id is the session key (dependencies.ts:135); changing it breaks --repeat-last and --history.
Discovery	Explicit cubePackages list in .nopyrc.json.
Migrate in-repo cubes/	Yes — packages/cubes-core, as the proof of concept.
Split an authoring package (@bitsquare/nopy-cube)	Yes. Bundles take a regular dependency on it; @bitsquare/nopy re-exports it for backwards compatibility. See Phase 4.

Current state

What already works, unchanged:

• --chdir <cubeDir> (nopy.executor.ts) means a deploy.py under node_modules runs fine; pyinfra only needs the path.
• scanDirectory skips node_modules when descending (loader.ts:101), not for the root it is handed. So "cubeDirs": ["./node_modules/@acme/cubes-net/cubes"] works today. That is the escape hatch until this lands, and it stays working afterwards.

What blocks a clean story:

1. Manifest imports. manifest.mjs does import { cubes } from '@bitsquare/nopy', resolved by ordinary Node resolution from the manifest's own directory. From inside node_modules/@acme/cubes-net/, that resolves upward into the consumer's node_modules — fine if the consumer installed @bitsquare/nopy, ERR_MODULE_NOT_FOUND if nopy is only installed globally. Same gotcha CLAUDE.md already documents for the local cubes/ tree.
2. No way to name a package in config, only paths.
3. Recursively scanning node_modules is not a workaround. pnpm symlinks direct deps, and readdir(withFileTypes) reports a symlink as isSymbolicLink(), not isDirectory() — the scan would skip every package. Package roots must be resolved explicitly.

Phase 0 — fixes that land first — done

Independent of packaging, and the duplicate-id work depends on them.

0.1 scanDirectory drops subtrees on duplicates. loader.ts:84-87 pushed the error and returned, which exited before the recursive descent at line 100. Cubes nested below a duplicate never got scanned, so the error report was incomplete: you fix one collision, re-run, find the next.

0.2 Duplicate detection is order-dependent. loadCubes() ran Promise.all over folders into a shared cubes object, so which source was "first" and which was "the duplicate" varied run to run.

Both are one restructure. Scanning and id resolution are now separate passes: each root fills its own ScanResult, the lists are concatenated in root order (Promise.all preserves input order regardless of completion order), and a grouping pass builds cubes and the errors. scanDirectory no longer decides anything about ids, so it always descends. Directory entries are sorted, and a directory reachable from two roots is deduped by path — one cube seen twice is not a collision, which it used to be reported as.

0.3 apt:essentials is already declared twice. cubes/apt/essentials declares it via id; packages/nopy/cubes/apt/essentials declared it via an [apt:essentials] prefix in name. cubeDirs merges root-first, so running nopy from packages/nopy collected both and aborted. Confirmed against the real trees before the rename:

Duplicate cube id 'apt:essentials' from 2 sources:
  /…/ansiblingz/cubes/apt/essentials
  /…/ansiblingz/packages/nopy/cubes/apt/essentials
Rename one of them, or remove a source from .nopyrc.json.

The three packages/nopy/cubes fixtures are now [test:apt-essentials], [test:apt-all] and [test:apt-more]; all 25 cubes load with no errors. Their dependencies were stale too — they named apt/more and apt/essentials, which are not ids anything declares — so they now point at the renamed ids.

0.4 coerceValue breaks if zod is ever duplicated. nopy.prompts.ts:147-154 discriminated with instanceof z.ZodDefault, z.ZodBoolean, z.ZodNumber and friends — checks against the running CLI's zod instance. The moment a bundle resolves its own copy of zod (entirely possible once manifests arrive from node_modules; see Phase 4), every check returns false and coerceValue falls through to the raw string, silently. Booleans stop being booleans.

defaultValueOf in cubes/types.ts had the same breakage, reached whenever a schema has one field without a .default() — getDefaults() tries safeParse({}) first, which is instance-agnostic, and only then drops to the per-field read.

Both now discriminate on def.type, a plain string that holds across instances, via two exported helpers (zodKind, zodInner). Verified on the installed zod 4.4.3:

z.boolean().default(false).def.type        → 'default'
z.boolean().default(false).def.innerType   → { def: { type: 'boolean' } }
z.number().def.type                        → 'number'

tests/helpers/foreign-zod.ts rebuilds a schema as plain objects carrying zod's def but not its prototype — structurally what a second copy of zod produces, and instanceof-blind, so neither call site can regress.

Worth noting for Phase 4: zod 4 exposes def.defaultValue as a getter that already invokes a lazily declared default, so the typeof === 'function' branch in defaultValueOf is now dead. It is kept as insurance against that changing.

Phase 1 — the bundle contract

A cube bundle is an npm package with a nopy field:

{
  "name": "@acme/cubes-net",
  "version": "1.0.0",
  "type": "module",
  "files": ["cubes", "README.md", "LICENSE"],
  "keywords": ["nopy", "nopy-cubes", "pyinfra"],
  "dependencies": {
    "@bitsquare/nopy-cube": "^1.0.0",
    "zod": "^4.4.3"
  },
  "publishConfig": { "access": "public" }
}

Rules:

• Cube location is a convention, <root>/cubes. (Amended after Phase 5; originally nopy.cubes was a required field.) The field bought nothing a convention does not: it is not a discovery marker — naming the package in cubePackages already is one — and it says nothing about whether the directories were actually packed, which is the failure authors really hit. nopy.cubes remains as an override, directories relative to the package root, for the bundle whose cubes are elsewhere (dist/cubes after a build). Absent means the default; present-and-malformed is an error rather than a fall back. Finding no cube directory at all is still an error, not a silent skip: listing a package means the user expects cubes from it.
• Both dependencies are regular dependencies, not peers, and both are load-bearing: a manifest imports Manifest from @bitsquare/nopy-cube and z from zod. @bitsquare/nopy-cube peer-depends on zod, so the bundle's copy is the one everybody uses — see Phase 4.
• The package needs no exports entry for this to work — resolution reads package.json off disk (Phase 2), so the exports map is irrelevant.
• A bundle's directory is read-only at runtime. Under pnpm, node_modules content is hardlinked into the global store; a cube writing next to its own deploy.py corrupts that store for every project on the machine. Cubes must write to /tmp or the remote host, never their own dir.
• A bundle must not ship a .nopyrc.json. Config discovery walks up from process.cwd(), never from cube directories, so it would never be read.

Phase 2 — resolution — done

Config surface

{
  "cubePackages": ["@acme/cubes-net", "@acme/cubes-caddy"]
}

Merges through the existing resolution machinery for free — arrays concat and dedupe — so a parent config supplies the org baseline and a child adds to it.

Resolution origin. A package must be resolved from the directory of the config file that declared it, not from process.cwd(). Otherwise a bundle listed in ~/.nopyrc.json cannot resolve unless every project happens to depend on it. This is the same problem PATH_PROPERTIES solves for cubeDirs, but the output is a tagged reference rather than a rewritten string:

export interface CubePackageRef {
  spec: string;   // '@acme/cubes-net'
  from: string;   // dirname of the .nopyrc.json that declared it
}

So the file format and the loaded format diverge for this one key:

interface NopyConfigFile extends Omit<Partial<NopyConfig>, 'cubePackages'> {
  cubePackages?: string[];
  resolution?: ResolutionConfig;
}

interface NopyConfig {
  cubePackages: CubePackageRef[];
  // ...
}

resolveConfigPaths() performs the string → CubePackageRef conversion, next to where it resolves PATH_PROPERTIES. Two consequences to handle:

• mergeValue's array dedupe only fires when every element is a primitive (config.ts:142), so refs fall through to plain concat. Dedupe by spec in the resolver instead.
• Dedupe is last-wins: merge order is root-first, so the last occurrence is the most specific config, and its from is the right resolution origin.

Resolver

New file packages/nopy/src/cubes/packages.ts:

export interface CubePackage {
  name: string;
  root: string;
  dirs: string[];   // absolute, from nopy.cubes
}

export function resolveCubePackages(
  refs: CubePackageRef[]
): { packages: CubePackage[]; errors: string[] };

Locate the package root without going through exports and without tripping on pnpm symlinks:

const req = createRequire(path.join(ref.from, 'noop.js'));
for (const dir of req.resolve.paths(ref.spec) ?? []) {
  const manifest = path.join(dir, ref.spec, 'package.json');
  if (fs.existsSync(manifest)) return path.dirname(manifest);
}

resolve.paths() walks the node_modules chain upward from ref.from plus the global paths; existsSync follows symlinks, so pnpm's node_modules/@acme/cubes-net → ../.pnpm/… resolves correctly.

Errors (each aborts the run, consistent with the existing errors contract):

• package not found on any candidate path
• package.json unparseable
• neither a cubes/ directory nor a nopy.cubes override
• nopy.cubes present but not a non-empty array of strings
• a nopy.cubes entry escapes the package root, or does not exist

Wiring

findCubeDirectories() currently returns string[]. It becomes the union of three sources, each tagged so the loader can attribute a cube to it:

export type CubeRoot =
  | { type: 'dir'; dir: string }                              // cubeDirs, .npcubes markers
  | { type: 'package'; dir: string; packageName: string };    // cubePackages

export function findCubeRoots(): { roots: CubeRoot[]; errors: string[] };

Keep findCubeDirectories() as a thin wrapper returning roots.map(r => r.dir) — it is exported from src/cubes/index.ts and covered by tests. The node_modules skip inside scanDirectory stays and is now correct: a bundle's own node_modules should not be scanned.

Phase 3 — hard errors with attribution — done

Cube gains a source, as an optional fourth constructor parameter so the public signature stays backwards compatible:

export type CubeSource =
  | { type: 'dir'; dir: string }
  | { type: 'package'; packageName: string; dir: string };

class Cube {
  constructor(
    manifest: Manifest<Schema>,
    dir: string,
    deployScript: string,
    source: CubeSource = { type: 'dir', dir }
  ) {}
}

The duplicate error carries both sources and is order-independent (Phase 0.2):

Duplicate cube id 'apt:essentials' from 2 sources:
  package @bitsquare/cubes-core  /…/node_modules/@bitsquare/cubes-core/cubes/apt/essentials
  directory                      /repo/packages/nopy/cubes/apt/essentials
Rename one of them, or remove a source from .nopyrc.json.

There is deliberately no override, alias or precedence rule. If two bundles ever claim the same id they are mutually exclusive, and the fix is upstream.

Surface the source in the interactive picker and in --json output so a user can see where a cube came from before running it.

Phase 4 — @bitsquare/nopy-cube, the authoring package — done

The problem: a manifest does import { cubes } from '@bitsquare/nopy', resolved by ordinary Node resolution from the manifest's own directory. From inside node_modules/@acme/cubes-net/, that only resolves if the consumer installed @bitsquare/nopy locally — a globally-installed CLI leaves nothing to find.

The fix is to give bundles something they can depend on normally, so resolution is plain, boring, spec-compliant Node with no loader tricks in the critical path.

The package

packages/nopy-cube — the Manifest factory, the Cube class, and the types from cubes/types.ts. No CLI, no execa, inquirer, enquirer, zx, or commander. Today a cube manifest — a file that ships nothing but data — drags the entire CLI in as a transitive dependency; this makes the authoring surface honest about how small it is, and gives the contract a version number that moves independently of the CLI's.

{
  "name": "@bitsquare/nopy-cube",
  "version": "1.0.0-alpha0",
  "type": "module",
  "exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } },
  "peerDependencies": { "zod": "^4.4.3" },
  "files": ["dist", "README.md", "LICENSE"]
}

zod is a peer, deliberately. Bundles declare zod as a regular dependency, so exactly one zod instance serves the manifest, the schema it builds, and the Manifest factory. Phase 0.4 removes the CLI's instanceof dependence on that being the same copy the CLI uses, but keeping the bundle side single-instance is still the right default.

Moving cubes/types.ts

@bitsquare/nopy re-exports everything from @bitsquare/nopy-cube — through src/cubes/index.ts and the cubes namespace in src/nopy.cubes.ts, both already coverage-excluded barrels — so import { cubes } from '@bitsquare/nopy' in every existing manifest keeps working unchanged. Nothing in cubes/ has to be touched at migration time.

cubes/types.ts and cubes/factories.ts moved wholesale, with tests/cubes.types.test.ts and tests/cubes.factories.test.ts behind them. tests/helpers/foreign-zod.ts is duplicated rather than shared — fifteen lines, and the alternative is a test-only dependency edge between the packages.

Repo plumbing it took:

• tsconfig.base.json: "@bitsquare/nopy-cube": ["./packages/nopy-cube/src"].
• Root tsconfig.json and packages/nopy/tsconfig.json: the project reference. This is the first reference edge in the repo, and it broke the gate immediately: tsc --build --noEmit is not legal once a project has references — TS6310, "referenced project may not disable emit", because a composite project has to emit the declarations its dependents read. The root typecheck script is now plain tsc --build. It still fails on a type error, and it now also proves the build works; the cost is that it writes dist, which is gitignored.
• packages/nopy/package.json: "@bitsquare/nopy-cube": "workspace:*".
• packages/nopy/vitest.config.ts: a resolve.alias for @bitsquare/nopy-cube pointing at ../nopy-cube/src/index.ts. Without it the workspace link resolves through exports to dist, so pnpm test on a clean checkout would fail until something had built it, and a stale dist would silently be what the tests ran against. The same config excludes **/nopy-cube/** from coverage — the aliased files were being counted against nopy's thresholds.
• A vitest.config.ts for the new package with the same thresholds. It sits at 100 % statements/functions/lines, 91 % branches.

The release lane needed fixing first

This is the part that is easy to miss. link-workspace-packages is unset and pnpm 10+ defaults it to false, so a plain semver range would resolve @bitsquare/nopy-cube from the registry instead of linking the workspace copy — the dependency has to use workspace:*.

But both workflows publish with npm publish, and npm does not understand the workspace: protocol. @bitsquare/nopy would ship a manifest carrying "@bitsquare/nopy-cube": "workspace:*", which fails on install with EUNSUPPORTEDPROTOCOL. This has never mattered because the two current packages do not depend on each other; nopy → nopy-cube is the first edge, and the PoC bundle in Phase 5 adds a second.

Pick one before publishing anything:

• Switch to pnpm publish --no-git-checks, which rewrites the protocol to a concrete version on pack. Cleanest, but changes the publish step in both workflows and pulls in pnpm's own lifecycle behaviour.
• Rewrite the range with npm pkg set before publishing, extending the pattern publish-snapshot.yml already uses for version. In release.yml one package ships at a time, so it pins to whatever version packages/nopy-cube/package.json declares at that commit. In publish-snapshot.yml the loop needs to become two passes — compute every snapshot version first, then publish — so nopy can pin the exact nopy-cube snapshot from the same run.

Measured, both directions. npm pack in packages/nopy produces a tarball whose manifest still reads "@bitsquare/nopy-cube": "workspace:*"; pnpm pack produces one that reads "1.0.0-alpha0". So the failure was real and the fix works.

Went with pnpm publish --ignore-scripts --no-git-checks in both workflows. --no-git-checks is not optional in either: release.yml runs on a detached HEAD, and publish-snapshot.yml dirties the tree by stamping versions. (pnpm pack has no --ignore-scripts, only pnpm publish does.)

Three small scripts carry the parts that are easy to get wrong, all runnable locally:

• scripts/verify-pack.mjs — packs every publishable package and fails if a workspace: range survived into the tarball. Runs between build and publish in both workflows. Turns "npm would have shipped a broken manifest" from an install-time surprise into a red run.
• scripts/publish-order.mjs — topologically sorts the publishable packages. packages/*/ alphabetically puts nopy ahead of the nopy-cube it depends on; the snapshot workflow now iterates this instead.
• scripts/linked-deps.mjs — lists a package's workspace links as <name> <version>, resolved by package name rather than by directory. release.yml uses it to refuse a release whose linked dependency is not on npmjs yet, which is the one mistake that cannot be taken back after 72 hours.

publish-snapshot.yml also became two passes over the packages: stamp every version first, then publish. pnpm publish substitutes the version the linked package declares at pack time, so nopy-cube has to be carrying its snapshot version before nopy is packed.

Still unverified: none of this has run against the Gitea registry. Worth a throwaway version before the first real release.

Also: the resolve hook — built

Independent of the split, and worth building anyway — it retires the ERR_MODULE_NOT_FOUND gotcha CLAUDE.md documents for the local cubes/ tree, where manifests import @bitsquare/nopy from a directory that has no link to it.

With the split, the hook is a convenience rather than load-bearing: bundles resolve @bitsquare/nopy-cube through their own node_modules and never reach it.

The gotcha is bigger than CLAUDE.md says: it is two specifiers, not one. Measured by linking @bitsquare/nopy into the root node_modules and loading the real tree — every manifest then failed on Cannot find package 'zod' instead. Manifests import z directly to build their schema, and pnpm's isolated layout puts zod under packages/nopy/node_modules, not the root. A hook that only covers @bitsquare/nopy moves the error rather than fixing it, so it has to fall back for zod too. With both linked, all 25 cubes load.

Falling back for zod hands local cubes the CLI's zod instance, so no duplication arises there. Bundles are the case that duplicates it, and Phase 0.4 is what makes that safe.

packages/nopy/src/cubes/resolve-hook.mjs, registered once from loadCubes() before the first import(manifestPath):

module.register('./resolve-hook.mjs', import.meta.url, { data: { from: import.meta.url } });

from is a URL inside the running CLI's own package; the hook thread builds a createRequire from it and resolves the fallbacks out of the CLI's own dependencies.

The hook tries next(specifier, ctx) first and only falls back on failure. That ordering matters: a consumer that has its own copy installed keeps using it, so the hook never silently introduces version skew. There is a test for exactly that — a stub zod beside the cube wins over the CLI's real one.

Constraints, as built:

• module.register() is process-global and cannot be undone. Installed once, behind a module-level guard, and wrapped in a try — the hook is a convenience, so a registration failure must not abort a run.
• The hook file runs on a separate thread; the data payload must be structured-cloneable (a string URL is).
• The .mjs has to reach dist, and tsc does not copy it: nopy's build is now tsc && cp src/cubes/*.mjs dist/cubes/. files already covers it via the dist entry.
• It covers three specifiers, not the two the plan named: zod, @bitsquare/nopy, and @bitsquare/nopy-cube — a hand-written local cube is as entitled to the new authoring package as to the old one. Subpaths count (@bitsquare/nopy/package.json), anything else stays a hard failure.

The tests have to spawn a real node. Written inside the vitest worker they pass whether or not the hook is installed: vite resolves the dynamic import itself and finds zod from the project root. tests/cubes.resolve-hook.test.ts therefore runs each case in a child process, and the first case asserts the failure without the hook so the rest cannot silently stop proving anything.

Verified end to end. From a plain node at the repo root, with nothing linked, the built loader reads all 22 cubes under cubes/ with zero errors. The ERR_MODULE_NOT_FOUND gotcha in CLAUDE.md is retired.

Phase 5 — proof of concept: packages/cubes-core — done

Depends on Phase 4 shipping first — the bundle cannot declare @bitsquare/nopy-cube as a dependency until it exists, and the publish-lane fix has to be in place before either package is published.

1. git mv cubes packages/cubes-core/cubes — preserves per-file history.
2. Add packages/cubes-core/package.json per the Phase 1 contract. Version 1.0.0-alpha0, tracking the current alpha train. Not private. Its @bitsquare/nopy-cube dependency uses workspace:* in the repo, which is exactly the case the Phase 4 publish fix has to handle. Migrating the manifests' import { cubes } from '@bitsquare/nopy' to import { Manifest } from '@bitsquare/nopy-cube' is optional — the re-export keeps the old form working — but doing it here is what proves the bundle resolves without the CLI present at all.
3. Root .nopyrc.json: replace "cubeDirs": ["./cubes"] with "cubePackages": ["@bitsquare/cubes-core"]. Replace, not add — keeping both means every id resolves from two sources and the hard error fires on every run.
4. Root package.json: add "@bitsquare/cubes-core": "workspace:*" to devDependencies, so pnpm symlinks it into the root node_modules. This is what makes the PoC exercise the real pnpm symlink resolution path rather than a plain directory.
5. packages/nopy/.nopyrc.json keeps "cubeDirs": ["./cubes"] for its fixtures. Config merges root-first, so running from packages/nopy now pulls in @bitsquare/cubes-core and the fixtures — which is exactly the collision Phase 0.3 renames away.
6. Workflow changes are limited to the publish-lane fix from Phase 4. publish-snapshot.yml loops for dir in packages/*/ and picks both new packages up automatically; release.yml resolves packages/<pkg> from the tag, so cubes-core-v1.0.0 and nopy-cube-v1.0.0 work as-is. Verify on the first snapshot run that a package with no build script is skipped cleanly by pnpm -r run build (it is) and that publishing is happy with no lifecycle scripts.
7. No tsconfig reference for cubes-core — the bundle has no TypeScript. (The nopy-cube references from Phase 4 are separate.)
8. Biome already lints cubes/**/*.mjs from the root; only the path changes.

What differed from the plan

• Step 2's optional migration was done. All 22 manifests now import { Manifest } from @bitsquare/nopy-cube, not { cubes } from @bitsquare/nopy. Optional for correctness, but it is the only version of the PoC that proves anything: leaving the old import in place would have resolved through the CLI that happens to sit in the same tree.
• uniqid had to move too. Two manifests use it (admin:hostname bare, user:add via cubes.uniqid), so src/cubes/utils.ts and its test went to nopy-cube alongside types.ts, and uniqid joined the authoring barrel. Otherwise one migrated manifest would still have been importing the CLI.
• files needs a log exclusion. Cubes that have been run leave a gitignored pyinfra-debug.log next to deploy.py; gitignore does not filter an npm tarball. "files": ["cubes", "!cubes/**/*.log", …] does. Verified: 22 manifests, 22 deploy scripts, 0 logs in the packed artefact.
• verify-pack.mjs picks the bundle up for free — it walks every non-private packages/*, so cubes-core's workspace:* edge is checked like nopy's.

Verifying the PoC — done

• In-workspace: the built loader, run from the repo root against the new root .nopyrc.json, reads 22 cubes with 0 errors and reports source: { type: 'package', packageName: '@bitsquare/cubes-core', dir: '…/node_modules/@bitsquare/cubes-core/cubes' } — the pnpm symlink path, not a plain directory.

• Out-of-workspace (the real test): pnpm pack for nopy-cube, nopy and cubes-core, then npm install of all three tarballs into a throwaway directory with a .nopyrc.json naming only the bundle. npm is the strict test here — it does not understand workspace:, so a leaked range fails the install outright. It installed clean, and the installed @bitsquare/nopy/package.json carries "@bitsquare/nopy-cube": "1.0.0-alpha0". nopy install -l session.json -P -D then resolved apt:essentials and printed a --chdir into node_modules/@bitsquare/cubes-core/cubes/apt/essentials. Since the loader aborts on any manifest error and this run did not, all 22 manifests imported @bitsquare/nopy-cube and zod successfully from a tree containing no workspace links.

  Note for anyone repeating this: -P on its own is interactive, and a replay still prompts for anything a manifest declares in secrets (they are never persisted to a session) — net:tailscale will sit there waiting. Use a session file with a cube that has no secrets, or answer the prompt.

Phase 6 — documentation — done

• CLAUDE.md: the repo table gains two rows (packages/nopy-cube, packages/cubes-core) and loses the cubes/ one; "The two packages do not depend on each other" is no longer true; the loader section in nopy architecture; and the Gotcha paragraph, which the resolve hook retires.
• packages/nopy/docs/CUBE-BUNDLES.md (new): authoring guide — package shape, read-only constraint, id collision policy, publishing.
• packages/nopy/docs/API.md + README.md: cubePackages.
• README.PUBLISH.md: nopy-cube-v* and cubes-core-v* as new tag prefixes, plus the ordering constraint — nopy-cube releases before anything that depends on it.

Beyond the list: CLAUDE.md also needed the typecheck command corrected (tsc --build, not --noEmit — see Phase 4), a note on the vitest source alias and the coverage exclusion, and three entries under Known drift. README.PUBLISH.md absorbed the whole publish-lane rework, not just the tag prefixes: pnpm publish over npm publish and why, the two-pass version stamping, verify-pack.mjs, publish-order.mjs, linked-deps.mjs, and a local rehearsal recipe that uses npm to install the tarballs precisely because npm is the one that rejects a leaked workspace: range.

One workflow change came out of writing this up: ci.yml now runs verify-pack.mjs too. It was only in the two publish workflows, which means a leaked range would have failed the release rather than the pull request that introduced it — the wrong end of the process for a mistake that is free to catch early.

Testing

The coverage gate (85 % branches/functions, 80 % lines/statements, per package) is not a CI flag — new modules without tests fail the gate locally and on the runner alike.

tests/cubes.packages.test.ts (new) — build a fake node_modules tree under os.tmpdir() and chdir into it, as the existing loader/config tests do:

• resolves a scoped and an unscoped package
• resolves through a symlinked package directory (mimicking pnpm)
• resolves from the declaring config's directory, not cwd
• missing package → error naming the spec
• package without nopy.cubes → falls back to cubes/
• package with neither → error; malformed nopy.cubes → error, no fall back
• nopy.cubes entry that does not exist, and one that escapes the root → errors
• last-wins dedupe when parent and child config both name a package

tests/cubes.loader.test.ts — package-sourced cubes load; source attribution is correct for all three root types.

tests/cubes.loader.edge.test.ts — duplicate across a dir and a package errors and names both; cubes nested below a duplicate still get scanned (Phase 0.1); the error is identical regardless of scan order (Phase 0.2).

tests/config.test.ts — cubePackages merge, override resolution strategy, CubePackageRef provenance.

tests/prompts.test.ts — coerceValue against schemas built by a different zod instance, so Phase 0.4 cannot silently regress to instanceof.

packages/nopy-cube/ — its own vitest.config.ts at the same thresholds. The Manifest() / Manifest.create() / Cube.getDefaults() cases move over from tests/cubes.factories.test.ts; what stays behind is whatever tests the re-export surface.

Resolve hook — module.register() is process-global, so this cannot be unit tested in-process. Add an integration test that spawns the CLI as a child process against a fixture tree, under the existing test:integration script.

Risks

1. module.register() is irreversible and process-wide. It affects everything loaded afterwards, including the CLI's own lazy imports. Guarded single install, next()-first ordering.
2. Hard-error duplicates have no escape hatch. Two bundles claiming one id cannot be used together, full stop. If that bites in practice the follow-up is a cubeAliases map or a per-package id prefix — explicitly out of scope here.
3. Store corruption. A bundled cube writing to its own directory damages the pnpm global store for every project on the machine. Documented in Phase 1; a runtime warning is a possible follow-up.
4. No version compatibility check. A bundle authored against a future nopy loaded by an older one fails at manifest-import time with a confusing error. A nopy.engines field checked at resolution time would fix it. Deferred.
5. Bundles vendoring cubes in their own node_modules will not be found, by design.
6. workspace:* escaping into a published manifest. The failure is silent at publish time and only shows up when someone installs the package. Phase 4 fixes the lane; a postpack assertion that no dependency range starts with workspace: would make it impossible to regress.
7. Three packages, three version lines. nopy-cube is the contract, so a breaking change there ripples to every published bundle in the wild — which is the point of versioning it separately, but it means the compatibility question from risk 4 gets more pressing, not less.