@hraness/sponge 0.2.5 → 0.3.0

package/dist/src/acquisition/capture.js

@@ -4,10 +4,11 @@ import { fileURLToPath } from 'node:url';
 import { limits } from '../../contracts/index.js';
 import { privateRoot, physicalBytes } from './files.js';
 import { runOwned, isolatedEnvironment } from './process.js';
-import { inspectCaptureRuntime, CaptureSetupError } from './runtime.js';
-import { settleCaptureRoot, CaptureCleanupError } from './cleanup.js';
+import { inspectCaptureRuntime } from './runtime.js';
+import { settleCaptureRoot } from './cleanup.js';
 import { failure, upstreamFailure } from './errors.js';
 import { normalizeBundle, object } from './normalize.js';
+import { SpongeError, publicCode, codeOf } from '../errors.js';
 export async function captureArticle(request) {
     const { requestId, signal } = request;
     if (!/^[a-zA-Z0-9_-]{1,128}$/.test(requestId))
@@ -28,7 +29,7 @@ export async function captureArticle(request) {
         runtime = await inspectCaptureRuntime(request.runtime.root, request.runtime.pins);
     }
     catch (error) {
-        return failure(requestId, error instanceof CaptureSetupError ? error.code : 'runtime-missing', 'setup');
+        return failure(requestId, publicCode(error, 'runtime-missing'), 'setup');
     }
     let base;
     try {
@@ -43,7 +44,24 @@ export async function captureArticle(request) {
     const deadline = request.deadlineMs ?? limits.captureDeadlineMs;
     if (!Number.isSafeInteger(deadline) || deadline < 100 || deadline > limits.captureDeadlineMs)
         return failure(requestId, 'invalid-input');
-    const args = [runtime.ghostget, 'clip', request.sourceUrl, 'article', '--media', 'images', '--timeout-ms', String(deadline), '--max-html-bytes', String(limits.markdownBytes), '--max-asset-bytes', String(limits.imageBytes), '--max-total-asset-bytes', String(500 * 1024 ** 2), '--quiet', '--json'];
+    const args = [
+        runtime.ghostget,
+        'clip',
+        request.sourceUrl,
+        'article',
+        '--media',
+        'images',
+        '--timeout-ms',
+        String(deadline),
+        '--max-html-bytes',
+        String(limits.markdownBytes),
+        '--max-asset-bytes',
+        String(limits.imageBytes),
+        '--max-total-asset-bytes',
+        String(500 * 1024 ** 2),
+        '--quiet',
+        '--json',
+    ];
     if (request.allowPrivateNetwork)
         args.push('--allow-private-network');
     let selectedState;
@@ -74,27 +92,40 @@ export async function captureArticle(request) {
     if (signal?.aborted)
         abort();
     let cleanup = 'settled', keep = false, quota = false, checking = false;
-    const monitor = setInterval(async () => { if (checking)
-        return; checking = true; try {
-        if (await physicalBytes(root) > limits.stagingBytes) {
+    const monitor = setInterval(async () => {
+        if (checking)
+            return;
+        checking = true;
+        try {
+            if ((await physicalBytes(root)) > limits.stagingBytes) {
+                quota = true;
+                controller.abort();
+            }
+        }
+        catch {
             quota = true;
             controller.abort();
         }
-    }
-    catch {
-        quota = true;
-        controller.abort();
-    }
-    finally {
-        checking = false;
-    } }, 100);
+        finally {
+            checking = false;
+        }
+    }, 100);
     const started = Date.now();
     try {
         await mkdir(home, { mode: 0o700 });
         await mkdir(output, { mode: 0o700 });
-        await writeFile(join(root, 'ownership.json'), JSON.stringify({ schemaVersion: 1, requestId, state: 'acquiring' }), { mode: 0o600 });
+        await writeFile(join(root, 'ownership.json'), JSON.stringify({ schemaVersion: 1, requestId, state: 'acquiring' }), {
+            mode: 0o600,
+        });
         cleanup = 'pending';
-        const result = await (request.runProcess ?? runOwned)(runtime.bun, args, { cwd: root, env, signal: controller.signal, deadlineMs: deadline, maxOutputBytes: limits.metadataBytes, graceMs: 5000 });
+        const result = await (request.runProcess ?? runOwned)(runtime.bun, args, {
+            cwd: root,
+            env,
+            signal: controller.signal,
+            deadlineMs: deadline,
+            maxOutputBytes: limits.metadataBytes,
+            graceMs: 5000,
+        });
         cleanup = result.cleanup;
         // Ghostget reports escaped browser custody separately from generic descendants.
         let summary;
@@ -109,9 +140,13 @@ export async function captureArticle(request) {
             cleanup = 'pending';
         if (cleanup === 'settled' && request.connection?.kind === 'cdp') {
             cleanup = 'pending';
-            const census = await (request.runProcess ?? runOwned)('/bin/ps', ['-axo', 'command'], { env, deadlineMs: 3000, maxOutputBytes: 4 * 1024 ** 2 });
+            const census = await (request.runProcess ?? runOwned)('/bin/ps', ['-axo', 'command'], {
+                env,
+                deadlineMs: 3000,
+                maxOutputBytes: 4 * 1024 ** 2,
+            });
             cleanup = census.cleanup;
-            if (census.code !== 0 || census.stopped || census.stdout.split('\n').some(line => line.includes(root)))
+            if (census.code !== 0 || census.stopped || census.stdout.split('\n').some((line) => line.includes(root)))
                 cleanup = 'pending';
         }
         if (cleanup !== 'settled')
@@ -123,11 +158,19 @@ export async function captureArticle(request) {
         if (result.code !== 0 || object(summary).ok !== true)
             return upstream;
         const outputDirectory = object(summary).outputDirectory;
-        if (typeof outputDirectory !== 'string' || !outputDirectory.startsWith(output + '/') || await realpath(outputDirectory) !== outputDirectory)
+        if (typeof outputDirectory !== 'string' ||
+            !outputDirectory.startsWith(output + '/') ||
+            (await realpath(outputDirectory)) !== outputDirectory)
             return failure(requestId, 'integrity', 'verification');
         const helper = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './verify-helper.ts' : './verify-helper.js', import.meta.url));
         cleanup = 'pending';
-        const checked = await (request.runProcess ?? runOwned)(runtime.bun, [helper, runtime.root, outputDirectory], { cwd: root, env, signal: controller.signal, deadlineMs: Math.max(1, deadline - (Date.now() - started)), maxOutputBytes: limits.helperFrameBytes });
+        const checked = await (request.runProcess ?? runOwned)(runtime.bun, [helper, runtime.root, outputDirectory], {
+            cwd: root,
+            env,
+            signal: controller.signal,
+            deadlineMs: Math.max(1, deadline - (Date.now() - started)),
+            maxOutputBytes: limits.helperFrameBytes,
+        });
         cleanup = checked.cleanup;
         if (cleanup !== 'settled')
             return failure(requestId, 'cleanup-required', 'cleanup');
@@ -135,26 +178,42 @@ export async function captureArticle(request) {
             return failure(requestId, checked.stopped);
         if (checked.code !== 0)
             return failure(requestId, 'integrity', 'verification');
-        const capture = await normalizeBundle({ bundleRoot: outputDirectory, inspection: JSON.parse(checked.stdout), summary, requestId, sourceUrl: request.sourceUrl, wordcellVersion: runtime.pins.wordcell.version });
+        const capture = await normalizeBundle({
+            bundleRoot: outputDirectory,
+            inspection: JSON.parse(checked.stdout),
+            summary,
+            requestId,
+            sourceUrl: request.sourceUrl,
+            wordcellVersion: runtime.pins.wordcell.version,
+        });
         if (controller.signal.aborted)
             return failure(requestId, quota ? 'limit-exceeded' : 'cancelled');
-        await writeFile(join(root, 'ownership.json'), JSON.stringify({ schemaVersion: 1, requestId, state: 'verified' }), { mode: 0o600 });
+        await writeFile(join(root, 'ownership.json'), JSON.stringify({ schemaVersion: 1, requestId, state: 'verified' }), {
+            mode: 0o600,
+        });
         keep = true;
-        return { ok: true, capture, bundleRoot: outputDirectory, dispose: async () => { if (await settleCaptureRoot(root, requestId) === 'pending')
-                throw new CaptureCleanupError(); } };
+        return {
+            ok: true,
+            capture,
+            bundleRoot: outputDirectory,
+            dispose: async () => {
+                if ((await settleCaptureRoot(root, requestId)) === 'pending')
+                    throw new SpongeError('cleanup-required');
+            },
+        };
     }
     catch (error) {
         if (cleanup !== 'settled')
             return failure(requestId, 'cleanup-required', 'cleanup');
-        const code = (error instanceof Error && ['integrity', 'limit-exceeded', 'schema-newer'].includes(error.message) ? error.message : 'unclassified');
+        const raw = codeOf(error), code = raw === 'integrity' || raw === 'limit-exceeded' || raw === 'schema-newer' ? raw : 'unclassified';
         return failure(requestId, code, 'verification');
     }
     finally {
         clearInterval(monitor);
         while (checking)
-            await new Promise(r => setTimeout(r, 5));
+            await new Promise((r) => setTimeout(r, 5));
         signal?.removeEventListener('abort', abort);
-        if (!keep && cleanup === 'settled' && await settleCaptureRoot(root, requestId) === 'pending')
+        if (!keep && cleanup === 'settled' && (await settleCaptureRoot(root, requestId)) === 'pending')
             return failure(requestId, 'cleanup-required', 'cleanup');
     }
 }

package/dist/src/acquisition/cleanup.d.ts

@@ -1,6 +1,2 @@
-export declare class CaptureCleanupError extends Error {
-    readonly code = "cleanup-required";
-    constructor();
-}
 /** Cleanup failure retains ownership evidence and must not settle the queue attempt. */
 export declare function settleCaptureRoot(root: string, requestId: string): Promise<'settled' | 'pending'>;

package/dist/src/acquisition/cleanup.js

@@ -1,9 +1,5 @@
 import { rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-export class CaptureCleanupError extends Error {
-    code = 'cleanup-required';
-    constructor() { super('cleanup-required'); }
-}
 /** Cleanup failure retains ownership evidence and must not settle the queue attempt. */
 export async function settleCaptureRoot(root, requestId) {
     try {
@@ -14,7 +10,9 @@ export async function settleCaptureRoot(root, requestId) {
         try {
             await writeFile(join(root, 'ownership.json'), JSON.stringify({ schemaVersion: 1, requestId, state: 'cleanup-required' }), { mode: 0o600 });
         }
-        catch { /* Existing ownership record remains when directory access itself failed. */ }
+        catch {
+            /* Existing ownership record remains when directory access itself failed. */
+        }
         return 'pending';
     }
 }

package/dist/src/acquisition/errors.js

@@ -1,4 +1,15 @@
-const mappings = { 'unknown': 'unclassified', 'permission-required': 'grant-permission', 'auth-required': 'repair-auth', 'invalid-input': 'invalid-input', 'cancelled': 'cancelled', 'timeout': 'unavailable', 'transient': 'unavailable', 'unsupported': 'unsupported', 'cleanup-pending': 'cleanup-required', 'rate-limited': 'rate-limited' };
+const mappings = {
+    unknown: 'unclassified',
+    'permission-required': 'grant-permission',
+    'auth-required': 'repair-auth',
+    'invalid-input': 'invalid-input',
+    cancelled: 'cancelled',
+    timeout: 'unavailable',
+    transient: 'unavailable',
+    unsupported: 'unsupported',
+    'cleanup-pending': 'cleanup-required',
+    'rate-limited': 'rate-limited',
+};
 export const failure = (requestId, code, phase = 'acquisition', retryable = false) => ({ schemaVersion: 1, requestId, ok: false, code, phase, retryable });
 export function upstreamFailure(value, requestId) {
     const fallback = failure(requestId, 'unclassified');
@@ -11,7 +22,11 @@ export function upstreamFailure(value, requestId) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw))
         return fallback;
     const typed = raw;
-    if (Object.keys(typed).some(k => !['schemaVersion', 'code', 'retryable'].includes(k)) || typed.schemaVersion !== 1 || typeof typed.code !== 'string' || !Object.hasOwn(mappings, typed.code) || typeof typed.retryable !== 'boolean')
+    if (Object.keys(typed).some((k) => !['schemaVersion', 'code', 'retryable'].includes(k)) ||
+        typed.schemaVersion !== 1 ||
+        typeof typed.code !== 'string' ||
+        !Object.hasOwn(mappings, typed.code) ||
+        typeof typed.retryable !== 'boolean')
         return fallback;
     const code = mappings[typed.code];
     if (typed.retryable && !['timeout', 'transient', 'rate-limited'].includes(typed.code))

package/dist/src/acquisition/files.d.ts

@@ -1,4 +1,3 @@
-export declare const hash: (bytes: Uint8Array | string) => string;
 export declare function privateRoot(path: string): Promise<string>;
 export declare function readConfined(root: string, name: string, maxBytes: number): Promise<Buffer>;
 export declare function physicalBytes(root: string): Promise<number>;

package/dist/src/acquisition/files.js

@@ -1,31 +1,34 @@
 import { constants } from 'node:fs';
 import { open, lstat, realpath, readdir } from 'node:fs/promises';
 import { resolve, relative, isAbsolute, join } from 'node:path';
-import { createHash } from 'node:crypto';
-export const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+import { SpongeError } from '../errors.js';
 export async function privateRoot(path) {
     if (!isAbsolute(path))
-        throw Error('invalid-input');
+        throw new SpongeError('invalid-input');
     const canonical = await realpath(path), stat = await lstat(path);
-    if (canonical !== path || !stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0)
-        throw Error('invalid-input');
+    if (canonical !== path ||
+        !stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        stat.uid !== process.getuid?.() ||
+        (stat.mode & 0o077) !== 0)
+        throw new SpongeError('invalid-input');
     return canonical;
 }
 export async function readConfined(root, name, maxBytes) {
-    if (!name || isAbsolute(name) || name.includes('\\') || name.split('/').some(p => !p || p === '.' || p === '..'))
-        throw Error('integrity');
+    if (!name || isAbsolute(name) || name.includes('\\') || name.split('/').some((p) => !p || p === '.' || p === '..'))
+        throw new SpongeError('integrity');
     const path = resolve(root, name);
-    if (relative(root, path).startsWith('..') || await realpath(path) !== path)
-        throw Error('integrity');
+    if (relative(root, path).startsWith('..') || (await realpath(path)) !== path)
+        throw new SpongeError('integrity');
     const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
         const stat = await file.stat();
         if (!stat.isFile() || stat.size > maxBytes)
-            throw Error('limit-exceeded');
+            throw new SpongeError('limit-exceeded');
         const data = Buffer.alloc(stat.size + 1);
         const { bytesRead } = await file.read(data, 0, data.length, 0);
         if (bytesRead !== stat.size)
-            throw Error('integrity');
+            throw new SpongeError('integrity');
         return data.subarray(0, bytesRead);
     }
     finally {

package/dist/src/acquisition/index.d.ts

@@ -1,6 +1,5 @@
 export { captureArticle } from './capture.js';
 export type { CaptureConnection, CaptureRequest, CaptureOutcome } from './capture.js';
-export { provisionCapture, inspectCaptureRuntime, captureSetupPlan, CaptureSetupError } from './runtime.js';
-export type { CaptureRuntime, CapturePins, SetupPlan } from './runtime.js';
+export { provisionCapture, inspectCaptureRuntime, captureSetupPlan } from './runtime.js';
+export type { CaptureRuntime } from './runtime.js';
 export { defaultCapturePins } from './pins.js';
-export { CaptureCleanupError } from './cleanup.js';

package/dist/src/acquisition/index.js

@@ -1,4 +1,3 @@
 export { captureArticle } from './capture.js';
-export { provisionCapture, inspectCaptureRuntime, captureSetupPlan, CaptureSetupError } from './runtime.js';
+export { provisionCapture, inspectCaptureRuntime, captureSetupPlan } from './runtime.js';
 export { defaultCapturePins } from './pins.js';
-export { CaptureCleanupError } from './cleanup.js';