@moewolf/moe-icons-cli 0.0.1

package/dist/project/install.d.ts

@@ -0,0 +1,115 @@
+import type { mkdirSync, writeFileSync, readFileSync, existsSync, renameSync, rmSync, readdirSync, copyFileSync } from "node:fs";
+/**
+ * Transactional install: stage sibling, verify all files, backup existing
+ * managed output, rename atomically, update config last, restore on failure.
+ * Never touches the project tree until every file is verified in staging.
+ */
+export interface InstallPlanItem {
+    readonly kind: "mkdir" | "write" | "remove" | "config";
+    readonly path: string;
+    /** Relative path inside the install root, used to stage nested files safely. */
+    readonly rel?: string;
+    readonly content?: string;
+    readonly bytes?: Uint8Array;
+}
+export interface InstallPlan {
+    readonly items: readonly InstallPlanItem[];
+}
+export interface TransactionalFs {
+    readonly mkdirSync: typeof mkdirSync;
+    readonly writeFileSync: typeof writeFileSync;
+    readonly existsSync: typeof existsSync;
+    readonly renameSync: typeof renameSync;
+    readonly rmSync: typeof rmSync;
+}
+export interface TransactionalFsWithCopy extends TransactionalFs {
+    readonly readFileSync: typeof readFileSync;
+    readonly readdirSync: typeof readdirSync;
+    readonly copyFileSync: typeof copyFileSync;
+}
+/**
+ * Atomically reconcile an explicit cross-directory managed set. `removePaths`
+ * must come from trusted metadata; this function never scans or uses globs.
+ */
+export declare function executeManagedReconcile(projectRoot: string, writes: Readonly<Record<string, string | Uint8Array>>, removePaths: readonly string[], fs_: TransactionalFsWithCopy): void;
+/** Pure list of install operations with expected checksums. */
+export declare function createInstallPlan(targetRoot: string, files: Readonly<Record<string, string | Uint8Array>>): InstallPlan;
+/** Create a deterministic ZIP for delivery (fixed mtime). */
+export declare function createArtifactZip(files: Readonly<Record<string, string>>): Uint8Array;
+/** Unzip an artifact, rejecting unsafe paths. */
+export declare function extractArtifact(zipBytes: Uint8Array, limits: {
+    maxEntries: number;
+    maxExpandedBytes: number;
+}): {
+    files: Record<string, string>;
+    errors: string[];
+};
+/** SHA-256 hex of a string. */
+export declare function sha256Hex(content: string): string;
+/**
+ * Execute an install plan against a filesystem with a staging dir, verifying
+ * checksums before any rename. Restores the original tree on failure.
+ */
+export declare function executeInstallPlan(plan: InstallPlan, fs_: TransactionalFs): void;
+/**
+ * Transactionally replace only generated files. Existing files outside this
+ * explicit list are left untouched, which makes the output directory safe to
+ * share with user-owned files.
+ */
+export declare function executeGeneratedFiles(files: readonly {
+    path: string;
+    content: string;
+}[], projectRoot: string, outputDir: string, fs_: TransactionalFs): void;
+/**
+ * Directory-level transactional generate: writes all CLI-managed files into a
+ * sibling staging directory, renames the current output directory to a backup,
+ * renames staging to output, then merges user-owned files (files not in the
+ * CLI-managed set) back from the backup. Restores the backup on any failure so
+ * the output directory is never left in a partial state.
+ *
+ * The set of CLI-managed paths is determined by the `files` argument. Any file
+ * that already exists in outputDir but is NOT in that set is considered
+ * user-owned and is preserved. Older CLI-managed files are identified by the
+ * generated-file header and are intentionally not restored.
+ */
+export declare function executeGeneratedFilesDir(files: readonly {
+    path: string;
+    content: string | Uint8Array;
+}[], projectRoot: string, outputDir: string, fs_: TransactionalFsWithCopy): void;
+/** Atomically create a new file without replacing an existing user file. */
+export declare function createFileIfAbsent(target: string, content: string, fs_: TransactionalFs): boolean;
+export interface DownloadLimits {
+    readonly maxBytes: number;
+    readonly timeoutMs: number;
+    readonly maxRedirects: number;
+    readonly allowedHosts?: readonly string[];
+    readonly userAgent?: string;
+    readonly onProgress?: (event: {
+        readonly downloadedBytes: number;
+        readonly totalBytes?: number;
+    }) => void;
+    readonly allowHttpLoopback?: boolean;
+}
+export type DownloadResult = {
+    readonly ok: true;
+    readonly bytes: Uint8Array;
+    readonly finalUrl: string;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * Download an artifact. HTTPS only, optional host allowlist, bounded redirects,
+ * timeout, byte limit. Abort and temporary-file cleanup are handled by the
+ * caller via the injected fetch/signal.
+ */
+export declare function downloadArtifact(url: string, limits: DownloadLimits, deps?: {
+    fetchFn?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<DownloadResult>;
+/** Verify a downloaded artifact against an expected SHA-256 (and optional signature). */
+export declare function verifyArtifact(bytes: Uint8Array, expectedSha256: string): {
+    ok: boolean;
+    actual: string;
+};

package/dist/project/install.js

@@ -0,0 +1,537 @@
+import { join, relative, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { strToU8, zipSync, unzipSync } from "fflate";
+/**
+ * Atomically reconcile an explicit cross-directory managed set. `removePaths`
+ * must come from trusted metadata; this function never scans or uses globs.
+ */
+export function executeManagedReconcile(projectRoot, writes, removePaths, fs_) {
+    const stagingRoot = join(projectRoot, ".moeicons", ".reconcile-staging");
+    const backupRoot = join(projectRoot, ".moeicons", ".reconcile-backup");
+    const safe = (relative) => {
+        const normalized = relative.replace(/\\/g, "/");
+        if (!normalized || normalized.startsWith("/") || normalized.split("/").includes("..") || /^[A-Za-z]:/.test(normalized))
+            throw new Error(`unsafe managed path: ${relative}`);
+        const target = resolve(projectRoot, normalized);
+        if (!target.startsWith(`${resolve(projectRoot)}/`) && !target.startsWith(`${resolve(projectRoot)}\\`))
+            throw new Error(`managed path escapes project: ${relative}`);
+        return { normalized, target };
+    };
+    const entries = Object.entries(writes).map(([relative, content]) => ({ ...safe(relative), content }));
+    const removals = [...new Set(removePaths)].map(safe).filter((item) => !Object.hasOwn(writes, item.normalized));
+    if (fs_.existsSync(stagingRoot))
+        fs_.rmSync(stagingRoot, { recursive: true, force: true });
+    if (fs_.existsSync(backupRoot)) {
+        const recover = (dir) => {
+            let names;
+            try {
+                names = fs_.readdirSync(dir);
+            }
+            catch {
+                const rel = relative(backupRoot, dir);
+                const target = join(projectRoot, rel);
+                if (fs_.existsSync(target))
+                    fs_.rmSync(target, { recursive: true, force: true });
+                fs_.mkdirSync(join(target, ".."), { recursive: true });
+                fs_.renameSync(dir, target);
+                return;
+            }
+            for (const name of names)
+                recover(join(dir, name));
+        };
+        recover(backupRoot);
+        fs_.rmSync(backupRoot, { recursive: true, force: true });
+    }
+    const backedUp = [];
+    const installed = [];
+    let preserveBackup = false;
+    try {
+        for (const entry of entries) {
+            const staged = join(stagingRoot, entry.normalized);
+            fs_.mkdirSync(join(staged, ".."), { recursive: true });
+            fs_.writeFileSync(staged, entry.content);
+        }
+        for (const item of [...removals, ...entries]) {
+            if (!fs_.existsSync(item.target))
+                continue;
+            const backup = join(backupRoot, item.normalized);
+            fs_.mkdirSync(join(backup, ".."), { recursive: true });
+            fs_.renameSync(item.target, backup);
+            backedUp.push({ target: item.target, backup });
+        }
+        for (const entry of entries) {
+            const staged = join(stagingRoot, entry.normalized);
+            fs_.mkdirSync(join(entry.target, ".."), { recursive: true });
+            fs_.renameSync(staged, entry.target);
+            installed.push(entry.target);
+        }
+        if (fs_.existsSync(backupRoot))
+            fs_.rmSync(backupRoot, { recursive: true, force: true });
+    }
+    catch (error) {
+        for (const target of installed.reverse())
+            if (fs_.existsSync(target))
+                fs_.rmSync(target, { force: true });
+        for (const item of backedUp.reverse()) {
+            if (fs_.existsSync(item.backup)) {
+                fs_.mkdirSync(join(item.target, ".."), { recursive: true });
+                try {
+                    fs_.renameSync(item.backup, item.target);
+                }
+                catch {
+                    preserveBackup = true;
+                }
+            }
+        }
+        throw error;
+    }
+    finally {
+        if (fs_.existsSync(stagingRoot))
+            fs_.rmSync(stagingRoot, { recursive: true, force: true });
+        if (!preserveBackup && fs_.existsSync(backupRoot))
+            fs_.rmSync(backupRoot, { recursive: true, force: true });
+    }
+}
+const GENERATED_FILE_HEADER = "// Generated by moeicons CLI.";
+/** Pure list of install operations with expected checksums. */
+export function createInstallPlan(targetRoot, files) {
+    const items = [];
+    const sorted = Object.keys(files).sort((a, b) => a.localeCompare(b));
+    for (const rel of sorted) {
+        const content = files[rel];
+        if (content !== undefined) {
+            items.push(typeof content === "string"
+                ? { kind: "write", path: join(targetRoot, rel), rel, content }
+                : { kind: "write", path: join(targetRoot, rel), rel, bytes: content });
+        }
+    }
+    return { items };
+}
+/** Create a deterministic ZIP for delivery (fixed mtime). */
+export function createArtifactZip(files) {
+    const sorted = Object.keys(files).sort((a, b) => a.localeCompare(b));
+    const dict = {};
+    for (const rel of sorted) {
+        dict[rel] = strToU8(files[rel] ?? "");
+    }
+    return zipSync(dict, { level: 9, mtime: new Date("2020-01-01T00:00:00.000Z") });
+}
+/** Unzip an artifact, rejecting unsafe paths. */
+export function extractArtifact(zipBytes, limits) {
+    const files = {};
+    const errors = [];
+    let entries = 0;
+    let expanded = 0;
+    const dict = unzipSync(zipBytes);
+    for (const [rel, bytes] of Object.entries(dict)) {
+        entries += 1;
+        if (entries > limits.maxEntries) {
+            errors.push(`too many entries (> ${limits.maxEntries})`);
+            break;
+        }
+        const cleaned = rel.replace(/\\/g, "/");
+        if (cleaned.startsWith("/") || cleaned.split("/").includes("..")) {
+            errors.push(`unsafe path "${rel}"`);
+            continue;
+        }
+        expanded += bytes.byteLength;
+        if (expanded > limits.maxExpandedBytes) {
+            errors.push(`expanded size exceeds limit`);
+            break;
+        }
+        files[cleaned] = new TextDecoder().decode(bytes);
+    }
+    return { files, errors };
+}
+/** SHA-256 hex of a string. */
+export function sha256Hex(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/**
+ * Execute an install plan against a filesystem with a staging dir, verifying
+ * checksums before any rename. Restores the original tree on failure.
+ */
+export function executeInstallPlan(plan, fs_) {
+    const writes = plan.items.filter((i) => i.kind === "write");
+    // stage all writes into a sibling staging dir
+    const firstWrite = writes[0];
+    if (!firstWrite)
+        return;
+    const stagingRoot = `${resolve(firstWrite.path)}.staging`;
+    if (fs_.existsSync(stagingRoot))
+        fs_.rmSync(stagingRoot, { recursive: true, force: true });
+    fs_.mkdirSync(stagingRoot, { recursive: true });
+    const backups = [];
+    const installed = [];
+    try {
+        for (const item of writes) {
+            const rel = item.rel ?? item.path.replace(/\\/g, "/").split("/").pop() ?? "file";
+            const staged = join(stagingRoot, rel);
+            fs_.mkdirSync(join(staged, ".."), { recursive: true });
+            fs_.writeFileSync(staged, item.bytes ?? item.content ?? "");
+        }
+        // move staged files into place, backing up existing managed output
+        for (const item of writes) {
+            const rel = item.rel ?? item.path.replace(/\\/g, "/").split("/").pop() ?? "file";
+            const staged = join(stagingRoot, rel);
+            if (fs_.existsSync(item.path)) {
+                const backup = `${item.path}.bak`;
+                fs_.renameSync(item.path, backup);
+                backups.push({ original: item.path, backup });
+            }
+            fs_.mkdirSync(join(item.path, ".."), { recursive: true });
+            fs_.renameSync(staged, item.path);
+            installed.push(item.path);
+        }
+    }
+    catch (error) {
+        for (const path of installed) {
+            if (!backups.some((backup) => backup.original === path) && fs_.existsSync(path)) {
+                fs_.rmSync(path, { force: true });
+            }
+        }
+        // restore any backups made before the failure
+        for (const b of backups) {
+            try {
+                if (fs_.existsSync(b.backup))
+                    fs_.renameSync(b.backup, b.original);
+            }
+            catch {
+                // ignore restore errors; the original remains at .bak
+            }
+        }
+        throw error;
+    }
+    finally {
+        if (fs_.existsSync(stagingRoot))
+            fs_.rmSync(stagingRoot, { recursive: true, force: true });
+    }
+    for (const backup of backups) {
+        if (fs_.existsSync(backup.backup))
+            fs_.rmSync(backup.backup, { force: true });
+    }
+}
+/**
+ * Transactionally replace only generated files. Existing files outside this
+ * explicit list are left untouched, which makes the output directory safe to
+ * share with user-owned files.
+ */
+export function executeGeneratedFiles(files, projectRoot, outputDir, fs_) {
+    const outputRoot = resolve(projectRoot, outputDir);
+    const stagingRoot = `${outputRoot}.staging`;
+    if (fs_.existsSync(stagingRoot))
+        fs_.rmSync(stagingRoot, { recursive: true, force: true });
+    const entries = files.map((file) => {
+        const target = resolve(projectRoot, file.path);
+        const relative = target.slice(outputRoot.length).replace(/^[/\\]/, "");
+        if (target !== outputRoot && !target.startsWith(`${outputRoot}/`) && !target.startsWith(`${outputRoot}\\`)) {
+            throw new Error(`generated path escapes output directory: ${file.path}`);
+        }
+        return { target, staged: join(stagingRoot, relative), content: file.content };
+    });
+    fs_.mkdirSync(stagingRoot, { recursive: true });
+    const backups = [];
+    const installed = [];
+    try {
+        for (const entry of entries) {
+            fs_.mkdirSync(join(entry.staged, ".."), { recursive: true });
+            fs_.writeFileSync(entry.staged, entry.content);
+        }
+        for (const entry of entries) {
+            if (fs_.existsSync(entry.target)) {
+                const backup = `${entry.target}.bak`;
+                fs_.renameSync(entry.target, backup);
+                backups.push({ original: entry.target, backup });
+            }
+            fs_.mkdirSync(join(entry.target, ".."), { recursive: true });
+            fs_.renameSync(entry.staged, entry.target);
+            installed.push(entry.target);
+        }
+    }
+    catch (error) {
+        for (const path of installed) {
+            if (!backups.some((backup) => backup.original === path) && fs_.existsSync(path)) {
+                fs_.rmSync(path, { force: true });
+            }
+        }
+        for (const backup of backups) {
+            try {
+                if (fs_.existsSync(backup.backup))
+                    fs_.renameSync(backup.backup, backup.original);
+            }
+            catch {
+                // Preserve the backup when the filesystem cannot restore it.
+            }
+        }
+        throw error;
+    }
+    finally {
+        if (fs_.existsSync(stagingRoot))
+            fs_.rmSync(stagingRoot, { recursive: true, force: true });
+    }
+    for (const backup of backups) {
+        if (fs_.existsSync(backup.backup))
+            fs_.rmSync(backup.backup, { force: true });
+    }
+}
+/**
+ * Directory-level transactional generate: writes all CLI-managed files into a
+ * sibling staging directory, renames the current output directory to a backup,
+ * renames staging to output, then merges user-owned files (files not in the
+ * CLI-managed set) back from the backup. Restores the backup on any failure so
+ * the output directory is never left in a partial state.
+ *
+ * The set of CLI-managed paths is determined by the `files` argument. Any file
+ * that already exists in outputDir but is NOT in that set is considered
+ * user-owned and is preserved. Older CLI-managed files are identified by the
+ * generated-file header and are intentionally not restored.
+ */
+export function executeGeneratedFilesDir(files, projectRoot, outputDir, fs_) {
+    const outputRoot = resolve(projectRoot, outputDir);
+    const stagingRoot = `${outputRoot}.staging`;
+    const backupRoot = `${outputRoot}.bak`;
+    // Validate all paths up front.
+    const managedRelPaths = new Set();
+    const entries = files.map((file) => {
+        const target = resolve(projectRoot, file.path);
+        if (target !== outputRoot && !target.startsWith(`${outputRoot}/`) && !target.startsWith(`${outputRoot}\\`)) {
+            throw new Error(`generated path escapes output directory: ${file.path}`);
+        }
+        const rel = target.slice(outputRoot.length).replace(/^[/\\]/, "");
+        managedRelPaths.add(rel);
+        return { staged: join(stagingRoot, rel), content: file.content };
+    });
+    // Clean up any leftover staging/backup from a previous failed run.
+    if (fs_.existsSync(stagingRoot))
+        fs_.rmSync(stagingRoot, { recursive: true, force: true });
+    if (fs_.existsSync(backupRoot))
+        fs_.rmSync(backupRoot, { recursive: true, force: true });
+    fs_.mkdirSync(stagingRoot, { recursive: true });
+    try {
+        // 1. Write all CLI-managed files into staging.
+        for (const entry of entries) {
+            fs_.mkdirSync(join(entry.staged, ".."), { recursive: true });
+            fs_.writeFileSync(entry.staged, entry.content);
+        }
+        // 2. Rename existing output → backup (if it exists).
+        const hadOutput = fs_.existsSync(outputRoot);
+        if (hadOutput) {
+            fs_.renameSync(outputRoot, backupRoot);
+        }
+        // 3. Rename staging → output (atomic on same-filesystem).
+        try {
+            fs_.renameSync(stagingRoot, outputRoot);
+        }
+        catch (renameError) {
+            // staging rename failed; try to restore backup.
+            if (hadOutput && fs_.existsSync(backupRoot)) {
+                try {
+                    fs_.renameSync(backupRoot, outputRoot);
+                }
+                catch { /* best-effort */ }
+            }
+            throw renameError;
+        }
+        // 4. Merge user-owned files from backup back into the new output directory.
+        if (hadOutput) {
+            const userFiles = collectUserFiles(backupRoot, backupRoot, managedRelPaths, fs_);
+            for (const { rel, src } of userFiles) {
+                const dest = join(outputRoot, rel);
+                fs_.mkdirSync(join(dest, ".."), { recursive: true });
+                try {
+                    fs_.copyFileSync(src, dest);
+                }
+                catch {
+                    // Non-fatal: a user file could not be restored. Proceed with generation.
+                }
+            }
+            fs_.rmSync(backupRoot, { recursive: true, force: true });
+        }
+    }
+    catch (error) {
+        // On failure, restore backup → output if backup exists.
+        if (fs_.existsSync(backupRoot) && !fs_.existsSync(outputRoot)) {
+            try {
+                fs_.renameSync(backupRoot, outputRoot);
+            }
+            catch { /* best-effort */ }
+        }
+        if (fs_.existsSync(stagingRoot)) {
+            fs_.rmSync(stagingRoot, { recursive: true, force: true });
+        }
+        throw error;
+    }
+}
+/** Recursively collect files in `dir` that are NOT in `managedRelPaths`. */
+function collectUserFiles(dir, rootDir, managedRelPaths, fs_) {
+    const result = [];
+    let entries;
+    try {
+        entries = fs_.readdirSync(dir);
+    }
+    catch {
+        return result;
+    }
+    for (const name of entries) {
+        const full = join(dir, name);
+        const rel = full.slice(rootDir.length).replace(/^[/\\]/, "");
+        // Check if it is a directory without using withFileTypes (avoids Dirent overload issues).
+        let isDir = false;
+        try {
+            // readdirSync on the path will succeed for directories.
+            fs_.readdirSync(full);
+            isDir = true;
+        }
+        catch {
+            isDir = false;
+        }
+        if (isDir) {
+            result.push(...collectUserFiles(full, rootDir, managedRelPaths, fs_));
+        }
+        else if (!managedRelPaths.has(rel) && !isManagedAssetPath(rel) && !isCliManagedFile(full, fs_)) {
+            result.push({ rel, src: full });
+        }
+    }
+    return result;
+}
+function isManagedAssetPath(rel) {
+    const posix = rel.replace(/\\/g, "/");
+    return posix === "assets" || posix.startsWith("assets/");
+}
+function isCliManagedFile(path, fs_) {
+    try {
+        return fs_.readFileSync(path, "utf8").startsWith(GENERATED_FILE_HEADER);
+    }
+    catch {
+        return false;
+    }
+}
+/** Atomically create a new file without replacing an existing user file. */
+export function createFileIfAbsent(target, content, fs_) {
+    if (fs_.existsSync(target))
+        return false;
+    const staging = `${target}.staging`;
+    if (fs_.existsSync(staging))
+        fs_.rmSync(staging, { force: true });
+    fs_.mkdirSync(join(target, ".."), { recursive: true });
+    try {
+        fs_.writeFileSync(staging, content, { flag: "wx" });
+        fs_.renameSync(staging, target);
+        return true;
+    }
+    finally {
+        if (fs_.existsSync(staging))
+            fs_.rmSync(staging, { force: true });
+    }
+}
+/**
+ * Download an artifact. HTTPS only, optional host allowlist, bounded redirects,
+ * timeout, byte limit. Abort and temporary-file cleanup are handled by the
+ * caller via the injected fetch/signal.
+ */
+export async function downloadArtifact(url, limits, deps = {}) {
+    const parsed = new URL(url);
+    const loopbackHttp = limits.allowHttpLoopback === true && parsed.protocol === "http:" && (parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost" || parsed.hostname === "::1");
+    if (parsed.protocol !== "https:" && !loopbackHttp) {
+        return { ok: false, code: "NON_HTTPS", message: "artifact URLs must use https" };
+    }
+    if (limits.allowedHosts && !limits.allowedHosts.includes(parsed.host)) {
+        return { ok: false, code: "HOST_NOT_ALLOWED", message: `host ${parsed.host} not in allowlist` };
+    }
+    const fetchFn = deps.fetchFn ?? globalThis.fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), limits.timeoutMs);
+    const abortHandler = () => controller.abort();
+    deps.signal?.addEventListener("abort", abortHandler, { once: true });
+    try {
+        let currentUrl = url;
+        let redirects = 0;
+        let response;
+        for (;;) {
+            response = await fetchFn(currentUrl, {
+                method: "GET",
+                redirect: "manual",
+                signal: controller.signal,
+                ...(limits.userAgent ? { headers: { "user-agent": limits.userAgent } } : {}),
+            });
+            if (response.status >= 300 && response.status < 400) {
+                redirects += 1;
+                if (redirects > limits.maxRedirects) {
+                    return { ok: false, code: "TOO_MANY_REDIRECTS", message: `exceeded ${limits.maxRedirects} redirects` };
+                }
+                const location = response.headers.get("location");
+                if (!location) {
+                    return { ok: false, code: "REDIRECT_NO_LOCATION", message: "redirect without location header" };
+                }
+                currentUrl = new URL(location, currentUrl).toString();
+                const next = new URL(currentUrl);
+                const nextLoopback = limits.allowHttpLoopback === true && next.protocol === "http:" && (next.hostname === "127.0.0.1" || next.hostname === "localhost" || next.hostname === "::1");
+                if (next.protocol !== "https:" && !nextLoopback) {
+                    return { ok: false, code: "NON_HTTPS", message: "redirect to non-https url" };
+                }
+                if (limits.allowedHosts && !limits.allowedHosts.includes(next.host)) {
+                    return { ok: false, code: "HOST_NOT_ALLOWED", message: `redirect host ${next.host} not in allowlist` };
+                }
+                continue;
+            }
+            break;
+        }
+        if (!response || response.status >= 400) {
+            return { ok: false, code: "HTTP_ERROR", message: `request failed with ${response.status ?? "unknown"}` };
+        }
+        const rawLength = response.headers.get("content-length");
+        const contentLength = rawLength !== null && /^\d+$/.test(rawLength) ? Number(rawLength) : undefined;
+        if (contentLength !== undefined && contentLength > limits.maxBytes) {
+            return { ok: false, code: "TOO_LARGE", message: `content-length ${contentLength} exceeds limit` };
+        }
+        const chunks = [];
+        let downloadedBytes = 0;
+        if (response.body) {
+            const reader = response.body.getReader();
+            for (;;) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                const value = chunk.value;
+                downloadedBytes += value.byteLength;
+                if (downloadedBytes > limits.maxBytes) {
+                    await reader.cancel();
+                    return { ok: false, code: "TOO_LARGE", message: `body exceeds byte limit ${limits.maxBytes}` };
+                }
+                chunks.push(value);
+                limits.onProgress?.({ downloadedBytes, ...(contentLength !== undefined ? { totalBytes: contentLength } : {}) });
+            }
+        }
+        else {
+            const buffer = await response.arrayBuffer();
+            downloadedBytes = buffer.byteLength;
+            if (downloadedBytes > limits.maxBytes)
+                return { ok: false, code: "TOO_LARGE", message: `body exceeds byte limit ${limits.maxBytes}` };
+            chunks.push(new Uint8Array(buffer));
+            limits.onProgress?.({ downloadedBytes, ...(contentLength !== undefined ? { totalBytes: contentLength } : {}) });
+        }
+        const bytes = new Uint8Array(downloadedBytes);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return { ok: true, bytes, finalUrl: currentUrl };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            code: "NETWORK_ERROR",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        deps.signal?.removeEventListener("abort", abortHandler);
+    }
+}
+/** Verify a downloaded artifact against an expected SHA-256 (and optional signature). */
+export function verifyArtifact(bytes, expectedSha256) {
+    const actual = createHash("sha256").update(bytes).digest("hex");
+    return { ok: actual.toLowerCase() === expectedSha256.toLowerCase(), actual };
+}

package/dist/project/project-lock.d.ts

@@ -0,0 +1,11 @@
+export interface ProjectLockIo {
+    readonly exists: (path: string) => boolean;
+    readonly read: (path: string) => string;
+    readonly createExclusive: (path: string, content: string) => void;
+    readonly remove: (path: string) => void;
+    readonly isProcessAlive: (pid: number) => boolean;
+    readonly now: () => number;
+    readonly pid: number;
+}
+export declare function withProjectLock<T>(projectRoot: string, operation: "install" | "update" | "reload", work: () => Promise<T> | T, io?: ProjectLockIo): Promise<T>;
+export declare function withProjectLockSync<T>(projectRoot: string, operation: "install" | "update" | "reload", work: () => T, io?: ProjectLockIo): T;