@sequenceholdings/studio-cli 0.1.9

package/dist/process/commands.js

@@ -0,0 +1,786 @@
+/**
+ * seq-studio process * commands. Each command is a small function with
+ * its own argv slice, called by the argv router in main.ts. Network I/O
+ * happens through `atlas-client.ts` and `getAccessToken()`; commands
+ * themselves do not know about the token file or config TOML.
+ */
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { forEachSerializedNode, } from '@sequenceholdings/lattice/bundle';
+import { getJson, getJsonOr404, postJson, AtlasApiError } from '../atlas-client.js';
+import { generateProcessFiles } from './codegen.js';
+import { getAccessToken, NotLoggedInError } from '../auth.js';
+import { ENV_NAMES, readConfig, resolveEnv } from '../config.js';
+import { buildBundleFromProcesses, summarizeBundle } from './build.js';
+import { buildResolveProcessPinFromEnv } from './resolve-process-pin.js';
+import { loadBundleForPublish } from './local-bundle.js';
+import { loadProcessDefinitions } from './discover.js';
+import { lintProcesses, formatLintResult } from './lint.js';
+import { diffBundleAgainstActive, formatPlanDiff, } from './plan-diff.js';
+import { simulateProcess, formatSimulateResult } from './simulate.js';
+import { buildAgentSchemaLoader } from './agent-loader.js';
+export function parseArgs(rest) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '--') {
+            positional.push(...rest.slice(i + 1));
+            break;
+        }
+        if (arg.startsWith('--')) {
+            const body = arg.slice(2);
+            // Accept `--key=value` (POSIX-style). Without this, `--env=staging`
+            // would land in flags as `env=staging` → true and resolveEnv
+            // would fall back to default_env, silently deploying to the
+            // wrong target.
+            const eqIdx = body.indexOf('=');
+            if (eqIdx >= 0) {
+                flags[body.slice(0, eqIdx)] = body.slice(eqIdx + 1);
+                continue;
+            }
+            const key = body;
+            const next = rest[i + 1];
+            // Same sentinel as the short-flag branch below: any leading `-`
+            // is another flag, not a value. Without this `--out -e staging`
+            // would consume `-e` as the value of `--out` and silently swallow
+            // the `-e` flag.
+            if (next && !next.startsWith('-')) {
+                flags[key] = next;
+                i += 1;
+            }
+            else {
+                flags[key] = true;
+            }
+        }
+        else if (arg.startsWith('-') && arg.length >= 2 && !arg.startsWith('--')) {
+            // single-letter shorthand: -e, -o, -e=foo, -o=path/to/file
+            // Without supporting the `-e=value` form, a user running
+            // `seq-studio process apply -e=production` would silently fall
+            // back to the configured default env and deploy to local.
+            const eqIdx = arg.indexOf('=');
+            const shortName = eqIdx >= 0 ? arg.slice(0, eqIdx) : arg;
+            const longName = SHORT_FLAG_ALIASES[shortName];
+            if (!longName || shortName.length !== 2) {
+                positional.push(arg);
+                continue;
+            }
+            if (eqIdx >= 0) {
+                flags[longName] = arg.slice(eqIdx + 1);
+                continue;
+            }
+            const next = rest[i + 1];
+            if (next && !next.startsWith('-')) {
+                flags[longName] = next;
+                i += 1;
+            }
+            else {
+                flags[longName] = true;
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, flags };
+}
+const SHORT_FLAG_ALIASES = {
+    '-e': 'env',
+    '-m': 'message',
+    '-o': 'out',
+};
+async function getEnvAndToken(args) {
+    const config = await readConfig();
+    const requested = typeof args.flags.env === 'string' ? args.flags.env : undefined;
+    const env = resolveEnv({ config, requested });
+    let token;
+    try {
+        token = await getAccessToken();
+    }
+    catch (err) {
+        if (err instanceof NotLoggedInError) {
+            throw err;
+        }
+        throw err;
+    }
+    return { env, token };
+}
+// ---------------------------------------------------------------------------
+// init
+// ---------------------------------------------------------------------------
+export async function initCommand(args) {
+    const target = args.positional[0];
+    if (!target) {
+        console.error('usage: seq-studio process init <name-or-dir>');
+        return 1;
+    }
+    const dir = resolve(target);
+    const name = dir.split('/').filter(Boolean).at(-1) ?? 'my-process';
+    if (existsSync(dir)) {
+        console.error(`${dir} already exists`);
+        return 1;
+    }
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    // After build, templates/ is at the package root, two levels up from
+    // dist/process/commands.js. During tsx dev runs, two levels up from
+    // src/process/commands.ts lands at the package root too.
+    const candidates = [
+        resolve(moduleDir, '..', '..', 'templates', 'process'),
+        resolve(moduleDir, '..', 'templates', 'process'),
+    ];
+    const templateRoot = candidates.find((p) => existsSync(p));
+    if (!templateRoot) {
+        console.error('seq-studio install is missing templates/process/');
+        return 1;
+    }
+    const slug = slugify(name);
+    await mkdir(dir, { recursive: true });
+    await cp(templateRoot, dir, { recursive: true });
+    // Rename the placeholder per-process folder to the user's slug so
+    // `<slug>/process.ts` matches the cwd discovery contract.
+    const placeholderDir = join(dir, 'example-process');
+    const targetDir = join(dir, slug);
+    if (existsSync(placeholderDir) && placeholderDir !== targetDir) {
+        const { rename } = await import('node:fs/promises');
+        await rename(placeholderDir, targetDir);
+    }
+    for (const relPath of ['package.json', join(slug, 'process.ts')]) {
+        const path = join(dir, relPath);
+        if (existsSync(path)) {
+            const body = (await readFile(path, 'utf8'))
+                .replace(/\{\{name\}\}/g, name)
+                .replace(/\{\{slug\}\}/g, slug);
+            await writeFile(path, body, 'utf8');
+        }
+    }
+    console.log(`[seq-studio] scaffolded process repo at ${relative(process.cwd(), dir)}`);
+    console.log('Next:');
+    // pnpm is recommended over npm so the scaffolded
+    // pnpm-workspace.yaml's `minimumReleaseAge: 10080` supply-chain
+    // gate actually takes effect (npm has no equivalent setting).
+    console.log(`  cd ${relative(process.cwd(), dir) || '.'} && pnpm install`);
+    console.log('  seqapi login');
+    console.log('  seq-studio process plan -e local');
+    return 0;
+}
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'process';
+}
+// ---------------------------------------------------------------------------
+// lint
+// ---------------------------------------------------------------------------
+export async function lintCommand(args) {
+    const defs = await loadProcessDefinitions();
+    const loadAgentSchemaEdgeIdEnum = await tryBuildAgentLoader(args);
+    const result = await lintProcesses({ defs, loadAgentSchemaEdgeIdEnum });
+    const formatted = formatLintResult(result);
+    if (formatted.text)
+        console.log(formatted.text);
+    if (formatted.hasErrors) {
+        console.error(`\nlint FAILED — ${result.errors.length} error(s), ${result.warnings.length} warning(s)`);
+        return 1;
+    }
+    console.log(`\nlint ok — ${defs.length} process(es) checked, ${result.warnings.length} warning(s)`);
+    return 0;
+}
+async function tryBuildAgentLoader(args) {
+    // Agent loader is only meaningful when we have a target env + token.
+    // If either fails to resolve, skip the check; lint will emit a warning
+    // for multi-edge agent nodes instead of failing.
+    try {
+        const { env, token } = await getEnvAndToken(args);
+        return buildAgentSchemaLoader({ baseUrl: env.url, token });
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// plan
+// ---------------------------------------------------------------------------
+async function buildBundleForPublish(args, defs) {
+    const hasSubprocess = defs.some((d) => d.process.nodes.some((n) => n.kind === 'subprocess'));
+    try {
+        const { env, token } = await getEnvAndToken(args);
+        const resolveProcessPin = buildResolveProcessPinFromEnv(env, token);
+        return await buildBundleFromProcesses(defs, { resolveProcessPin });
+    }
+    catch (err) {
+        if (hasSubprocess) {
+            throw new Error('subprocess nodes require -e <env> and `seqapi login` to resolve child process versions', { cause: err });
+        }
+        return await buildBundleFromProcesses(defs);
+    }
+}
+export async function planCommand(args) {
+    const defs = await loadProcessDefinitions();
+    const bundle = await buildBundleForPublish(args, defs);
+    const summary = summarizeBundle(bundle);
+    console.log(JSON.stringify(summary, null, 2));
+    const loadActiveProcess = await tryBuildActiveProcessLoader(args);
+    if (!loadActiveProcess) {
+        console.log('\n(no diff — env or auth unavailable; pass --env <name> and run `seqapi login`)');
+        return 0;
+    }
+    const diff = await diffBundleAgainstActive({ newBundle: bundle, loadActiveProcess });
+    console.log('\n--- diff against active ---');
+    console.log(formatPlanDiff(diff));
+    if (diff.has_breaking_change) {
+        console.log('\nthis plan includes BREAKING changes for new runs (in-flight runs are pinned and unaffected)');
+    }
+    return 0;
+}
+async function tryBuildActiveProcessLoader(args) {
+    try {
+        const { env, token } = await getEnvAndToken(args);
+        return async (processId) => {
+            // GET /api/lattice/processes/:id returns
+            // `{ process_id, activeVersion, activeBundleHash }` flat at the
+            // top level — NOT a nested `{ process: { ... } }`, NOT snake_case.
+            // See atlas/src/app/api/lattice/processes/[processId]/route.ts.
+            const meta = await getJsonOr404({
+                baseUrl: env.url,
+                token,
+                path: `/api/lattice/processes/${encodeURIComponent(processId)}`,
+            });
+            if (!meta?.activeVersion || !meta.activeBundleHash)
+                return null;
+            const bundleData = await getJsonOr404({
+                baseUrl: env.url,
+                token,
+                path: `/api/lattice/bundles/${encodeURIComponent(meta.activeBundleHash)}`,
+            });
+            if (!bundleData?.bundle)
+                return null;
+            const proc = bundleData.bundle.processes.find((p) => p.id === processId);
+            if (!proc)
+                return null;
+            return { version: meta.activeVersion, process: proc };
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+// ---------------------------------------------------------------------------
+// test (CI wrapper)
+// ---------------------------------------------------------------------------
+export async function testCommand(args) {
+    const defs = await loadProcessDefinitions();
+    const loadAgentSchemaEdgeIdEnum = await tryBuildAgentLoader(args);
+    const lintResult = await lintProcesses({ defs, loadAgentSchemaEdgeIdEnum });
+    const formattedLint = formatLintResult(lintResult);
+    if (formattedLint.text)
+        console.log(formattedLint.text);
+    if (formattedLint.hasErrors) {
+        console.error(`\nlint FAILED — ${lintResult.errors.length} error(s), ${lintResult.warnings.length} warning(s)`);
+        return 1;
+    }
+    console.log(`\nlint ok — ${defs.length} process(es) checked, ${lintResult.warnings.length} warning(s)`);
+    const bundle = await buildBundleForPublish(args, defs);
+    const offline = args.flags.offline === true;
+    const loadActiveProcess = await tryBuildActiveProcessLoader(args);
+    if (!loadActiveProcess) {
+        // `process test` is the CI gate — silently skipping the diff would
+        // let a misconfigured CI job ship BREAKING changes as a green
+        // build. Require explicit `--offline` to opt out.
+        if (offline) {
+            console.log('\n(skipped diff — --offline flag set)');
+            return 0;
+        }
+        console.error('\nFAIL — could not load the active version for diff (env or auth missing).\n' +
+            '  Either pass -e <env> with valid seqapi auth (run `seq-studio doctor` to debug),\n' +
+            '  or pass --offline if you intentionally want CI to skip the diff.');
+        return 1;
+    }
+    const diff = await diffBundleAgainstActive({ newBundle: bundle, loadActiveProcess });
+    console.log('\n--- diff against active ---');
+    console.log(formatPlanDiff(diff));
+    if (diff.has_breaking_change) {
+        console.error('\nFAIL — plan includes BREAKING changes');
+        return 1;
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// apply (build → register → promote)
+// ---------------------------------------------------------------------------
+/**
+ * Parse + validate the `--only <id1,id2,...>` promote filter for `apply`.
+ * The bundle is still built and registered from the full discovery root
+ * (registration is content-addressed and inert — only the promote flips
+ * active versions), so CI can target a subset of a shared root per
+ * environment. Returns `ids: null` when the flag is absent (promote all).
+ */
+export function resolveOnlyIds({ only, knownIds, }) {
+    if (only === undefined)
+        return { ids: null };
+    if (typeof only !== 'string' || !only.trim()) {
+        return { ids: null, error: 'usage: --only <process-id>[,<process-id>...]' };
+    }
+    const ids = new Set(only
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean));
+    const unknown = [...ids].filter((id) => !knownIds.has(id));
+    if (unknown.length > 0) {
+        return {
+            ids: null,
+            error: `--only names process(es) not found in this root: ${unknown.join(', ')}\n` +
+                `known: ${[...knownIds].sort().join(', ')}`,
+        };
+    }
+    return { ids };
+}
+export async function applyCommand(args) {
+    const { env, token } = await getEnvAndToken(args);
+    const defs = await loadProcessDefinitions();
+    const onlyResult = resolveOnlyIds({
+        only: args.flags.only,
+        knownIds: new Set(defs.map((d) => d.process.id)),
+    });
+    if (onlyResult.error) {
+        console.error(onlyResult.error);
+        return 1;
+    }
+    const onlyIds = onlyResult.ids;
+    // Layer-3 lint before touching the registry. Server-side lint runs
+    // again on POST /bundles; this is a local fast-fail so we don't ship
+    // a bundle that will be rejected.
+    const loadAgentSchemaEdgeIdEnum = buildAgentSchemaLoader({ baseUrl: env.url, token });
+    const lintResult = await lintProcesses({ defs, loadAgentSchemaEdgeIdEnum });
+    const formatted = formatLintResult(lintResult);
+    if (formatted.text)
+        console.log(formatted.text);
+    if (formatted.hasErrors) {
+        console.error('\napply FAILED — lint rejected the bundle');
+        return 1;
+    }
+    const bundle = await buildBundleForPublish(args, defs);
+    console.log(`[seq-studio] built bundle ${bundle.bundle_hash.slice(0, 12)} ` +
+        `(${bundle.processes.length} process(es))`);
+    // We send only the bundle. `created_by` (and `promoted_by` for the
+    // promote call below) are derived server-side from the authenticated
+    // user — we deliberately do NOT forward `bundle.metadata.created_by`
+    // (which is built from local `process.env.USER`) as authoritative
+    // attribution. The descriptive value still lives inside the bundle
+    // JSON for local debugging; the server-side audit log uses the JWT
+    // sub.
+    const registered = await postJson({
+        baseUrl: env.url,
+        token,
+        path: '/api/lattice/bundles',
+        body: { bundle },
+    });
+    console.log(`[seq-studio] registered bundle ${registered.bundleHash.slice(0, 12)} → ${registered.storedUri} (written=${registered.written})`);
+    for (const pv of registered.processVersions) {
+        if (onlyIds && !onlyIds.has(pv.processId)) {
+            console.log(`[seq-studio] skipped promote of ${pv.processId} (not in --only)`);
+            continue;
+        }
+        await postJson({
+            baseUrl: env.url,
+            token,
+            path: `/api/lattice/processes/${encodeURIComponent(pv.processId)}/promote`,
+            body: { version: pv.version },
+        });
+        console.log(`[seq-studio] promoted ${pv.processId} → ${pv.version}`);
+    }
+    console.log(`\napply OK against ${env.name} (${env.url})`);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// bundle build|pull
+// ---------------------------------------------------------------------------
+/**
+ * Pull a published process's source back into a local tree. Resolves the
+ * requested (or active) version to a bundle, then regenerates `process.ts`
+ * (+ `recommendations.ts`) under `<out>/<processId>/`. Pulls the process and
+ * its co-located subprocess children by default (`--no-children` for just the
+ * root). This closes the loop: apply a change in the UI → publish an inactive
+ * version → pull it here → review + commit.
+ */
+export async function pullCommand(args) {
+    const processId = args.positional[0];
+    if (!processId) {
+        console.error('usage: seq-studio process pull <processId> [--version <v>] [-e <env>] [--out <dir>] [--no-children]');
+        return 1;
+    }
+    const { env, token } = await getEnvAndToken(args);
+    const version = typeof args.flags.version === 'string' ? args.flags.version : undefined;
+    const outDir = typeof args.flags.out === 'string' ? resolve(args.flags.out) : process.cwd();
+    const noChildren = args.flags['no-children'] === true;
+    // Resolve the bundle hash: a specific version, or the active pointer.
+    let bundleHash;
+    let resolvedVersion;
+    if (version) {
+        const v = await getJson({
+            baseUrl: env.url,
+            token,
+            path: `/api/lattice/processes/${encodeURIComponent(processId)}/versions/${encodeURIComponent(version)}`,
+        });
+        bundleHash = v.bundleHash;
+        resolvedVersion = version;
+    }
+    else {
+        const meta = await getJson({
+            baseUrl: env.url,
+            token,
+            path: `/api/lattice/processes/${encodeURIComponent(processId)}`,
+        });
+        bundleHash = meta.activeBundleHash;
+        resolvedVersion = meta.activeVersion;
+    }
+    const { bundle } = await getJson({
+        baseUrl: env.url,
+        token,
+        path: `/api/lattice/bundles/${encodeURIComponent(bundleHash)}`,
+    });
+    const root = bundle.processes.find((p) => p.id === processId);
+    if (!root) {
+        console.error(`[seq-studio] process "${processId}" not found in bundle ${resolvedVersion}`);
+        return 1;
+    }
+    const targets = noChildren ? [root] : reachableProcesses(root, bundle);
+    for (const proc of targets) {
+        const dir = join(outDir, proc.id);
+        await mkdir(dir, { recursive: true });
+        const files = generateProcessFiles(proc, bundle);
+        for (const [name, content] of Object.entries(files)) {
+            await writeFile(join(dir, name), content, 'utf8');
+        }
+        // This version has no recommendations — clear a stale file from a prior pull.
+        if (!files['recommendations.ts'])
+            await rm(join(dir, 'recommendations.ts'), { force: true });
+        console.log(`[seq-studio] wrote ${relative(process.cwd(), join(dir, 'process.ts'))}`);
+    }
+    console.log(`[seq-studio] pulled ${targets.length} process(es) at version ${resolvedVersion}`);
+    return 0;
+}
+/** A process + its transitive co-located subprocess children (those bundled here). */
+function reachableProcesses(root, bundle) {
+    const byId = new Map(bundle.processes.map((p) => [p.id, p]));
+    const seen = new Set();
+    const out = [];
+    const visit = (proc) => {
+        if (seen.has(proc.id))
+            return;
+        seen.add(proc.id);
+        out.push(proc);
+        forEachSerializedNode(proc.nodes, (node) => {
+            if (node.kind !== 'subprocess')
+                return;
+            const childId = node.metadata.subprocess
+                ?.process_id;
+            const child = childId ? byId.get(childId) : undefined;
+            if (child)
+                visit(child);
+        });
+    };
+    visit(root);
+    return out;
+}
+/**
+ * Make a published version the active one — the same promote `apply` runs, as a
+ * standalone command (and the same endpoint the UI version menu hits).
+ */
+export async function promoteCommand(args) {
+    const processId = args.positional[0];
+    const version = typeof args.flags.version === 'string' ? args.flags.version : undefined;
+    if (!processId || !version) {
+        console.error('usage: seq-studio process promote <processId> --version <v> [-e <env>]');
+        return 1;
+    }
+    const { env, token } = await getEnvAndToken(args);
+    const result = await postJson({
+        baseUrl: env.url,
+        token,
+        path: `/api/lattice/processes/${encodeURIComponent(processId)}/promote`,
+        body: { version },
+    });
+    console.log(`[seq-studio] promoted ${result.process_id} → ${result.active_version}`);
+    return 0;
+}
+export async function bundleCommand(args) {
+    const sub = args.positional[0];
+    switch (sub) {
+        case 'build': {
+            const defs = await loadProcessDefinitions();
+            const bundle = await buildBundleForPublish(args, defs);
+            const out = typeof args.flags.out === 'string' ? resolve(args.flags.out) : null;
+            if (out) {
+                await mkdir(dirname(out), { recursive: true });
+                await writeFile(out, JSON.stringify(bundle, null, 2), 'utf8');
+                console.log(`[seq-studio] wrote ${out}`);
+            }
+            else {
+                console.log(JSON.stringify(summarizeBundle(bundle), null, 2));
+            }
+            return 0;
+        }
+        case 'pull': {
+            const hash = args.positional[1];
+            if (!hash) {
+                console.error('usage: seq-studio process bundle pull <hash> [-o file.json] [-e <env>]');
+                return 1;
+            }
+            const { env, token } = await getEnvAndToken(args);
+            const data = await getJson({
+                baseUrl: env.url,
+                token,
+                path: `/api/lattice/bundles/${encodeURIComponent(hash)}`,
+            });
+            const body = JSON.stringify(data.bundle, null, 2);
+            const out = typeof args.flags.out === 'string' ? resolve(args.flags.out) : null;
+            if (out) {
+                await mkdir(dirname(out), { recursive: true });
+                await writeFile(out, body, 'utf8');
+                console.log(`[seq-studio] wrote ${out} (${body.length} bytes)`);
+            }
+            else {
+                process.stdout.write(body);
+                if (process.stdout.isTTY)
+                    process.stdout.write('\n');
+            }
+            return 0;
+        }
+        case 'archive': {
+            const hash = args.positional[1];
+            if (!hash) {
+                console.error('usage: seq-studio process bundle archive <hash> [-e <env>]');
+                return 1;
+            }
+            const { env, token } = await getEnvAndToken(args);
+            const result = await postJson({
+                baseUrl: env.url,
+                token,
+                path: `/api/lattice/bundles/${encodeURIComponent(hash)}/archive`,
+                body: {},
+            });
+            console.log(result.archived
+                ? `[seq-studio] archived bundle ${hash} (${result.processVersions.length} process version(s) hidden)`
+                : `[seq-studio] bundle ${hash} was not present (no-op)`);
+            return 0;
+        }
+        case 'inspect': {
+            const path = args.positional[1];
+            if (!path) {
+                console.error('usage: seq-studio process bundle inspect <bundle.json>');
+                return 1;
+            }
+            const body = await readFile(path, 'utf8');
+            const bundle = JSON.parse(body);
+            console.log(JSON.stringify(summarizeBundle(bundle), null, 2));
+            return 0;
+        }
+        case 'list': {
+            const { env, token } = await getEnvAndToken(args);
+            const pageLimit = typeof args.flags.limit === 'string'
+                ? Math.min(Math.max(Number.parseInt(args.flags.limit, 10) || 100, 1), 500)
+                : 500;
+            let cursor = typeof args.flags.cursor === 'string' ? args.flags.cursor : undefined;
+            let pages = 0;
+            const maxPages = 100;
+            do {
+                pages += 1;
+                if (pages > maxPages) {
+                    console.error(`[seq-studio] bundle list stopped after ${maxPages} pages — use --cursor to continue`);
+                    return 1;
+                }
+                const params = new URLSearchParams({ limit: String(pageLimit) });
+                if (cursor)
+                    params.set('cursor', cursor);
+                const data = await getJson({
+                    baseUrl: env.url,
+                    token,
+                    path: `/api/lattice/bundles?${params.toString()}`,
+                });
+                for (const entry of data.bundles) {
+                    console.log(`${entry.bundleHash}\t${entry.uri}`);
+                }
+                cursor = data.next_cursor ?? undefined;
+            } while (cursor);
+            return 0;
+        }
+        case 'publish': {
+            const hashOrPath = args.positional[1];
+            if (!hashOrPath) {
+                console.error('usage: seq-studio process bundle publish <hash|bundle.json> [-e <env>]');
+                return 1;
+            }
+            const { env, token } = await getEnvAndToken(args);
+            let bundle;
+            try {
+                bundle = await loadBundleForPublish({ hashOrPath });
+            }
+            catch (err) {
+                console.error(err instanceof Error ? err.message : String(err));
+                return 1;
+            }
+            const registered = await postJson({
+                baseUrl: env.url,
+                token,
+                path: '/api/lattice/bundles',
+                body: { bundle },
+            });
+            console.log(`[seq-studio] published ${registered.bundleHash.slice(0, 12)} → ${registered.storedUri} (written=${registered.written})`);
+            console.log(`  registered ${registered.processVersions.length} process version(s); run process apply to promote`);
+            return 0;
+        }
+        default:
+            console.error('usage: seq-studio process bundle build|pull|inspect|list|publish ...');
+            return 1;
+    }
+}
+// ---------------------------------------------------------------------------
+// simulate
+// ---------------------------------------------------------------------------
+export async function simulateCommand(args) {
+    const processId = args.positional[0];
+    if (!processId) {
+        console.error('usage: seq-studio process simulate <process-id>');
+        return 1;
+    }
+    const defs = await loadProcessDefinitions();
+    const def = defs.find((d) => d.process.id === processId);
+    if (!def) {
+        console.error(`process "${processId}" not found in lattice process roots`);
+        return 1;
+    }
+    const processesById = new Map(defs.map((d) => [d.process.id, d.process]));
+    const result = await simulateProcess({ process: def.process, processesById });
+    console.log(formatSimulateResult(result));
+    return result.status === 'failed' ? 1 : 0;
+}
+// ---------------------------------------------------------------------------
+// doctor (token + env + FGA gate)
+// ---------------------------------------------------------------------------
+export async function doctorCommand(args) {
+    const lines = [];
+    let ok = true;
+    const config = await readConfig().catch(() => null);
+    if (!config) {
+        lines.push('config: FAIL — could not read ~/.config/lattice/config.toml');
+        ok = false;
+    }
+    else {
+        lines.push(`config: ok — default_env=${config.defaultEnv}, envs=${Object.keys(config.envs).join(',')}`);
+    }
+    const requested = typeof args.flags.env === 'string' ? args.flags.env : undefined;
+    if (requested && !ENV_NAMES.includes(requested) && config && !(requested in config.envs)) {
+        lines.push(`env "${requested}": FAIL — not in built-ins (${ENV_NAMES.join(',')}) or config`);
+        ok = false;
+    }
+    let env = null;
+    if (config) {
+        try {
+            env = resolveEnv({ config, requested });
+            lines.push(`env: ok — ${env.name} (${env.url})`);
+        }
+        catch (err) {
+            lines.push(`env: FAIL — ${err.message}`);
+            ok = false;
+        }
+    }
+    let token = null;
+    try {
+        token = await getAccessToken();
+        lines.push('auth: ok — seqapi token present and not expired');
+    }
+    catch (err) {
+        lines.push(`auth: FAIL — ${err instanceof Error ? err.message.split('\n')[0] : String(err)}`);
+        ok = false;
+    }
+    if (env && token) {
+        // Hit a writer-gated endpoint with a fake hash so the request
+        // either:
+        //   - 404 NOT_FOUND  → writer gate passed (we're a Sequence-org
+        //     member, the hash just doesn't exist), OR
+        //   - 403 FORBIDDEN  → not a Sequence-org member.
+        // The GET /processes/:id endpoint uses plain `authenticate` so it
+        // cannot distinguish these cases. GET /bundles/:hash is gated by
+        // `authenticateLatticeWriter` and is the right probe.
+        // Use a syntactically-valid-but-nonexistent 64-char hex hash so the
+        // bundle store's HASH_PATTERN regex passes (atlas/lattice/src/bundle/
+        // store.ts) and we hit BundleNotFoundError → 404. A non-hex probe like
+        // "__doctor__" trips the regex first and lands in respondToError as
+        // 500 instead, which would surface as a misleading WARN.
+        const PROBE_HASH = '0'.repeat(64);
+        try {
+            await getJson({
+                baseUrl: env.url,
+                token,
+                path: `/api/lattice/bundles/${PROBE_HASH}`,
+            });
+            lines.push('writer gate: ok — Sequence-org member (probe via GET /bundles/<zeros>)');
+        }
+        catch (err) {
+            if (err instanceof AtlasApiError) {
+                if (err.status === 404) {
+                    lines.push('writer gate: ok — Sequence-org member (GET /bundles/<zeros> → 404 means we passed the writer gate, the probe hash is fake)');
+                }
+                else if (err.status === 403) {
+                    lines.push('writer gate: FAIL — 403 from Atlas. You need to be a member of organization:sequence in OpenFGA. ' +
+                        'Log in to Atlas at least once to materialize the membership tuple.');
+                    ok = false;
+                }
+                else if (err.status === 401) {
+                    lines.push('writer gate: FAIL — 401. Token is rejected by Atlas — run `seqapi login`.');
+                    ok = false;
+                }
+                else {
+                    lines.push(`writer gate: WARN — ${err.status} ${err.message}`);
+                }
+            }
+            else {
+                lines.push(`writer gate: WARN — could not probe: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Git-service discovery: empty current env often means the repos live on
+        // another deployment (agents historically probed banksouth → production →
+        // staging). Hint when staging has repos and the current env does not.
+        try {
+            const current = await getJson({
+                baseUrl: env.url,
+                token,
+                path: '/api/git-service/repos?limit=1&offset=0',
+            });
+            const currentTotal = current.total ?? current.items.length;
+            if (currentTotal === 0 && env.name !== 'staging' && config?.envs.staging?.url) {
+                try {
+                    const staging = await getJson({
+                        baseUrl: config.envs.staging.url,
+                        token,
+                        path: '/api/git-service/repos?limit=1&offset=0',
+                    });
+                    const stagingTotal = staging.total ?? staging.items.length;
+                    if (stagingTotal > 0) {
+                        lines.push(`git-service: ${env.name} has 0 visible repos, but staging has ${stagingTotal} — try \`seq-studio repos list -e staging\``);
+                    }
+                    else {
+                        lines.push(`git-service: ok — 0 visible repos on ${env.name} (staging also empty)`);
+                    }
+                }
+                catch {
+                    lines.push(`git-service: ok — 0 visible repos on ${env.name}`);
+                }
+            }
+            else {
+                lines.push(`git-service: ok — ${currentTotal} visible repo(s) on ${env.name}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof AtlasApiError) {
+                lines.push(`git-service: WARN — ${err.status} ${err.message}`);
+            }
+            else {
+                lines.push(`git-service: WARN — could not probe: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    for (const l of lines)
+        console.log(l);
+    return ok ? 0 : 1;
+}