@sequenceholdings/artifact-studio 0.1.6 → 0.1.10

package/dist/prepare-build.js

@@ -0,0 +1,119 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { stripInstallControlFiles } from './sanitize-remote-tree.js';
+import { assertTrustedArtifactInstallTree } from './trusted-install.js';
+/**
+ * Pinned pnpm for remote artifact installs, run via `npx`. Kept in lockstep
+ * with the repo's root `packageManager`. Do not float to latest: pnpm 11+ adds
+ * an UNCONDITIONAL tarball-URL verification policy (no opt-out) that rejects
+ * Chainguard's upstream-proxied tarballs at install time
+ * (ERR_PNPM_TARBALL_URL_MISMATCH). We run it via npx — which ships with npm on
+ * every Node release — rather than corepack, which Node 25+ no longer bundles.
+ */
+export const ARTIFACT_BUILD_PNPM = 'pnpm@10.28.2';
+/** Chainguard registry routing for ephemeral remote builds. */
+export const ARTIFACT_BUILD_NPMRC = `; Ephemeral install config for seq-studio artifact builds.
+registry=https://libraries.cgr.dev/javascript/
+//libraries.cgr.dev/javascript/:always-auth=true
+//libraries.cgr.dev/javascript-upstream/:always-auth=true
+ignore-scripts=true
+manage-package-manager-versions=false
+`;
+const CHAINGUARD_AUTH_LINE_RE = /^\/\/libraries\.cgr\.dev\/[^:]+:(_auth|_authToken|always-auth)=/;
+/** Pull only Chainguard registry auth lines from the developer ~/.npmrc. */
+export function extractChainguardAuthLines(userNpmrc) {
+    const lines = [];
+    for (const raw of userNpmrc.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith(';') || line.startsWith('#'))
+            continue;
+        if (CHAINGUARD_AUTH_LINE_RE.test(line))
+            lines.push(line);
+    }
+    return lines;
+}
+/** Merge trusted Chainguard auth from ~/.npmrc with pinned install settings. */
+export function buildControlledArtifactNpmrc(userNpmrcPath = join(homedir(), '.npmrc')) {
+    let authBlock = '';
+    if (existsSync(userNpmrcPath)) {
+        const authLines = extractChainguardAuthLines(readFileSync(userNpmrcPath, 'utf8'));
+        if (authLines.length > 0)
+            authBlock = `${authLines.join('\n')}\n`;
+    }
+    return `${authBlock}${ARTIFACT_BUILD_NPMRC}`;
+}
+/**
+ * Whether the build should run `pnpm install` before Vite bundles the tree.
+ * Only remote materializations (--repo / --git-url) are bare and need install.
+ */
+export function shouldInstallArtifactDependencies(dir, opts = {}) {
+    if (!opts.remote)
+        return false;
+    return existsSync(join(dir, 'package.json'));
+}
+/**
+ * Install artifact runtime deps into the build root. Platform peers (react,
+ * atlas-ui, react-query, artifact-studio SDK) are still force-aliased at build
+ * time — this step resolves app-specific imports like recharts or reactflow.
+ */
+export async function prepareArtifactBuildRoot(dir, opts = {}) {
+    if (!shouldInstallArtifactDependencies(dir, opts))
+        return;
+    if (!existsSync(join(dir, 'pnpm-lock.yaml'))) {
+        throw new Error('Remote artifact deploy requires pnpm-lock.yaml — run `pnpm install` locally and commit the lockfile.');
+    }
+    // Materialized git-service trees may still carry historical `.npmrc` /
+    // `pnpm-workspace.yaml` from early scaffolds. Strip them from the temp
+    // build root before the trust check so `--repo` deploy works; authors
+    // should still delete those files on main (see artifact-git-deploy skill).
+    const stripped = stripInstallControlFiles(dir);
+    if (stripped.length > 0) {
+        console.warn(`[seq-studio] stripped install-control files from remote tree (not committed): ${stripped.join(', ')}`);
+    }
+    assertTrustedArtifactInstallTree(dir);
+    // Defense-in-depth: never trust a node_modules committed into the checkout.
+    // The trust walk skips node_modules, so a crafted tree could smuggle a
+    // malicious `node_modules/pnpm` bin. We both (a) remove any pre-existing
+    // node_modules and (b) run npx from a trusted cwd below so npx can't resolve
+    // the pinned CLI out of the untrusted tree.
+    await rm(join(dir, 'node_modules'), { recursive: true, force: true });
+    const configDir = await mkdtemp(join(tmpdir(), 'artifact-pnpm-'));
+    const controlledNpmrc = join(configDir, '.npmrc');
+    const args = ['install', '--frozen-lockfile', '--ignore-scripts', '--prod'];
+    const userNpmrcPath = process.env.npm_config_userconfig ?? join(homedir(), '.npmrc');
+    console.log(`[seq-studio] installing dependencies (frozen lockfile, prod only) via ${ARTIFACT_BUILD_PNPM}…`);
+    try {
+        await writeFile(controlledNpmrc, buildControlledArtifactNpmrc(userNpmrcPath), { mode: 0o600 });
+        // Run a PINNED pnpm via `npx`, not the operator's ambient `pnpm`. The
+        // install must be reproducible across laptops and CI: in a bare temp clone
+        // dir the ambient pnpm resolves to latest (11.x), whose unconditional
+        // tarball-URL policy rejects Chainguard's upstream-proxied tarballs with
+        // ERR_PNPM_TARBALL_URL_MISMATCH. `npx` ships with npm on every Node release
+        // (including Node 25+, which dropped corepack), fetches the pinned pnpm, and
+        // caches it. `--yes` skips the install-confirmation prompt.
+        //
+        // SECURITY: run npx from the trusted `configDir` (not `dir`) so it can't
+        // resolve/execute a pnpm bin planted in the checkout's node_modules; pnpm
+        // still operates on the checkout via `--dir`.
+        execFileSync('npx', ['--yes', ARTIFACT_BUILD_PNPM, '--dir', dir, ...args], {
+            cwd: configDir,
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                npm_config_userconfig: controlledNpmrc,
+            },
+        });
+    }
+    catch (error) {
+        const hint = 'Lockfile out of sync, registry auth missing, or npx unavailable — ' +
+            'run `pnpm install` locally and commit pnpm-lock.yaml, and ensure Node ships npm/npx.';
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`artifact dependency install failed (${ARTIFACT_BUILD_PNPM}). ${hint} (${detail})`);
+    }
+    finally {
+        await rm(configDir, { recursive: true, force: true });
+    }
+}

package/dist/project.js

@@ -24,7 +24,8 @@ export async function readArtifactStudioSource(rootDir) {
         root,
         manifest,
         files,
-        sourceHash: computeSourceHash({ files, manifest }),
+        // Hash the RAW manifest, not the parsed one — see computeSourceHash.
+        sourceHash: computeSourceHash({ files, manifest: rawManifest }),
     };
 }
 async function collectSourceFiles(root) {

package/dist/sandbox-lint.d.ts

@@ -0,0 +1,21 @@
+import type { ArtifactStudioSourceFile } from './project.js';
+/**
+ * Static lint for the iframe-sandbox traps that neither the type checker nor
+ * `vite build` can see — APIs that work under standalone `vite` dev but silently
+ * fail in the deployed artifact (no `allow-modals`/`allow-popups`, CSP
+ * `font-src data:` + `connect-src 'self'`, request/response bridge only).
+ *
+ * Findings are warnings, not errors: they're heuristics (a regex can't prove a
+ * `confirm(` is `window.confirm`), so they inform rather than block. Full
+ * reference: build-artifact-studio-app/references/sandbox-gotchas.md.
+ */
+export interface SandboxWarning {
+    file: string;
+    line: number;
+    rule: string;
+    message: string;
+}
+/** Scan artifact source for sandbox-incompatible APIs. Pure; safe to call often. */
+export declare function lintArtifactSandbox(files: readonly ArtifactStudioSourceFile[]): SandboxWarning[];
+/** Print warnings to stderr in a compact, actionable form. Returns the count. */
+export declare function reportSandboxWarnings(warnings: readonly SandboxWarning[]): number;

package/dist/sandbox-lint.js

@@ -0,0 +1,95 @@
+const RULES = [
+    {
+        name: 'no-native-modals',
+        // window.confirm/alert/prompt, or the bare global call (not a method like foo.confirm()).
+        pattern: /(?<![\w.])(?:window\.)?(confirm|alert|prompt)\s*\(/g,
+        message: 'window.confirm/alert/prompt are blocked in the sandbox (no allow-modals) and silently return — use AlertDialog/ConfirmDialog from @sequenceholdings/atlas-ui.',
+    },
+    {
+        name: 'no-popups',
+        pattern: /(?<![\w.])window\.open\s*\(/g,
+        message: 'window.open is blocked in the sandbox (no allow-popups) — navigate in-app or surface the URL as copyable text.',
+    },
+    {
+        name: 'no-fullscreen',
+        pattern: /\.(?:webkit)?requestFullscreen\s*\(/g,
+        message: 'The Fullscreen API is blocked in the sandbox — use a CSS overlay (fixed inset-0 z-50) toggled by state.',
+    },
+    {
+        name: 'no-remote-fonts',
+        pattern: /fonts\.(?:googleapis|gstatic)\.com/g,
+        message: 'Remote web fonts will not load (CSP font-src data:), and the deploy ignores index.html. Use the system stack, or inline a base64 data: @font-face.',
+    },
+    {
+        name: 'no-remote-fontface',
+        extensions: ['.css'],
+        pattern: /@font-face[^}]*url\(\s*['"]?https?:/gis,
+        message: 'A @font-face with an http(s) src is blocked by CSP (font-src data:) — inline the font as a base64 data: URI instead.',
+    },
+    {
+        name: 'no-sse',
+        pattern: /(?<![\w.])new\s+EventSource\s*\(/g,
+        message: 'EventSource/SSE is unavailable — the seq.api bridge is request/response only. Poll on an interval instead.',
+    },
+    {
+        name: 'no-websocket',
+        pattern: /(?<![\w.])new\s+WebSocket\s*\(/g,
+        message: 'WebSocket is unavailable in the sandbox — the seq.api bridge is request/response only. Poll on an interval instead.',
+    },
+    {
+        name: 'no-direct-external-fetch',
+        pattern: /(?<![\w.])fetch\s*\(\s*['"`]https?:\/\//g,
+        message: "Direct fetch() to an external origin is blocked (CSP connect-src 'self') — call Atlas routes via seq.api.fetch.",
+    },
+];
+const LINTABLE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.css', '.html']);
+function extensionOf(path) {
+    return path.includes('.') ? path.slice(path.lastIndexOf('.')) : '';
+}
+function lineNumberAt(content, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < content.length; i++) {
+        if (content[i] === '\n')
+            line += 1;
+    }
+    return line;
+}
+/** Scan artifact source for sandbox-incompatible APIs. Pure; safe to call often. */
+export function lintArtifactSandbox(files) {
+    const warnings = [];
+    for (const file of files) {
+        const ext = extensionOf(file.path);
+        if (!LINTABLE_EXTENSIONS.has(ext))
+            continue;
+        for (const rule of RULES) {
+            if (rule.extensions && !rule.extensions.includes(ext))
+                continue;
+            // Fresh lastIndex per file since the rule regexes are global/stateful.
+            rule.pattern.lastIndex = 0;
+            let match;
+            while ((match = rule.pattern.exec(file.content)) !== null) {
+                warnings.push({
+                    file: file.path,
+                    line: lineNumberAt(file.content, match.index),
+                    rule: rule.name,
+                    message: rule.message,
+                });
+                if (match.index === rule.pattern.lastIndex)
+                    rule.pattern.lastIndex += 1;
+            }
+        }
+    }
+    return warnings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+/** Print warnings to stderr in a compact, actionable form. Returns the count. */
+export function reportSandboxWarnings(warnings) {
+    if (warnings.length === 0)
+        return 0;
+    const noun = warnings.length === 1 ? 'warning' : 'warnings';
+    console.warn(`\n[seq-studio] ${warnings.length} sandbox ${noun} (these work in vite dev but fail in the deployed artifact):`);
+    for (const warning of warnings) {
+        console.warn(`  ${warning.file}:${warning.line}  [${warning.rule}] ${warning.message}`);
+    }
+    console.warn('  Reference: build-artifact-studio-app/references/sandbox-gotchas.md\n');
+    return warnings.length;
+}

package/dist/sanitize-remote-tree.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Install-control files that must never influence a remote `--repo` /
+ * `--git-url` install. seq-studio pins Chainguard registry + ignore-scripts
+ * itself; a committed `.npmrc` / workspace file / pnpm hook would either
+ * fail the trust check or let the artifact redirect resolution.
+ *
+ * We strip them from the *materialized temp tree* (not from the git repo)
+ * so a dirty historical tip can still deploy while authors clean main via
+ * a Pull that deletes the files for real.
+ *
+ * The hook/workspace matchers are shared with `assertTrustedArtifactInstallTree`
+ * so the strip set cannot drift from the reject set.
+ */
+export declare function listInstallControlFiles(dir: string, prefix?: string): string[];
+/**
+ * Delete install-control files from a materialized remote build root.
+ * Returns the relative paths that were removed (for logging).
+ */
+export declare function stripInstallControlFiles(dir: string): string[];

package/dist/sanitize-remote-tree.js

@@ -0,0 +1,52 @@
+import { existsSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { PNPM_HOOK_FILE_RE, PNPM_WORKSPACE_FILE_RE } from './trusted-install.js';
+/**
+ * Install-control files that must never influence a remote `--repo` /
+ * `--git-url` install. seq-studio pins Chainguard registry + ignore-scripts
+ * itself; a committed `.npmrc` / workspace file / pnpm hook would either
+ * fail the trust check or let the artifact redirect resolution.
+ *
+ * We strip them from the *materialized temp tree* (not from the git repo)
+ * so a dirty historical tip can still deploy while authors clean main via
+ * a Pull that deletes the files for real.
+ *
+ * The hook/workspace matchers are shared with `assertTrustedArtifactInstallTree`
+ * so the strip set cannot drift from the reject set.
+ */
+export function listInstallControlFiles(dir, prefix = '') {
+    const found = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (entry.name === 'node_modules' || entry.name === '.git')
+                continue;
+            found.push(...listInstallControlFiles(join(dir, entry.name), rel));
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        if (rel === '.npmrc' || rel.endsWith('/.npmrc'))
+            found.push(rel);
+        else if (PNPM_WORKSPACE_FILE_RE.test(rel))
+            found.push(rel);
+        else if (PNPM_HOOK_FILE_RE.test(rel))
+            found.push(rel);
+    }
+    return found;
+}
+/**
+ * Delete install-control files from a materialized remote build root.
+ * Returns the relative paths that were removed (for logging).
+ */
+export function stripInstallControlFiles(dir) {
+    const removed = [];
+    for (const rel of listInstallControlFiles(dir)) {
+        const abs = join(dir, rel);
+        if (!existsSync(abs))
+            continue;
+        unlinkSync(abs);
+        removed.push(rel);
+    }
+    return removed;
+}

package/dist/sdk.d.ts

@@ -36,10 +36,57 @@ export interface SequenceEnvironment {
 export interface SequenceAuth {
     hasPermission(permission: string): Promise<boolean>;
     getPermissions(): Promise<string[]>;
+    /**
+     * The current user's custom-role capabilities on THIS artifact (e.g.
+     * `['view', 'edit']` for a reporting tool), resolved server-side via the
+     * generic `/api/custom-roles/artifact/:projectId/resolve` endpoint. The host
+     * supplies the project id from its trusted context — artifacts cannot point
+     * this at another host. Distinct from `getPermissions()`, which returns the
+     * user's platform-wide permissions rather than per-artifact role grants.
+     * Rejects when the artifact has no project context or the user has no access
+     * to the host.
+     */
+    getCapabilities(): Promise<string[]>;
 }
 export interface SequenceFlags {
     isEnabled(flagName: string): Promise<boolean>;
 }
+/**
+ * The Lattice run/node/step this artifact is being served for. Populated by the
+ * embedding surface (the Lattice Inbox provides all four; the builder Artifacts
+ * tab has no live step). Each field is `null` when the artifact is not embedded
+ * in that surface — e.g. a standalone preview has no context at all.
+ */
+export interface SequenceLatticeContext {
+    /** The Lattice run the embed belongs to. */
+    runId: string | null;
+    /** The human node id the artifact is attached to (tells you which node you're serving). */
+    nodeId: string | null;
+    /** The specific step run (the assignee's task) — the step-scoped id reviewers hold access to. */
+    stepId: string | null;
+    /** The process the run belongs to. */
+    processId: string | null;
+}
+export interface SequenceLattice {
+    /**
+     * Read the embed context synchronously (no network round trip — the host
+     * injects it into the sandbox URL up front). Returns all-null fields when the
+     * artifact is not embedded in a Lattice surface.
+     */
+    context(): SequenceLatticeContext;
+}
+export interface SequenceHost {
+    /**
+     * Navigate the parent Atlas shell to an in-app route — e.g.
+     * `seq.host.navigate('/crm#/customers/<uid>')`. Fire-and-forget: the artifact
+     * sandbox cannot navigate the top frame itself (no `allow-top-navigation`),
+     * so this posts the request to the host, which validates it and drives the
+     * shell router. The host ignores anything that isn't a same-app relative
+     * path (must start with a single `/`), so an artifact can never push the
+     * user to an external origin.
+     */
+    navigate(path: string): void;
+}
 export interface SequenceArtifactSdk {
     api: SequenceApi;
     ai: {
@@ -50,6 +97,8 @@ export interface SequenceArtifactSdk {
     env: SequenceEnvironment;
     auth: SequenceAuth;
     flags: SequenceFlags;
+    lattice: SequenceLattice;
+    host: SequenceHost;
 }
 declare global {
     interface Window {

package/dist/source-resolver.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Build/deploy source is pluggable. A `deploy`/`build`/`plan` invocation reads
+ * its source tree from one of three places, all of which produce the same
+ * on-disk tree the rest of the pipeline (build → upload) already consumes:
+ *
+ *   - local folder (default, unchanged): `deploy [dir]`
+ *   - a platform git-service repo:        `deploy --repo <ns>/<name> [--ref <r>]`
+ *   - any external git URL:               `deploy --git-url <url> [--ref <r>]`
+ *
+ * Remote sources are materialized to a temp dir and torn down after the build.
+ */
+/** Provenance recorded on the deployment row (git_commit/git_branch/git_dirty). */
+export interface SourceProvenance {
+    gitCommit: string | null;
+    gitBranch: string | null;
+    gitDirty: boolean | null;
+}
+export type SourceSpec = {
+    kind: 'local';
+    dir: string;
+} | {
+    kind: 'git-service';
+    namespace: string;
+    name: string;
+    ref?: string;
+} | {
+    kind: 'git-url';
+    url: string;
+    ref?: string;
+};
+export interface ResolvedSource {
+    /** Absolute, canonical (realpath'd) directory the build should run against. */
+    dir: string;
+    /** True for --repo / --git-url materializations (bare tree, needs install). */
+    remote: boolean;
+    provenance: SourceProvenance;
+    /** Remove any temp materialization. No-op for a local source. Never throws. */
+    cleanup: () => Promise<void>;
+}
+export interface ParsedFlags {
+    positional: string[];
+    flags: Record<string, string | true>;
+}
+/** True for sources that must be fetched from a remote (git-service / git-url). */
+export declare function isRemoteSpec(spec: SourceSpec): boolean;
+/**
+ * Strip any userinfo (`user:token@`) from a git URL before it's logged or put
+ * in an error — an https git URL can carry a PAT in its authority, and leaking
+ * it to a terminal or CI log is a credential disclosure.
+ */
+export declare function redactGitUrl(url: string): string;
+/**
+ * Derive the source spec from parsed CLI args. Enforces mutual exclusivity:
+ * a `[dir]` positional, `--repo`, and `--git-url` are three ways to name the
+ * same input, so at most one may be given.
+ */
+export declare function parseSourceSpec(input: ParsedFlags): SourceSpec;
+/**
+ * Resolve a spec to an on-disk source directory + provenance. For git-service
+ * the caller must supply `baseUrl` + `token`; git-url needs neither (it shells
+ * out to `git clone`); local needs nothing.
+ */
+export declare function resolveArtifactSource(spec: SourceSpec, opts?: {
+    baseUrl?: string;
+    token?: string | null;
+}): Promise<ResolvedSource>;
+/** Working-tree git provenance for a local source (current behavior). */
+export declare function localGitMetadata(dir: string): SourceProvenance;

package/dist/source-resolver.js

@@ -0,0 +1,203 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, rmSync } from 'node:fs';
+import { mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { materializeRepo, resolveCommitSha, resolveRepo } from './git-service-client.js';
+import { gitServiceCloneUrl, resolveGitPatFromEnv, runGitClone } from './git-clone.js';
+/** True for sources that must be fetched from a remote (git-service / git-url). */
+export function isRemoteSpec(spec) {
+    return spec.kind !== 'local';
+}
+/**
+ * Strip any userinfo (`user:token@`) from a git URL before it's logged or put
+ * in an error — an https git URL can carry a PAT in its authority, and leaking
+ * it to a terminal or CI log is a credential disclosure.
+ */
+export function redactGitUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.username || parsed.password) {
+            parsed.username = '';
+            parsed.password = '';
+            return parsed.toString();
+        }
+        return url;
+    }
+    catch {
+        // Non-standard form (e.g. scp-like git@host:path) — drop a scheme://user@ prefix if present.
+        return url.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@]*@/i, '$1');
+    }
+}
+function flagString(flags, key) {
+    const value = flags[key];
+    if (value === true)
+        throw new Error(`--${key} requires a value.`);
+    return value;
+}
+/**
+ * Derive the source spec from parsed CLI args. Enforces mutual exclusivity:
+ * a `[dir]` positional, `--repo`, and `--git-url` are three ways to name the
+ * same input, so at most one may be given.
+ */
+export function parseSourceSpec(input) {
+    const repo = flagString(input.flags, 'repo');
+    const gitUrl = flagString(input.flags, 'git-url');
+    const ref = flagString(input.flags, 'ref');
+    const dir = input.positional[0];
+    if (repo && gitUrl)
+        throw new Error('Pass only one of --repo or --git-url.');
+    if ((repo || gitUrl) && dir)
+        throw new Error('A [dir] argument cannot be combined with --repo / --git-url.');
+    if (ref && !repo && !gitUrl)
+        throw new Error('--ref only applies together with --repo or --git-url.');
+    if (ref && ref.startsWith('-'))
+        throw new Error(`--ref must not start with "-" (got "${ref}").`);
+    if (repo) {
+        const parts = repo.split('/');
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            throw new Error(`--repo must be "<namespace>/<name>" (got "${repo}").`);
+        }
+        return { kind: 'git-service', namespace: parts[0], name: parts[1], ref };
+    }
+    if (gitUrl) {
+        // Guard against argument injection: git treats a leading-dash URL as a flag.
+        if (gitUrl.startsWith('-'))
+            throw new Error(`--git-url must be a URL, not a flag (got "${gitUrl}").`);
+        return { kind: 'git-url', url: gitUrl, ref };
+    }
+    return { kind: 'local', dir: resolve(dir ?? '.') };
+}
+/**
+ * Resolve a spec to an on-disk source directory + provenance. For git-service
+ * the caller must supply `baseUrl` + `token`; git-url needs neither (it shells
+ * out to `git clone`); local needs nothing.
+ */
+export async function resolveArtifactSource(spec, opts = {}) {
+    if (spec.kind === 'local') {
+        return { dir: spec.dir, remote: false, provenance: localGitMetadata(spec.dir), cleanup: async () => { } };
+    }
+    const dest = await makeTempDir();
+    const cleanup = () => removeDir(dest);
+    try {
+        if (spec.kind === 'git-service') {
+            if (!opts.baseUrl || !opts.token) {
+                throw new Error('Deploying from --repo needs a target environment and auth. ' +
+                    'Pass --env and run `seq-studio login`.');
+            }
+            // resolveRepo + resolveCommitSha use the Auth0/M2M token: the clone URL
+            // is id-addressed (no by-path endpoint), and we pin the build to the
+            // resolved SHA — the same commit recorded as provenance — rather than the
+            // mutable ref, matching the prior materialize behavior.
+            const repo = await resolveRepo({ baseUrl: opts.baseUrl, token: opts.token, namespace: spec.namespace, name: spec.name });
+            const ref = spec.ref ?? repo.defaultBranch;
+            const sha = await resolveCommitSha({ baseUrl: opts.baseUrl, token: opts.token, repoId: repo.id, ref });
+            // Human path: materialize via a smart-HTTP `git clone` (one pack
+            // transfer). The earlier per-blob JSON walk was O(files) serial HTTP
+            // round-trips and stalled/failed on large artifacts. Smart-HTTP
+            // authenticates by PAT (Basic-auth password), NOT the Auth0 bearer — the
+            // same token you clone the repo with. No PAT, no git workflow.
+            const pat = resolveGitPatFromEnv();
+            if (pat) {
+                const cloneUrl = gitServiceCloneUrl(opts.baseUrl, repo.id);
+                await runGitClone({ cloneUrl, destDir: dest, pat, ref: sha });
+                console.log(`[seq-studio] source: ${spec.namespace}/${spec.name}@${ref} (${sha.slice(0, 10)}, git clone)`);
+                return { dir: dest, remote: true, provenance: { gitCommit: sha, gitBranch: ref, gitDirty: false }, cleanup };
+            }
+            // CI/system path: the trusted M2M service account can't own a PAT (PAT
+            // issuance is gated on a human Auth0 user row), so it keeps the JSON
+            // materialize path it has always used, authenticated by its M2M token.
+            // Interactive callers (no PAT, no M2M) fall through to the hard error.
+            // TODO: teach the git-service smart-HTTP endpoint to accept the trusted
+            // M2M identity so CI can use the fast clone path too.
+            if (process.env.AUTH0_M2M_CLIENT_SECRET?.trim()) {
+                const count = await materializeRepo({ baseUrl: opts.baseUrl, token: opts.token, repoId: repo.id, ref: sha, destDir: dest });
+                console.log(`[seq-studio] source: ${spec.namespace}/${spec.name}@${ref} (${sha.slice(0, 10)}, ${count} file(s), M2M)`);
+                return { dir: dest, remote: true, provenance: { gitCommit: sha, gitBranch: ref, gitDirty: false }, cleanup };
+            }
+            throw new Error('Deploying from --repo requires a git PAT. Set ATLAS_GIT_PAT to a token with the ' +
+                'repo:read scope (create one in Atlas → Settings → Tokens, or `seq-studio auth pat create`). ' +
+                'The git-service clone uses smart-HTTP, which authenticates by PAT — the same token you clone the repo with.');
+        }
+        const { sha, branch } = cloneGitUrl(spec.url, spec.ref, dest);
+        console.log(`[seq-studio] source: ${redactGitUrl(spec.url)}${spec.ref ? `@${spec.ref}` : ''} (${sha.slice(0, 10)})`);
+        return { dir: dest, remote: true, provenance: { gitCommit: sha, gitBranch: branch, gitDirty: false }, cleanup };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+/** Working-tree git provenance for a local source (current behavior). */
+export function localGitMetadata(dir) {
+    const gitOpts = {
+        cwd: dir,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    };
+    try {
+        const gitCommit = String(execFileSync('git', ['rev-parse', 'HEAD'], gitOpts)).trim();
+        const gitBranch = String(execFileSync('git', ['branch', '--show-current'], gitOpts)).trim();
+        const gitDirty = String(execFileSync('git', ['status', '--porcelain'], gitOpts)).trim().length > 0;
+        return { gitCommit, gitBranch, gitDirty };
+    }
+    catch {
+        return { gitCommit: null, gitBranch: null, gitDirty: null };
+    }
+}
+async function makeTempDir() {
+    const dir = await mkdtemp(join(tmpdir(), 'artifact-src-'));
+    // Canonicalize: the Vite html plugin emits the entry file name relative to
+    // process.cwd() and rejects `..` segments. os.tmpdir() resolves through
+    // symlinks on macOS (/tmp -> /private/tmp, /var -> /private/var), so without
+    // realpath the build root and the realpath'd html input mismatch and the
+    // build fails with a "must not be a relative path" error.
+    return realpath(dir);
+}
+async function removeDir(dir) {
+    try {
+        await rm(dir, { recursive: true, force: true });
+    }
+    catch (error) {
+        console.warn(`[seq-studio] could not remove temp source dir ${dir}: ${error instanceof Error ? error.message : error}`);
+    }
+}
+function cloneGitUrl(url, ref, dest) {
+    const opts = {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        encoding: 'utf8',
+    };
+    const git = (args) => String(execFileSync('git', args, opts)).trim();
+    try {
+        if (ref) {
+            try {
+                // Fast path: shallow single-branch clone (works for a branch or tag).
+                git(['clone', '--depth', '1', '--single-branch', '--branch', ref, '--', url, dest]);
+            }
+            catch {
+                // A commit SHA can't be `--branch`ed — full clone, then checkout. Reset
+                // the destination first: a failed shallow attempt can leave partial
+                // contents, which would make `git clone` reject a non-empty directory.
+                rmSync(dest, { recursive: true, force: true });
+                mkdirSync(dest, { recursive: true });
+                git(['clone', '--', url, dest]);
+                git(['-C', dest, 'checkout', ref]);
+            }
+        }
+        else {
+            git(['clone', '--depth', '1', '--', url, dest]);
+        }
+    }
+    catch (error) {
+        // Never surface the raw URL — an https git URL can carry a PAT in userinfo.
+        // Scrub any occurrence of it from git's stderr/message too.
+        const safeUrl = redactGitUrl(url);
+        const detail = error.stderr?.trim() || (error instanceof Error ? error.message : String(error));
+        const safeDetail = detail.split(url).join(safeUrl);
+        throw new Error(`git clone failed for ${safeUrl}${ref ? `@${ref}` : ''}: ${safeDetail}`);
+    }
+    const sha = git(['-C', dest, 'rev-parse', 'HEAD']);
+    const abbrev = git(['-C', dest, 'rev-parse', '--abbrev-ref', 'HEAD']);
+    const branch = ref ?? (abbrev && abbrev !== 'HEAD' ? abbrev : null);
+    return { sha, branch };
+}