@sequenceholdings/artifact-studio 0.2.5 → 0.3.0

package/dist/next-dev.js

@@ -0,0 +1,267 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { deleteJson } from './api.js';
+import { createScrubbedChildEnv } from './child-environment.js';
+import { acquireDevLock } from './dev-lock.js';
+import { hashLinkedSources, rebuildLinkedDep, resolveLinkedDeps, syncLinkedDist } from './dev-link.js';
+import { readArtifactStudioSource } from './project.js';
+import { createNextChildEnv, validateNextProject } from './next-project.js';
+import { materializeNextPublicFonts } from './next-public-fonts-local.js';
+import { isTransientNextControlFailure, requestNextDevLease, renewNextDevLease, writeNextRuntimeFile } from './next-dev-control.js';
+import { openNextPreview, selectNextDevPort, startNextDevProcess } from './next-dev-process.js';
+import { connectLocalTunnel } from './tunnel/index.js';
+/** Shutdown never waits longer than this on Atlas; an unconfirmed session still expires with its lease. */
+const SESSION_REVOCATION_TIMEOUT_MS = 10_000;
+export async function runNextDevelopment({ root, manifest, projectId, baseUrl, environment, previewKey, port: requestedPort, links, getToken }) {
+    const { appRoot, nextBin } = await validateNextProject({ root, manifest, installed: true });
+    if (!nextBin)
+        throw new Error('Missing project-local Next.js executable. Run pnpm install.');
+    await materializeNextPublicFonts({ appRoot, fonts: manifest.build.public_fonts });
+    const port = await selectNextDevPort({ requested: requestedPort });
+    const source = await readArtifactStudioSource(root);
+    const initialManifest = await readFile(join(root, 'artifact.bundle.yml'), 'utf8');
+    let dependenciesHash = await nextDependencyHash({ root, appRoot });
+    const releaseLock = await acquireDevLock({ dir: root, previewKey });
+    const privateRoot = await mkdtemp(join(tmpdir(), 'seq-artifact-next-dev-'));
+    const runtimeFile = join(privateRoot, 'runtime.json');
+    const controller = new AbortController();
+    const onSignal = () => controller.abort();
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    let lease;
+    let child;
+    let status = 'starting';
+    let exitCode = 0;
+    const tasks = [];
+    let sessionMutation = Promise.resolve();
+    function serialSessionMutation(operation) {
+        const pending = sessionMutation.then(operation);
+        sessionMutation = pending.catch(() => { });
+        return pending;
+    }
+    try {
+        const linked = resolveLinkedDeps({ links, resolver: createRequire(join(appRoot, 'package.json')).resolve });
+        const linkedEnv = createScrubbedChildEnv({ homeDir: privateRoot });
+        let linkedHash;
+        const refreshLinked = async () => {
+            if (!linked.length)
+                return;
+            const hash = await hashLinkedSources(linked);
+            if (hash === linkedHash)
+                return;
+            for (const dep of linked) {
+                console.log(`[seq-studio] rebuilding linked ${dep.name}`);
+                await rebuildLinkedDep(dep, controller.signal, linkedEnv);
+                await syncLinkedDist(dep);
+            }
+            linkedHash = hash;
+            // Webpack observes source changes itself. Linked dependencies are copied
+            // into node_modules, which is excluded from its watcher, so restart after
+            // a completed package rebuild while retaining the same tunnel session.
+            if (child)
+                await child.stop();
+        };
+        await refreshLinked();
+        lease = await requestNextDevLease({ baseUrl, token: await getToken(), projectId, environment,
+            body: { manifest, sourceHash: source.sourceHash, previewKey }, signal: controller.signal,
+        });
+        await writeNextRuntimeFile({ path: runtimeFile, projectId, lease });
+        const env = createNextChildEnv({ homeDir: privateRoot, publicEnv: manifest.build.public_env, publicOrigin: lease.session.publicOrigin, egressHosts: manifest.server.egress, runtimeFile });
+        const startChild = () => startNextDevProcess({ appRoot, nextBin, port, env, signal: controller.signal,
+            onStatus: (value) => { status = value; },
+        });
+        child = startChild();
+        await child.ready;
+        console.log(`[seq-studio] Next.js running on loopback port ${port}; source stays on this machine.`);
+        console.log(`[seq-studio] owner-only Atlas preview: ${lease.session.previewUrl}`);
+        console.log('[seq-studio] Fast Refresh is active. Press Ctrl+C to stop and revoke the preview.');
+        const initialLease = lease;
+        let opened = false;
+        tasks.push(runTunnelConnections({
+            lease: initialLease, environment, port, signal: controller.signal,
+            refreshLease: (previous) => serialSessionMutation(async () => {
+                const renewed = await requestNextDevLease({ baseUrl, token: await getToken(), projectId, environment,
+                    sessionId: previous.session.id, body: { epoch: previous.tunnel.epoch, reconnect: true, status: 'reconnecting' },
+                    signal: controller.signal,
+                });
+                if (renewed.tunnel.epoch <= previous.tunnel.epoch || renewed.session.publicOrigin !== previous.session.publicOrigin || renewed.runtime.environment !== previous.runtime.environment) {
+                    throw new Error('Atlas returned a stale or changed tunnel lease. Start artifact dev again.');
+                }
+                await writeNextRuntimeFile({ path: runtimeFile, projectId, lease: renewed });
+                lease = renewed;
+                return renewed;
+            }), onStatus: (value) => { status = value; }, onConnected: () => {
+                if (!opened) {
+                    opened = true;
+                    openNextPreview(initialLease.session.previewUrl);
+                }
+            },
+        }));
+        tasks.push(runDevelopmentMaintenance({ signal: controller.signal, tick: () => serialSessionMutation(async () => {
+                if (!lease)
+                    return;
+                try {
+                    await renewNextDevLease({ baseUrl, token: await getToken(), projectId, lease, status, signal: controller.signal });
+                }
+                catch (error) {
+                    // Authorization/revocation failures stop immediately. Network failures
+                    // may recover only within the last server-authorized lease; the gateway
+                    // independently verifies expiry and permissions on incoming requests.
+                    if (!isTransientNextControlFailure(error) || Date.now() >= Date.parse(lease.session.expiresAt))
+                        throw error;
+                    console.warn('[seq-studio] Atlas is temporarily unavailable; retrying within the current preview lease.');
+                }
+            }), intervalMs: 30_000 }));
+        if (linked.length)
+            tasks.push(runDevelopmentMaintenance({ signal: controller.signal, tick: refreshLinked, intervalMs: 1500 }));
+        tasks.push(runDevelopmentMaintenance({ signal: controller.signal, intervalMs: 1500, tick: async () => {
+                if (await readFile(join(root, 'artifact.bundle.yml'), 'utf8') !== initialManifest) {
+                    throw new Error('artifact.bundle.yml changed. Restart artifact dev to authorize the updated runtime configuration and capabilities.');
+                }
+                const updated = await nextDependencyHash({ root, appRoot });
+                if (updated !== dependenciesHash) {
+                    await validateNextProject({ root, manifest, installed: true });
+                    dependenciesHash = updated;
+                    console.log('[seq-studio] Dependencies changed; restarting the local Next.js server.');
+                    await child?.stop();
+                }
+            } }));
+        tasks.push(superviseNextProcess({ initial: child, start: startChild, signal: controller.signal, onChild: (value) => { child = value; } }));
+        await Promise.race(tasks);
+    }
+    catch (error) {
+        if (!controller.signal.aborted) {
+            console.error(`[seq-studio] ${error instanceof Error ? error.message : String(error)}`);
+            exitCode = 1;
+        }
+    }
+    finally {
+        // Aborting cancels in-flight lease renewals and reconnects (they share controller.signal),
+        // so allSettled returns promptly; revocation below then gets its own bounded attempt.
+        controller.abort();
+        await child?.stop();
+        await Promise.allSettled(tasks);
+        if (lease) {
+            try {
+                await deleteJson({ baseUrl, token: await getToken(), path: `/api/artifact-studio/projects/${encodeURIComponent(projectId)}/next/dev-sessions/${encodeURIComponent(lease.session.id)}`,
+                    signal: AbortSignal.timeout(SESSION_REVOCATION_TIMEOUT_MS) });
+            }
+            catch {
+                console.warn('[seq-studio] Could not confirm session revocation. Its lease will expire; disconnect it in Atlas if needed.');
+            }
+        }
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+        releaseLock();
+        await rm(privateRoot, { recursive: true, force: true });
+    }
+    return exitCode;
+}
+async function nextDependencyHash({ root, appRoot }) {
+    const hash = createHash('sha256');
+    for (const path of [...new Set([join(root, 'package.json'), join(root, 'pnpm-lock.yaml'), join(appRoot, 'package.json')])]) {
+        hash.update(await readFile(path));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+async function superviseNextProcess({ initial, start, signal, onChild }) {
+    let current = initial;
+    let failures = 0;
+    while (!signal.aborted) {
+        const started = Date.now();
+        try {
+            await current.closed;
+        }
+        catch (error) {
+            if (signal.aborted)
+                return;
+            failures = Date.now() - started > 60_000 ? 1 : failures + 1;
+            if (failures > 3)
+                throw error;
+            console.warn('[seq-studio] Next.js stopped unexpectedly; restarting the local server.');
+        }
+        if (signal.aborted)
+            return;
+        try {
+            await delay(1000, undefined, { signal });
+        }
+        catch {
+            return;
+        }
+        current = start();
+        onChild(current);
+        // The process's closed promise handles failed startups on the next loop.
+        await current.ready.catch(() => { });
+    }
+}
+async function runDevelopmentMaintenance({ signal, tick, intervalMs }) {
+    while (!signal.aborted) {
+        try {
+            await delay(intervalMs, undefined, { signal });
+        }
+        catch {
+            return;
+        }
+        if (!signal.aborted)
+            await tick();
+    }
+}
+async function runTunnelConnections({ lease: initialLease, environment, port, refreshLease, signal, onStatus, onConnected }) {
+    let lease = initialLease;
+    let attempt = 0;
+    while (!signal.aborted) {
+        try {
+            const connection = await connectLocalTunnel({
+                url: lease.tunnel.url, token: lease.tunnel.token, sessionId: lease.session.id, epoch: lease.tunnel.epoch,
+                localPort: port, publicOrigin: lease.session.publicOrigin, signal, allowInsecureLoopback: environment === 'local',
+            });
+            attempt = 0;
+            onStatus('ready');
+            onConnected();
+            const closed = await connection.closed;
+            if (signal.aborted)
+                return;
+            if (closed.code === 1008 || closed.code === 4001 || closed.code === 4003) {
+                throw new Error('Atlas revoked or replaced this development session. Start artifact dev again.');
+            }
+            console.warn('[seq-studio] Preview tunnel disconnected; reconnecting without replaying requests.');
+        }
+        catch (error) {
+            if (signal.aborted)
+                return;
+            if (error instanceof Error && /revoked or replaced/.test(error.message))
+                throw error;
+            console.warn('[seq-studio] Preview tunnel unavailable; acquiring a fresh connection lease.');
+        }
+        onStatus('reconnecting');
+        attempt += 1;
+        try {
+            await delay(Math.min(1000 * 2 ** Math.min(attempt, 5), 30_000), undefined, { signal });
+        }
+        catch {
+            return;
+        }
+        let refreshed = false;
+        while (!signal.aborted && !refreshed) {
+            try {
+                lease = await refreshLease(lease);
+                refreshed = true;
+            }
+            catch (error) {
+                if (!isTransientNextControlFailure(error) || Date.now() >= Date.parse(lease.session.expiresAt))
+                    throw error;
+                try {
+                    await delay(5000, undefined, { signal });
+                }
+                catch {
+                    return;
+                }
+            }
+        }
+    }
+}

package/dist/next-image-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Policy for Next's managed image optimizer. The hosted network remains the
+ * authoritative egress boundary; this also prevents accidental local dev SSRF.
+ * It does not govern arbitrary application fetches or browser image elements.
+ */
+export declare function resolveArtifactNextImages({ images, egressHosts }: {
+    images: unknown;
+    egressHosts: readonly string[];
+}): Record<string, unknown>;

package/dist/next-image-config.js

@@ -0,0 +1,101 @@
+const MAX_IMAGE_RESPONSE_BYTES = 10 * 1024 * 1024;
+const PUBLIC_HOST = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const REMOTE_PATTERN_FIELDS = new Set(['protocol', 'hostname', 'port', 'pathname', 'search']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function publicHost(value) {
+    return typeof value === 'string' && !/[\s\u0000-\u001f\u007f]/.test(value) && PUBLIC_HOST.test(value) &&
+        !/(?:^|\.)(?:localhost|local|internal)$/.test(value);
+}
+/**
+ * Policy for Next's managed image optimizer. The hosted network remains the
+ * authoritative egress boundary; this also prevents accidental local dev SSRF.
+ * It does not govern arbitrary application fetches or browser image elements.
+ */
+export function resolveArtifactNextImages({ images, egressHosts }) {
+    if (images !== undefined && !isRecord(images))
+        throw new Error('Invalid Next images configuration');
+    if (!Array.isArray(egressHosts) || egressHosts.length > 64 || !egressHosts.every(publicHost)) {
+        throw new Error('Image optimization requires a valid exact-host Artifact server.egress policy');
+    }
+    const source = images ?? {};
+    assertManagedOptimizer(source);
+    const responseLimit = source.maximumResponseBody ?? MAX_IMAGE_RESPONSE_BYTES;
+    if (typeof responseLimit !== 'number' || !Number.isSafeInteger(responseLimit) ||
+        responseLimit < 1 || responseLimit > MAX_IMAGE_RESPONSE_BYTES) {
+        throw new Error('images.maximumResponseBody must be between 1 byte and 10 MiB');
+    }
+    const patterns = source.remotePatterns ?? [];
+    if (!Array.isArray(patterns) || patterns.length > 64)
+        throw new Error('images.remotePatterns must contain at most 64 explicit patterns');
+    return {
+        ...source,
+        remotePatterns: patterns.map((pattern, index) => resolveRemotePattern({ pattern, index, egressHosts })),
+        maximumRedirects: 0,
+        maximumResponseBody: responseLimit,
+        dangerouslyAllowLocalIP: false,
+        dangerouslyAllowSVG: false,
+    };
+}
+function assertManagedOptimizer(images) {
+    if ((images.loader !== undefined && images.loader !== 'default') ||
+        (images.loaderFile !== undefined && images.loaderFile !== '') ||
+        (images.unoptimized !== undefined && images.unoptimized !== false)) {
+        throw new Error('Artifact images must use the managed default optimizer; custom loaders and images.unoptimized are unsupported');
+    }
+    if (images.path !== undefined && images.path !== '/_next/image' && images.path !== '/_next/image/') {
+        throw new Error('Artifact images must use the managed /_next/image optimizer path');
+    }
+    if (images.domains !== undefined && (!Array.isArray(images.domains) || images.domains.length > 0)) {
+        throw new Error('Use exact HTTPS images.remotePatterns instead of the legacy images.domains setting');
+    }
+    if (images.dangerouslyAllowLocalIP === true || images.dangerouslyAllowSVG === true) {
+        throw new Error('Artifact images cannot enable dangerouslyAllowLocalIP or dangerouslyAllowSVG; use local public SVG files directly');
+    }
+    if (images.maximumRedirects !== undefined && images.maximumRedirects !== 0) {
+        // Next does not re-check redirected image destinations against remotePatterns.
+        throw new Error('images.maximumRedirects must be 0; declare and use the final approved HTTPS image URL');
+    }
+}
+function resolveRemotePattern({ pattern, index, egressHosts }) {
+    const label = `images.remotePatterns[${index}]`;
+    const value = remotePatternFields({ pattern, label });
+    if (value.protocol !== 'https' || !publicHost(value.hostname) ||
+        (value.port !== undefined && value.port !== '' && value.port !== '443')) {
+        throw new Error(`${label} requires an exact public HTTPS hostname on port 443; wildcard, IP and local hosts are unsupported`);
+    }
+    if (!egressHosts.includes(value.hostname)) {
+        throw new Error(`${label} hostname must be declared in server.egress; run seq-studio artifact dev/build to supply the application's image policy`);
+    }
+    const pathname = remotePatternPathname({ pathname: value.pathname ?? '/**', label });
+    const search = remotePatternSearch({ search: value.search, label });
+    return { protocol: 'https', hostname: value.hostname, port: '', pathname, ...(search === undefined ? {} : { search }) };
+}
+/** A URL pattern is reduced to its matchable fields; object patterns may carry only those fields. */
+function remotePatternFields({ pattern, label }) {
+    if (pattern instanceof URL) {
+        if (pattern.username || pattern.password || pattern.hash)
+            throw new Error(`${label} cannot contain URL credentials or fragments`);
+        return { protocol: pattern.protocol.replace(/:$/, ''), hostname: pattern.hostname,
+            port: pattern.port, pathname: pattern.pathname, search: pattern.search };
+    }
+    if (!isRecord(pattern) || Object.keys(pattern).some((key) => !REMOTE_PATTERN_FIELDS.has(key))) {
+        throw new Error(`${label} must be a URL or a supported remote pattern object`);
+    }
+    return pattern;
+}
+function remotePatternPathname({ pathname, label }) {
+    if (typeof pathname !== 'string' || !pathname.startsWith('/') || pathname.length > 2048 || /[\\\u0000-\u001f\u007f]/.test(pathname)) {
+        throw new Error(`${label}.pathname must be an absolute image path pattern`);
+    }
+    return pathname;
+}
+function remotePatternSearch({ search, label }) {
+    if (search === undefined)
+        return undefined;
+    if (typeof search !== 'string' || (search !== '' && !search.startsWith('?')) || search.length > 2048 || /[\u0000-\u001f\u007f]/.test(search)) {
+        throw new Error(`${label}.search must be empty or an exact query string beginning with ?`);
+    }
+    return search;
+}

package/dist/next-project.d.ts

@@ -0,0 +1,22 @@
+import { type ArtifactStudioNextManifest } from './manifest.js';
+export declare function validateNextProject({ root, manifest, installed, nodeVersion }: {
+    root: string;
+    manifest: ArtifactStudioNextManifest;
+    installed: boolean;
+    nodeVersion?: string;
+}): Promise<{
+    appRoot: string;
+    nextBin?: string;
+}>;
+export declare function validateNextPublicOrigin({ value, environment }: {
+    value: string;
+    environment: string;
+}): string;
+export declare function createNextChildEnv({ homeDir, publicEnv, publicOrigin, egressHosts, runtimeFile, source }: {
+    homeDir: string;
+    publicEnv: Record<string, string>;
+    publicOrigin: string;
+    egressHosts?: readonly string[];
+    runtimeFile?: string;
+    source?: NodeJS.ProcessEnv;
+}): NodeJS.ProcessEnv;

package/dist/next-project.js

@@ -0,0 +1,64 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { join, resolve } from 'node:path';
+import { z } from 'zod';
+import { createScrubbedChildEnv } from './child-environment.js';
+import { ARTIFACT_NEXT_APPROVED_PACKAGES } from './manifest.js';
+const packageSchema = z.object({
+    dependencies: z.record(z.string(), z.string()).default({}),
+    devDependencies: z.record(z.string(), z.string()).default({}),
+});
+export async function validateNextProject({ root, manifest, installed, nodeVersion = process.versions.node }) {
+    const appRoot = resolve(root, manifest.artifact.app_root);
+    const pkg = packageSchema.parse(JSON.parse(await readFile(join(appRoot, 'package.json'), 'utf8')));
+    const dependencies = { ...pkg.devDependencies, ...pkg.dependencies };
+    for (const [dependency, approved] of Object.entries(ARTIFACT_NEXT_APPROVED_PACKAGES)) {
+        if (dependencies[dependency] !== approved) {
+            throw new Error(`The application must pin its own approved ${dependency}@${approved} dependency in package.json. Platform React aliases and version ranges are not used for Next.js 16.3.`);
+        }
+    }
+    if (!existsSync(join(appRoot, 'app')) && !existsSync(join(appRoot, 'src', 'app'))) {
+        throw new Error('Next.js artifacts require an App Router app/ or src/app/ directory.');
+    }
+    if (existsSync(join(appRoot, 'pages')) || existsSync(join(appRoot, 'src', 'pages'))) {
+        throw new Error('Artifact Studio supports App Router applications; move Pages Router routes into app/.');
+    }
+    if (!installed)
+        return { appRoot };
+    if (!nodeVersion.startsWith('24.'))
+        throw new Error(`Next.js artifact development requires Node.js 24 (current: ${nodeVersion}).`);
+    // Do not silently resolve a parent's or the CLI's copy of Next/React.
+    for (const [dependency, approved] of Object.entries(ARTIFACT_NEXT_APPROVED_PACKAGES)) {
+        const packagePath = join(appRoot, 'node_modules', dependency, 'package.json');
+        if (!existsSync(packagePath))
+            throw new Error(`Missing local ${dependency}. Run pnpm install in ${appRoot}.`);
+        const parsed = z.object({ version: z.string() }).parse(JSON.parse(await readFile(packagePath, 'utf8')));
+        if (parsed.version !== approved)
+            throw new Error(`Unsupported installed ${dependency}@${parsed.version}; approved version is ${approved}. Run pnpm install with the approved toolchain.`);
+    }
+    const nextBin = createRequire(join(appRoot, 'package.json')).resolve('next/dist/bin/next');
+    return { appRoot, nextBin };
+}
+export function validateNextPublicOrigin({ value, environment }) {
+    const url = new URL(value);
+    const local = environment === 'local' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
+    if ((url.protocol !== 'https:' && !(local && url.protocol === 'http:')) || url.username || url.password || url.search || url.hash || url.pathname !== '/') {
+        throw new Error('Atlas returned an invalid application origin; an exact credential-free HTTPS origin is required.');
+    }
+    return url.origin;
+}
+export function createNextChildEnv({ homeDir, publicEnv, publicOrigin, egressHosts = [], runtimeFile, source }) {
+    for (const name of Object.keys(publicEnv)) {
+        if (!/^NEXT_PUBLIC_[A-Z0-9_]+$/.test(name))
+            throw new Error('Build environment names must start with NEXT_PUBLIC_.');
+    }
+    return createScrubbedChildEnv({ homeDir, source, additionalEnv: {
+            ...publicEnv,
+            NODE_ENV: 'development',
+            NEXT_TELEMETRY_DISABLED: '1',
+            ARTIFACT_STUDIO_DEV_ORIGIN: publicOrigin,
+            ARTIFACT_NEXT_ALLOWED_EGRESS: JSON.stringify(egressHosts),
+            ...(runtimeFile ? { SEQUENCE_ARTIFACT_RUNTIME_FILE: runtimeFile } : {}),
+        } });
+}

package/dist/next-public-fonts-local.d.ts

@@ -0,0 +1,7 @@
+import { type ArtifactNextPublicFont } from './manifest-next.js';
+/** Materializes only declared files; an existing unmatching file is never replaced. */
+export declare function materializeNextPublicFonts({ appRoot, fonts, fetcher }: {
+    appRoot: string;
+    fonts: readonly ArtifactNextPublicFont[];
+    fetcher?: typeof fetch;
+}): Promise<void>;

package/dist/next-public-fonts-local.js

@@ -0,0 +1,64 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { artifactNextBuildConfigSchema } from './manifest-next.js';
+import { fetchNextPublicFont, NEXT_PUBLIC_FONT_MAX_BYTES, NEXT_PUBLIC_FONTS_MAX_BYTES, validateNextPublicFontBytes } from './next-public-fonts.js';
+/** Materializes only declared files; an existing unmatching file is never replaced. */
+export async function materializeNextPublicFonts({ appRoot, fonts, fetcher }) {
+    artifactNextBuildConfigSchema.parse({ public_fonts: fonts });
+    if (!fonts.length)
+        return;
+    const canonicalRoot = await realpath(appRoot);
+    for (const path of ['public', 'public/fonts']) {
+        const directory = join(canonicalRoot, path);
+        await mkdir(directory).catch((error) => { if (!hasCode(error, 'EEXIST'))
+            throw error; });
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink() || await realpath(directory) !== directory)
+            throw new Error('Declared public font directories cannot use symlinks');
+    }
+    let total = 0;
+    for (const font of fonts) {
+        const path = join(canonicalRoot, font.path);
+        const existing = await readExistingFont(path);
+        const bytes = existing ?? await fetchNextPublicFont({ font, fetcher });
+        validateNextPublicFontBytes({ font, bytes });
+        total += bytes.length;
+        if (total > NEXT_PUBLIC_FONTS_MAX_BYTES)
+            throw new Error('Declared public fonts exceed 8 MiB combined');
+        if (!existing) {
+            const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+            try {
+                await handle.writeFile(bytes);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+    }
+}
+async function readExistingFont(path) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW).catch((error) => {
+        if (hasCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    });
+    if (!handle)
+        return undefined;
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > NEXT_PUBLIC_FONT_MAX_BYTES)
+            throw new Error('Existing public font must be a regular file under 2 MiB without hardlinks');
+        const bytes = Buffer.alloc(stat.size + 1);
+        const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
+        if (bytesRead !== stat.size)
+            throw new Error('Public font changed while reading; retry development startup');
+        return bytes.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function hasCode(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}

package/dist/next-public-fonts.d.ts

@@ -0,0 +1,13 @@
+import { type ArtifactNextPublicFont } from './manifest-next.js';
+export declare const NEXT_PUBLIC_FONT_MAX_BYTES: number;
+export declare const NEXT_PUBLIC_FONTS_MAX_BYTES: number;
+/** Format and digest checks apply equally to committed files and fetched inputs. */
+export declare function validateNextPublicFontBytes({ font, bytes }: {
+    font: ArtifactNextPublicFont;
+    bytes: Buffer;
+}): void;
+/** No author headers, fetch options, alternate host, redirect, or code execution. */
+export declare function fetchNextPublicFont({ font, fetcher }: {
+    font: ArtifactNextPublicFont;
+    fetcher?: typeof fetch;
+}): Promise<Buffer>;

package/dist/next-public-fonts.js

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+import { artifactNextPublicFontSchema } from './manifest-next.js';
+export const NEXT_PUBLIC_FONT_MAX_BYTES = 2 * 1024 * 1024;
+export const NEXT_PUBLIC_FONTS_MAX_BYTES = 8 * 1024 * 1024;
+/** Format and digest checks apply equally to committed files and fetched inputs. */
+export function validateNextPublicFontBytes({ font, bytes }) {
+    artifactNextPublicFontSchema.parse(font);
+    if (bytes.length > NEXT_PUBLIC_FONT_MAX_BYTES)
+        throw new Error(`Public font ${font.path} exceeds 2 MiB`);
+    if (bytes.length < 48 || bytes.toString('ascii', 0, 4) !== 'wOF2' || bytes.readUInt32BE(8) !== bytes.length || bytes.readUInt16BE(12) === 0 || bytes.readUInt16BE(14) !== 0) {
+        throw new Error(`Public font ${font.path} is not a valid WOFF2 input`);
+    }
+    if (createHash('sha256').update(bytes).digest('hex') !== font.sha256)
+        throw new Error(`Public font ${font.path} does not match its reviewed SHA-256 pin`);
+}
+/** No author headers, fetch options, alternate host, redirect, or code execution. */
+export async function fetchNextPublicFont({ font, fetcher = fetch }) {
+    artifactNextPublicFontSchema.parse(font);
+    const response = await fetcher(font.url, { redirect: 'error', credentials: 'omit', signal: AbortSignal.timeout(15_000), headers: { accept: 'font/woff2,application/octet-stream' } });
+    if (response.status !== 200 || !response.body) {
+        await response.body?.cancel();
+        throw new Error(`Public font retrieval returned ${response.status}; no redirects or alternate sources are allowed`);
+    }
+    const length = response.headers.get('content-length');
+    if (length && (!/^\d+$/.test(length) || Number(length) > NEXT_PUBLIC_FONT_MAX_BYTES)) {
+        await response.body.cancel();
+        throw new Error(`Public font ${font.path} exceeds 2 MiB`);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.length;
+            if (total > NEXT_PUBLIC_FONT_MAX_BYTES)
+                throw new Error(`Public font ${font.path} exceeds 2 MiB`);
+            chunks.push(Buffer.from(value));
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    const bytes = Buffer.concat(chunks, total);
+    validateNextPublicFontBytes({ font, bytes });
+    return bytes;
+}

package/dist/next-source-hash.d.ts

@@ -0,0 +1,14 @@
+export interface HashableNextSourceFile {
+    path: string;
+    content: string;
+    encoding: 'utf8' | 'base64';
+}
+/**
+ * Identity of validated Next source bytes, independent of their wire encoding.
+ * Callers must first validate canonical, unique paths and encoded contents.
+ * Manifest identity comes from artifact.bundle.yml bytes in the source files,
+ * not a parsed object whose schema defaults can change across CLI versions.
+ */
+export declare function computeNextSourceHash({ files }: {
+    files: readonly HashableNextSourceFile[];
+}): string;

package/dist/next-source-hash.js

@@ -0,0 +1,18 @@
+import { createHash } from 'node:crypto';
+/**
+ * Identity of validated Next source bytes, independent of their wire encoding.
+ * Callers must first validate canonical, unique paths and encoded contents.
+ * Manifest identity comes from artifact.bundle.yml bytes in the source files,
+ * not a parsed object whose schema defaults can change across CLI versions.
+ */
+export function computeNextSourceHash({ files }) {
+    const digest = createHash('sha256');
+    // Explicit code-unit ordering is consistent across operating-system locales.
+    const ordered = [...files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    for (const file of ordered) {
+        const bytes = Buffer.from(file.content, file.encoding);
+        digest.update(`${Buffer.byteLength(file.path)}:${file.path}:${bytes.length}:`);
+        digest.update(bytes);
+    }
+    return digest.digest('hex');
+}