@sequenceholdings/artifact-studio 0.2.5 → 0.3.0

package/dist/next-source.d.ts

@@ -0,0 +1,35 @@
+export interface NextSourceLimits {
+    maxFiles: number;
+    maxFileBytes: number;
+    maxTotalBytes: number;
+}
+export declare const NEXT_SOURCE_LIMITS: Readonly<NextSourceLimits>;
+export interface NextSourceFile {
+    path: string;
+    content: string;
+    encoding: 'base64';
+    contentType: string;
+    sha256: string;
+    sizeBytes: number;
+}
+export interface NextSourceSnapshot<Manifest, Provenance = never> {
+    root: string;
+    manifest: Manifest;
+    files: NextSourceFile[];
+    sourceHash: string;
+    totalSizeBytes: number;
+    ignorePatterns: string[];
+    provenance?: Provenance;
+}
+/**
+ * Captures raw source, including binary assets. The manifest is returned for
+ * callers; source identity includes the raw artifact.bundle.yml file bytes.
+ * This is an upload payload, not attested build provenance. Atlas must validate
+ * it again before materializing source in an isolated build sandbox.
+ */
+export declare function readNextSourceSnapshot<Manifest, Provenance = never>({ root: inputRoot, manifest, provenance, limits: overrides, }: {
+    root: string;
+    manifest: Manifest;
+    provenance?: Provenance;
+    limits?: Partial<NextSourceLimits>;
+}): Promise<NextSourceSnapshot<Manifest, Provenance>>;

package/dist/next-source.js

@@ -0,0 +1,155 @@
+import { constants } from 'node:fs';
+import { lstat, open, readdir, realpath } from 'node:fs/promises';
+import { extname, join, resolve } from 'node:path';
+import { ARTIFACT_IGNORE_FILE, isArtifactIgnoredPath, parseArtifactIgnore } from './artifact-ignore.js';
+import { sha256Hex } from './hash.js';
+import { computeNextSourceHash } from './next-source-hash.js';
+import { ARTIFACT_NEXT_SOURCE_LIMITS, artifactSourcePathSchema, isExcludedArtifactSourcePath, } from './runtime-contracts.js';
+export const NEXT_SOURCE_LIMITS = ARTIFACT_NEXT_SOURCE_LIMITS;
+/**
+ * Captures raw source, including binary assets. The manifest is returned for
+ * callers; source identity includes the raw artifact.bundle.yml file bytes.
+ * This is an upload payload, not attested build provenance. Atlas must validate
+ * it again before materializing source in an isolated build sandbox.
+ */
+export async function readNextSourceSnapshot({ root: inputRoot, manifest, provenance, limits: overrides = {}, }) {
+    const limits = { ...NEXT_SOURCE_LIMITS, ...overrides };
+    const limitNames = ['maxFiles', 'maxFileBytes', 'maxTotalBytes'];
+    for (const name of limitNames) {
+        const value = limits[name];
+        if (!Number.isSafeInteger(value) || value <= 0 || value > NEXT_SOURCE_LIMITS[name]) {
+            throw new Error(`Invalid source limit: ${name}; overrides may only lower the platform limit`);
+        }
+    }
+    const input = resolve(inputRoot);
+    const rootStat = await lstat(input);
+    if (rootStat.isSymbolicLink())
+        throw new Error('Source root cannot be a symbolic link');
+    if (!rootStat.isDirectory())
+        throw new Error('Source root must be a directory');
+    const root = await realpath(input);
+    const ignore = await readIgnorePatterns({ root, limits });
+    const ignorePatterns = ignore.patterns;
+    const files = [];
+    let totalSizeBytes = 0;
+    let visited = 0;
+    async function walk(directory, prefix = '') {
+        const before = await lstat(directory);
+        if (!before.isDirectory() || before.isSymbolicLink() || await realpath(directory) !== directory) {
+            throw new Error(`Source directory changed or is a symbolic link: ${prefix || '.'}`);
+        }
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            // Excluded trees may contain platform-controlled links (node_modules).
+            // Do not inspect or traverse them, and never include them in the payload.
+            if (isExcludedArtifactSourcePath({ path: entry.name }))
+                continue;
+            if (++visited > limits.maxFiles * 4)
+                throw new Error('Source directory entry count exceeds limit');
+            const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+            validateCanonicalPath(path);
+            if (isArtifactIgnoredPath(path, ignorePatterns))
+                continue;
+            const absolute = join(directory, entry.name);
+            if (entry.isSymbolicLink())
+                throw new Error(`Source symbolic link is not allowed: ${path}`);
+            if (entry.isDirectory()) {
+                await walk(absolute, path);
+                continue;
+            }
+            if (!entry.isFile())
+                throw new Error(`Source path must be a regular file: ${path}`);
+            await capture({ absolute, path });
+        }
+        const after = await lstat(directory);
+        if (after.isSymbolicLink() || before.dev !== after.dev || before.ino !== after.ino || before.mtimeMs !== after.mtimeMs) {
+            throw new Error(`Source directory changed while capturing snapshot: ${prefix || '.'}; retry the build`);
+        }
+    }
+    async function capture({ absolute, path }) {
+        if (files.length >= limits.maxFiles)
+            throw new Error(`Source file count exceeds limit (${limits.maxFiles})`);
+        const bytes = await readBoundedFile({ absolute, path, limits, remaining: limits.maxTotalBytes - totalSizeBytes });
+        if (path === ARTIFACT_IGNORE_FILE && sha256Hex(bytes) !== ignore.sha256) {
+            throw new Error('.artifactignore changed while capturing snapshot; retry the build');
+        }
+        files.push({ path, content: bytes.toString('base64'), encoding: 'base64',
+            contentType: inferContentType(path), sha256: sha256Hex(bytes), sizeBytes: bytes.length });
+        totalSizeBytes += bytes.length;
+    }
+    await walk(root);
+    for (const required of ['artifact.bundle.yml', 'package.json', 'pnpm-lock.yaml']) {
+        if (!files.some((file) => file.path === required)) {
+            throw new Error(`Next.js builds require ${required} at the source root; it cannot be excluded by .artifactignore`);
+        }
+    }
+    files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    return { root, manifest, files, sourceHash: computeNextSourceHash({ files }), totalSizeBytes, ignorePatterns,
+        ...(provenance === undefined ? {} : { provenance }) };
+}
+function validateCanonicalPath(path) {
+    if (path.trim() !== path || !artifactSourcePathSchema.safeParse(path).success) {
+        throw new Error(`Source path must be a canonical relative POSIX path: ${JSON.stringify(path)}`);
+    }
+}
+async function readIgnorePatterns({ root, limits }) {
+    const absolute = join(root, ARTIFACT_IGNORE_FILE);
+    try {
+        const bytes = await readBoundedFile({ absolute, path: ARTIFACT_IGNORE_FILE, limits, remaining: limits.maxTotalBytes });
+        return { patterns: parseArtifactIgnore(bytes.toString('utf8')), sha256: sha256Hex(bytes) };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return { patterns: [] };
+        throw error;
+    }
+}
+async function readBoundedFile({ absolute, path, limits, remaining }) {
+    const expected = await lstat(absolute);
+    if (expected.isSymbolicLink())
+        throw new Error(`Source symbolic link is not allowed: ${path}`);
+    if (!expected.isFile())
+        throw new Error(`Source path must be a regular file: ${path}`);
+    if (expected.nlink > 1)
+        throw new Error(`Source hard link is not allowed: ${path}`);
+    if (expected.size > limits.maxFileBytes)
+        throw new Error(`Source file exceeds byte limit: ${path}`);
+    if (expected.size > remaining)
+        throw new Error(`Source total bytes exceed limit (${limits.maxTotalBytes})`);
+    const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.dev !== expected.dev || before.ino !== expected.ino || before.size !== expected.size) {
+            throw new Error(`Source file changed before capture: ${path}; retry the build`);
+        }
+        // A growing file cannot bypass the pre-read limit or allocate unbounded memory.
+        const bytes = Buffer.alloc(before.size + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const read = await handle.read(bytes, length, bytes.length - length, length);
+            if (read.bytesRead === 0)
+                break;
+            length += read.bytesRead;
+        }
+        const after = await handle.stat();
+        const current = await lstat(absolute);
+        if (length !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs ||
+            before.ctimeMs !== after.ctimeMs || current.isSymbolicLink() || current.dev !== after.dev || current.ino !== after.ino) {
+            throw new Error(`Source file changed while capturing snapshot: ${path}; retry the build`);
+        }
+        return bytes.subarray(0, length);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function inferContentType(path) {
+    const types = {
+        '.ts': 'text/typescript', '.tsx': 'text/typescript', '.js': 'text/javascript', '.jsx': 'text/javascript',
+        '.mjs': 'text/javascript', '.cjs': 'text/javascript', '.json': 'application/json', '.css': 'text/css',
+        '.html': 'text/html', '.md': 'text/markdown', '.yml': 'text/yaml', '.yaml': 'text/yaml', '.svg': 'image/svg+xml',
+        '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif',
+        '.ico': 'image/x-icon', '.avif': 'image/avif', '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf',
+        '.otf': 'font/otf', '.txt': 'text/plain', '.wasm': 'application/wasm',
+    };
+    return types[extname(path).toLowerCase()] ?? 'application/octet-stream';
+}

package/dist/next.d.ts

@@ -0,0 +1,9 @@
+export { createNextArtifactBridge } from './next/bridge.js';
+export type { NextArtifactBridge, NextArtifactBridgeOptions, NextArtifactBridgeSnapshot } from './next/bridge.js';
+export { createNextArtifactThemeApplier } from './next/theme.js';
+export { installNextArtifactBrowserIntegration } from './next/browser.js';
+export { NEXT_ARTIFACT_BRIDGE_TYPE, NEXT_ARTIFACT_BRIDGE_VERSION, createNextArtifactBridgeEnvelope, parseNextArtifactBridgeEnvelope, validateNextArtifactBootstrap, isNextArtifactRelativePath, nextArtifactInitialContextSchema, nextArtifactThemeSchema, nextArtifactLatticeContextSchema, } from './next/protocol.js';
+export type { NextArtifactBridgeBootstrap, NextArtifactBridgeEnvelope, NextArtifactInitialContext, NextArtifactTheme, NextArtifactRuntimeLog } from './next/protocol.js';
+export type { NextArtifactMessageEvent, NextArtifactMessageTransport } from './next/transport.js';
+export type { NextArtifactBridgeRequest } from './next/requests.js';
+export type { NextArtifactStreamRequest } from './next/streams.js';

package/dist/next.js

@@ -0,0 +1,5 @@
+'use client';
+export { createNextArtifactBridge } from './next/bridge.js';
+export { createNextArtifactThemeApplier } from './next/theme.js';
+export { installNextArtifactBrowserIntegration } from './next/browser.js';
+export { NEXT_ARTIFACT_BRIDGE_TYPE, NEXT_ARTIFACT_BRIDGE_VERSION, createNextArtifactBridgeEnvelope, parseNextArtifactBridgeEnvelope, validateNextArtifactBootstrap, isNextArtifactRelativePath, nextArtifactInitialContextSchema, nextArtifactThemeSchema, nextArtifactLatticeContextSchema, } from './next/protocol.js';

package/dist/project.d.ts

@@ -3,6 +3,8 @@ export interface ArtifactStudioSourceFile {
     path: string;
     content: string;
     contentType: string;
+    /** Next source snapshots preserve binary assets; static sources remain UTF-8. */
+    encoding?: 'utf8' | 'base64';
 }
 export interface ArtifactStudioSource {
     root: string;
@@ -13,5 +15,6 @@ export interface ArtifactStudioSource {
     ignorePatterns: string[];
 }
 export declare function hasArtifactStudioManifest(rootDir: string): boolean;
+export declare function readArtifactStudioManifest(rootDir: string): Promise<ArtifactStudioManifest>;
 export declare function readArtifactStudioSource(rootDir: string): Promise<ArtifactStudioSource>;
 export declare function loadArtifactIgnorePatterns(root: string): Promise<string[]>;

package/dist/project.js

@@ -4,7 +4,8 @@ import { join, relative, resolve } from 'node:path';
 import yaml from 'js-yaml';
 import { ARTIFACT_IGNORE_FILE, isArtifactIgnoredPath, parseArtifactIgnore, } from './artifact-ignore.js';
 import { computeSourceHash } from './hash.js';
-import { parseArtifactStudioManifest } from './manifest.js';
+import { isNextArtifactManifest, parseArtifactStudioManifest } from './manifest.js';
+import { readNextSourceSnapshot } from './next-source.js';
 import { normalizeArtifactPath } from './paths.js';
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', '.next', '.artifact-studio']);
 const TEXT_EXTENSIONS = new Set([
@@ -13,10 +14,17 @@ const TEXT_EXTENSIONS = new Set([
 export function hasArtifactStudioManifest(rootDir) {
     return existsSync(join(resolve(rootDir), 'artifact.bundle.yml'));
 }
+export async function readArtifactStudioManifest(rootDir) {
+    return parseArtifactStudioManifest(yaml.load(await readFile(join(resolve(rootDir), 'artifact.bundle.yml'), 'utf8')));
+}
 export async function readArtifactStudioSource(rootDir) {
     const root = resolve(rootDir);
     const rawManifest = yaml.load(await readFile(join(root, 'artifact.bundle.yml'), 'utf8'));
     const manifest = parseArtifactStudioManifest(rawManifest);
+    if (isNextArtifactManifest(manifest)) {
+        const snapshot = await readNextSourceSnapshot({ root, manifest: rawManifest });
+        return { ...snapshot, manifest };
+    }
     const ignorePatterns = await loadArtifactIgnorePatterns(root);
     const files = await collectSourceFiles(root, ignorePatterns);
     if (!files.some((file) => file.path === manifest.artifact.entrypoint)) {

package/dist/runtime-contracts.d.ts

@@ -0,0 +1,229 @@
+import { z } from 'zod';
+export { resolveArtifactNextImages } from './next-image-config.js';
+/** Shared by local collection, repository collection and the bounded source-upload API. */
+export declare const ARTIFACT_NEXT_SOURCE_LIMITS: Readonly<{
+    maxFiles: 2000;
+    maxFileBytes: number;
+    maxTotalBytes: number;
+}>;
+export declare const artifactSha256DigestSchema: z.ZodString;
+/** Immutable Next deploymentId from compiled output; distinct from the Atlas activation ID. */
+export declare const artifactNextFrameworkBuildIdSchema: z.ZodString;
+/** Shared upload exclusion policy. Content scanning and filesystem containment remain separate checks. */
+export declare function isExcludedArtifactSourcePath({ path }: {
+    path: string;
+}): boolean;
+/** POSIX source paths only; filesystem readers must additionally reject symlink escapes. */
+export declare const artifactSourcePathSchema: z.ZodString;
+/** An exact browser origin, not a URL prefix or an allowlist wildcard. */
+export declare const artifactRuntimeOriginSchema: z.ZodString;
+/** Metadata points to an immutable snapshot; file bytes travel through the source-upload API. */
+export declare const artifactNextBuildInputSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    framework: z.ZodLiteral<"nextjs">;
+    projectId: z.ZodString;
+    source: z.ZodObject<{
+        snapshotId: z.ZodString;
+        sha256: z.ZodString;
+        git: z.ZodObject<{
+            repositoryId: z.ZodString;
+            commitSha: z.ZodString;
+        }, z.core.$strict>;
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+            sizeBytes: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    lockfile: z.ZodObject<{
+        path: z.ZodLiteral<"pnpm-lock.yaml">;
+        sha256: z.ZodString;
+    }, z.core.$strict>;
+    toolchain: z.ZodObject<{
+        node: z.ZodString;
+        next: z.ZodString;
+        react: z.ZodString;
+        packageManager: z.ZodObject<{
+            name: z.ZodLiteral<"pnpm">;
+            version: z.ZodString;
+        }, z.core.$strict>;
+        builderImageDigest: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const artifactDeploymentOutputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"static">;
+    bundle: z.ZodObject<{
+        objectId: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"next-server">;
+    frameworkBuildId: z.ZodString;
+    imageRef: z.ZodString;
+    assets: z.ZodObject<{
+        objectId: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>;
+    buildInputSha256: z.ZodString;
+}, z.core.$strict>], "kind">;
+export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"queued">;
+    id: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    kind: z.ZodEnum<{
+        preview: "preview";
+        build: "build";
+        deploy: "deploy";
+        rollback: "rollback";
+        suspend: "suspend";
+        delete: "delete";
+    }>;
+    deploymentId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"running">;
+    progress: z.ZodOptional<z.ZodObject<{
+        stage: z.ZodString;
+        percent: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    id: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    kind: z.ZodEnum<{
+        preview: "preview";
+        build: "build";
+        deploy: "deploy";
+        rollback: "rollback";
+        suspend: "suspend";
+        delete: "delete";
+    }>;
+    deploymentId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"succeeded">;
+    completedAt: z.ZodISODateTime;
+    id: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    kind: z.ZodEnum<{
+        preview: "preview";
+        build: "build";
+        deploy: "deploy";
+        rollback: "rollback";
+        suspend: "suspend";
+        delete: "delete";
+    }>;
+    deploymentId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"failed">;
+    completedAt: z.ZodISODateTime;
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    kind: z.ZodEnum<{
+        preview: "preview";
+        build: "build";
+        deploy: "deploy";
+        rollback: "rollback";
+        suspend: "suspend";
+        delete: "delete";
+    }>;
+    deploymentId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"cancelled">;
+    completedAt: z.ZodISODateTime;
+    id: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    kind: z.ZodEnum<{
+        preview: "preview";
+        build: "build";
+        deploy: "deploy";
+        rollback: "rollback";
+        suspend: "suspend";
+        delete: "delete";
+    }>;
+    deploymentId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>], "status">;
+/** Runtime bootstrap is ephemeral. Do not persist bootstrap URLs in deployment history. */
+export declare const artifactRuntimeSessionSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    mode: z.ZodEnum<{
+        preview: "preview";
+        published: "published";
+        local: "local";
+    }>;
+    origin: z.ZodString;
+    parentOrigin: z.ZodString;
+    bootstrapUrl: z.ZodURL;
+    bridge: z.ZodObject<{
+        protocolVersion: z.ZodLiteral<1>;
+        channelId: z.ZodString;
+    }, z.core.$strict>;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strict>;
+/** Public session metadata contains no tunnel bearer, local credentials or managed secrets. */
+export declare const artifactLocalDevSessionSchema: z.ZodObject<{
+    id: z.ZodString;
+    ownerId: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    origin: z.ZodString;
+    sourceRevision: z.ZodOptional<z.ZodString>;
+    revision: z.ZodNumber;
+    state: z.ZodEnum<{
+        failed: "failed";
+        starting: "starting";
+        compiling: "compiling";
+        ready: "ready";
+        reconnecting: "reconnecting";
+        offline: "offline";
+        revoked: "revoked";
+        expired: "expired";
+    }>;
+    lease: z.ZodObject<{
+        id: z.ZodString;
+        fence: z.ZodNumber;
+        expiresAt: z.ZodISODateTime;
+    }, z.core.$strict>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const artifactActivationSchema: z.ZodObject<{
+    id: z.ZodString;
+    projectId: z.ZodString;
+    environment: z.ZodString;
+    deploymentId: z.ZodString;
+    configurationSha256: z.ZodString;
+    policySha256: z.ZodString;
+    secretVersions: z.ZodArray<z.ZodObject<{
+        binding: z.ZodString;
+        secretId: z.ZodString;
+        version: z.ZodNumber;
+    }, z.core.$strict>>;
+    cacheGeneration: z.ZodString;
+    activatedAt: z.ZodISODateTime;
+    activatedBy: z.ZodString;
+}, z.core.$strict>;
+export type ArtifactNextBuildInput = z.infer<typeof artifactNextBuildInputSchema>;
+export type ArtifactDeploymentOutput = z.infer<typeof artifactDeploymentOutputSchema>;
+export type ArtifactOperation = z.infer<typeof artifactOperationSchema>;
+export type ArtifactRuntimeSession = z.infer<typeof artifactRuntimeSessionSchema>;
+export type ArtifactLocalDevSession = z.infer<typeof artifactLocalDevSessionSchema>;
+export type ArtifactActivation = z.infer<typeof artifactActivationSchema>;