@sequenceholdings/artifact-studio 0.2.6 → 0.3.0

package/dist/next-cache/valkey-transport.js

@@ -0,0 +1,189 @@
+import { isIP } from 'node:net';
+import { checkServerIdentity } from 'node:tls';
+import { Compute } from 'google-auth-library';
+import { Redis } from 'ioredis';
+/** A failed EVAL may have committed. Callers must never automatically replay it. */
+export class ValkeyUnavailableError extends Error {
+    outcome;
+    code = 'CACHE_UNAVAILABLE';
+    constructor(outcome = 'not-dispatched') {
+        super('Artifact cache is unavailable.');
+        this.outcome = outcome;
+        this.name = 'ValkeyUnavailableError';
+    }
+}
+const COMMAND_TIMEOUT_MS = 150;
+const CONNECT_TIMEOUT_MS = 1_500;
+const MAX_PENDING = 128;
+const CREDENTIAL_MAX_AGE_MS = 45 * 60_000;
+const CREDENTIAL_EXPIRY_MARGIN_MS = 60_000;
+export function valkeyTlsOptions(connection) {
+    return {
+        ca: connection.caCertificates,
+        servername: isIP(connection.serverIdentity) ? undefined : connection.serverIdentity,
+        rejectUnauthorized: true,
+        // A literal assertion preserves the Node TLS option's narrow union type.
+        minVersion: 'TLSv1.2',
+        checkServerIdentity: (_hostname, certificate) => checkServerIdentity(connection.serverIdentity, certificate),
+    };
+}
+/** Bounded, multiplexed TLS transport; credentials come from the attached identity. */
+export class ValkeyScriptExecutor {
+    connection;
+    auth;
+    getAccessToken;
+    connections = new Set();
+    current;
+    connecting;
+    active = 0;
+    closed = false;
+    constructor({ connection, getAccessToken }) {
+        if (!connection.host || !connection.serverIdentity
+            || !Number.isInteger(connection.port) || connection.port < 1 || connection.port > 65_535
+            || connection.caCertificates.length === 0 || connection.caCertificates.some((ca) => !ca.trim())) {
+            throw new ValkeyUnavailableError();
+        }
+        this.connection = { ...connection, caCertificates: [...connection.caCertificates] };
+        if (getAccessToken) {
+            this.getAccessToken = getAccessToken;
+        }
+        else {
+            // Compute uses metadata-server credentials, never developer ADC or a key file.
+            this.auth = new Compute({ scopes: ['https://www.googleapis.com/auth/cloud-platform'] });
+            const auth = this.auth;
+            this.getAccessToken = async () => {
+                const access = await auth.getAccessToken();
+                if (!access.token)
+                    throw new ValkeyUnavailableError();
+                return access.token;
+            };
+        }
+    }
+    async eval(input) {
+        if (this.closed || this.active >= MAX_PENDING)
+            throw new ValkeyUnavailableError();
+        this.active++;
+        let connection;
+        let dispatched = false;
+        try {
+            connection = await this.acquireConnection();
+            if (this.closed || connection.client.status !== 'ready')
+                throw new ValkeyUnavailableError();
+            connection.pending++;
+            dispatched = true;
+            return await connection.client.eval(input.script, input.keys.length, ...input.keys, ...input.arguments);
+        }
+        catch {
+            if (connection)
+                this.disconnect(connection);
+            // Never chain raw library errors: they can include credentials and endpoints.
+            throw new ValkeyUnavailableError(dispatched ? 'unknown' : 'not-dispatched');
+        }
+        finally {
+            if (connection && dispatched) {
+                connection.pending--;
+                if (connection.retired && connection.pending === 0)
+                    this.disconnect(connection);
+            }
+            this.active--;
+        }
+    }
+    close() {
+        this.closed = true;
+        for (const connection of this.connections)
+            this.disconnect(connection);
+    }
+    disconnect(connection) {
+        connection.retired = true;
+        connection.client.disconnect();
+        this.connections.delete(connection);
+        if (this.current === connection)
+            this.current = undefined;
+    }
+    async acquireConnection() {
+        if (this.current?.client.status === 'ready' && Date.now() < this.current.refreshAt)
+            return this.current;
+        if (this.current) {
+            const previous = this.current;
+            this.current = undefined;
+            previous.retired = true;
+            // Token refresh must not interrupt unrelated in-flight cache operations.
+            if (previous.pending === 0)
+                this.disconnect(previous);
+        }
+        if (this.connecting)
+            return this.connecting;
+        const attempt = this.openConnection().then((connection) => {
+            this.current = connection;
+            return connection;
+        });
+        this.connecting = attempt;
+        try {
+            return await attempt;
+        }
+        finally {
+            if (this.connecting === attempt)
+                this.connecting = undefined;
+        }
+    }
+    async openConnection() {
+        let connection;
+        let cancelled = false;
+        let timer;
+        const attempt = (async () => {
+            const token = await this.getAccessToken();
+            if (cancelled || this.closed || !token)
+                throw new ValkeyUnavailableError();
+            const refreshAt = Math.min(Date.now() + CREDENTIAL_MAX_AGE_MS, (this.auth?.credentials.expiry_date ?? Infinity) - CREDENTIAL_EXPIRY_MARGIN_MS);
+            if (refreshAt <= Date.now())
+                throw new ValkeyUnavailableError();
+            connection = {
+                client: this.createClient({ token }), refreshAt, pending: 0, retired: false,
+            };
+            this.connections.add(connection);
+            await connection.client.connect();
+            if (cancelled || this.closed)
+                throw new ValkeyUnavailableError();
+            return connection;
+        })();
+        try {
+            return await Promise.race([
+                attempt,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new ValkeyUnavailableError()), CONNECT_TIMEOUT_MS);
+                }),
+            ]);
+        }
+        catch {
+            cancelled = true;
+            if (connection)
+                this.disconnect(connection);
+            throw new ValkeyUnavailableError();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    createClient({ token }) {
+        const client = new Redis({
+            host: this.connection.host,
+            port: this.connection.port,
+            username: 'default',
+            password: token,
+            tls: valkeyTlsOptions(this.connection),
+            lazyConnect: true,
+            connectTimeout: CONNECT_TIMEOUT_MS,
+            commandTimeout: COMMAND_TIMEOUT_MS,
+            enableOfflineQueue: false,
+            enableReadyCheck: false,
+            retryStrategy: () => null,
+            maxRetriesPerRequest: 0,
+            autoResendUnfulfilledCommands: false,
+            autoResubscribe: false,
+        });
+        client.on('error', () => {
+            // Sanitized at the operation boundary; never log provider errors here.
+        });
+        return client;
+    }
+}

package/dist/next-dev-control.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+declare const devLeaseSchema: z.ZodObject<{
+    session: z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodString;
+        previewUrl: z.ZodString;
+        publicOrigin: z.ZodString;
+        expiresAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    tunnel: z.ZodObject<{
+        url: z.ZodString;
+        token: z.ZodString;
+        epoch: z.ZodNumber;
+    }, z.core.$strip>;
+    runtime: z.ZodObject<{
+        environment: z.ZodString;
+        atlasUrl: z.ZodString;
+        sessionToken: z.ZodString;
+        publicKeys: z.ZodRecord<z.ZodString, z.ZodString>;
+        bindings: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type NextDevLease = z.infer<typeof devLeaseSchema>;
+export declare function isTransientNextControlFailure(error: unknown): boolean;
+export declare function requestNextDevLease({ baseUrl, token, projectId, sessionId, body, environment, signal }: {
+    baseUrl: string;
+    token: string;
+    projectId: string;
+    sessionId?: string;
+    body: unknown;
+    environment: string;
+    /** Aborted when artifact dev shuts down, so a stalled request cannot delay revocation and cleanup. */
+    signal?: AbortSignal;
+}): Promise<NextDevLease>;
+export declare function writeNextRuntimeFile({ path, projectId, lease }: {
+    path: string;
+    projectId: string;
+    lease: NextDevLease;
+}): Promise<void>;
+export declare function renewNextDevLease({ baseUrl, token, projectId, lease, status, signal }: {
+    baseUrl: string;
+    token: string;
+    projectId: string;
+    lease: NextDevLease;
+    status: string;
+    signal?: AbortSignal;
+}): Promise<void>;
+export {};

package/dist/next-dev-control.js

@@ -0,0 +1,63 @@
+import { chmod, rename, writeFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { ArtifactApiError, postJson } from './api.js';
+import { validateNextPublicOrigin } from './next-project.js';
+const devLeaseSchema = z.object({
+    session: z.object({
+        id: z.string().min(1), status: z.string(), previewUrl: z.string().url(),
+        publicOrigin: z.string().url(), expiresAt: z.iso.datetime(),
+    }),
+    tunnel: z.object({ url: z.string().url(), token: z.string().min(1), epoch: z.number().int().nonnegative() }),
+    runtime: z.object({
+        environment: z.string().min(1), atlasUrl: z.string().url(), sessionToken: z.string().min(16),
+        publicKeys: z.record(z.string(), z.string()), bindings: z.unknown().optional(),
+    }),
+});
+export function isTransientNextControlFailure(error) {
+    if (error instanceof ArtifactApiError)
+        return error.status === 429 || error.status >= 500;
+    return error instanceof TypeError && /fetch failed|network|connection/i.test(error.message);
+}
+export async function requestNextDevLease({ baseUrl, token, projectId, sessionId, body, environment, signal }) {
+    const root = `/api/artifact-studio/projects/${encodeURIComponent(projectId)}/next/dev-sessions`;
+    const path = sessionId ? `${root}/${encodeURIComponent(sessionId)}/lease` : root;
+    // Session creation/epoch rotation cannot replay after an ambiguous response.
+    const lease = devLeaseSchema.parse(await postJson({ baseUrl, token, path, body, retry503: false, signal }));
+    validateNextPublicOrigin({ value: lease.session.publicOrigin, environment });
+    if (sessionId && lease.session.id !== sessionId)
+        throw new Error('Atlas returned credentials for a different development session.');
+    // CLI aliases (including "local") need not equal the deployment's APP_ENV.
+    // Bind to the authenticated Atlas origin; the SDK verifies the server's
+    // environment identifier against the signed request context.
+    if (new URL(lease.runtime.atlasUrl).origin !== new URL(baseUrl).origin)
+        throw new Error('Atlas returned a runtime credential for a different environment.');
+    if (new URL(lease.session.previewUrl).origin !== new URL(baseUrl).origin)
+        throw new Error('Atlas returned a preview link outside the selected environment.');
+    return lease;
+}
+export async function writeNextRuntimeFile({ path, projectId, lease }) {
+    const temporary = `${path}.pending`;
+    await writeFile(temporary, JSON.stringify({
+        atlasUrl: new URL(lease.runtime.atlasUrl).origin,
+        projectId,
+        environment: lease.runtime.environment,
+        sessionToken: lease.runtime.sessionToken,
+        publicKeys: lease.runtime.publicKeys,
+        devSessionId: lease.session.id,
+    }), { mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, path);
+}
+export async function renewNextDevLease({ baseUrl, token, projectId, lease, status, signal }) {
+    const response = z.object({ session: z.object({ id: z.string(), expiresAt: z.iso.datetime() }), epoch: z.number().int() }).parse(await postJson({
+        baseUrl, token,
+        path: `/api/artifact-studio/projects/${encodeURIComponent(projectId)}/next/dev-sessions/${encodeURIComponent(lease.session.id)}/lease`,
+        body: { epoch: lease.tunnel.epoch, status },
+        retry503: false,
+        signal,
+    }));
+    if (response.session.id !== lease.session.id || response.epoch !== lease.tunnel.epoch) {
+        throw new Error('The development session was replaced. Start artifact dev again.');
+    }
+    lease.session.expiresAt = response.session.expiresAt;
+}

package/dist/next-dev-process.d.ts

@@ -0,0 +1,17 @@
+export declare function selectNextDevPort({ requested }: {
+    requested?: string;
+}): Promise<number>;
+export interface NextDevProcess {
+    ready: Promise<void>;
+    closed: Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function openNextPreview(url: string): void;
+export declare function startNextDevProcess({ appRoot, nextBin, port, env, signal, onStatus }: {
+    appRoot: string;
+    nextBin: string;
+    port: number;
+    env: NodeJS.ProcessEnv;
+    signal: AbortSignal;
+    onStatus: (status: 'starting' | 'compiling' | 'ready' | 'failed') => void;
+}): NextDevProcess;

package/dist/next-dev-process.js

@@ -0,0 +1,110 @@
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:net';
+import { setTimeout as delay } from 'node:timers/promises';
+export async function selectNextDevPort({ requested }) {
+    const port = requested === undefined ? 0 : Number(requested);
+    if (!Number.isInteger(port) || port < 0 || port > 65535 || (requested !== undefined && port < 1024)) {
+        throw new Error('--port must be an integer between 1024 and 65535.');
+    }
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+            const address = server.address();
+            server.close((error) => {
+                if (error)
+                    reject(error);
+                else if (address && typeof address !== 'string')
+                    resolve(address.port);
+                else
+                    reject(new Error('Unable to reserve a loopback port for Next.js.'));
+            });
+        });
+    });
+}
+export function openNextPreview(url) {
+    if (!process.stdout.isTTY)
+        return;
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer.exe' : 'xdg-open';
+    const browser = spawn(command, [url], { stdio: 'ignore', detached: true });
+    browser.once('error', () => console.warn('[seq-studio] Open the printed Atlas preview link in your browser.'));
+    browser.unref();
+}
+function stopChild(child, signal) {
+    if (!child.pid || child.exitCode !== null || child.signalCode !== null)
+        return;
+    try {
+        if (process.platform === 'win32')
+            child.kill(signal);
+        else
+            process.kill(-child.pid, signal);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ESRCH'))
+            throw error;
+    }
+}
+export function startNextDevProcess({ appRoot, nextBin, port, env, signal, onStatus }) {
+    signal.throwIfAborted();
+    const child = spawn(process.execPath, [nextBin, 'dev', '--webpack', '--hostname', '127.0.0.1', '--port', String(port)], {
+        cwd: appRoot, env, stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32',
+    });
+    let isReady = false;
+    let stopping = false;
+    let resolveReady = () => { };
+    let rejectReady = () => { };
+    const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+    // Startup can fail while the caller is waiting for another connection.
+    void ready.catch(() => { });
+    const startupTimeout = setTimeout(() => {
+        rejectReady(new Error('Next.js did not become ready within 90 seconds. Inspect the local compiler output.'));
+        stopChild(child, 'SIGTERM');
+    }, 90_000);
+    const observe = (chunk) => {
+        const message = chunk.toString('utf8').replace(/\u001b\[[0-9;]*m/g, '');
+        if (/Ready in|✓ Ready/.test(message)) {
+            isReady = true;
+            clearTimeout(startupTimeout);
+            resolveReady();
+            onStatus('ready');
+        }
+        else if (/Compiling/.test(message))
+            onStatus('compiling');
+        else if (/⨯|Module not found|Failed to compile/.test(message))
+            onStatus('failed');
+        else if (/Compiled|GET |POST /.test(message) && isReady)
+            onStatus('ready');
+    };
+    child.stdout?.on('data', observe);
+    child.stderr?.on('data', observe);
+    child.stdout?.pipe(process.stdout, { end: false });
+    child.stderr?.pipe(process.stderr, { end: false });
+    onStatus('starting');
+    const closed = new Promise((resolve, reject) => {
+        child.once('error', (error) => { rejectReady(error); reject(error); });
+        child.once('close', (code, exitSignal) => {
+            clearTimeout(startupTimeout);
+            signal.removeEventListener('abort', onAbort);
+            if (!isReady)
+                rejectReady(new Error('Next.js exited before becoming ready.'));
+            if (stopping || signal.aborted) {
+                resolve();
+                return;
+            }
+            onStatus('failed');
+            reject(new Error(`Next.js exited (${exitSignal ?? code ?? 'unknown'}). Fix the reported error and restart artifact dev.`));
+        });
+    });
+    void closed.catch(() => { });
+    async function stop() {
+        stopping = true;
+        stopChild(child, 'SIGTERM');
+        const exited = await Promise.race([closed.then(() => true, () => true), delay(3000).then(() => false)]);
+        if (!exited)
+            stopChild(child, 'SIGKILL');
+        await closed.catch(() => { });
+    }
+    const onAbort = () => { void stop(); };
+    signal.addEventListener('abort', onAbort, { once: true });
+    return { ready, closed, stop };
+}

package/dist/next-dev.d.ts

@@ -0,0 +1,12 @@
+import type { ArtifactStudioNextManifest } from './manifest.js';
+export declare function runNextDevelopment({ root, manifest, projectId, baseUrl, environment, previewKey, port: requestedPort, links, getToken }: {
+    root: string;
+    manifest: ArtifactStudioNextManifest;
+    projectId: string;
+    baseUrl: string;
+    environment: string;
+    previewKey: string;
+    port?: string;
+    links: string[];
+    getToken: () => Promise<string>;
+}): Promise<number>;