zyrk 0.3.7 → 0.3.9

package/dist/dlx/create.js

@@ -0,0 +1,59 @@
+/**
+ * Project scaffolding: `zyrk create <name>[@spec] [args...]`.
+ *
+ * The initializer mapping mirrors npm exactly (verified against npm's own
+ * `init` command): `foo` runs `create-foo`, `@scope/bar` runs
+ * `@scope/create-bar`, and a bare `@scope` runs `@scope/create`, each with
+ * the requested version or `*` when none was given. An already-prefixed
+ * `create-foo` is used as-is. Execution is the dlx flow, so temporary
+ * environments, trust policy, and cleanup all behave identically.
+ */
+import npa from "npm-package-arg";
+import { ZyrkError } from "../errors.js";
+import { runDlx } from "./run.js";
+/**
+ * Map an initializer to its starter package specifier. Throws ZYRK_USAGE
+ * for non-registry inputs (Git/hosted initializers are deferred along with
+ * every other non-registry protocol).
+ */
+export function starterSpecFor(input) {
+    const bareScope = /^@([^/]+?)(@([^/]+))?$/.exec(input);
+    if (bareScope !== null) {
+        const scope = bareScope[1] ?? "";
+        const version = bareScope[3];
+        if (scope === "")
+            throw usage(input);
+        return version === undefined
+            ? `@${scope}/create`
+            : `@${scope}/create@${version}`;
+    }
+    let parsed;
+    try {
+        parsed = npa(input);
+    }
+    catch (error) {
+        throw usage(input, error);
+    }
+    if (typeof parsed.name !== "string" ||
+        parsed.name === "" ||
+        typeof parsed.rawSpec !== "string" ||
+        parsed.registry !== true) {
+        throw usage(input);
+    }
+    const unscoped = parsed.name.replace(/^@[^/]+\//, "");
+    const packageName = unscoped.startsWith("create-")
+        ? parsed.name
+        : parsed.name.replace(/^(@[^/]+\/)?/, "$1create-");
+    return `${packageName}@${parsed.rawSpec}`;
+}
+function usage(input, cause) {
+    return new ZyrkError("ZYRK_USAGE", `unrecognized initializer: ${input}.`, {
+        detail: { input },
+        remedy: "use a registry package name with an optional @version, @range, or @tag",
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+export async function runCreate(options) {
+    const { input, ...rest } = options;
+    return runDlx({ ...rest, spec: starterSpecFor(input) });
+}

package/dist/dlx/run.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Temporary tool environments: `zyrk dlx <spec> [args...]` (SPEC 22.4).
+ *
+ * A tool specifier resolves to an exact package identity; its closure is
+ * fetched, verified, and realized through the shared store (reused across
+ * runs by exact graph identity, never a mutable `latest`); the tool binary
+ * runs with inherited stdio in an isolated task directory outside the
+ * store; the directory is removed afterwards. The running process is the
+ * lease: nothing else can collect the environment mid-run, and cleanup
+ * never touches a running tool.
+ *
+ * Trust policy is honored strictly: dependency lifecycle scripts are denied
+ * by default, and no script runner exists yet, so any tool closure
+ * declaring install-time scripts fails with ZYRK_SCRIPT_BLOCKED instead of
+ * running anything.
+ */
+import type { RegistryClient } from "../fetch/registry.ts";
+import type { Logger } from "../log.ts";
+import type { Store } from "../store/layout.ts";
+export type DlxOptions = {
+    store: Store;
+    registry: RegistryClient;
+    /** Tool specifier: name[@version|range|tag], possibly an npm alias. */
+    spec: string;
+    /** Arguments forwarded to the tool binary. */
+    args?: readonly string[];
+    /** Working directory for the tool (default: current directory). */
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Explicit bin name; otherwise auto-selected (single or package-named). */
+    binName?: string;
+    /** Capture stdio instead of inheriting it (used by tests). */
+    capture?: boolean;
+    logger?: Logger;
+};
+export type DlxResult = {
+    exitCode: number;
+    key: string;
+    name: string;
+    version: string;
+    /** True when every needed realization already existed. */
+    reused: boolean;
+    stdout: string;
+    stderr: string;
+    /** Removed temp environment path (assertable, always deleted). */
+    envDir: string;
+};
+/** Split a tool specifier into its edge name and version part. */
+export declare function splitDlxSpec(spec: string): {
+    name: string;
+    versionSpec: string;
+};
+export declare function runDlx(options: DlxOptions): Promise<DlxResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/dlx/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/dlx/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAUhD,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;IACzB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB,CAqBA;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAuGpE"}

package/dist/dlx/run.js

@@ -0,0 +1,274 @@
+/**
+ * Temporary tool environments: `zyrk dlx <spec> [args...]` (SPEC 22.4).
+ *
+ * A tool specifier resolves to an exact package identity; its closure is
+ * fetched, verified, and realized through the shared store (reused across
+ * runs by exact graph identity, never a mutable `latest`); the tool binary
+ * runs with inherited stdio in an isolated task directory outside the
+ * store; the directory is removed afterwards. The running process is the
+ * lease: nothing else can collect the environment mid-run, and cleanup
+ * never touches a running tool.
+ *
+ * Trust policy is honored strictly: dependency lifecycle scripts are denied
+ * by default, and no script runner exists yet, so any tool closure
+ * declaring install-time scripts fails with ZYRK_SCRIPT_BLOCKED instead of
+ * running anything.
+ */
+import { spawn } from "node:child_process";
+import { lstat, mkdtemp, readFile } from "node:fs/promises";
+import npa from "npm-package-arg";
+import * as os from "node:os";
+import * as path from "node:path";
+import { ZyrkError } from "../errors.js";
+import { fetchSources } from "../fetch/all.js";
+import { installProjection } from "../project/projection.js";
+import { createGraphDoc } from "../store/graph.js";
+import { packageDirIn, realizeGraph } from "../store/realize.js";
+import { resolveRequirements, } from "../resolve/resolver.js";
+import { Transaction } from "../store/txn.js";
+import { rmrfNoFollow } from "../util/fsx.js";
+import { closeCode } from "../util/proc.js";
+/** Split a tool specifier into its edge name and version part. */
+export function splitDlxSpec(spec) {
+    const invalid = (cause) => new ZyrkError("ZYRK_RESOLUTION_FAILED", `invalid tool specifier "${spec}"`, {
+        detail: { spec },
+        remedy: "use a package name with an optional @version, @range, or @tag",
+        ...(cause === undefined ? {} : { cause }),
+    });
+    let parsed;
+    try {
+        parsed = npa(spec);
+    }
+    catch (error) {
+        throw invalid(error);
+    }
+    if (typeof parsed.name !== "string" || parsed.name === "")
+        throw invalid();
+    if (spec === parsed.name)
+        return { name: parsed.name, versionSpec: "" };
+    if (!spec.startsWith(`${parsed.name}@`))
+        throw invalid();
+    return { name: parsed.name, versionSpec: spec.slice(parsed.name.length + 1) };
+}
+export async function runDlx(options) {
+    const { store, registry } = options;
+    const args = options.args ?? [];
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env ?? process.env;
+    const split = splitDlxSpec(options.spec);
+    const resolved = await resolveRequirements({
+        provider: registry,
+        requirements: [{ name: split.name, spec: split.versionSpec }],
+    });
+    const root = resolved.roots.find((entry) => entry.name === split.name);
+    if (root === undefined)
+        throw internal(`resolution lost the root for "${options.spec}"`);
+    const byKey = new Map(resolved.nodes.map((node) => [node.key, node]));
+    const tool = byKey.get(root.target);
+    if (tool === undefined)
+        throw internal(`resolution lost node ${root.target}`);
+    const txn = await Transaction.begin(store, "dlx");
+    try {
+        await txn.setState("fetching");
+        const fetched = await fetchSources({
+            store,
+            registry,
+            txn,
+            requests: resolved.nodes.map((node) => ({
+                key: node.key,
+                name: node.name,
+                version: node.version,
+            })),
+            ...(options.logger === undefined ? {} : { logger: options.logger }),
+        });
+        for (const node of resolved.nodes) {
+            const committed = fetched.get(node.key);
+            if (committed === undefined)
+                throw internal(`fetch lost ${node.key}`);
+            if (committed.sourceId !== node.sourceId) {
+                throw new ZyrkError("ZYRK_INTERNAL", `fetch skew for ${node.name}@${node.version}: resolved and committed identities disagree`, {
+                    detail: { name: node.name, version: node.version },
+                    remedy: "retry the operation; registries must serve immutable versioned content",
+                });
+            }
+        }
+        await txn.setState("sources-committed");
+        const graph = createGraphDoc(resolved.nodes.map((node) => ({
+            key: node.key,
+            name: node.name,
+            version: node.version,
+            sourceId: node.sourceId,
+            deps: node.edges.map((edge) => ({
+                name: edge.name,
+                target: edge.target,
+            })),
+        })));
+        const realized = await realizeGraph({
+            store,
+            graph,
+            ...(options.logger === undefined ? {} : { logger: options.logger }),
+        });
+        await txn.setState("realizations-ready");
+        const toolRealization = realized.realizationDirByKey.get(tool.key);
+        if (toolRealization === undefined)
+            throw internal(`missing realization for ${tool.key}`);
+        const toolPkgDir = packageDirIn(toolRealization, tool.name);
+        await assertNoInstallScripts(realized.packageDirByKey, byKey);
+        const binKey = selectBin(tool, options.binName);
+        const binTarget = tool.bin[binKey];
+        if (binTarget === undefined)
+            throw internal(`selected bin ${binKey} vanished`);
+        const script = await resolveBinScript(toolPkgDir, tool, binKey, binTarget);
+        const envDir = await mkdtemp(path.join(os.tmpdir(), "zyrk-dlx-"));
+        try {
+            await installProjection(envDir, [
+                { name: tool.name, linkTarget: toolPkgDir },
+            ]);
+            return {
+                ...(await runTool(script, args, cwd, env, options.capture === true)),
+                key: tool.key,
+                name: tool.name,
+                version: tool.version,
+                reused: realized.created.length === 0,
+                envDir,
+            };
+        }
+        finally {
+            await rmrfNoFollow(envDir).catch((error) => {
+                options.logger?.warn(`temporary tool environment at ${envDir} was not removed: ${String(error)}`);
+            });
+        }
+    }
+    finally {
+        await txn.finish().catch(() => { });
+    }
+}
+// ---------------------------------------------------------------------------
+/** Deny-by-default script policy: any install-time script blocks the run. */
+async function assertNoInstallScripts(packageDirByKey, byKey) {
+    for (const [key, pkgDir] of packageDirByKey) {
+        const node = byKey.get(key);
+        const label = node === undefined ? key : `${node.name}@${node.version}`;
+        let raw;
+        try {
+            raw = JSON.parse(await readFile(path.join(pkgDir, "package.json"), "utf8"));
+        }
+        catch (error) {
+            throw new ZyrkError("ZYRK_RESOLUTION_FAILED", `tool closure package ${label} has no readable package.json`, {
+                detail: { package: label },
+                remedy: "tools must ship a readable package manifest",
+                cause: error,
+            });
+        }
+        const scripts = raw.scripts;
+        const table = typeof scripts === "object" && scripts !== null && !Array.isArray(scripts)
+            ? scripts
+            : {};
+        for (const stage of ["preinstall", "install", "postinstall"]) {
+            const script = table[stage];
+            if (typeof script === "string" && script.trim() !== "") {
+                throw new ZyrkError("ZYRK_SCRIPT_BLOCKED", `tool ${label} declares install-time script "${stage}"`, {
+                    detail: { package: label, script: stage },
+                    remedy: "dependency lifecycle scripts are denied by default; remove the scripted dependency or approve it explicitly once script review is available",
+                });
+            }
+        }
+    }
+}
+function selectBin(tool, binName) {
+    const label = `${tool.name}@${tool.version}`;
+    if (binName !== undefined) {
+        if (tool.bin[binName] === undefined) {
+            throw new ZyrkError("ZYRK_RESOLUTION_FAILED", `tool ${label} has no bin entry "${binName}"`, {
+                detail: {
+                    package: label,
+                    requested: binName,
+                    available: Object.keys(tool.bin),
+                },
+                remedy: "pick one of the available bin names",
+            });
+        }
+        return binName;
+    }
+    const names = Object.keys(tool.bin);
+    if (names.length === 0) {
+        throw new ZyrkError("ZYRK_RESOLUTION_FAILED", `tool ${label} declares no executable bin entry`, {
+            detail: { package: label },
+            remedy: "tools run through their declared bin entry; pick a package that declares one",
+        });
+    }
+    const only = names[0];
+    if (names.length === 1 && only !== undefined)
+        return only;
+    const short = tool.name.startsWith("@")
+        ? (tool.name.split("/")[1] ?? tool.name)
+        : tool.name;
+    if (tool.bin[short] !== undefined)
+        return short;
+    throw new ZyrkError("ZYRK_RESOLUTION_FAILED", `tool ${label} declares several bins (${names.join(", ")}); select one explicitly`, {
+        detail: { package: label, available: names },
+        remedy: "rerun with an explicit bin name",
+    });
+}
+async function resolveBinScript(pkgDir, tool, binKey, target) {
+    const label = `${tool.name}@${tool.version}`;
+    const script = path.resolve(pkgDir, target);
+    const relative = path.relative(pkgDir, script);
+    if (relative === "" ||
+        relative.startsWith("..") ||
+        path.isAbsolute(relative)) {
+        throw new ZyrkError("ZYRK_RESOLUTION_FAILED", `tool ${label} bin "${binKey}" escapes the package`, {
+            detail: { package: label, bin: binKey },
+            remedy: "bin targets must stay inside the package directory",
+        });
+    }
+    let stat;
+    try {
+        stat = await lstat(script);
+    }
+    catch (error) {
+        throw new ZyrkError("ZYRK_RESOLUTION_FAILED", `tool ${label} bin "${binKey}" is missing from the package`, {
+            detail: { package: label, bin: binKey },
+            remedy: "the registry archive does not match its manifest; report the package",
+            cause: error,
+        });
+    }
+    if (!stat.isFile() && !stat.isSymbolicLink()) {
+        throw new ZyrkError("ZYRK_RESOLUTION_FAILED", `tool ${label} bin "${binKey}" is not a file`, {
+            detail: { package: label, bin: binKey },
+            remedy: "bin entries must point at executable files",
+        });
+    }
+    return script;
+}
+async function runTool(script, args, cwd, env, capture) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [script, ...args], {
+            cwd,
+            env,
+            stdio: capture ? "pipe" : "inherit",
+        });
+        let stdout = "";
+        let stderr = "";
+        if (capture) {
+            child.stdout?.on("data", (chunk) => {
+                stdout += chunk.toString();
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderr += chunk.toString();
+            });
+        }
+        child.on("error", (error) => {
+            reject(new ZyrkError("ZYRK_INTERNAL", "failed to launch the tool process", {
+                cause: error,
+                remedy: "verify the Node.js executable is usable",
+            }));
+        });
+        child.on("close", (code, signal) => {
+            resolve({ exitCode: closeCode(code, signal), stdout, stderr });
+        });
+    });
+}
+function internal(message) {
+    return new ZyrkError("ZYRK_INTERNAL", message);
+}

package/dist/errors.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Stable error codes and the one error type the CLI turns into output.
+ *
+ * The table in SPEC 29.1 is the contract. Codes beginning with ZYRK_ that are
+ * not listed there are internal extensions; they follow the same rules:
+ * name the failed action, name the subject, and carry a remedy.
+ */
+export declare const SPEC_ERROR_CODES: readonly ["ZYRK_MANIFEST_INVALID", "ZYRK_LOCK_MISMATCH", "ZYRK_RESOLUTION_FAILED", "ZYRK_PEER_CONFLICT", "ZYRK_INTEGRITY_FAILED", "ZYRK_SIGNATURE_INVALID", "ZYRK_EXTRACTION_UNSAFE", "ZYRK_SCRIPT_BLOCKED", "ZYRK_BUILD_FAILED", "ZYRK_WORKSPACE_BUILD_CONTEXT_UNSUPPORTED", "ZYRK_OFFLINE_MISSING", "ZYRK_LINK_UNSUPPORTED", "ZYRK_STORE_CORRUPT", "ZYRK_PROJECT_LOCKED", "ZYRK_DISK_FULL", "ZYRK_DEPLOY_ESCAPE", "ZYRK_DEPLOY_NONRELOCATABLE", "ZYRK_PLATFORM_UNSUPPORTED", "ZYRK_REGISTRY_AUTH", "ZYRK_POLICY_DENIED", 
+/** Global installation requested through zyrk; added by SPEC v1.2 §29.1. */
+"ZYRK_GLOBAL_INSTALL_UNSUPPORTED"];
+export type SpecErrorCode = (typeof SPEC_ERROR_CODES)[number];
+/** Internal extensions. Keep this list short and justified. */
+export declare const INTERNAL_ERROR_CODES: readonly [
+/** Bad invocation: unknown command, contradictory flags, missing argument. */
+"ZYRK_USAGE", 
+/** A documented command or mode that has not been implemented yet. */
+"ZYRK_NOT_IMPLEMENTED", 
+/** npm executable missing for an explicitly delegated command (D-3). */
+"ZYRK_NPM_UNAVAILABLE", 
+/** Store root fails ownership/permission safety checks. */
+"ZYRK_STORE_UNSAFE", 
+/** Store format marker missing or newer/older than this CLI understands. */
+"ZYRK_STORE_FORMAT_UNSUPPORTED", 
+/**
+ * A fetched artifact was refused before use: download exceeded the
+ * configured size bound, or a bounded retry budget was exhausted on a
+ * refusal-worthy response. Distinct from ZYRK_INTEGRITY_FAILED: nothing
+ * was verified or accepted.
+ */
+"ZYRK_FETCH_REFUSED", 
+/**
+ * Transport failure reaching the registry (DNS, TLS, connect, timeout,
+ * HTTP 5xx) after bounded retries. Retryable later; not an integrity or
+ * resolution verdict.
+ */
+"ZYRK_FETCH_FAILED", 
+/** Unexpected internal failure; always a bug. */
+"ZYRK_INTERNAL"];
+export type InternalErrorCode = (typeof INTERNAL_ERROR_CODES)[number];
+export type ErrorCode = SpecErrorCode | InternalErrorCode;
+export type ZyrkErrorOptions = {
+    /** Structured facts about the failure. Never include credentials. */
+    detail?: Record<string, unknown>;
+    /** One actionable line: what the user can do next. */
+    remedy?: string;
+    cause?: unknown;
+};
+export declare class ZyrkError extends Error {
+    readonly code: ErrorCode;
+    readonly detail: Record<string, unknown> | undefined;
+    readonly remedy: string | undefined;
+    constructor(code: ErrorCode, message: string, options?: ZyrkErrorOptions);
+}
+export declare function isZyrkError(error: unknown): error is ZyrkError;
+/**
+ * Wrap an unknown thrown value. Node system errors get their code preserved
+ * in `detail.errno` so disk-full and permission failures stay diagnosable
+ * without dumping the environment.
+ */
+export declare function toZyrkError(error: unknown, fallbackMessage: string): ZyrkError;
+/**
+ * Process exit status. SPEC 15.4 requires nonzero for integrity failure,
+ * unresolved required dependencies, blocked required builds, and failed
+ * required builds; 1 covers all of those. Usage errors use 2 so scripts can
+ * tell "you called it wrong" from "the operation failed".
+ */
+export declare function exitCodeFor(error: ZyrkError): number;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB,YAC3B,uBAAuB,EACvB,oBAAoB,EACpB,wBAAwB,EACxB,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,0CAA0C,EAC1C,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACpB,4BAA4B,EAC5B,2BAA2B,EAC3B,oBAAoB,EACpB,oBAAoB;AACpB,4EAA4E;AAC5E,iCAAiC,CACzB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,+DAA+D;AAC/D,eAAO,MAAM,oBAAoB;AAC/B,8EAA8E;AAC9E,YAAY;AACZ,sEAAsE;AACtE,sBAAsB;AACtB,wEAAwE;AACxE,sBAAsB;AACtB,2DAA2D;AAC3D,mBAAmB;AACnB,4EAA4E;AAC5E,+BAA+B;AAC/B;;;;;GAKG;AACH,oBAAoB;AACpB;;;;GAIG;AACH,mBAAmB;AACnB,iDAAiD;AACjD,eAAe,CACP,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,iBAAiB,CAAC;AAE1D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAEpC,YACE,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gBAAqB,EAU/B;CACF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,eAAe,EAAE,MAAM,GACtB,SAAS,CAsBX;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEpD"}

package/dist/errors.js

@@ -0,0 +1,111 @@
+/**
+ * Stable error codes and the one error type the CLI turns into output.
+ *
+ * The table in SPEC 29.1 is the contract. Codes beginning with ZYRK_ that are
+ * not listed there are internal extensions; they follow the same rules:
+ * name the failed action, name the subject, and carry a remedy.
+ */
+export const SPEC_ERROR_CODES = [
+    "ZYRK_MANIFEST_INVALID",
+    "ZYRK_LOCK_MISMATCH",
+    "ZYRK_RESOLUTION_FAILED",
+    "ZYRK_PEER_CONFLICT",
+    "ZYRK_INTEGRITY_FAILED",
+    "ZYRK_SIGNATURE_INVALID",
+    "ZYRK_EXTRACTION_UNSAFE",
+    "ZYRK_SCRIPT_BLOCKED",
+    "ZYRK_BUILD_FAILED",
+    "ZYRK_WORKSPACE_BUILD_CONTEXT_UNSUPPORTED",
+    "ZYRK_OFFLINE_MISSING",
+    "ZYRK_LINK_UNSUPPORTED",
+    "ZYRK_STORE_CORRUPT",
+    "ZYRK_PROJECT_LOCKED",
+    "ZYRK_DISK_FULL",
+    "ZYRK_DEPLOY_ESCAPE",
+    "ZYRK_DEPLOY_NONRELOCATABLE",
+    "ZYRK_PLATFORM_UNSUPPORTED",
+    "ZYRK_REGISTRY_AUTH",
+    "ZYRK_POLICY_DENIED",
+    /** Global installation requested through zyrk; added by SPEC v1.2 §29.1. */
+    "ZYRK_GLOBAL_INSTALL_UNSUPPORTED",
+];
+/** Internal extensions. Keep this list short and justified. */
+export const INTERNAL_ERROR_CODES = [
+    /** Bad invocation: unknown command, contradictory flags, missing argument. */
+    "ZYRK_USAGE",
+    /** A documented command or mode that has not been implemented yet. */
+    "ZYRK_NOT_IMPLEMENTED",
+    /** npm executable missing for an explicitly delegated command (D-3). */
+    "ZYRK_NPM_UNAVAILABLE",
+    /** Store root fails ownership/permission safety checks. */
+    "ZYRK_STORE_UNSAFE",
+    /** Store format marker missing or newer/older than this CLI understands. */
+    "ZYRK_STORE_FORMAT_UNSUPPORTED",
+    /**
+     * A fetched artifact was refused before use: download exceeded the
+     * configured size bound, or a bounded retry budget was exhausted on a
+     * refusal-worthy response. Distinct from ZYRK_INTEGRITY_FAILED: nothing
+     * was verified or accepted.
+     */
+    "ZYRK_FETCH_REFUSED",
+    /**
+     * Transport failure reaching the registry (DNS, TLS, connect, timeout,
+     * HTTP 5xx) after bounded retries. Retryable later; not an integrity or
+     * resolution verdict.
+     */
+    "ZYRK_FETCH_FAILED",
+    /** Unexpected internal failure; always a bug. */
+    "ZYRK_INTERNAL",
+];
+export class ZyrkError extends Error {
+    code;
+    detail;
+    remedy;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "ZyrkError";
+        this.code = code;
+        this.detail = options.detail;
+        this.remedy = options.remedy;
+    }
+}
+export function isZyrkError(error) {
+    return error instanceof ZyrkError;
+}
+/**
+ * Wrap an unknown thrown value. Node system errors get their code preserved
+ * in `detail.errno` so disk-full and permission failures stay diagnosable
+ * without dumping the environment.
+ */
+export function toZyrkError(error, fallbackMessage) {
+    if (isZyrkError(error))
+        return error;
+    const detail = {};
+    let message = fallbackMessage;
+    if (error instanceof Error) {
+        message = error.message === "" ? fallbackMessage : error.message;
+        const errno = error.code;
+        if (typeof errno === "string") {
+            detail.errno = errno;
+            if (errno === "ENOSPC") {
+                return new ZyrkError("ZYRK_DISK_FULL", message, {
+                    detail,
+                    cause: error,
+                });
+            }
+            if (errno === "EACCES" || errno === "EPERM") {
+                detail.errno = errno;
+            }
+        }
+    }
+    return new ZyrkError("ZYRK_INTERNAL", message, { detail, cause: error });
+}
+/**
+ * Process exit status. SPEC 15.4 requires nonzero for integrity failure,
+ * unresolved required dependencies, blocked required builds, and failed
+ * required builds; 1 covers all of those. Usage errors use 2 so scripts can
+ * tell "you called it wrong" from "the operation failed".
+ */
+export function exitCodeFor(error) {
+    return error.code === "ZYRK_USAGE" ? 2 : 1;
+}

package/dist/extract/tarball.d.ts

@@ -0,0 +1,82 @@
+import { type ModeClass } from "../util/hash.ts";
+/**
+ * Safe archive extraction (SPEC 13.4).
+ *
+ * Two passes over the archive: the first validates every entry (paths,
+ * collisions, limits, supported types) and decides how a single common root
+ * directory, if any, is stripped; the second writes entries under the
+ * transaction's staging directory. The validation pass writes nothing.
+ *
+ * Rules enforced here:
+ * - absolute paths, drive letters, backslashes, NUL bytes, and `..`
+ *   traversal are rejected;
+ * - case-folding collisions are rejected; Windows-reserved names and
+ *   invalid characters are detected and reported (deploy targets re-check);
+ * - only regular files, directories, symlinks, and validated hard links are
+ *   accepted;
+ * - symlink and hard-link targets must stay inside the package root;
+ * - setuid/setgid/sticky bits and archive ownership are never applied;
+ * - files are created exclusively (`wx`) and never written through a
+ *   previously created symlink;
+ * - entry count, total bytes, and path lengths are bounded.
+ */
+export type ExtractionLimits = {
+    maxEntries: number;
+    maxTotalBytes: number;
+    maxPathLength: number;
+    maxComponentLength: number;
+    maxSymlinkTargetLength: number;
+};
+export declare const DEFAULT_EXTRACTION_LIMITS: ExtractionLimits;
+export type ExtractedFileEntry = {
+    path: string;
+    type: "file";
+    mode: ModeClass;
+    size: number;
+    innerDigest: string;
+    /** Absolute path inside the staging tree, for the commit step. */
+    stagingPath: string;
+};
+export type ExtractedDirEntry = {
+    path: string;
+    type: "dir";
+};
+export type ExtractedSymlinkEntry = {
+    path: string;
+    type: "symlink";
+    target: string;
+};
+export type ExtractedEntry = ExtractedFileEntry | ExtractedDirEntry | ExtractedSymlinkEntry;
+export type ExtractionResult = {
+    entries: ExtractedEntry[];
+    totals: {
+        files: number;
+        dirs: number;
+        symlinks: number;
+        logicalBytes: number;
+    };
+    /** Deterministic, sorted outcome codes; stored in the source manifest. */
+    outcomes: string[];
+    /** The stripped common root directory, if one was found. */
+    commonRoot: string | null;
+    /** Non-fatal observations for CLI warnings. */
+    observations: string[];
+};
+export declare function extractTarball(options: {
+    tarballPath: string;
+    destDir: string;
+    limits?: Partial<ExtractionLimits>;
+}): Promise<ExtractionResult>;
+export type PathCheck = {
+    normalized: string;
+    reserved: boolean;
+    invalidWindows: boolean;
+};
+/** Normalize and validate an archive path; anything that can escape fails. */
+export declare function normalizeArchivePath(rawInput: string, limits: ExtractionLimits): PathCheck;
+export declare function chaseSymlinkChain(linkPath: string, target: string, symlinks: Map<string, string>): {
+    finalPath: string;
+    escaped: boolean;
+    cyclic: boolean;
+};
+//# sourceMappingURL=tarball.d.ts.map

package/dist/extract/tarball.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tarball.d.ts","sourceRoot":"","sources":["../../src/extract/tarball.ts"],"names":[],"mappings":"AAaA,OAAO,EAAuB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGtE;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,eAAO,MAAM,yBAAyB,EAAE,gBAMvC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAE9D,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,cAAc,GACxB,kBAAkB,GAAG,iBAAiB,GAAG,qBAAqB,CAAC;AAEjE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,MAAM,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,+CAA+C;IAC/C,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAeF,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACpC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAyW5B;AAMD,MAAM,MAAM,SAAS,GAAG;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,gBAAgB,GACvB,SAAS,CAkDX;AAmND,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,CA2B1D"}