zyrk 0.3.9 → 0.4.8

package/README.md

@@ -37,9 +37,9 @@ zyrk --help
 zyrk --version
 ```
 
-Requires **Node.js 24 or newer**. The source runs directly with Node's native
-TypeScript support; no compilation step or native toolchain is required to
-install zyrk itself.
+Requires **Node.js 24 or newer**. Published packages contain compiled JavaScript. A checkout runs TypeScript
+through Node's native type stripping; the check gate also builds and tests the
+source-free package layout. Installing zyrk requires no native toolchain.
 
 From a checkout:
 
@@ -90,19 +90,60 @@ Offline installs use locked verified sources and fail if an input is missing.
 Manifest, lock, and projection changes are journaled for process-crash recovery;
 a failed resolution, verification, or build-policy check keeps the prior graph.
 
-Dependency install scripts and implicit native builds are blocked by default.
-`--ignore-scripts` explicitly produces an **intentionally unbuilt** installation.
-Root install hooks are reported and never run automatically. Script approval,
-private native builds, runtime-mutable packages, workspaces, overrides, Git/local
-sources, and authenticated or mixed scoped registries are not supported by this
-install path yet. Unsupported platform constraints and failed optional packages
-currently fail installation instead of being silently omitted. macOS/Windows
-compatibility and framework support remain unverified.
+Dependency install scripts and implicit `binding.gyp` builds require explicit
+approval. Review first, trust the selected sources, then install:
 
-Use `--registry=https://your-registry.example/` for a compatible unauthenticated
-registry. The adapter reads the default registry from user/project `.npmrc`, and
-fails closed on scoped registry routing or disabled TLS verification. Tool
-commands (`dlx`/`create`) still use their existing public-registry configuration.
+```bash
+zyrk approve-builds                # inspect exact sources and commands; executes no package code
+zyrk approve-builds esbuild        # approve reviewed candidates by package name
+zyrk install
+zyrk rebuild --offline             # rebuild the complete approved locked graph
+```
+
+Approvals are local to the exact graph, sources, patch contents, and script
+policy. Mandatory user denies override project approvals. Approved scripts run
+with your account's permissions; permission is not a sandbox. Packages that need
+writes use a complete private dependency generation under `.zyrk-local/`, with
+independent writable files and dependency links confined to that generation.
+Build failure keeps the previous project graph active. `--ignore-scripts`
+explicitly publishes an **intentionally unbuilt** installation. Root install
+hooks never run automatically. A project can request runtime writable packages
+with `"zyrk": { "mutablePackages": ["package-name"] }`; this also uses a complete
+private graph.
+
+Default registry and authentication settings are loaded from user/project
+`.npmrc` for installation, dependency edits, `dlx`, and `create`. Environment
+token placeholders are supported. Credentials are restricted to their configured
+scheme, host, port, and path; redirects cannot expand that scope. Use
+`--registry=https://your-registry.example/` on install for an explicit registry.
+Mixed scoped routing and disabled TLS verification are rejected before public
+lookup. Git sources, non-workspace local sources, and overrides remain unsupported;
+they fail explicitly. Optional dependencies incompatible with the selected platform
+are omitted; missing packages, integrity failures, and other optional failures
+remain errors. Platform selection is recorded in the lock. macOS, Windows, and
+broad framework compatibility have not passed their release gates.
+
+### Workspaces
+
+Standard `package.json` workspaces use one root lock and a recoverable transaction
+for all importer projections. Workspace packages remain editable live directories;
+registry closures independent of live sources can still use shared realizations.
+Run install or dependency edits from the root or a member directory. Root settings
+and registry policy apply to every member.
+
+```bash
+zyrk install
+zyrk run --workspace app start       # exact workspace name or relative path
+zyrk run --recursive build           # dependency-first member scripts
+cd packages/app
+zyrk add package-name                # edit this importer, preserve other selections
+```
+
+Frozen/offline installs, live peers, patches, mutable registry packages, inspection,
+and repair have workspace fixtures. Builds that reach live workspace sources are
+blocked before execution. Workspace npm-lock adoption and portable workspace
+export still need adapters and fail explicitly. Recursive execution supports
+member scripts; filters are exact names or paths, not arbitrary glob expressions.
 
 ### Run a one-off tool
 
@@ -115,15 +156,17 @@ When running from source, replace `zyrk` with `node bin/zyrk.js`.
 
 `dlx` resolves the requested package and its dependencies, verifies downloaded
 archives, creates a dependency-aware tool graph, and launches the selected
-JavaScript bin entry with the supplied arguments. Its temporary projection is
+JavaScript, shell, or native executable bin entry with the supplied arguments. Its temporary projection is
 removed afterward; verified sources and shared realizations remain in the
 store.
 
 `create` uses the same execution path and maps initializer names to their
 `create-*` packages. For example, `vite` maps to `create-vite`, while a scoped
 initializer stays in its scope. Compatibility depends on the selected tool:
-closures declaring install lifecycle scripts are currently blocked, and native
-or shell executable bins are not supported by the JavaScript-only launcher.
+closures declaring install lifecycle scripts, implicit native builds, or bundled
+install hooks are blocked. Dependency executables are available on the tool
+PATH. Parent cancellation terminates the supervised process group with bounded
+escalation on POSIX systems.
 
 These commands run the tool's code with your account's permissions. The tool
 working directory is your current directory. A temporary tool projection is
@@ -131,16 +174,77 @@ not a sandbox.
 
 ### Current command coverage
 
-| Surface                                                                                | Current behavior                                                                    |
-| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `install`, `i`                                                                         | Resolve or reuse the lock, verify sources, and publish shared project dependencies. |
-| `--help`, `--version`                                                                  | Show the CLI surface and package version.                                           |
-| `dlx`, `create`                                                                        | Resolve, fetch, verify archives, and run temporary tool environments.               |
-| `publish`, `unpublish`, `access`, `deprecate`, `dist-tag`, `owner`                     | Explicitly delegate to your npm CLI.                                                |
-| `token`, `adduser`, `login`, `logout`, `whoami`, `ping`, `pack`                        | Explicitly delegate to your npm CLI.                                                |
-| `add`, `remove`, `update`, `run`, `exec`                                               | Report `ZYRK_NOT_IMPLEMENTED`.                                                      |
-| `store`, `projects`, `repair`, `import`, `deploy`, `docker`                            | Report `ZYRK_NOT_IMPLEMENTED`.                                                      |
-| `list`, `why`, `doctor`, `approve-builds`, `rebuild`, `audit`, `patch`, `patch-commit` | Report `ZYRK_NOT_IMPLEMENTED`.                                                      |
+| Commands                                                                                                                            | Behavior                                                                                                                  |
+| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `install`, `i`, `add`, `remove`, `update`                                                                                           | Resolve or reuse exact selections; publish verified dependencies transactionally.                                         |
+| `import --from npm`                                                                                                                 | Adopt supported npm v2/v3 lock selections without changing versions.                                                      |
+| `fetch --frozen-lockfile`                                                                                                           | Prefetch verified locked sources without running scripts or publishing a projection.                                      |
+| `run`, `exec`                                                                                                                       | Execute project scripts or installed binaries; `exec` never fetches.                                                      |
+| `dlx`, `create`                                                                                                                     | Verify and run temporary tool closures.                                                                                   |
+| `list`, `why`, `doctor`                                                                                                             | Inspect selected dependencies, dependency paths, and project health.                                                      |
+| `approve-builds`, `rebuild`                                                                                                         | Review and approve exact build candidates; build a new private generation.                                                |
+| `audit`                                                                                                                             | Query exact selected versions under the project privacy policy; distinguish unavailable service from no known advisories. |
+| `patch`, `patch-commit`                                                                                                             | Create a private editing area and portable source-bound patch; apply on reinstall.                                        |
+| `repair`                                                                                                                            | Re-fetch corrupt locked sources and publish a new realization closure without editing existing shared inodes.             |
+| `store path/status/verify/gc/pin/unpin`, `projects list/forget`                                                                     | Inspect storage, verify content, and manage explicit retention roots.                                                     |
+| `deploy`, `docker init/build/run`                                                                                                   | Export supported production closures or generate and invoke a pinned Docker setup.                                        |
+| `publish`, `unpublish`, `access`, `deprecate`, `dist-tag`, `owner`, `token`, `adduser`, `login`, `logout`, `whoami`, `ping`, `pack` | Explicitly delegate to your npm CLI.                                                                                      |
+
+### Patches, recovery, and cleanup
+
+```bash
+zyrk patch package-name            # prints a private editing directory
+# Edit files in that directory, then:
+zyrk patch-commit <editing-directory>
+zyrk install                       # refresh the lock and apply the patch privately
+zyrk install --offline --frozen-lockfile
+
+zyrk doctor
+zyrk store verify --full
+zyrk repair                        # preserve locked versions, publish replacement instances
+zyrk store gc --dry-run
+zyrk store gc
+```
+
+Commit `package.json`, `package-lock.json`, and `.zyrk/patches/` artifacts.
+Keep `.zyrk-local/` out of version control: it contains approvals, private builds,
+logs, and local install state. Patches bind to verified source manifests; changed
+patches invalidate frozen selections. Other projects retain their selected
+package instances. Repair retains incident evidence and replaces corrupted
+object pathnames, so existing hard links are never rewritten in place.
+
+GC uses recorded project roots, pins, leases, a store coordination lock, and a
+30-day grace period. Preview collection before removing retention roots. Live
+or uncertain owners are retained. A process killed inside the short lock-publication
+guard can leave a guard requiring manual recovery after all zyrk processes stop;
+zyrk fails closed instead of guessing which process owns it.
+
+### Export an application
+
+Declare runtime files explicitly and select a direct Node entry:
+
+```bash
+zyrk deploy --out ./dist-runtime --omit=dev --files dist --entry dist/server.js
+node ./dist-runtime/dist/server.js
+```
+
+The exporter validates that links stay inside the output and excludes the host
+store. Generic export supports shared production graphs and relocatable private
+JavaScript outputs, including selected patches and generated files. Native binaries,
+host-path-dependent outputs, workspace export, and arbitrary shell startup adapters
+remain unsupported. Exports validate active generation/profile metadata and reject
+credentials or escaping links. Structural validation does not prove application health. Run an
+application smoke test from the exported directory with host-store access removed.
+
+`zyrk docker init` requires a supported Node image pinned by SHA-256, a local CLI
+tarball pinned by SHA-512, runtime files, and an entry. It generates reviewable
+`Dockerfile`, `.dockerignore`, `zyrk-docker.json`, and `ZYRK_DOCKER.md`. Builds fetch
+with an optional BuildKit npmrc secret, then install and export without networking.
+`zyrk docker build --tag app:local` and `zyrk docker run --tag app:local` require a
+reachable Docker daemon. Generated configuration has fixture coverage. The opt-in
+`node scripts/docker-smoke.mjs` gate exercises a pinned image and a network-free
+runtime. A Linux daemon run passed cold/warm builds, imports and asset access
+without host mounts. Broad framework compatibility still requires application-specific checks.
 
 Native commands that support `--json` return a versioned result envelope.
 `dlx` and `create` reject that option because the tool owns stdout. Delegated
@@ -164,16 +268,18 @@ The design separates three things:
   publication. Extraction rejects unsafe paths and links and normalizes modes.
 - **Dependency context:** a package instance records its selected dependency
   wiring, so incompatible versions and peer contexts are not merged.
-- **Mutable work:** the planned build/runtime mutation model uses private
-  project generations. Writable build outputs must not change shared source.
+- **Mutable work:** approved builds, patches, and runtime-writable packages use
+  independent private project generations. Writable outputs do not alter shared source.
 
 Read-only modes help prevent accidental writes; they are not a security boundary
 against code running as the same OS user. Shared stores should be used only by
 mutually trusted processes. Do not share them across unrelated CI trust domains.
 
-Native tool commands currently use the public npm registry. Private registry
-configuration and credential support are not implemented; do not use these
-commands for internal tools that depend on private registry routing.
+Archive expansion, metadata sizes, resolution growth, fetch totals, and operation
+deadlines are bounded. These limits defend against accidental and hostile
+resource exhaustion; they do not make executed dependencies trustworthy.
+Security reports belong in the private reporting channel described in
+[SECURITY.md](SECURITY.md).
 
 ## Global installs and npm delegation
 
@@ -222,7 +328,10 @@ tag after the commit. Keep changes focused and never bypass the hooks.
 
 CI checks pushed commits and pull requests. The separate
 [npm publishing action](.github/workflows/npm-publish.yml) is triggered when a
-GitHub release is created; ordinary commits do not trigger that action.
+GitHub release is published. It verifies the release tag, formatting, typecheck,
+build, and tests, then publishes that exact commit. Ordinary commits do not
+publish packages. Dependabot and a scheduled advisory check supplement CI; an
+unavailable advisory service fails separately from a clean result.
 
 The contributor guide is [AGENTS.md](AGENTS.md). Bug reports and reproducible
 compatibility cases belong in

package/SECURITY.md

@@ -0,0 +1,42 @@
+# Security policy
+
+zyrk is pre-release software under active construction. There is no stable or
+long-term-support release line. Security fixes target current development and
+the latest published pre-release; older versions do not receive promised
+backports. No response or remediation deadline is guaranteed.
+
+## Report a vulnerability privately
+
+Use [GitHub private vulnerability reporting](https://github.com/kingjethro999/zyrk/security/advisories/new).
+Private reporting is enabled for this repository. Please keep exploit details,
+credentials, and affected users' data out of public issues and discussions.
+
+If the form is unavailable, use the contact links on
+[the maintainer's profile](https://github.com/kingjethro999) to request a private
+reporting channel. A public request should contain no vulnerability details.
+
+Include the affected version or commit, Node.js version, OS and filesystem,
+a minimal reproduction using disposable fixtures, expected and observed
+behavior, and the likely impact. Describe relevant registry, script-policy,
+store, and command options. Redact tokens, credentials, private package names,
+and personal filesystem paths. A report should not require access to a real
+account or production data to reproduce.
+
+The maintainer will assess the report and coordinate fixes and disclosure when
+possible. Please allow coordination before publishing a working exploit. This
+project offers no bug bounty or guaranteed response time.
+
+## Scope and operational limits
+
+Reports involving integrity verification, archive extraction, credentials,
+shared-store mutation, project isolation, subprocess cleanup, and portable
+exports are useful. The shared store is scoped to one OS account. Package code
+runs with that account's permissions when explicitly invoked or approved;
+read-only modes and subprocess supervision are not a sandbox. Compatibility
+and platform support are limited to the cases documented and tested in the
+repository.
+
+Scheduled dependency audits and Dependabot updates supplement review. An audit
+service failure is reported as unavailable and fails the scheduled check;
+only a valid successful zero-finding report counts as clean. A clean dependency
+audit does not establish that zyrk or its dependencies are free of vulnerabilities.

package/VERSION

@@ -1 +1 @@
-v0.3.9
+v0.4.8

package/bin/zyrk.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
-import { runCli } from "../dist/cli/main.js";
+import { existsSync } from "node:fs";
+
+// Checkouts run the current source. Published packages contain emitted JS only.
+const source = new URL("../src/cli/main.ts", import.meta.url);
+const { runCli } = await import(
+  existsSync(source)
+    ? source.href
+    : new URL("../dist/cli/main.js", import.meta.url).href
+);
 
 process.exitCode = await runCli({
   argv: process.argv.slice(2),

package/dist/cli/main.d.ts

@@ -1,17 +1,3 @@
-/**
- * zyrk command dispatch (SPEC 15).
- *
- * This is the roadmap skeleton, not the whole implementation: `dlx` and
- * `create` run temporary tool environments; `--help`, `--version`, the
- * global-install rejection, and explicit npm delegation do their jobs.
- * `install` publishes a verified shared project graph. Other dependency
- * commands fail with ZYRK_NOT_IMPLEMENTED rather than pretending to work;
- * unknown commands fail with ZYRK_USAGE
- * and the help text.
- * Nothing here launches a subprocess: rejection happens before resolution,
- * downloads, lifecycle execution, project/store mutation, or any child
- * process (SPEC 15.3.1).
- */
 import { ZyrkError } from "../errors.ts";
 export { ZyrkError };
 import { RegistryClient } from "../fetch/registry.ts";

package/dist/cli/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAkBH,OAAO,EAAe,SAAS,EAAe,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,OAAO,EAAoB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAExE,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAM3C,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhF,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAmDzC,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAwBhD;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AA6EF;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,GACnD,SAAS,CAgDX;AAmBD,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC1C,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;CACxC,CAAC;AAEF,gFAAgF;AAChF,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAqPpE"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/cli/main.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAe,SAAS,EAAe,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,OAAO,EAAoB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAExE,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAM3C,OAAO,EAAqC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhF,eAAO,MAAM,uBAAuB,IAAI,CAAC;AA2DzC,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAwBhD;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AA6EF;;;GAGG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,GACnD,SAAS,CAgDX;AAmBD,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC1C,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;CACxC,CAAC;AAEF,gFAAgF;AAChF,wBAAsB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAqZpE"}

package/dist/cli/main.js

@@ -1,16 +1,11 @@
-/**
- * zyrk command dispatch (SPEC 15).
- *
- * This is the roadmap skeleton, not the whole implementation: `dlx` and
- * `create` run temporary tool environments; `--help`, `--version`, the
- * global-install rejection, and explicit npm delegation do their jobs.
- * `install` publishes a verified shared project graph. Other dependency
- * commands fail with ZYRK_NOT_IMPLEMENTED rather than pretending to work;
- * unknown commands fail with ZYRK_USAGE
- * and the help text.
- * Nothing here launches a subprocess: rejection happens before resolution,
- * downloads, lifecycle execution, project/store mutation, or any child
- * process (SPEC 15.3.1).
+import { runMaintenanceCommand } from "../commands/maintenance.js";
+import { runDeployCommand } from "../commands/deploy.js";
+import { runPatchCommand } from "../commands/patch.js";
+import { sanitizeDiagnostic, redactSecrets } from "../log.js";
+/** zyrk command dispatch (SPEC 15).
+ * Native handlers share validated graph and registry adapters; delegated registry
+ * operations preserve npm arguments. Global install rejection precedes effects.
+ * Unsupported command modes fail explicitly in their handler.
  */
 import { installProject } from "../install/run.js";
 import { installRegistry } from "../install/registry.js";
@@ -76,6 +71,14 @@ const IMPLEMENTED_COMMANDS = new Set([
     "repair",
     "store",
     "projects",
+    "fetch",
+    "audit",
+    "approve-builds",
+    "rebuild",
+    "patch",
+    "patch-commit",
+    "deploy",
+    "docker",
 ]);
 export function helpText(version) {
     const lines = [
@@ -125,7 +128,7 @@ function fail(error, parsed, stdoutHint = "") {
         body.remedy = error.remedy;
     return {
         exitCode: exitCodeFor(error),
-        stdout: `${JSON.stringify(body)}\n`,
+        stdout: `${JSON.stringify(sanitizeDiagnostic(body))}\n`,
         stderr: "",
     };
 }
@@ -216,6 +219,11 @@ export async function runCli(options) {
             options.stderr.write(result.stderr);
         return result.exitCode;
     };
+    if (!parsed.help &&
+        !parsed.version &&
+        parsed.command &&
+        isGlobalInstallRequest(parsed.command, parsed.commandArgs, options.env))
+        return emit(fail(globalInstallError(parsed.command), parsed));
     // Delegation bypasses dispatch: zyrk interprets no command arguments
     // itself, adds no JSON envelope, and forwards every non-zyrk token
     // verbatim — before the command as well as after it. A leading
@@ -244,6 +252,128 @@ export async function runCli(options) {
             return emit(fail(toZyrkError(error, "zyrk failed while delegating to npm."), parsed));
         }
     }
+    if (!parsed.help &&
+        !parsed.version &&
+        parsed.command &&
+        [
+            "fetch",
+            "audit",
+            "approve-builds",
+            "rebuild",
+            "repair",
+            "patch",
+            "patch-commit",
+            "deploy",
+            "docker",
+        ].includes(parsed.command)) {
+        try {
+            const command = parsed.command, cwd = options.cwd ?? process.cwd();
+            if (command === "deploy" || command === "docker")
+                return await runDeployCommand({
+                    command,
+                    args: parsed.commandArgs,
+                    cwd,
+                    env: options.env,
+                    stdout: options.stdout,
+                    stderr: options.stderr,
+                    json: parsed.json,
+                });
+            const tools = options.tools
+                ? await options.tools()
+                : await defaultTools(options.env, version, cwd);
+            let result;
+            if (command === "patch" || command === "patch-commit")
+                result = await runPatchCommand({
+                    command,
+                    args: parsed.commandArgs,
+                    cwd,
+                    store: tools.store,
+                });
+            else if (command === "approve-builds") {
+                if (parsed.commandArgs.some((v) => v.startsWith("-") && v !== "--all"))
+                    throw new ZyrkError("ZYRK_USAGE", "Unsupported build approval option.", {
+                        remedy: "Use approve-builds to review; approve-builds <name...> or --all explicitly trusts reviewed source code.",
+                    });
+                const selected = parsed.commandArgs.includes("--all")
+                    ? ["*"]
+                    : parsed.commandArgs;
+                result = await installProject({
+                    ...tools,
+                    projectDir: cwd,
+                    env: options.env,
+                    reviewBuilds: true,
+                    ...(selected.length ? { approveBuilds: selected } : {}),
+                });
+            }
+            else if (command === "rebuild") {
+                if (parsed.commandArgs.some((v) => v !== "--offline"))
+                    throw new ZyrkError("ZYRK_USAGE", "Rebuild operates on the complete approved project graph.", { remedy: "Use zyrk rebuild [--offline]; review approvals first." });
+                result = await installProject({
+                    ...tools,
+                    projectDir: cwd,
+                    env: options.env,
+                    frozen: true,
+                    rebuild: true,
+                    offline: parsed.commandArgs.includes("--offline"),
+                });
+            }
+            else if (command === "repair") {
+                if (parsed.commandArgs.some((arg) => arg !== "--offline"))
+                    throw new ZyrkError("ZYRK_USAGE", "Repair accepts only --offline.", {
+                        remedy: "Use zyrk repair to rebuild verified instances selected by the lock.",
+                    });
+                result = await installProject({
+                    ...tools,
+                    projectDir: cwd,
+                    env: options.env,
+                    frozen: true,
+                    repair: true,
+                    offline: parsed.commandArgs.includes("--offline"),
+                });
+            }
+            else
+                result = await runMaintenanceCommand({
+                    command: command,
+                    env: options.env,
+                    args: parsed.commandArgs,
+                    projectDir: cwd,
+                    ...tools,
+                });
+            const payload = (command === "audit" ? sanitizeDiagnostic(result) : result);
+            if (Array.isArray(payload.builds))
+                payload.builds = sanitizeDiagnostic(payload.builds);
+            const exitCode = payload.status === "unavailable" || payload.thresholdExceeded === true
+                ? 1
+                : 0;
+            if (parsed.json)
+                return emit({
+                    exitCode,
+                    stdout: `${JSON.stringify({ schemaVersion: CLI_JSON_SCHEMA_VERSION, ...payload, status: payload.status ?? "ok" })}\n`,
+                    stderr: "",
+                });
+            if (command === "approve-builds") {
+                const builds = (payload.builds ?? []);
+                return emit({
+                    exitCode,
+                    stdout: builds.length
+                        ? builds
+                            .map((b) => `${b.name}@${b.version} ${b.sourceId}\n${b.stages.map((s) => `  ${s.name}: ${redactSecrets(s.command)}`).join("\n")}`)
+                            .join("\n") +
+                            "\nReview runs no package code. Approval trusts these exact candidate sources.\n"
+                        : "No dependency builds require approval.\n",
+                    stderr: "",
+                });
+            }
+            return emit({
+                exitCode,
+                stdout: `${JSON.stringify(payload)}\n`,
+                stderr: "",
+            });
+        }
+        catch (error) {
+            return emit(fail(toZyrkError(error, `zyrk ${parsed.command} failed.`), parsed));
+        }
+    }
     if (!parsed.help &&
         !parsed.version &&
         (parsed.command === "install" || parsed.command === "i")) {
@@ -300,6 +430,7 @@ export async function runCli(options) {
                 };
             const result = await installProject({
                 ...flags,
+                env: options.env,
                 specs,
                 projectDir: cwd,
                 ...tools,
@@ -342,10 +473,11 @@ export async function runCli(options) {
             parsed.command === "import")) {
         try {
             const tools = options.tools === undefined
-                ? await defaultTools(options.env, version)
+                ? await defaultTools(options.env, version, options.cwd ?? process.cwd())
                 : await options.tools();
             const result = await runDependencyCommand({
                 command: parsed.command,
+                env: options.env,
                 args: parsed.commandArgs,
                 projectDir: options.cwd ?? process.cwd(),
                 store: tools.store,
@@ -397,13 +529,16 @@ export async function runCli(options) {
         !parsed.version &&
         (parsed.command === "store" || parsed.command === "projects")) {
         try {
-            const tools = options.tools === undefined
-                ? await defaultTools(options.env, version)
-                : await options.tools();
+            const store = options.tools === undefined
+                ? await Store.open({
+                    root: resolveStoreRoot({ env: options.env }).root,
+                    create: false,
+                })
+                : (await options.tools()).store;
             const result = await runStoreCommand({
                 command: parsed.command,
                 args: parsed.commandArgs,
-                store: tools.store,
+                store,
                 cwd: options.cwd ?? process.cwd(),
                 json: parsed.json,
             });
@@ -426,15 +561,12 @@ export async function runCli(options) {
     }
     return emit(dispatch(parsed, { version, env: options.env }));
 }
-async function defaultTools(env, version) {
+async function defaultTools(env, version, cwd = process.cwd()) {
+    const registry = await installRegistry({ cwd, env, version });
     const store = await Store.open({
         root: resolveStoreRoot({ env }).root,
         create: true,
     });
-    const registry = new RegistryClient({
-        registry: DEFAULT_REGISTRY,
-        userAgent: `zyrk/${version}`,
-    });
     return { store, registry };
 }
 async function runToolCommand(command, parsed, options, version) {
@@ -457,7 +589,7 @@ async function runToolCommand(command, parsed, options, version) {
         });
     }
     const tools = options.tools === undefined
-        ? await defaultTools(options.env, version)
+        ? await defaultTools(options.env, version, options.cwd ?? process.cwd())
         : await options.tools();
     const base = {
         store: tools.store,

package/dist/cli/npm-delegate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"npm-delegate.d.ts","sourceRoot":"","sources":["../../src/cli/npm-delegate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAuBH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAEvD,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAK7C;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAC3C,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA2B7E"}
+{"version":3,"file":"npm-delegate.d.ts","sourceRoot":"","sources":["../../src/cli/npm-delegate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAsBH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAEvD,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAK7C;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,EAAE;QAAE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAC3C,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAsB7E"}

package/dist/cli/npm-delegate.js

@@ -16,9 +16,8 @@
  * operate outside zyrk's dependency management. Global installs are never
  * delegated (F-018); see parse.ts.
  */
-import { spawn } from "node:child_process";
 import { ZyrkError } from "../errors.js";
-import { closeCode } from "../util/proc.js";
+import { superviseChild } from "../util/proc.js";
 /** Delegated command, its aliases collapsed, plus help text. */
 const DELEGATED_COMMANDS = [
     [["publish"], "Publish the current package to the registry (via npm)."],
@@ -49,20 +48,16 @@ export function delegatedHelpLines() {
  */
 export async function delegateToNpm(options) {
     options.stderr.write(`zyrk: delegating \`zyrk ${options.command}\` to npm; zyrk does not implement publishing or registry authentication.\n`);
-    return new Promise((resolve, reject) => {
-        const child = spawn("npm", [options.command, ...options.args], {
+    try {
+        return (await superviseChild("npm", [options.command, ...options.args], {
             env: options.env,
-            stdio: "inherit",
+        })).exitCode;
+    }
+    catch (error) {
+        throw new ZyrkError("ZYRK_NPM_UNAVAILABLE", "zyrk could not launch npm for an explicitly delegated command.", {
+            detail: { command: options.command },
+            remedy: "Install Node.js with npm on PATH, or run the npm command directly.",
+            cause: error,
         });
-        child.on("error", (error) => {
-            reject(new ZyrkError("ZYRK_NPM_UNAVAILABLE", "zyrk could not launch npm for an explicitly delegated command.", {
-                detail: { command: options.command },
-                remedy: "Install Node.js with npm on PATH, or run the npm command directly.",
-                cause: error,
-            }));
-        });
-        child.on("close", (code, signal) => {
-            resolve(closeCode(code, signal));
-        });
-    });
+    }
 }

package/dist/commands/dependencies.d.ts

@@ -8,5 +8,6 @@ export declare function runDependencyCommand(options: {
     projectDir: string;
     store: Store;
     registry: RegistryClient;
+    env?: NodeJS.ProcessEnv;
 }): Promise<InstallResult>;
 //# sourceMappingURL=dependencies.d.ts.map

package/dist/commands/dependencies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../src/commands/dependencies.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAavE,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;CAC1B,GAAG,OAAO,CAAC,aAAa,CAAC,CA0HzB"}
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../src/commands/dependencies.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAavE,wBAAsB,oBAAoB,CAAC,OAAO,EAAE;IAClD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,OAAO,CAAC,aAAa,CAAC,CA2HzB"}