@sequenceholdings/artifact-studio 0.2.6 → 0.3.1

package/VERSION-PIN.md

@@ -4,12 +4,23 @@ A (re)built Artifact Studio app gets whatever `@sequenceholdings/atlas-ui` the
 **building CLI** carries — not a semver the artifact's own `package.json`
 declares.
 
-Artifact Studio 0.2.5 (Studio CLI 0.1.31) pins Atlas UI 3.1.2 exactly.
+Artifact Studio 0.2.7 (Studio CLI 0.1.36) pins Atlas UI 3.3.0 exactly.
 Ordinary builds now use its canonical, mode-aware `tokens.css`. Rebuilding an
 existing artifact adopts this toolchain; previously uploaded immutable bundles
 keep their original CSS. Migrate retired numbered black/white utilities to
 semantic roles and verify a preview before activating a rebuilt artifact.
 
+Artifact Studio 0.3.0 (Studio CLI 0.2.0) adds the opt-in Next.js runtime. The
+static compiler continues to pin Atlas UI 3.3.0. Next.js applications own their
+React 19 dependencies and use the `/next` client boundary that Atlas UI 3.4.0
+introduces; they do not inherit the static compiler's aliases. The new packages must be published
+before a fresh external Next.js scaffold can be installed. A local candidate
+build is not evidence of registry availability.
+
+Artifact Studio 0.3.1 (Studio CLI 0.2.2) verifies the per-request `jti` that the
+gateway now signs into every request context. The 0.3.0 context schema predates
+that claim and rejects those contexts, so Next.js applications need 0.3.1 or newer.
+
 ## What this means
 
 `shared/services/artifact-studio/src/build.ts` force-aliases platform peers via

package/dist/api.d.ts

@@ -2,13 +2,23 @@ export interface ApiClientOptions {
     baseUrl: string;
     token: string;
 }
+export declare class ArtifactApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
 export declare function getJson<T>({ baseUrl, token, path }: ApiClientOptions & {
     path: string;
 }): Promise<T>;
 export declare function getJsonOr404<T>({ baseUrl, token, path }: ApiClientOptions & {
     path: string;
 }): Promise<T | null>;
-export declare function postJson<T>({ baseUrl, token, path, body, }: ApiClientOptions & {
+export declare function postJson<T>({ baseUrl, token, path, body, retry503, signal, }: ApiClientOptions & {
     path: string;
     body?: unknown;
+    retry503?: boolean;
+    signal?: AbortSignal;
 }): Promise<T>;
+export declare function deleteJson({ baseUrl, token, path, signal }: ApiClientOptions & {
+    path: string;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/api.js

@@ -1,4 +1,13 @@
+import { setTimeout as delay } from 'node:timers/promises';
 import { authenticatedRequestUrl } from './deployment-validation.js';
+export class ArtifactApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'ArtifactApiError';
+    }
+}
 const MAX_503_RETRIES = 5;
 const DEFAULT_RETRY_AFTER_SECONDS = 2;
 /**
@@ -36,19 +45,20 @@ function extraHeaders() {
         return {};
     }
 }
-async function fetchWith503Retry(input, init) {
+async function fetchWith503Retry(input, init, maxRetries = MAX_503_RETRIES) {
     let attempt = 0;
     while (true) {
         const response = await fetch(input, init);
-        if (response.status !== 503 || attempt >= MAX_503_RETRIES)
+        if (response.status !== 503 || attempt >= maxRetries)
             return response;
         const retryAfter = Number(response.headers.get('Retry-After')) || DEFAULT_RETRY_AFTER_SECONDS;
         attempt += 1;
         console.warn(`[seq-studio] backend warming up (503); retrying in ${retryAfter}s (attempt ${attempt}/${MAX_503_RETRIES})`);
-        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
+        // An aborted caller (e.g. artifact dev shutting down) must not wait out a Retry-After.
+        await delay(retryAfter * 1000, undefined, init.signal ? { signal: init.signal } : undefined);
     }
 }
-async function authenticatedFetch({ baseUrl, init = {}, path, token, }) {
+async function authenticatedFetch({ baseUrl, init = {}, path, token, retry503 = true, }) {
     const url = authenticatedRequestUrl({ baseUrl, path });
     return fetchWith503Retry(url, {
         ...init,
@@ -58,12 +68,12 @@ async function authenticatedFetch({ baseUrl, init = {}, path, token, }) {
             ...init.headers,
             Authorization: `Bearer ${token}`,
         },
-    });
+    }, retry503 ? MAX_503_RETRIES : 0);
 }
 export async function getJson({ baseUrl, token, path }) {
     const response = await authenticatedFetch({ baseUrl, token, path });
     if (!response.ok)
-        throw new Error(await responseError('GET', path, response));
+        throw new ArtifactApiError(await responseError('GET', path, response), response.status);
     return response.json();
 }
 export async function getJsonOr404({ baseUrl, token, path }) {
@@ -71,24 +81,31 @@ export async function getJsonOr404({ baseUrl, token, path }) {
     if (response.status === 404)
         return null;
     if (!response.ok)
-        throw new Error(await responseError('GET', path, response));
+        throw new ArtifactApiError(await responseError('GET', path, response), response.status);
     return response.json();
 }
-export async function postJson({ baseUrl, token, path, body, }) {
+export async function postJson({ baseUrl, token, path, body, retry503 = true, signal, }) {
     const response = await authenticatedFetch({
         baseUrl,
         token,
         path,
+        retry503,
         init: {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: body === undefined ? undefined : JSON.stringify(body),
+            ...(signal ? { signal } : {}),
         },
     });
     if (!response.ok)
-        throw new Error(await responseError('POST', path, response));
+        throw new ArtifactApiError(await responseError('POST', path, response), response.status);
     return response.json();
 }
+export async function deleteJson({ baseUrl, token, path, signal }) {
+    const response = await authenticatedFetch({ baseUrl, token, path, init: { method: 'DELETE', ...(signal ? { signal } : {}) } });
+    if (!response.ok)
+        throw new ArtifactApiError(await responseError('DELETE', path, response), response.status);
+}
 /**
  * Build an actionable error message from a failed response: which request
  * failed, with what status, and what the server said. A deploy runs several

package/dist/build.d.ts

@@ -1,6 +1,6 @@
 import { type ObservedBuildEvidence } from './build-provenance.js';
 import { type ArtifactStudioSourceFile } from './project.js';
-import type { ArtifactStudioManifest } from './manifest.js';
+import { type ArtifactStudioStaticManifest } from './manifest.js';
 import { type ArtifactStudioPeerVersions } from './peer-versions.js';
 /**
  * Released Atlas UI 2.0.1 exports its canonical sheet from dist, while the
@@ -17,7 +17,7 @@ export interface ArtifactStudioRuntimeChunk {
 }
 export type ArtifactStudioBundleFormat = 'esm';
 export interface ArtifactStudioBuildResult {
-    manifest: ArtifactStudioManifest;
+    manifest: ArtifactStudioStaticManifest;
     files: ArtifactStudioSourceFile[];
     /** Entry module (ESM). Lazy routes land in `chunks`. */
     bundle: string;

package/dist/build.js

@@ -10,6 +10,7 @@ import { collectResolvedStylesheets } from './resolved-stylesheets.js';
 import { sha256Hex } from './hash.js';
 import { isArtifactIgnoredPath } from './artifact-ignore.js';
 import { readArtifactStudioSource } from './project.js';
+import { isNextArtifactManifest } from './manifest.js';
 import { normalizeArtifactPath } from './paths.js';
 import { resolveArtifactStudioPeerVersions, } from './peer-versions.js';
 import { ARTIFACT_RUNTIME_CHUNK_DIR, assertSafeRuntimeChunkFileName } from './runtime-chunks.js';
@@ -103,6 +104,9 @@ export async function buildArtifactStudioProject(rootDir, { candidateTokenCompat
     const selectedAtlasUiDist = resolve(atlasUiPackageDir ?? atlasUiDir, 'dist');
     const selectedAtlasUiTokens = resolveAtlasUiTokensPath(selectedAtlasUiDir);
     const source = await readArtifactStudioSource(rootDir);
+    if (isNextArtifactManifest(source.manifest)) {
+        throw new Error('Next.js applications are built by Atlas. Run seq-studio artifact build --env <env>.');
+    }
     const diagnostics = [
         ...(hasUnifiedAtlasUiTokens(selectedAtlasUiDir)
             ? collectDeprecatedTokenImportDiagnostics({ files: source.files })

package/dist/cli.d.ts

@@ -5,6 +5,7 @@ interface RemoteProject {
     id: string;
     slug: string;
     title: string;
+    projectType?: string;
     activeDeployment?: {
         version: string;
         sourceHash: string;

package/dist/cli.js

@@ -1,5 +1,5 @@
-import { cp, mkdir, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { copyFile, cp, mkdir, writeFile } from 'node:fs/promises';
+import { constants, existsSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getJson, getJsonOr404, postJson } from './api.js';
@@ -8,21 +8,22 @@ import { writeBuildArtifact } from './build.js';
 import { buildArtifactStudioProjectIsolated } from './build-subprocess.js';
 import { resolveArtifactStudioPeerVersions, } from './peer-versions.js';
 import { prepareArtifactBuildRoot } from './prepare-build.js';
-import { parseArtifactStudioManifest } from './manifest.js';
-import { hasArtifactStudioManifest, readArtifactStudioSource } from './project.js';
+import { isNextArtifactManifest, parseArtifactStudioManifest } from './manifest.js';
+import { hasArtifactStudioManifest, readArtifactStudioManifest, readArtifactStudioSource } from './project.js';
 import { localGitMetadata, parseSourceSpec, resolveArtifactSource, } from './source-resolver.js';
 import { acquireDevLock } from './dev-lock.js';
 import { runWatchLoop } from './watch-loop.js';
 import { hashLinkedSources, hasLinkedAtlasUiToolchain, parseLinks, rebuildLinkedDep, resolveLinkedDeps, syncLinkedDist, } from './dev-link.js';
 import { lintArtifactSandbox, reportSandboxWarnings } from './sandbox-lint.js';
 import { assertActiveDeployProvenance } from './active-deploy-policy.js';
+import { normalizeArtifactPath } from './paths.js';
 import yaml from 'js-yaml';
 const COMMANDS = [
     'init', 'whoami', 'link', 'env', 'status', 'list', 'show',
     'validate', 'build', 'plan', 'deploy', 'dev', 'promote', 'pull', 'rollback',
 ];
 const USAGE = `usage:
-  seq-studio artifact init <dir>
+  seq-studio artifact init <dir> [--template react-vite|nextjs]
   seq-studio artifact whoami --env <env>
   seq-studio artifact link --env <env> [--project <id>]
   seq-studio artifact env list|use <env>
@@ -33,11 +34,13 @@ const USAGE = `usage:
   seq-studio artifact build [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--out dist/artifact-bundle.json]
   seq-studio artifact plan [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] --env <env>
   seq-studio artifact deploy [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] --env <env> [--skip-unchanged] [--no-create] [--project <id>]
-  seq-studio artifact dev [dir] --env <env> [--once] [--key default] [--link <pkgDir>[,<pkgDir>]]
+  seq-studio artifact dev [dir] --env <env> [--once] [--key default] [--link <pkgDir>[,<pkgDir>]] [--port <port>]
   seq-studio artifact promote <deployment-id> --env <env>
   seq-studio artifact pull <project-id> --env <env> --out <dir>
   seq-studio artifact rollback <deployment-id> --env <env>
 
+  Add --help or -h to any artifact command to print this usage without running it.
+
   Source: a local [dir] (default), a platform git-service repo (--repo <ns>/<name>),
   or a public HTTPS git URL (--git-url <url>). --ref picks a branch/tag/commit (default: the
   repo's default branch). The target project comes from the source's
@@ -57,6 +60,12 @@ const USAGE = `usage:
   seq-studio login are still needed to resolve the repo and upload the
   deployment.)
 
+  Next.js: init --template nextjs, then pnpm install with Node.js 24. dev starts
+  a local Next server and an owner-only Atlas preview tunnel (no cloud credentials).
+  build --env creates an immutable hosted preview; deploy builds and publishes
+  a reviewed Git Service revision through Atlas. For local build checks, use pnpm build.
+  --once applies to static artifacts; --port applies to Next development.
+
   Authenticate with: seq-studio login`;
 export async function runCli(argv = process.argv.slice(2)) {
     if (argv.some((arg) => arg === '--token' || arg.startsWith('--token='))) {
@@ -64,6 +73,10 @@ export async function runCli(argv = process.argv.slice(2)) {
             'Authenticate with seq-studio login.');
         return 1;
     }
+    if (argv.some((arg) => arg === '--help' || arg === '-h')) {
+        console.log(USAGE);
+        return 0;
+    }
     const parsed = parseArgs(argv);
     if ('error' in parsed) {
         console.error(parsed.error);
@@ -118,17 +131,35 @@ async function initCommand(args) {
     const dir = resolve(args.positional[0] ?? '.');
     const name = dir.split('/').filter(Boolean).at(-1) ?? 'my-artifact';
     const slug = slugify(name);
+    const template = args.flags.template ?? 'react-vite';
+    if (template !== 'react-vite' && template !== 'nextjs') {
+        throw new Error('--template must be react-vite or nextjs.');
+    }
     const moduleDir = dirname(fileURLToPath(import.meta.url));
-    const templateRoot = existsSync(resolve(moduleDir, 'templates', 'react-vite'))
-        ? resolve(moduleDir, 'templates', 'react-vite')
-        : resolve(moduleDir, '..', 'templates', 'react-vite');
+    const templateRoot = existsSync(resolve(moduleDir, 'templates', template))
+        ? resolve(moduleDir, 'templates', template)
+        : resolve(moduleDir, '..', 'templates', template);
     await mkdir(dir, { recursive: true });
-    await cp(templateRoot, dir, { recursive: true, force: false, errorOnExist: false });
+    const templateGitignore = join(templateRoot, 'gitignore');
+    await cp(templateRoot, dir, {
+        recursive: true, force: false, errorOnExist: false,
+        filter: (source) => source !== templateGitignore,
+    });
+    await installTemplateGitignore({ source: templateGitignore, dir });
     await replaceInFile(join(dir, 'artifact.bundle.yml'), /\{\{slug\}\}/g, slug);
     await replaceInFile(join(dir, 'artifact.bundle.yml'), /\{\{title\}\}/g, titleize(slug));
     await replaceInFile(join(dir, 'package.json'), /\{\{slug\}\}/g, slug);
+    if (template === 'nextjs') {
+        const peers = resolveArtifactStudioPeerVersions();
+        await replaceInFile(join(dir, 'package.json'), /\{\{artifactStudioVersion\}\}/g, peers.cliVersion);
+        for (const file of ['app/layout.tsx', 'app/page.tsx']) {
+            await replaceInFile(join(dir, file), /\{\{title\}\}/g, titleize(slug));
+        }
+    }
     console.log(`[seq-studio] initialized ${dir}`);
-    console.log('Next: seq-studio login && seq-studio artifact dev --env <env>  (see: seq-studio envs list)');
+    console.log(template === 'nextjs'
+        ? 'Next: cd into the app, run pnpm install, then seq-studio login && seq-studio artifact dev --env <env>. Commit pnpm-lock.yaml before deploying. No cloud credentials are required.'
+        : 'Next: seq-studio login && seq-studio artifact dev --env <env>  (see: seq-studio envs list)');
     return 0;
 }
 async function whoamiCommand(args) {
@@ -184,10 +215,12 @@ async function linkCommand(args) {
                 title: source.manifest.artifact.title,
                 slug: source.manifest.artifact.project_id,
                 description: source.manifest.artifact.description ?? null,
+                ...(isNextArtifactManifest(source.manifest) ? { projectType: 'nextjs' } : {}),
             },
         });
         project = created.project;
     }
+    assertProjectRuntime({ project, artifactType: source.manifest.artifact.type, declaredSlug: source.manifest.artifact.project_id });
     await writeLocalConfig({
         projectId: project.id,
         projectSlug: project.slug,
@@ -343,6 +376,12 @@ async function validateCommand(args) {
     console.log(`[seq-studio] valid ${source.manifest.bundle.name}`);
     console.log(`[seq-studio] files: ${source.files.length}`);
     console.log(`[seq-studio] source: ${source.sourceHash}`);
+    if (isNextArtifactManifest(source.manifest)) {
+        const { validateNextProject } = await import('./next-project.js');
+        await validateNextProject({ root: dir, manifest: source.manifest, installed: false });
+        console.log('[seq-studio] Next.js source is valid; Atlas performs the release build and hosted policy checks.');
+        return 0;
+    }
     reportSandboxWarnings(lintArtifactSandbox(source.files));
     return 0;
 }
@@ -372,6 +411,9 @@ async function buildCommand(args) {
             : {};
     const source = await resolveArtifactSource(spec, remote);
     try {
+        if (isNextArtifactManifest(await readArtifactStudioManifest(source.dir))) {
+            return await buildNextCommand({ args, source, active: false });
+        }
         const result = await buildPreparedArtifactSource(source);
         reportBuildDiagnostics(result);
         // A remote source's dir is a temp dir we tear down below, so default the
@@ -402,6 +444,11 @@ async function planCommand(args) {
         token,
     });
     try {
+        const manifest = await readArtifactStudioManifest(source.dir);
+        if (isNextArtifactManifest(manifest)) {
+            const { planNextProject } = await import('./next-build.js');
+            return await planNextProject({ root: source.dir, manifest, environment: env.name });
+        }
         const result = await buildPreparedArtifactSource(source);
         reportBuildDiagnostics(result);
         console.log(`[seq-studio] plan ${result.manifest.artifact.project_id} -> ${env.name}`);
@@ -458,6 +505,9 @@ async function deployCommand(args) {
         // the current branch and dirty working tree.
         if (env.name !== 'local')
             assertActiveDeployProvenance(source.provenance);
+        if (isNextArtifactManifest(await readArtifactStudioManifest(source.dir))) {
+            return await buildNextCommand({ args, source, active: true });
+        }
         // --skip-unchanged: hash the raw source (no build needed) and no-op when
         // the remote active deployment already matches *and* was built with the
         // same CLI/atlas-ui pin. Lets CI redeploy every artifact on every release
@@ -506,12 +556,56 @@ async function deployCommand(args) {
         await source.cleanup();
     }
 }
+async function buildNextCommand({ args, source, active }) {
+    const env = await envFromArgs(args);
+    const token = await getRequiredToken(args);
+    const manifest = await readArtifactStudioManifest(source.dir);
+    if (!isNextArtifactManifest(manifest))
+        throw new Error('Expected a Next.js application manifest.');
+    const { nextSourceRepository, resolveNextRepositoryId, submitNextBuild } = await import('./next-build.js');
+    const spec = parseSourceSpec(args);
+    const repository = nextSourceRepository({ spec, root: source.dir });
+    if (active)
+        assertActiveDeployProvenance(source.provenance);
+    const repositoryId = active || spec.kind === 'git-service'
+        ? await resolveNextRepositoryId({ spec, repository, baseUrl: env.url, token })
+        : undefined;
+    const project = await ensureRemoteProject({
+        env: env.url, token, result: { manifest }, linkConfigDir: spec.kind === 'local' ? source.dir : null,
+        allowCreate: args.flags['no-create'] !== true,
+        explicitProjectId: typeof args.flags.project === 'string' ? args.flags.project : null,
+    });
+    if (args.flags['skip-unchanged']) {
+        console.log('[seq-studio] Next.js submits source to Atlas for build verification; local static-bundle skip checks do not apply.');
+    }
+    return submitNextBuild({
+        root: source.dir, manifest, projectId: project.id, baseUrl: env.url,
+        getToken: () => getRequiredToken(args), provenance: source.provenance, repository, repositoryId,
+        channel: active ? 'active' : 'preview', out: typeof args.flags.out === 'string' ? resolve(args.flags.out) : undefined,
+    });
+}
 async function devCommand(args) {
     if (args.flags.repo || args.flags['git-url']) {
         throw new Error('dev watches a local folder; --repo / --git-url are only for build, plan, and deploy.');
     }
     const dir = resolve(args.positional[0] ?? '.');
     const env = await envFromArgs(args);
+    const initialManifest = await readArtifactStudioManifest(dir);
+    if (isNextArtifactManifest(initialManifest)) {
+        if (args.flags.once)
+            throw new Error('Next.js dev is a live local session. Use artifact build --env <env> for an immutable hosted preview.');
+        const auth = await getRequiredAuth(args);
+        if (auth.authMode !== 'user')
+            throw new Error('Local Next.js development requires a user login. Run seq-studio login.');
+        const project = await ensureRemoteProject({ env: env.url, token: auth.token, result: { manifest: initialManifest }, linkConfigDir: dir });
+        const { runNextDevelopment } = await import('./next-dev.js');
+        return runNextDevelopment({
+            root: dir, manifest: initialManifest, projectId: project.id, baseUrl: env.url,
+            environment: env.name, previewKey: typeof args.flags.key === 'string' ? args.flags.key : 'default',
+            port: typeof args.flags.port === 'string' ? args.flags.port : undefined,
+            links: parseLinks(args.flags.link), getToken: () => getRequiredToken(args),
+        });
+    }
     // Validate auth up front for a fast failure, but resolve a fresh token on
     // every push (below) so a long-running watcher survives access-token expiry
     // instead of dying with "Authentication failed" once the initial token's TTL
@@ -725,9 +819,9 @@ async function pullCommand(args) {
         path: `/api/artifact-studio/projects/${projectId}/deployments/${projectData.project.activeDeploymentId}/files`,
     });
     for (const file of filesData.files) {
-        const target = join(out, file.path);
+        const target = join(out, normalizeArtifactPath(file.path));
         await mkdir(dirname(target), { recursive: true });
-        await writeFile(target, file.content, 'utf8');
+        await writeFile(target, file.encoding === 'base64' ? Buffer.from(file.content, 'base64') : file.content);
     }
     console.log(`[seq-studio] pulled ${projectId} to ${out}`);
     return 0;
@@ -774,18 +868,21 @@ async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCre
             throw new Error(`--project ${explicitProjectId} resolves to slug "${data.project.slug}" but this source's ` +
                 `artifact.bundle.yml declares project_id "${result.manifest.artifact.project_id}" — refusing to deploy over a different project`);
         }
+        assertProjectRuntime({ project: data.project, artifactType: result.manifest.artifact.type, declaredSlug: result.manifest.artifact.project_id });
         return data.project;
     }
     const config = linkConfigDir ? await readLocalConfig(linkConfigDir) : {};
     if (config.projectId) {
         const data = await getJsonOr404({ baseUrl: env, token, path: `/api/artifact-studio/projects/${config.projectId}` });
         if (data) {
+            assertProjectRuntime({ project: data.project, artifactType: result.manifest.artifact.type, declaredSlug: result.manifest.artifact.project_id });
             return data.project;
         }
         console.warn(`[seq-studio] cached projectId ${config.projectId} not found on ${env} — relinking by slug`);
     }
     const existing = await fetchRemoteProject({ env, token, slug: result.manifest.artifact.project_id });
     if (existing) {
+        assertProjectRuntime({ project: existing, artifactType: result.manifest.artifact.type, declaredSlug: result.manifest.artifact.project_id });
         if (linkConfigDir)
             await writeLocalConfig({ ...config, projectId: existing.id, projectSlug: existing.slug }, linkConfigDir);
         return existing;
@@ -803,12 +900,21 @@ async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCre
             title: result.manifest.artifact.title,
             slug: result.manifest.artifact.project_id,
             description: result.manifest.artifact.description ?? null,
+            ...(result.manifest.artifact.type === 'nextjs' ? { projectType: 'nextjs' } : {}),
         },
     });
     if (linkConfigDir)
         await writeLocalConfig({ ...config, projectId: created.project.id, projectSlug: created.project.slug }, linkConfigDir);
     return created.project;
 }
+function assertProjectRuntime({ project, artifactType, declaredSlug }) {
+    if (artifactType === 'nextjs' && project.slug !== declaredSlug) {
+        throw new Error(`Linked project ${project.slug} does not match artifact.bundle.yml project_id ${declaredSlug}. Relink to the intended project.`);
+    }
+    if (artifactType === 'nextjs' && project.projectType && project.projectType !== 'nextjs') {
+        throw new Error(`Project ${project.slug} uses the static runtime. Create a separate Next.js project in Atlas and update artifact.bundle.yml project_id before linking.`);
+    }
+}
 async function uploadDeployment({ env, token, projectId, result, channel, previewKey, linked = false, provenance, message, }) {
     // Active deploys omit `version`: the server derives it from its own
     // sourceHash and de-dupes against the (projectId, version) unique
@@ -894,6 +1000,21 @@ async function resolveAuth(options) {
     }
     return null;
 }
+/**
+ * npm always leaves `.gitignore` out of published tarballs, so templates ship it
+ * as `gitignore`. Install it without replacing an ignore file the directory has.
+ */
+async function installTemplateGitignore({ source, dir }) {
+    if (!existsSync(source))
+        return;
+    try {
+        await copyFile(source, join(dir, '.gitignore'), constants.COPYFILE_EXCL);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+    }
+}
 async function replaceInFile(path, pattern, value) {
     const content = await import('node:fs/promises').then((fs) => fs.readFile(path, 'utf8'));
     await writeFile(path, content.replace(pattern, value), 'utf8');

package/dist/dev-link.d.ts

@@ -53,7 +53,7 @@ export declare function resolveLinkedDeps({ links, cwd, resolver, readPackageNam
  */
 export declare function hashLinkedSources(deps: readonly LinkedDep[]): Promise<string>;
 /** Run a linked package's `build` script in a child process. */
-export declare function rebuildLinkedDep(dep: LinkedDep, signal?: AbortSignal): Promise<void>;
+export declare function rebuildLinkedDep(dep: LinkedDep, signal?: AbortSignal, env?: NodeJS.ProcessEnv): Promise<void>;
 /**
  * Copy a linked package's freshly built `dist` and root CSS entries into the
  * location the artifact build resolves them from. A no-op when the artifact

package/dist/dev-link.js

@@ -135,7 +135,7 @@ async function collectFiles(root) {
     return out;
 }
 /** Run a linked package's `build` script in a child process. */
-export function rebuildLinkedDep(dep, signal) {
+export function rebuildLinkedDep(dep, signal, env) {
     return new Promise((resolveBuild, reject) => {
         if (signal?.aborted) {
             reject(new Error('build aborted'));
@@ -143,6 +143,7 @@ export function rebuildLinkedDep(dep, signal) {
         }
         const child = spawn('pnpm', ['run', 'build'], {
             cwd: dep.dir,
+            ...(env ? { env } : {}),
             stdio: ['ignore', 'inherit', 'inherit'],
         });
         const onAbort = () => {

package/dist/gateway/admission.d.ts

@@ -0,0 +1,56 @@
+import type { EventEmitter } from 'node:events';
+export interface AdmissionRedis {
+    readonly options: {
+        enableOfflineQueue?: boolean;
+        autoResendUnfulfilledCommands?: boolean;
+        maxRetriesPerRequest?: number | null;
+    };
+    eval(script: string, numberOfKeys: number, ...parameters: (string | number)[]): Promise<unknown>;
+}
+export interface AdmissionTarget {
+    environment: string;
+    projectId: string;
+    deploymentId: string;
+    resources?: {
+        concurrency?: number;
+        max_instances?: number;
+        timeout_seconds?: number;
+    };
+}
+type ResponseLifecycle = Pick<EventEmitter, 'once' | 'off'> & {
+    writableFinished?: boolean;
+    destroyed?: boolean;
+};
+export interface AdmissionLease {
+    requestId: string;
+    /** Redis-server deadline, for tracing; local cancellation uses elapsed time. */
+    deadline: number;
+    timeoutMs: number;
+    release(): Promise<void>;
+    /** Register immediately after admission, before starting upstream work.
+     * onTimeout must synchronously abort the upstream before the permit is freed. */
+    bind(response: ResponseLifecycle, onTimeout: () => void): () => void;
+}
+export declare class ArtifactAdmissionError extends Error {
+    readonly status: 429 | 503;
+    readonly code: 'capacity_exceeded' | 'admission_unavailable';
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(status: 429 | 503, code: 'capacity_exceeded' | 'admission_unavailable', retryAfterSeconds?: number | undefined);
+}
+/** Fail-closed admission with no command retries. An uncertain acquisition is
+ * never used; its unique permit expires even if Redis accepted it before loss. */
+export declare class ArtifactRequestAdmission {
+    private readonly options;
+    private readonly namespace;
+    private readonly ceiling;
+    constructor(options: {
+        redis: AdmissionRedis;
+        namespace: string;
+        platformCeiling?: number;
+        onError?: (event: {
+            kind: 'admission_release_failed' | 'admission_timeout_callback_failed';
+        }) => void;
+    });
+    acquire(target: AdmissionTarget): Promise<AdmissionLease>;
+}
+export {};