@orkestrel/scaffold 0.0.103 → 0.0.104

package/dist/host/agents/skills/orkestrel-publish/references/wave.md

@@ -9,10 +9,20 @@ prepare the next.
 
 `scripts/wave.ts --visit` runs these steps in this order and stops at the first one that fails; a
 step that reads generated or installed state is invalid before the step that writes it. Run a step
-by hand only to repair it, then resume with `--from <step>`.
-
-1. Re-pin every `@orkestrel` range to the registry caret (peer ranges included) and install, so
-   the overwrite runs the current vendored host.
+by hand only to repair it, then resume with `--from <step>`. Read a failed step's journal, which
+its row names under the target's `tmp/units/wave/`, before running the step again. Journals and
+overwrite receipts are written only where the work tree ignores `tmp/`.
+
+1. Re-pin every range the audit's release readings name to the caret of its returned release,
+   and install before the overwrite. Read the audit population as the declared `@orkestrel`
+   dependencies in `dependencies` and `devDependencies`, plus declared foreign tools that the
+   blueprint plans in those sections; exclude the fixed showcase tool pair from ordinary release lookups.
+   Look up fleet releases with `*`; look up foreign tools with
+   a caret over the declared major when one can be extracted, otherwise with the declared range.
+   Do not treat a declared minor or patch bound as the lookup bound. Peer-only dependencies produce no release reading;
+   rewrite a peer range only when its name shares an audited release reading. For example, with
+   peer-only `@orkestrel/peer-only: ^0.0.1`, leave that peer unchanged; with a planned tool whose
+   registry serves `8.3.4`, apply `vite: ~8.2.0 -> ^8.3.4` even though the tilde excludes `8.3.4`.
 2. Commit the manifest and the lockfile as the preparation commit. `scaffold overwrite` refuses a
    tree carrying uncommitted changes, and the install left both dirty.
 3. Run `scaffold overwrite`. One run repairs the `AGENTS.md` and `CLAUDE.md` pointers and deletes
@@ -33,17 +43,24 @@ by hand only to repair it, then resume with `--from <step>`.
      rather than waiving past it.
    - A copy the target git-ignores stays a `foreign` finding, so that target never reaches exit `0`
      again. Keep a local MCP server registration outside the repository rather than at `.mcp.json`.
-4. Force-verify every `@orkestrel` range against a registry sweep taken after the previous layer
-   published.
+4. Force-verify the same audit population and lookup bounds against a registry sweep taken after
+   the previous layer published. Do not infer verification of peer-only declarations from that audit.
 5. Run the full install. The overwrite re-declares the toolchain ranges and declares each planned
    dependency the manifest lacks, so the lockfile the first install regenerated no longer matches the
    manifest.
 6. Sweep the self-pins, per § Sweep the self-pins: the re-pin moves the snapshot class.
 7. Run the mutating `format` script to converge generated writes.
-8. Run the quality gates.
-9. Run `node .agents/skills/orkestrel-publish/scripts/compare.ts` to compare the rebuilt `dist/`
-   against the published tarball for material content. An exit of 2 is an unanswered comparison,
-   never a moved dist: fetch and re-run rather than ruling a bump owed.
+8. Commit the overwrite's writes as `Overwrite with scaffold <version>`: every path the overwrite
+   wrote or removed, and the manifest and lockfile the install converged. The step refuses a dirty
+   path the overwrite did not write and names it. After committing an unrelated path, complete the intended overwrite commit by hand:
+   inspect the receipt's written and removed paths, stage those paths and the converged manifest
+   and lockfile, and commit them as `Overwrite with scaffold <version>`. Then resume with `--from gates`.
+   Treat the receipt as stale after any intervening commit; never use that receipt to authorize
+   another `record` commit. Skip this step for an offline overwrite and the `@orkestrel/scaffold` package.
+9. Run the quality gates.
+10. Run `node .agents/skills/orkestrel-publish/scripts/compare.ts` to compare the rebuilt `dist/`
+    against the published tarball for material content. An exit of 2 is an unanswered comparison,
+    never a moved dist: fetch and re-run rather than ruling a bump owed.
 
 Restore every pin the target holds with `scripts/swap.ts --restore` before the visit's first step, per
 [release.md](release.md) § Fix a dependency before it publishes, because the visit reads and
@@ -72,6 +89,30 @@ against that checkout.
 Run visits in parallel slices of disjoint repositories, each slice strictly serial inside itself,
 reporting per target. Refuse a failed target, name it, repair it, and re-run it alone.
 
+### Regenerate a lock the install cannot move
+
+When the install in step 1 or step 5 fails with `ERESOLVE`, read its conflict and rerun command.
+An exact-peer cluster, such as `vitest` with `@vitest/browser-playwright`, can prevent npm from
+moving the lockfile in place. Without the flag, the step deletes nothing.
+
+- Pass `--regenerate` only when the user's instruction for the visit names it: the regeneration is a
+  destructive command under `.agents/orchestration.md` § Permission floor. A unit whose brief does
+  not name it, or whose sandbox refused a deletion, stops at the refusal and reports it.
+- With the flag, refuse before moving anything when `node_modules` is a link, the lockfile is
+  untracked or carries uncommitted changes, the manifest names a local dependency spec or declares
+  `workspaces`, `tmp/` is not git-ignored, or the target is not the root of its work tree.
+- Validate the backup and journal paths' ancestry and physical containment before writing or moving,
+  and revalidate before cleanup. Refuse a linked ancestor while permitting ignored scratch beneath a real target.
+- Otherwise copy the lockfile and move `node_modules` under `tmp/units/wave/<stamp>/`, delete the
+  lockfile, install from the manifest, and prove the result: the install exits `0`, the lockfile
+  exists, `npm ls --all` exits `0`, and the manifest bytes are unchanged. Read each package named
+  by the conflict with its installed version in the step's note. A proved result deletes the moved
+  tree; a failed result restores the copied lockfile and moved tree and names why the step failed.
+  Confirm a recoverable tree and lock backup before deleting the active tree. Attempt rollback at
+  most once. If rollback fails, retain both backup paths for recovery. If completion journaling or
+  backup cleanup fails, report that failure and retain the restored or proved installation.
+- Resume a visit that stopped at the refusal with `--regenerate --from <step>`.
+
 ## Rule on the bump
 
 Bump on either trigger: `scripts/compare.ts` exits 3 (the rebuilt dist differs materially from the
@@ -100,6 +141,8 @@ registry copy over any staged tip, so every consumer stays red until that tip is
 
 ## Prepare a layer
 
+- When the manifest's `engines.node` names a floor below the `DEFAULT_ENGINES` a generated workspace declares, raise it to that floor and move the package's CI floor row with it.
+- Before the release, rule the package's guide and source comments against `.claude/rules/writing.md` § Substitutions and reword each hit its rows name; identifiers stay.
 - Compare release packs between hosts by paths, sizes, and content hashes, and report executable-mode differences separately; a pack made on Windows records `0644` for an entry git tracks as `100755`.
 
 An unpublished package's first version is `0.0.1`. Do not bump it before that first publish. The
@@ -117,9 +160,9 @@ Prepare a published package's layer in this order, after the visit has ruled the
    bumped manifest.
 3. **Sweep the self-pins**, per the following section: the bump moves the version class.
 4. **Run each package's own `prepublishOnly` script to green.**
-   When the host npm is below the `MINIMUM_NPM_VERSION` floor a generated workspace declares in
-   `devEngines`, prepend a local npm 11 install's `node_modules/.bin` to `PATH` for the visit and
-   this script.
+   Run the visit and this script on a Node whose bundled npm meets the `MINIMUM_NPM_VERSION` floor a
+   generated workspace declares in `devEngines`: the scripts spawn the npm CLI beside the running
+   Node binary when one is there, so a `PATH` change reaches them only where none is.
 5. **Write the release commit and push before the window opens.** The preparation commit inside
    the visit is a different commit at a different moment.
 

package/dist/host/agents/skills/orkestrel-publish/references/window.md

@@ -128,7 +128,7 @@ rest of the layer either fits inside it or takes another approval.
   its own URL.
 - Relay every new URL to the user the moment it appears, through a journal watcher, and never
   pause the chain to wait for a click: a poll outlives the relay.
-- Tell the user to click only the URL last in log order. A click on a superseded URL poisons the
+- Tell the user to click only the URL last in log order. A click on a superseded URL invalidates the
   live attempt, and the current poll then fails `403 Forbidden - GET /-/v1/done` mid-flight.
   § Read a `403` on the poll owns the recovery.
 - **Never retry a publish that is still waiting for its authorization.** Each `npm publish`
@@ -151,7 +151,7 @@ the same status. Rule from the evidence, never from which cause reads likelier.
 
 - Nobody clicked inside the session's life. The poll ran out its 45 seconds against a URL no one
   opened, and the registry closed the session.
-- The user clicked a superseded URL and poisoned the live attempt. The poll fails mid-flight while
+- The user clicked a superseded URL and invalidated the live attempt. The poll fails mid-flight while
   the user is looking at a page that reports success.
 - The registry refused the attempt's first poll, seconds after the mint and before anyone could
   click, because the poll left from an egress address other than the one that minted the session.
@@ -160,7 +160,7 @@ the same status. Rule from the evidence, never from which cause reads likelier.
   survives its first poll and relaying that one alone, per § Reach the approval.
 - Tell those causes apart from the log and the user, never from the status alone. A single minted
   URL that nobody opened in time is the abandon. A log carrying a URL the running attempt
-  superseded, with the user reporting a click, is the poisoned attempt. A drop within seconds of
+  superseded, with the user reporting a click, is the invalidated attempt. A drop within seconds of
   the mint, before any relay, is the egress refusal.
 - Recover the same way whichever it was: read the registry for the version, confirm no publish
   process is live, then mint exactly one fresh attempt with the user at the keyboard.
@@ -178,9 +178,9 @@ the same status. Rule from the evidence, never from which cause reads likelier.
   status of the pipeline, and a CDN read straight after a publish can still serve the previous
   version.
 - Treat a `404` after a first publish as pending rather than failed. A first publish creates the
-  packument and can serve `404` for minutes after success, so for a package with no prior version
-  re-read on an interval before reporting either way. A bump serving the old version is CDN lag,
-  same rule.
+  packument and can serve `404` for minutes after success. For a first publish, rerun
+  `window.ts --confirm NAME@VERSION` with a `--wait` long enough for a first publish before reporting
+  either way. A bump serving the old version is CDN lag, same rule.
 - Rule on a pack-time manifest-rewriting warning by fetching the registry's copy of the manifest,
   never by the warning's own text.
 - Re-read the registry before telling the user a package failed. A chain still running, a retry

package/dist/host/agents/skills/orkestrel-publish/scripts/swap.ts

@@ -45,18 +45,20 @@ import {
 	readFileSync,
 	realpathSync,
 	renameSync,
-	rmSync,
 	writeFileSync,
 } from 'node:fs'
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import {
+	isRecord,
 	normalizeSlashes,
 	parseJsonRecord,
 	readMissingFlags,
 	readOption,
 	readOptions,
 	readString,
+	removeTree,
 	runNpm,
+	scanLocalSpecs,
 } from '../../orkestrel-dispatch/scripts/helpers.ts'
 
 type Manifest = Readonly<Record<string, unknown>>
@@ -256,25 +258,6 @@ const OVERRIDE_PRECEDERS: readonly string[] = [
 	'resolutions',
 ]
 
-// The manifest blocks whose values are dependency specs; `overrides` nests records of them.
-const SPEC_BLOCKS: readonly string[] = [
-	'dependencies',
-	'devDependencies',
-	'peerDependencies',
-	'optionalDependencies',
-	'overrides',
-]
-
-// npm-package-arg reads a spec as local when it carries a `file:` or `link:` prefix or begins like a
-// path: a dot, `~/`, a separator, or a drive letter.
-const LOCAL_SPEC_PATTERN = /^(?:file:|link:|\.|~[\\/]|[\\/]|[A-Za-z]:)/iu
-
-// It also reads a spec as local when the spec ends in an archive extension and carries no protocol...
-const ARCHIVE_SPEC_PATTERN = /^[^:]+\.(?:tgz|tar\.gz|tar)$/iu
-
-// ...unless the spec is a `user/repo` shorthand, which names a hosted repository whatever it ends in.
-const SHORTHAND_SPEC_PATTERN = /^[^:@%/\s.-][^:@%/\s]*\/[^:@\s/%]+$/u
-
 // An optional `@scope/` and a name of the characters a registry URL carries untouched; a path
 // separator beyond the scope's one `/`, an absolute form, and a drive form fall outside it.
 const PACKAGE_NAME_PATTERN = /^(?:@[A-Za-z0-9~-][A-Za-z0-9._~-]*\/)?[A-Za-z0-9~-][A-Za-z0-9._~-]*$/u
@@ -287,18 +270,6 @@ const USAGE = [
 	'       swap.ts --status --consumer DIR [--json]',
 ].join('\n')
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
-}
-
-function isLocalSpec(spec: string): boolean {
-	const text = spec.trimStart()
-	return (
-		LOCAL_SPEC_PATTERN.test(text) ||
-		(ARCHIVE_SPEC_PATTERN.test(text) && !SHORTHAND_SPEC_PATTERN.test(text))
-	)
-}
-
 function isPackageName(name: string): boolean {
 	return (
 		name.length <= PACKAGE_NAME_LIMIT && !name.includes('..') && PACKAGE_NAME_PATTERN.test(name)
@@ -899,10 +870,6 @@ function replaceFile(path: string, text: string): void {
 	renameSync(temporary, path)
 }
 
-function removeTree(path: string): void {
-	rmSync(path, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
-}
-
 // Vite keys its pre-bundle on the installed version, so a same-version tarball would serve stale bytes.
 function installConsumer(consumer: string): void {
 	invokeNpm(['install', '--ignore-scripts', '--no-audit', '--no-fund'], consumer)
@@ -1146,22 +1113,11 @@ function readPackedManifest(directory: string): string | undefined {
 // or not a ledger recorded the spec.
 function scanPackedSpecs(source: Source): readonly string[] {
 	const manifest = loadPackedManifest(source.directory)
-	return SPEC_BLOCKS.flatMap((block) =>
-		collectSpecs(block, manifest[block]).flatMap(([path, spec]) =>
-			isLocalSpec(spec)
-				? [`${source.name} would pack a local dependency spec: ${path} is ${spec}`]
-				: [],
-		),
+	return scanLocalSpecs(manifest).map(
+		([path, spec]) => `${source.name} would pack a local dependency spec: ${path} is ${spec}`,
 	)
 }
 
-// An `overrides` value can nest records, so the path names every key down to the spec.
-function collectSpecs(path: string, value: unknown): ReadonlyArray<readonly [string, string]> {
-	if (typeof value === 'string') return [[path, value]]
-	if (!isRecord(value)) return []
-	return Object.entries(value).flatMap(([key, child]) => collectSpecs(`${path}.${key}`, child))
-}
-
 // A source that carries a ledger of its own has its manifest rewritten to the recorded ranges for the
 // pack and restored byte for byte whether the pack succeeds or throws, so a consumer never receives a
 // tarball spec that resolves only inside the source.