@sequenceholdings/artifact-studio 0.1.6 → 0.1.9

package/dist/cli.js

@@ -1,33 +1,54 @@
 import { cp, mkdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { execFileSync } from 'node:child_process';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getJson, getJsonOr404, postJson } from './api.js';
 import { readLocalConfig, resolveEnvironment, writeLocalConfig, writeTokenConfig, } from './config.js';
 import { buildArtifactStudioProject, writeBuildArtifact } from './build.js';
+import { buildArtifactStudioProjectIsolated } from './build-subprocess.js';
+import { prepareArtifactBuildRoot } from './prepare-build.js';
+import { parseArtifactStudioManifest } from './manifest.js';
 import { hasArtifactStudioManifest, readArtifactStudioSource } from './project.js';
+import { localGitMetadata, parseSourceSpec, resolveArtifactSource, } from './source-resolver.js';
 import { getAccessToken, loginWithPkce } from './auth.js';
+import { acquireDevLock } from './dev-lock.js';
+import { runWatchLoop } from './watch-loop.js';
+import { hashLinkedSources, parseLinks, rebuildLinkedDep, resolveLinkedDeps, syncLinkedDist, } from './dev-link.js';
+import { lintArtifactSandbox, reportSandboxWarnings } from './sandbox-lint.js';
+import yaml from 'js-yaml';
 const COMMANDS = [
-    'init', 'login', 'logout', 'whoami', 'link', 'env', 'status',
+    'init', 'login', 'logout', 'whoami', 'link', 'env', 'status', 'list', 'show',
     'validate', 'build', 'plan', 'deploy', 'dev', 'promote', 'pull', 'rollback',
 ];
 const USAGE = `usage:
-  artifact-studio init <dir>
-  artifact-studio login [--token <token>]
-  artifact-studio logout
-  artifact-studio whoami --env <env>
-  artifact-studio link --env <env> [--project <id>]
-  artifact-studio env list|use <env>
-  artifact-studio status [--env <env>]
-  artifact-studio validate [dir]
-  artifact-studio build [dir] [--out dist/artifact-bundle.json]
-  artifact-studio plan [dir] --env <env>
-  artifact-studio deploy [dir] --env <env>
-  artifact-studio dev [dir] --env <env> [--once] [--key default]
-  artifact-studio promote <deployment-id> --env <env>
-  artifact-studio pull <project-id> --env <env> --out <dir>
-  artifact-studio rollback <deployment-id> --env <env>`;
+  seq-studio artifact init <dir>
+  seq-studio artifact whoami --env <env>
+  seq-studio artifact link --env <env> [--project <id>]
+  seq-studio artifact env list|use <env>
+  seq-studio artifact status [--env <env>]
+  seq-studio artifact list --env <env>
+  seq-studio artifact show <slug-or-id> --env <env>
+  seq-studio artifact validate [dir]
+  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 promote <deployment-id> --env <env>
+  seq-studio artifact pull <project-id> --env <env> --out <dir>
+  seq-studio artifact rollback <deployment-id> --env <env>
+
+  Source: a local [dir] (default), a platform git-service repo (--repo <ns>/<name>),
+  or any 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
+  artifact.bundle.yml project_id.
+
+  --repo clones over smart-HTTP and REQUIRES a git PAT in ATLAS_GIT_PAT
+  (repo:read scope) — create one with \`seq-studio auth pat create --scopes
+  repo:read\` or in Atlas → Settings → Tokens. It's the same token you clone the
+  repo with. (--env + seqapi login are still needed to resolve the repo and
+  upload the deployment.)
+
+  Authenticate with: seqapi login`;
 export async function runCli(argv = process.argv.slice(2)) {
     const parsed = parseArgs(argv);
     if ('error' in parsed) {
@@ -42,6 +63,8 @@ export async function runCli(argv = process.argv.slice(2)) {
         case 'link': return linkCommand(parsed);
         case 'env': return envCommand(parsed);
         case 'status': return statusCommand(parsed);
+        case 'list': return listCommand(parsed);
+        case 'show': return showCommand(parsed);
         case 'validate': return validateCommand(parsed);
         case 'build': return buildCommand(parsed);
         case 'plan': return planCommand(parsed);
@@ -92,24 +115,24 @@ async function initCommand(args) {
     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);
-    console.log(`[artifact-studio] initialized ${dir}`);
-    console.log('Next: artifact-studio login && artifact-studio dev --env staging');
+    console.log(`[seq-studio] initialized ${dir}`);
+    console.log('Next: seqapi login && seq-studio artifact dev --env staging');
     return 0;
 }
 async function loginCommand(args) {
     const token = typeof args.flags.token === 'string' ? args.flags.token : undefined;
     if (token) {
         await writeTokenConfig({ accessToken: token });
-        console.log('[artifact-studio] saved access token');
+        console.log('[seq-studio] saved access token');
         return 0;
     }
     await loginWithPkce();
-    console.log('[artifact-studio] logged in');
+    console.log('[seq-studio] logged in');
     return 0;
 }
 async function logoutCommand() {
     await writeTokenConfig({});
-    console.log('[artifact-studio] logged out');
+    console.log('[seq-studio] logged out');
     return 0;
 }
 async function whoamiCommand(args) {
@@ -120,8 +143,24 @@ async function whoamiCommand(args) {
         token,
         path: '/api/auth/me',
     }).catch(async () => {
-        const projects = await getJson({ baseUrl: env.url, token, path: '/api/artifact-studio/projects' });
-        return { subject: `authenticated (${projects.projects.length} visible project(s))` };
+        const projects = await getJson({
+            baseUrl: env.url,
+            token,
+            path: '/api/artifact-studio/projects',
+        });
+        const slugs = projects.projects
+            .map((p) => p.slug)
+            .filter((slug) => typeof slug === 'string' && slug.length > 0);
+        const preview = slugs.slice(0, 5);
+        const more = slugs.length > preview.length
+            ? ` (+${slugs.length - preview.length} more — run seq-studio artifact list -e ${env.name})`
+            : slugs.length === 0
+                ? ` — run seq-studio artifact list -e ${env.name}`
+                : '';
+        const slugPart = preview.length > 0 ? `: ${preview.join(', ')}` : '';
+        return {
+            subject: `authenticated (${slugs.length} visible project(s)${slugPart}${more})`,
+        };
     });
     console.log('user' in data ? (data.user?.email ?? data.user?.sub ?? 'authenticated') : data.subject);
     return 0;
@@ -159,7 +198,7 @@ async function linkCommand(args) {
         defaultEnv: env.name,
         previewKey: 'default',
     }, dir);
-    console.log(`[artifact-studio] linked ${project.title} (${project.id})`);
+    console.log(`[seq-studio] linked ${project.title} (${project.id})`);
     return 0;
 }
 async function envCommand(args) {
@@ -172,10 +211,10 @@ async function envCommand(args) {
         const env = resolveEnvironment(value);
         const config = await readLocalConfig();
         await writeLocalConfig({ ...config, defaultEnv: env.name });
-        console.log(`[artifact-studio] default env set to ${env.name}`);
+        console.log(`[seq-studio] default env set to ${env.name}`);
         return 0;
     }
-    console.error('artifact-studio env list|use <env>');
+    console.error('seq-studio artifact env list|use <env>');
     return 1;
 }
 async function statusCommand(args) {
@@ -194,75 +233,292 @@ async function statusCommand(args) {
     }
     return 0;
 }
+async function listCommand(args) {
+    const env = await envFromArgs(args);
+    const token = await getRequiredToken(args);
+    const data = await getJson({
+        baseUrl: env.url,
+        token,
+        path: '/api/artifact-studio/projects',
+    });
+    if (data.projects.length === 0) {
+        console.log(`[seq-studio] no artifact projects visible on ${env.name}`);
+        return 0;
+    }
+    const sorted = [...data.projects].sort((a, b) => a.slug.localeCompare(b.slug));
+    console.log(`[seq-studio] ${sorted.length} project${sorted.length === 1 ? '' : 's'} on ${env.name}:`);
+    for (const project of sorted) {
+        // Rows can carry activeDeploymentId with the deployment detail nulled
+        // (the serializer masks it for reduced-access rows) — label those
+        // "deployed" rather than falsely claiming "not deployed".
+        const active = project.activeDeployment
+            ? project.activeDeployment.version
+            : project.activeDeploymentId
+                ? 'deployed'
+                : 'not deployed';
+        const visibility = project.visibility ? `  ${project.visibility}` : '';
+        console.log(`  ${project.slug}  id=${project.id}  [${active}]${visibility}  ${project.title}`);
+    }
+    return 0;
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function showCommand(args) {
+    const ref = args.positional[0];
+    if (!ref) {
+        console.error('usage: seq-studio artifact show <slug-or-id> --env <env>');
+        return 1;
+    }
+    const env = await envFromArgs(args);
+    const token = await getRequiredToken(args);
+    // A UUID targets the project directly; anything else resolves by slug (hard
+    // error on cross-owner duplicates, same rule as deploy's slug resolution).
+    let projectId = ref;
+    if (!UUID_RE.test(ref)) {
+        const bySlug = await fetchRemoteProject({
+            env: env.url,
+            token,
+            slug: ref,
+            disambiguator: 'pass the project id instead: `seq-studio artifact show <id> --env <env>`.',
+        });
+        if (!bySlug) {
+            console.error(`[seq-studio] no project with slug "${ref}" on ${env.name}`);
+            return 1;
+        }
+        projectId = bySlug.id;
+    }
+    const data = await getJsonOr404({
+        baseUrl: env.url,
+        token,
+        path: `/api/artifact-studio/projects/${projectId}`,
+    });
+    if (!data) {
+        console.error(`[seq-studio] project ${projectId} not found on ${env.name}`);
+        return 1;
+    }
+    const project = data.project;
+    console.log(`[seq-studio] project on ${env.name}:`);
+    console.log(`  id:          ${project.id}`);
+    console.log(`  slug:        ${project.slug}`);
+    console.log(`  title:       ${project.title}`);
+    if (project.description)
+        console.log(`  description: ${project.description}`);
+    if (project.visibility)
+        console.log(`  visibility:  ${project.visibility}`);
+    if (project.appEligible !== undefined)
+        console.log(`  appEligible: ${project.appEligible ? 'yes' : 'no'}`);
+    if (project.createdBy)
+        console.log(`  createdBy:   ${project.createdBy}`);
+    if (project.updatedAt)
+        console.log(`  updated:     ${project.updatedAt}`);
+    const deployment = project.activeDeployment;
+    if (deployment) {
+        console.log(`  active deployment:`);
+        console.log(`    version:    ${deployment.version}`);
+        console.log(`    sourceHash: ${deployment.sourceHash}`);
+        if (deployment.gitCommit) {
+            const dirty = deployment.gitDirty ? ' (dirty)' : '';
+            const branch = deployment.gitBranch ? ` on ${deployment.gitBranch}` : '';
+            console.log(`    git:        ${deployment.gitCommit.slice(0, 12)}${branch}${dirty}`);
+        }
+        if (deployment.deployMessage)
+            console.log(`    message:    ${deployment.deployMessage}`);
+        if (deployment.createdAt)
+            console.log(`    deployedAt: ${deployment.createdAt}`);
+        if (deployment.createdBy)
+            console.log(`    deployedBy: ${deployment.createdBy}`);
+    }
+    else {
+        console.log(`  active deployment: none`);
+    }
+    return 0;
+}
 async function validateCommand(args) {
     const dir = resolve(args.positional[0] ?? '.');
     const source = await readArtifactStudioSource(dir);
-    console.log(`[artifact-studio] valid ${source.manifest.bundle.name}`);
-    console.log(`[artifact-studio] files: ${source.files.length}`);
-    console.log(`[artifact-studio] source: ${source.sourceHash}`);
+    console.log(`[seq-studio] valid ${source.manifest.bundle.name}`);
+    console.log(`[seq-studio] files: ${source.files.length}`);
+    console.log(`[seq-studio] source: ${source.sourceHash}`);
+    reportSandboxWarnings(lintArtifactSandbox(source.files));
     return 0;
 }
+async function buildPreparedArtifactSource(source) {
+    await prepareArtifactBuildRoot(source.dir, { remote: source.remote });
+    return buildArtifactStudioProject(source.dir);
+}
 async function buildCommand(args) {
-    const dir = resolve(args.positional[0] ?? '.');
-    const result = await buildArtifactStudioProject(dir);
-    const out = typeof args.flags.out === 'string' ? resolve(args.flags.out) : resolve(dir, 'dist', 'artifact-bundle.json');
-    await writeBuildArtifact(result, out);
-    console.log(`[artifact-studio] built ${result.manifest.bundle.name}`);
-    console.log(`[artifact-studio] source: ${result.sourceHash}`);
-    console.log(`[artifact-studio] bundle: ${result.bundleHash}`);
-    console.log(`[artifact-studio] wrote ${out}`);
-    return 0;
+    const spec = parseSourceSpec(args);
+    // build is offline for a local/git-url source; only a git-service source
+    // needs an env + token to fetch the tree.
+    const remote = spec.kind === 'git-service'
+        ? { baseUrl: (await envFromArgs(args)).url, token: await getRequiredToken(args) }
+        : {};
+    const source = await resolveArtifactSource(spec, remote);
+    try {
+        const result = await buildPreparedArtifactSource(source);
+        // A remote source's dir is a temp dir we tear down below, so default the
+        // bundle output next to the cwd rather than into the throwaway tree.
+        const defaultOutDir = spec.kind === 'local' ? source.dir : process.cwd();
+        const out = typeof args.flags.out === 'string' ? resolve(args.flags.out) : resolve(defaultOutDir, 'dist', 'artifact-bundle.json');
+        await writeBuildArtifact(result, out);
+        console.log(`[seq-studio] built ${result.manifest.bundle.name}`);
+        console.log(`[seq-studio] source: ${result.sourceHash}`);
+        console.log(`[seq-studio] bundle: ${result.bundleHash}`);
+        console.log(`[seq-studio] wrote ${out}`);
+        reportSandboxWarnings(lintArtifactSandbox(result.files));
+        return 0;
+    }
+    finally {
+        await source.cleanup();
+    }
 }
 async function planCommand(args) {
-    const dir = resolve(args.positional[0] ?? '.');
     const env = await envFromArgs(args);
     const token = await getOptionalToken(args);
-    const result = await buildArtifactStudioProject(dir);
-    console.log(`[artifact-studio] plan ${result.manifest.artifact.project_id} -> ${env.name}`);
-    console.log(`  source: ${result.sourceHash}`);
-    console.log(`  bundle: ${result.bundleHash}`);
-    if (!token) {
-        console.log('  remote: skipped (run artifact-studio login)');
+    const spec = parseSourceSpec(args);
+    const source = await resolveArtifactSource(spec, { baseUrl: env.url, token });
+    try {
+        const result = await buildPreparedArtifactSource(source);
+        console.log(`[seq-studio] plan ${result.manifest.artifact.project_id} -> ${env.name}`);
+        console.log(`  source: ${result.sourceHash}`);
+        console.log(`  bundle: ${result.bundleHash}`);
+        if (!token) {
+            console.log('  remote: skipped (run seqapi login)');
+            return 0;
+        }
+        const remote = await fetchRemoteProject({ env: env.url, token, slug: result.manifest.artifact.project_id });
+        if (!remote)
+            console.log('  action: create project and deploy');
+        else if (remote.activeDeployment?.sourceHash === result.sourceHash)
+            console.log('  action: no-op');
+        else
+            console.log(`  action: deploy over ${remote.activeDeployment?.version ?? 'no active deployment'}`);
         return 0;
     }
-    const remote = await fetchRemoteProject({ env: env.url, token, slug: result.manifest.artifact.project_id });
-    if (!remote)
-        console.log('  action: create project and deploy');
-    else if (remote.activeDeployment?.sourceHash === result.sourceHash)
-        console.log('  action: no-op');
-    else
-        console.log(`  action: deploy over ${remote.activeDeployment?.version ?? 'no active deployment'}`);
-    return 0;
+    finally {
+        await source.cleanup();
+    }
 }
 async function deployCommand(args) {
-    const dir = resolve(args.positional[0] ?? '.');
     const env = await envFromArgs(args);
     const token = await getRequiredToken(args);
-    const result = await buildArtifactStudioProject(dir);
-    const project = await ensureRemoteProject({ env: env.url, token, result, dir });
-    const deployment = await uploadDeployment({ env: env.url, token, projectId: project.id, result, channel: 'active', dir });
-    console.log(`[artifact-studio] deployed ${project.title} ${deployment.version}`);
-    console.log(`${env.url}/artifact-studio/projects/${project.id}/deployments/${deployment.id}`);
-    return 0;
+    const spec = parseSourceSpec(args);
+    const explicitProjectId = typeof args.flags.project === 'string' ? args.flags.project : null;
+    const source = await resolveArtifactSource(spec, { baseUrl: env.url, token });
+    try {
+        // --skip-unchanged: hash the raw source (no build needed) and no-op when
+        // the remote active deployment already matches. Lets CI redeploy every
+        // artifact on every release without paying a vite build + upload for the
+        // unchanged ones. sourceHash covers manifest + all source files, so any
+        // real change falls through to a full deploy.
+        if (args.flags['skip-unchanged'] === true) {
+            const unbuilt = await readArtifactStudioSource(source.dir);
+            const slug = unbuilt.manifest.artifact.project_id;
+            const remote = explicitProjectId
+                ? (await getJsonOr404({ baseUrl: env.url, token, path: `/api/artifact-studio/projects/${explicitProjectId}` }))?.project ?? null
+                : await fetchRemoteProject({ env: env.url, token, slug });
+            if (remote?.activeDeployment?.sourceHash === unbuilt.sourceHash) {
+                console.log(`[seq-studio] ${slug} unchanged on ${env.name} ` +
+                    `(active ${remote.activeDeployment.version} matches source ${unbuilt.sourceHash.slice(0, 12)}) — skipping deploy`);
+                return 0;
+            }
+        }
+        const result = await buildPreparedArtifactSource(source);
+        warnIfInlinedManifestDriftsFromBundle(result);
+        // Local sources read/write the project link in their working dir; remote
+        // sources resolve strictly by manifest project_id (never a stray config.json
+        // in the materialized tree), so pass null.
+        const project = await ensureRemoteProject({
+            env: env.url,
+            token,
+            result,
+            linkConfigDir: spec.kind === 'local' ? source.dir : null,
+            allowCreate: args.flags['no-create'] !== true,
+            explicitProjectId,
+        });
+        const deployment = await uploadDeployment({ env: env.url, token, projectId: project.id, result, channel: 'active', provenance: source.provenance });
+        console.log(`[seq-studio] deployed ${project.title} ${deployment.version}`);
+        console.log(`${env.url}/artifact-studio/projects/${project.id}/deployments/${deployment.id}`);
+        return 0;
+    }
+    finally {
+        await source.cleanup();
+    }
 }
 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 token = await 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
+    // elapses.
+    await getRequiredToken(args);
     const config = await readLocalConfig(dir);
     const previewKey = typeof args.flags.key === 'string' ? args.flags.key : config.previewKey ?? 'default';
     const once = args.flags.once === true;
+    const controller = new AbortController();
     let projectId = null;
     let lastSourceHash = null;
+    let lastDepsHash = null;
     let buildCount = 0;
+    // `--link` lets the watcher rebuild local source packages (e.g. atlas-ui) and
+    // refresh the artifact automatically, instead of the rebuild/reinstall/restart
+    // dance. Resolved once up front so a bad path fails fast.
+    const linkedDeps = resolveLinkedDeps({ links: parseLinks(args.flags.link) });
+    for (const dep of linkedDeps) {
+        const where = relative(process.cwd(), dep.dir) || '.';
+        console.log(`[seq-studio] linked ${dep.name} ← ${where}${dep.inPlace ? ' (in place)' : ''}`);
+    }
+    // Rebuild any linked package whose source changed and copy its dist into the
+    // location the artifact build resolves it from. Returns true when a rebuild
+    // happened so the caller forces an artifact rebuild even if its own source is
+    // unchanged (the artifact source hash doesn't cover dependency dist).
+    async function syncLinkedDeps() {
+        if (linkedDeps.length === 0)
+            return false;
+        const depsHash = await hashLinkedSources(linkedDeps);
+        if (depsHash === lastDepsHash)
+            return false;
+        for (const dep of linkedDeps) {
+            console.log(`[seq-studio] rebuilding ${dep.name}…`);
+            await rebuildLinkedDep(dep, controller.signal);
+            await syncLinkedDist(dep);
+        }
+        // Record the hash only after every linked dep rebuilt + synced successfully,
+        // so a failed rebuild leaves the hash stale and the next tick retries instead
+        // of going quiet until the source changes again.
+        lastDepsHash = depsHash;
+        return true;
+    }
     async function pushPreview() {
-        const result = await buildArtifactStudioProject(dir);
-        if (result.sourceHash === lastSourceHash)
+        // Rebuild linked source packages first; a dep change forces the artifact
+        // rebuild below even when the artifact's own source is untouched.
+        const depsChanged = await syncLinkedDeps();
+        // Cheap in-process change detection (fs read + hash, no Vite) so we only
+        // pay for the expensive build when the source actually changed.
+        const { sourceHash } = await readArtifactStudioSource(dir);
+        if (!depsChanged && sourceHash === lastSourceHash)
+            return;
+        // Run the real build in a short-lived child process: repeated in-process
+        // Vite builds leak memory that GC can't reclaim and eventually OOM a
+        // long-running watch. Isolating each build keeps memory flat. The signal
+        // reaps the child if the watcher is shutting down mid-build.
+        const result = await buildArtifactStudioProjectIsolated(dir, { signal: controller.signal });
+        warnIfInlinedManifestDriftsFromBundle(result);
+        // The tree can change between the cheap pre-read above and the build
+        // finishing — including reverting back to the last-shipped snapshot. Trust
+        // the authoritative build hash and skip the redundant preview push when the
+        // source is unchanged — unless a linked dep changed, where the artifact
+        // source hash is identical but the bundled dependency code is not.
+        if (!depsChanged && result.sourceHash === lastSourceHash)
             return;
-        lastSourceHash = result.sourceHash;
         buildCount += 1;
+        // Resolve per push so the token refreshes across a long watch session.
+        const token = await getRequiredToken(args);
         if (!projectId) {
-            const project = await ensureRemoteProject({ env: env.url, token, result, dir });
+            const project = await ensureRemoteProject({ env: env.url, token, result, linkConfigDir: dir });
             projectId = project.id;
         }
         const deployment = await uploadDeployment({
@@ -272,25 +528,90 @@ async function devCommand(args) {
             result,
             channel: 'preview',
             previewKey,
-            dir,
+            provenance: localGitMetadata(dir),
             message: `Preview push ${buildCount}`,
         });
-        console.log(`[artifact-studio] preview ${deployment.version}`);
+        // Mark this source as shipped only after the upload succeeds, so a failed
+        // build/upload leaves lastSourceHash stale and the next tick retries.
+        lastSourceHash = result.sourceHash;
+        console.log(`[seq-studio] preview ${deployment.version}`);
         console.log(`${env.url}/artifact-studio/projects/${projectId}/preview?key=${encodeURIComponent(previewKey)}`);
     }
-    await pushPreview();
-    if (once)
+    // Best-effort liveness/build status to the dev server, so the preview page can
+    // show "live / watcher offline / build failed" instead of a fake spinner.
+    // Fire-and-forget: a heartbeat failure must never disrupt the watch loop.
+    async function sendHeartbeat(status) {
+        if (!projectId)
+            return;
+        try {
+            const token = await getRequiredToken(args);
+            await postJson({
+                baseUrl: env.url,
+                token,
+                path: `/api/artifact-studio/projects/${projectId}/preview-status?previewKey=${encodeURIComponent(previewKey)}`,
+                body: { buildOk: status.buildOk, error: status.error },
+            });
+        }
+        catch {
+            // ignore — dev telemetry only
+        }
+    }
+    // Run one build/push and report status. Build failure is captured (not thrown)
+    // so the heartbeat still goes out as buildOk=false with the error message.
+    async function tickWithHeartbeat() {
+        let buildOk = true;
+        let buildError = null;
+        try {
+            await pushPreview();
+        }
+        catch (error) {
+            buildOk = false;
+            buildError = error instanceof Error ? error.message : String(error);
+            console.error(buildError);
+        }
+        await sendHeartbeat({ buildOk, error: buildError });
+    }
+    // Surface sandbox traps once at startup (not per rebuild — that would spam the
+    // watch log). Re-run `dev`/`build`/`validate` to re-check after edits.
+    try {
+        const initial = await readArtifactStudioSource(dir);
+        reportSandboxWarnings(lintArtifactSandbox(initial.files));
+    }
+    catch {
+        // A malformed source surfaces its real error from the build below.
+    }
+    // One-shot push: no watcher, no lock.
+    if (once) {
+        await pushPreview();
         return 0;
-    console.log('[artifact-studio] watching for changes. Press Ctrl+C to stop.');
-    await new Promise((resolvePromise) => {
-        const interval = setInterval(() => {
-            pushPreview().catch((error) => console.error(error instanceof Error ? error.message : error));
-        }, 1500);
-        process.on('SIGINT', () => {
-            clearInterval(interval);
-            resolvePromise();
+    }
+    // Single-instance guard: stop any watcher already running for this project and
+    // take over, so re-running `dev` never orphans a watcher that keeps racing on
+    // the shared token file.
+    const releaseLock = await acquireDevLock({ dir, previewKey });
+    const shutdown = (exitSignal) => {
+        controller.abort();
+        releaseLock();
+        if (exitSignal)
+            process.exit(0);
+    };
+    process.once('SIGINT', () => shutdown('SIGINT'));
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+    process.once('exit', () => releaseLock());
+    try {
+        await pushPreview();
+        await sendHeartbeat({ buildOk: true, error: null });
+        console.log('[seq-studio] watching for changes. Press Ctrl+C to stop.');
+        await runWatchLoop({
+            tick: tickWithHeartbeat,
+            intervalMs: 1500,
+            signal: controller.signal,
+            onError: (error) => console.error(error instanceof Error ? error.message : error),
         });
-    });
+    }
+    finally {
+        releaseLock();
+    }
     return 0;
 }
 async function promoteCommand(args) {
@@ -301,14 +622,14 @@ async function promoteCommand(args) {
     const token = await getRequiredToken(args);
     const config = await readLocalConfig();
     if (!config.projectId)
-        throw new Error('Project is not linked. Run artifact-studio link.');
+        throw new Error('Project is not linked. Run seq-studio artifact link.');
     await postJson({
         baseUrl: env.url,
         token,
         path: `/api/artifact-studio/projects/${config.projectId}/deployments/${deploymentId}/promote`,
         body: {},
     });
-    console.log(`[artifact-studio] promoted ${deploymentId}`);
+    console.log(`[seq-studio] promoted ${deploymentId}`);
     return 0;
 }
 async function pullCommand(args) {
@@ -340,7 +661,7 @@ async function pullCommand(args) {
         await mkdir(dirname(target), { recursive: true });
         await writeFile(target, file.content, 'utf8');
     }
-    console.log(`[artifact-studio] pulled ${projectId} to ${out}`);
+    console.log(`[seq-studio] pulled ${projectId} to ${out}`);
     return 0;
 }
 async function rollbackCommand(args) {
@@ -351,29 +672,45 @@ async function rollbackCommand(args) {
     const token = await getRequiredToken(args);
     const config = await readLocalConfig();
     if (!config.projectId)
-        throw new Error('Project is not linked. Run artifact-studio link.');
+        throw new Error('Project is not linked. Run seq-studio artifact link.');
     await postJson({
         baseUrl: env.url,
         token,
         path: `/api/artifact-studio/projects/${config.projectId}/deployments/${deploymentId}/rollback`,
         body: {},
     });
-    console.log(`[artifact-studio] rolled back to ${deploymentId}`);
+    console.log(`[seq-studio] rolled back to ${deploymentId}`);
     return 0;
 }
-async function ensureRemoteProject({ env, token, result, dir }) {
-    const config = await readLocalConfig(dir);
+async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCreate = true, explicitProjectId = null }) {
+    if (explicitProjectId) {
+        const data = await getJsonOr404({ baseUrl: env, token, path: `/api/artifact-studio/projects/${explicitProjectId}` });
+        if (!data)
+            throw new Error(`--project ${explicitProjectId}: project not found on this environment`);
+        if (data.project.slug !== result.manifest.artifact.project_id) {
+            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`);
+        }
+        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)
             return data.project;
-        console.warn(`[artifact-studio] cached projectId ${config.projectId} not found on ${env} — relinking by slug`);
+        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) {
-        await writeLocalConfig({ ...config, projectId: existing.id, projectSlug: existing.slug }, dir);
+        if (linkConfigDir)
+            await writeLocalConfig({ ...config, projectId: existing.id, projectSlug: existing.slug }, linkConfigDir);
         return existing;
     }
+    if (!allowCreate) {
+        throw new Error(`project "${result.manifest.artifact.project_id}" does not exist on ${env} and --no-create is set. ` +
+            `First-time provisioning is a human step: run \`seq-studio artifact deploy . -e <env>\` once with your ` +
+            `own login (seqapi login) to create the project, then the CI sweep keeps it updated.`);
+    }
     const created = await postJson({
         baseUrl: env,
         token,
@@ -384,13 +721,21 @@ async function ensureRemoteProject({ env, token, result, dir }) {
             description: result.manifest.artifact.description ?? null,
         },
     });
-    await writeLocalConfig({ ...config, projectId: created.project.id, projectSlug: created.project.slug }, dir);
+    if (linkConfigDir)
+        await writeLocalConfig({ ...config, projectId: created.project.id, projectSlug: created.project.slug }, linkConfigDir);
     return created.project;
 }
-async function uploadDeployment({ env, token, projectId, result, channel, previewKey, dir, message, }) {
+async function uploadDeployment({ env, token, projectId, result, channel, previewKey, provenance, message, }) {
+    // Active deploys omit `version`: the server derives it from its own
+    // sourceHash and de-dupes against the (projectId, version) unique
+    // constraint. Pinning it client-side is how a stale CLI-side hash turned
+    // redeploys into opaque 500s (unique violation on a version string minted
+    // from a hash the server no longer agrees with). Previews keep a
+    // timestamped version so successive pushes of identical source stay
+    // distinguishable.
     const version = channel === 'preview'
         ? `preview-${Date.now().toString(36)}-${result.sourceHash.slice(0, 8)}`
-        : result.sourceHash.slice(0, 12);
+        : undefined;
     const data = await postJson({
         baseUrl: env,
         token,
@@ -400,32 +745,59 @@ async function uploadDeployment({ env, token, projectId, result, channel, previe
             files: result.files,
             bundle: result.bundle,
             sourceMap: result.sourceMap,
-            version,
+            ...(version ? { version } : {}),
             channel,
             previewKey,
             deployMessage: message ?? null,
-            ...gitMetadata(dir),
+            ...provenance,
         },
     });
     return data.deployment;
 }
-async function fetchRemoteProject({ env, token, slug }) {
+async function fetchRemoteProject({ env, token, slug, disambiguator }) {
     const data = await getJson({ baseUrl: env, token, path: '/api/artifact-studio/projects' });
-    return data.projects.find((project) => project.slug === slug) ?? null;
+    const matches = data.projects.filter((project) => project.slug === slug);
+    // Slugs are only unique per creator — a caller who can see several users'
+    // projects (notably the CI service account, which sees everything) can get
+    // multiple hits. Picking "whichever sorts first" would deploy over an
+    // arbitrary project, so ambiguity is a hard error with the disambiguator.
+    if (matches.length > 1) {
+        throw new Error(`${matches.length} projects with slug "${slug}" exist on this environment ` +
+            `(ids: ${matches.map((project) => project.id).join(', ')}) — ` +
+            (disambiguator ??
+                'target one explicitly with --project <id> (deploy) or `seq-studio artifact link . --project <id>`.'));
+    }
+    return matches[0] ?? null;
 }
 async function envFromArgs(args) {
     const config = await readLocalConfig().catch(() => ({ defaultEnv: undefined }));
     return resolveEnvironment(typeof args.flags.env === 'string' ? args.flags.env : undefined, config.defaultEnv);
 }
+/**
+ * Optional refreshing token provider, injected by an embedder (e.g. seq-studio)
+ * that owns the shared seqapi token file and can mint a fresh access token on
+ * demand. Consulted before the static ARTIFACT_STUDIO_TOKEN env var so a
+ * long-running `dev` watcher keeps deploying past the initial token's TTL —
+ * the env var is captured once at process start and never refreshes.
+ */
+let tokenProvider = null;
+export function setTokenProvider(provider) {
+    tokenProvider = provider;
+}
 async function getRequiredToken(args) {
     const token = await getOptionalToken(args);
     if (!token)
-        throw new Error('Missing token. Run artifact-studio login or pass --token.');
+        throw new Error('Missing token. Run seqapi login or pass --token.');
     return token;
 }
 async function getOptionalToken(args) {
     if (typeof args.flags.token === 'string')
         return args.flags.token;
+    if (tokenProvider) {
+        const provided = await tokenProvider();
+        if (provided)
+            return provided;
+    }
     if (process.env.ARTIFACT_STUDIO_TOKEN)
         return process.env.ARTIFACT_STUDIO_TOKEN;
     return getAccessToken();
@@ -434,31 +806,27 @@ 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');
 }
-function gitMetadata(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 };
-    }
-}
 function slugify(value) {
     return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'my-artifact';
 }
 function titleize(slug) {
     return slug.split('-').map((part) => part ? part[0].toUpperCase() + part.slice(1) : '').join(' ');
 }
-// Phase 2 of the seq-lattice rollout (see
-// shared/services/lattice-cli/README.md): this module is now a pure
-// library export. The CLI entry point lives in `bin.ts` and is what the
-// `artifact-studio` binary points at. seq-lattice imports `runCli` from
-// `@sequenceholdings/artifact-studio/cli` and re-invokes it after injecting a
+function warnIfInlinedManifestDriftsFromBundle(result) {
+    const bundleFile = result.files.find((file) => file.path === 'artifact.bundle.yml');
+    if (!bundleFile)
+        return;
+    try {
+        const fromBundle = parseArtifactStudioManifest(yaml.load(bundleFile.content));
+        if (fromBundle.sidebarBadge && !result.manifest.sidebarBadge) {
+            console.warn('[seq-studio] warning: artifact.bundle.yml declares sidebarBadge but the deploy payload omits it — upgrade @sequenceholdings/artifact-studio / seq-studio');
+        }
+    }
+    catch {
+        // validate/build already surfaced parse errors
+    }
+}
+// This module is a pure library export. `seq-studio artifact` imports
+// `runCli` from `@sequenceholdings/artifact-studio/cli` (see
+// shared/services/studio-cli/README.md) and invokes it after injecting a
 // shared base URL + Bearer token.