@sequenceholdings/studio-cli 0.1.9

package/README.md

@@ -0,0 +1,258 @@
+# `@sequenceholdings/studio-cli` — `seq-studio`
+
+Standalone CLI for the Sequence platform: Lattice processes, Artifact Studio
+apps, Managed Functions, Managed Secrets, and platform git repos. Runs from
+any repo against the platform over HTTP — no monorepo checkout required.
+
+```
+seq-studio process lint
+seq-studio process plan -e staging
+seq-studio process apply -e staging
+seq-studio artifact deploy -e staging
+seq-studio doctor
+```
+
+> **Note:** all network commands require a Sequence platform account with the
+> appropriate permissions. Without one, only the offline commands
+> (`init`, `lint`, `simulate`, `build`, `bundle inspect`) work.
+> Sequence-internal contributors: see `INTERNAL.md` in the monorepo for
+> rollout SOPs, preview environments, and publishing docs.
+
+## Install
+
+```bash
+# In a process or artifact repo (devDependency, using pnpm — see below):
+pnpm add -D @sequenceholdings/studio-cli @sequenceholdings/lattice
+
+# Or globally:
+pnpm add -g @sequenceholdings/studio-cli
+```
+
+### Why pnpm and not npm
+
+Sequence uses pnpm's `minimumReleaseAge` setting (in `pnpm-workspace.yaml`)
+as a 7-day supply-chain quarantine on new package releases. `npm` has no
+equivalent and would happily install a freshly-published malicious
+version of any transitive dep. **External process repos scaffolded by
+`seq-studio process init` ship a `pnpm-workspace.yaml` with the same
+guard.** Stick with pnpm so the policy actually applies.
+(The seq-studio publish chain — `atlas-ui`, `lattice-form-renderer`,
+`artifact-studio`, `lattice`, `studio-cli` — is excluded from the quarantine;
+those come from the Studio repo's own publish pipeline, so new `seq-studio`
+releases install immediately.)
+
+## Authenticate
+
+`seq-studio` is a **read-only consumer of seqapi tokens** — it does not
+have its own login flow. Run `seqapi login` once to mint tokens at
+`~/.config/sequence-api/tokens.json`; `seqapi`, `seq-studio process`, and
+`seq-studio artifact` all share that file.
+
+```bash
+seqapi login
+seq-studio doctor   # confirms config + auth + authorization
+```
+
+### Headless auth (CI) — M2M
+
+When there's no interactive login (CI, automation), set the service-account
+secret and `seq-studio` mints a token via the Auth0 client-credentials grant
+(M2M wins when the secret is set, otherwise the cached user token is used):
+
+```bash
+export AUTH0_M2M_CLIENT_SECRET=...   # provided by your platform administrator
+seq-studio artifact deploy -e staging
+```
+
+The secret is read at runtime — never commit it. M2M carries app scopes but
+**no user identity / workspace membership**, so it's blind to
+user-scoped/private resources.
+
+**Manual escape hatch:** any `artifact` command also accepts an explicit
+`--token <jwt>`, which wins over both the M2M and cached-user paths.
+
+## Environments (`~/.config/lattice/config.toml`)
+
+Environment names map to platform URLs. Your deployment's URLs are configured
+in `~/.config/lattice/config.toml`:
+
+```toml
+[env.local]
+url = "http://localhost:5001"
+
+[env.staging]
+url = "https://staging.example.com"
+
+default_env = "local"
+```
+
+Pass `--env <name>` (or `-e <name>`) on commands that talk to the platform.
+
+`default_env` applies to `process` commands. `artifact` commands read
+`config.toml` only when `--env` *is* passed; with no `--env` they fall back to
+the artifact folder's `.artifact-studio/config.json` `defaultEnv` (set by
+`artifact link` / `artifact env use`).
+
+## Process commands
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio process init <dir>` | Scaffold a process repo: `package.json`, sample `process.ts`, `tsconfig.json` |
+| `seq-studio process lint` | Static checks (graph, return contracts, agent schema, timeouts) |
+| `seq-studio process plan -e <env>` | Build bundle, diff against currently-active version |
+| `seq-studio process apply -e <env> [--only <id1,id2>]` | Build → register bundle → promote each process. `--only` promotes just the named process ids (the bundle still contains the whole root — registration is inert) |
+| `seq-studio process test -e <env>` | CI wrapper: lint + plan, non-zero exit on errors or BREAKING diffs |
+| `seq-studio process simulate <id>` | In-process walk with stubbed runners (offline) |
+| `seq-studio process bundle build [-o file.json]` | Build a bundle locally |
+| `seq-studio process bundle pull <hash> [-e <env>] [-o file.json]` | Fetch a stored bundle |
+| `seq-studio process bundle inspect <bundle.json>` | Show a saved bundle's summary |
+| `seq-studio process bundle list [-e <env>] [--limit N] [--cursor <hash>]` | List registered bundles (paginated; CLI auto-fetches all pages) |
+| `seq-studio process bundle publish <hash or bundle.json> [-e <env>]` | Register a local bundle (no promote) |
+
+### Process discovery
+
+`seq-studio` walks the current working directory for any subfolder
+containing a `process.ts` file. Each `process.ts` must
+`export default defineProcess(...)`. Set `LATTICE_PROCESSES_ROOT` to
+point at a different folder.
+
+```
+my-processes/
+  demo-process/
+    process.ts
+  loan-origination/
+    process.ts
+```
+
+```bash
+cd my-processes
+seq-studio process lint     # finds both processes
+```
+
+## Artifact commands
+
+`seq-studio artifact <sub>` is the entry point for Artifact Studio. It runs
+the `@sequenceholdings/artifact-studio` library (its `./cli` `runCli` export),
+routed through `~/.config/lattice/config.toml` and the shared seqapi token.
+
+| Command | Underlying `runCli` verb |
+|---------|--------------------------|
+| `seq-studio artifact init <dir>` | `init <dir>` |
+| `seq-studio artifact link [dir] -e <env> [--project <id>]` | `link [dir] --env <env>` |
+| `seq-studio artifact build [dir]` | `build [dir]` |
+| `seq-studio artifact plan [dir] -e <env>` | `plan [dir] --env <env>` |
+| `seq-studio artifact deploy [dir] -e <env> [--skip-unchanged] [--no-create] [--project <id>]` | `deploy [dir] --env <env>` — `--skip-unchanged` no-ops (before building) when the remote active deployment's `sourceHash` already matches the local source; `--no-create` errors instead of creating a missing project; `--project <id>` targets a project directly when duplicate slugs make the lookup ambiguous (slug must still match the manifest) |
+| `seq-studio artifact dev [dir] -e <env>` | `dev [dir] --env <env>` |
+| `seq-studio artifact pull <project-id> -e <env> [--out <dir>]` | `pull <project-id> --env <env> [--out <dir>]` |
+| `seq-studio artifact list -e <env>` | `list --env <env>` — projects visible on the environment (slug, id, active version, visibility) |
+| `seq-studio artifact show <slug-or-id> -e <env>` | `show <slug-or-id> --env <env>` — one project's detail incl. active deployment + git provenance |
+| `seq-studio artifact promote <deployment-id> -e <env>` | `promote <deployment-id> --env <env>` |
+| `seq-studio artifact rollback <deployment-id> -e <env>` | `rollback <deployment-id> --env <env>` |
+
+`pull` writes the **active deployment's** source files (default out dir:
+`./<project-id>`) and errors when the project has no active deployment.
+`promote` and `rollback` resolve the target project from the current
+directory's `.artifact-studio/config.json` — run them from the linked artifact
+folder (or run `seq-studio artifact link` first).
+
+### Source for `build` / `plan` / `deploy`
+
+These three commands read their source tree from one of three places — the rest
+of the pipeline (build → upload) is identical regardless of origin:
+
+| Flag | Source |
+|------|--------|
+| _(none)_ / `[dir]` | a local folder (default, unchanged) |
+| `--repo <ns>/<name>` | a repo in the platform Git Service, e.g. `--repo artifacts/accounts` |
+| `--git-url <url>` | any git URL (cloned to a temp dir) |
+
+`--ref <branch\|tag\|commit>` selects the revision (default: the repo's default
+branch). A remote source is materialized to a temp dir, built, and torn down;
+the target project is resolved from the source's `artifact.bundle.yml`
+`project_id`. The deployment records the resolved commit as its `git_commit`
+provenance. `--repo` needs `-e <env>` + a platform login; `--git-url` needs git
+credentials for private repos. `dev` is local-only.
+
+## Pull / clone / deploy — which path?
+
+These three look similar but fetch different things:
+
+| Command | What you get |
+|---------|--------------|
+| `seq-studio artifact pull <project-id>` | Active **deployment** source files for an Artifact Studio project (built bundle inputs), keyed by project UUID — **not** git history |
+| `seq-studio repos clone <ns>/<name>` | Repo source tree. With `ATLAS_GIT_PAT`, a real `git clone` via smart-HTTP; otherwise JSON-API materialize (no `.git` dir) |
+| `seq-studio artifact deploy --repo <ns>/<name>` | Build + deploy an artifact whose source lives in the platform git service (materializes, builds, uploads) |
+
+## Auth (git-service PATs)
+
+Personal Access Tokens authenticate `git clone` / `git push` (Basic auth:
+any username, PAT as password). **You do not need `seqapi`.**
+
+### Everyone (recommended) — Atlas UI
+
+1. Open **Settings → Tokens** in Atlas for your environment, e.g.
+   - Staging: https://staging.atlas.seqholdings.com/settings/tokens
+   - Production: https://atlas.seqholdings.com/settings/tokens
+   - BankSouth: https://banksouth.seqholdings.com/settings/tokens
+2. **New token** → scopes `repo:read` (add `repo:write` for push) → copy once
+3. Export and clone:
+
+```bash
+export ATLAS_GIT_PAT=atlas_git_…
+seq-studio repos clone artifacts/ai-fluency -e staging
+# or: git clone https://git:$ATLAS_GIT_PAT@staging.atlas.seqholdings.com/api/git-service/repos/<id>/git
+```
+
+You can also open **Repositories → Access tokens** / the clone popover’s
+**Manage tokens** link.
+
+### Sequence staff — CLI mint (optional)
+
+Requires `seqapi login` (Auth0). Same tokens as the UI:
+
+```bash
+seqapi login
+seq-studio auth pat create --name laptop --scopes repo:read,repo:write -e staging
+# optional: --expires 7d|30d|90d|1y|never  (default 30d)
+# optional: --store-credentials   # git credential approve for the env host
+
+seq-studio auth pat list -e staging
+seq-studio auth pat revoke <id> -e staging --yes
+```
+
+The raw token is printed **once** on create.
+
+## Repos commands
+
+`seq-studio repos <sub>` manages repos in the platform Git Service over the
+JSON API — the same repos `--repo <ns>/<name>` sources build from.
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio repos list [-e <env>] [--namespace <slug>] [--mine]` | repos visible on the environment (permission-filtered) |
+| `seq-studio repos namespaces [create <slug>] [-e <env>]` | list namespaces, or create one (creator becomes owner) |
+| `seq-studio repos show <ns>/<name> [-e <env>]` | detail: id, branches, clone URL; artifact project id when slug matches |
+| `seq-studio repos create <ns>/<name> [-e <env>] [--default-branch <b>]` | create an empty repo (needs namespace write) |
+| `seq-studio repos clone <ns>/<name> \| --url <clone-url> \| --id <uuid> [-e <env>] [--ref <r>] [--out <dir>] [--force]` | smart-HTTP `git clone` when `ATLAS_GIT_PAT` is set (`--url`/`--id` need no seqapi); otherwise JSON materialize + PAT hint |
+| `seq-studio repos pull <ns>/<name> [-e <env>] [--ref <r>] [--out <dir>] [--force]` | always materialize via JSON API (no `.git` dir); refuses a non-empty destination unless `--force` |
+| `seq-studio repos delete <ns>/<name> [-e <env>] [--yes]` | delete a repo — interactive confirm unless `--yes` |
+
+`show` prints the smart-HTTP clone URL (`…/repos/<id>/git`). Basic auth:
+any username, PAT as password. Prefer `repos clone` over hand-rolling the
+tree API.
+
+## Authorization
+
+The CLI carries no permissions of its own: every request is authorized
+server-side against your platform identity. Process `apply` and bundle
+registration require platform write access; managed functions, secrets,
+artifact projects, and repos are each gated by their own per-resource
+permissions. A `403` means your account lacks the grant for that resource —
+contact your platform administrator.
+
+## Design
+
+`seq-studio` knows only the platform HTTP API, the seqapi token file, and
+`config.toml`. The server does the work — register the bundle, promote the
+version, write the audit log — so the CLI runs from any checkout without
+server-side wiring on the developer's machine.

package/dist/artifact/delegate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `seq-studio artifact <sub>` — manage Artifact Studio apps.
+ *
+ * Delegates to `runCli` from the `@sequenceholdings/artifact-studio/cli`
+ * library export, so the command implementations live in one place. We:
+ *
+ *   1. Resolve `--env` from `~/.config/lattice/config.toml`.
+ *   2. Set `ARTIFACT_STUDIO_BASE_URL` so artifact-studio's API client
+ *      uses the resolved URL (instead of its own built-in env map).
+ *   3. Set `ARTIFACT_STUDIO_TOKEN` from the seqapi token file so auth
+ *      is shared with the rest of `seq-studio`.
+ *   4. Forward all remaining argv to `runCli`.
+ */
+export declare function runArtifactCommand(sub: string | undefined, rest: string[]): Promise<number>;
+/**
+ * Strip the seq-studio-only `--pr <number>` and `--env-url <url>` flags from
+ * argv and return the rest (forwarded to artifact-studio) plus the parsed
+ * values. These never reach artifact-studio — they're consumed here to resolve
+ * the preview base URL.
+ */
+export declare function extractPreviewFlags(argv: readonly string[]): {
+    rest: string[];
+    prNumber?: number;
+    envUrl?: string;
+};

package/dist/artifact/delegate.js

@@ -0,0 +1,263 @@
+/**
+ * `seq-studio artifact <sub>` — manage Artifact Studio apps.
+ *
+ * Delegates to `runCli` from the `@sequenceholdings/artifact-studio/cli`
+ * library export, so the command implementations live in one place. We:
+ *
+ *   1. Resolve `--env` from `~/.config/lattice/config.toml`.
+ *   2. Set `ARTIFACT_STUDIO_BASE_URL` so artifact-studio's API client
+ *      uses the resolved URL (instead of its own built-in env map).
+ *   3. Set `ARTIFACT_STUDIO_TOKEN` from the seqapi token file so auth
+ *      is shared with the rest of `seq-studio`.
+ *   4. Forward all remaining argv to `runCli`.
+ */
+import { getAccessToken, tryGetAccessToken } from '../auth.js';
+import { readConfig, resolveEnv } from '../config.js';
+import { normalizeShortEnvFlag, readEnvFromArgv } from '../env-flags.js';
+import { PREVIEW_DOMAIN, PREVIEW_PROJECT, resolvePreviewByPr } from '../preview.js';
+const ARTIFACT_USAGE = `usage:
+  seq-studio artifact init <dir>
+  seq-studio artifact validate [dir]
+  seq-studio artifact build [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--out file.json]
+  seq-studio artifact plan [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] -e <env>
+  seq-studio artifact deploy [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] -e <env> [--skip-unchanged] [--no-create] [--project <id>]
+  seq-studio artifact dev [dir] -e <env> [--once] [--key default]
+  seq-studio artifact pull <project-id> -e <env> --out <dir>
+  seq-studio artifact promote <deployment-id> -e <env>
+  seq-studio artifact rollback <deployment-id> -e <env>
+  seq-studio artifact list -e <env>
+  seq-studio artifact show <slug-or-id> -e <env>
+  seq-studio artifact status [-e <env>]
+  seq-studio artifact whoami -e <env>
+  seq-studio artifact env list
+
+  Built-in envs: local, staging, production, banksouth.
+
+  Source for build/plan/deploy: a local [dir] (default), a platform git-service
+  repo (--repo <ns>/<name>), or any git URL (--git-url <url>). --ref selects a
+  branch/tag/commit (default: the repo's default branch).
+
+  --repo clones over smart-HTTP and requires ATLAS_GIT_PAT (a repo:read PAT —
+  seq-studio auth pat create, or Atlas → Settings → Tokens).
+
+  Per-PR preview environments (https://studio-atlas-git-<slug>.preview.seqholdings.com):
+    -e preview:<branch-or-slug>   compute the preview host from a branch name
+    --pr <number>                 resolve the preview host from a PR (handles long slugs)
+    --env-url <url>               target an explicit preview URL (escape hatch)
+
+  Preview deploys sit behind a Cloudflare WAF gate. Off the company network/VPN,
+  set PREVIEW_ACCESS_HEADER=<secret> and the CLI sends it as x-preview-access.
+
+  Authenticate with: seqapi login
+`;
+export async function runArtifactCommand(sub, rest) {
+    if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+        console.log(ARTIFACT_USAGE);
+        return sub ? 0 : 1;
+    }
+    // Normalize `-e <env>` / `-e=<env>` to `--env <env>` because
+    // artifact-studio's argv parser (`shared/services/artifact-studio/src/cli.ts`)
+    // only recognizes long flags. Without this rewrite `seq-studio
+    // artifact plan -e staging` would land `-e` as positional and
+    // `staging` as the next positional, with `flags.env` undefined.
+    const normalizedRest = normalizeShortEnvFlag(rest);
+    // Pull off seq-studio-only preview flags (`--pr`, `--env-url`) so they're not
+    // forwarded to artifact-studio (its parser would store them as stray flags).
+    const { rest: forwardRest, prNumber, envUrl } = extractPreviewFlags(normalizedRest);
+    // Resolve --env if present so we can map to lattice config URLs. We
+    // pull from the cleaned argv so both `-e` and `--env` paths work.
+    const requested = readEnvFromArgv(forwardRest);
+    let resolved;
+    let argvForCli = forwardRest;
+    if (envUrl !== undefined) {
+        const validated = validatePreviewEnvUrl(envUrl);
+        // Explicit override wins over everything. Keep the user's --env name if
+        // they gave one, else label it `preview`.
+        resolved = { name: requested ?? 'preview', url: validated };
+        argvForCli = ensureEnvFlag(forwardRest, resolved.name);
+    }
+    else if (prNumber !== undefined) {
+        const preview = await resolvePreviewByPr({ pr: prNumber });
+        resolved = { name: `preview:${preview.slug}`, url: preview.url };
+        argvForCli = ensureEnvFlag(forwardRest, resolved.name);
+    }
+    else if (requested) {
+        const config = await readConfig();
+        resolved = resolveEnv({ config, requested });
+        // For `preview:<slug>` normalize the forwarded --env to the canonical name.
+        if (resolved.name !== requested)
+            argvForCli = ensureEnvFlag(forwardRest, resolved.name);
+    }
+    if (resolved) {
+        process.env['ARTIFACT_STUDIO_BASE_URL'] = resolved.url;
+        // When targeting a preview host, thread the Cloudflare WAF bypass header so
+        // deploys work off the company network/VPN (mirrors atlas-ui-shot). Harmless
+        // on built-in envs, so we only gate it on the host actually being a preview.
+        if (isPreviewUrl(resolved.url))
+            applyPreviewAccessHeader();
+    }
+    // Share the seqapi token. `tryGetAccessToken` resolves an M2M
+    // service-account token when AUTH0_M2M_CLIENT_SECRET is set (headless /
+    // CI / cloud-agent path) and otherwise the cached `seqapi login` user
+    // token (see ../auth.ts). If neither is available, artifact-studio
+    // commands that need a token surface their own error — we don't force
+    // `seqapi login` here because some commands (init, validate, build) work
+    // offline. Manual escape hatch: pass `--token <jwt>` (artifact-studio's
+    // CLI accepts it and it wins over everything).
+    const token = await tryGetAccessToken({ failClosedForM2m: true });
+    if (token) {
+        process.env['ARTIFACT_STUDIO_TOKEN'] = token;
+    }
+    // Lazy import so `process` / `doctor` commands don't pull in
+    // artifact-studio's vite/react/tailwind dependency graph.
+    const { runCli: runArtifactStudio, setTokenProvider } = await import('@sequenceholdings/artifact-studio/cli');
+    // The ARTIFACT_STUDIO_TOKEN env var above is captured once and never
+    // refreshes, so long-running commands (notably `artifact dev`) would start
+    // failing with "Authentication failed" once the initial token's TTL elapses.
+    // Hand artifact-studio a refreshing source — getAccessToken() mints a fresh
+    // access token via the Auth0 refresh grant when the cached one is near
+    // expiry — so a watch session survives indefinitely.
+    setTokenProvider(async () => {
+        if (process.env.AUTH0_M2M_CLIENT_SECRET?.trim()) {
+            // Fail closed for configured M2M failures so headless deploys never
+            // silently fall back to another cached identity.
+            return await getAccessToken();
+        }
+        try {
+            return await getAccessToken();
+        }
+        catch {
+            return null;
+        }
+    });
+    return runArtifactStudio([sub, ...argvForCli]);
+}
+/**
+ * Strip the seq-studio-only `--pr <number>` and `--env-url <url>` flags from
+ * argv and return the rest (forwarded to artifact-studio) plus the parsed
+ * values. These never reach artifact-studio — they're consumed here to resolve
+ * the preview base URL.
+ */
+export function extractPreviewFlags(argv) {
+    const rest = [];
+    let prNumber;
+    let envUrl;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        const [flag, inlineValue] = splitInlineValue(arg);
+        if (flag === '--pr') {
+            const value = inlineValue ?? takeValue(argv, i, () => (i += 1));
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed <= 0) {
+                throw new Error(`--pr requires a positive integer (got "${value ?? ''}").`);
+            }
+            prNumber = parsed;
+        }
+        else if (flag === '--env-url') {
+            const value = inlineValue ?? takeValue(argv, i, () => (i += 1));
+            if (!value)
+                throw new Error('--env-url requires a URL value.');
+            envUrl = value;
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    return { rest, prNumber, envUrl };
+}
+function splitInlineValue(arg) {
+    const eq = arg.indexOf('=');
+    if (arg.startsWith('--') && eq !== -1)
+        return [arg.slice(0, eq), arg.slice(eq + 1)];
+    return [arg, undefined];
+}
+function takeValue(argv, i, advance) {
+    const next = argv[i + 1];
+    if (next !== undefined && !next.startsWith('-')) {
+        advance();
+        return next;
+    }
+    return undefined;
+}
+/** Set or replace the `--env <name>` token so artifact-studio gets a clean name. */
+function ensureEnvFlag(argv, name) {
+    const out = [];
+    let replaced = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--env') {
+            out.push('--env', name);
+            // Skip the original value token if present.
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('-'))
+                i += 1;
+            replaced = true;
+        }
+        else {
+            out.push(arg);
+        }
+    }
+    if (!replaced)
+        out.push('--env', name);
+    return out;
+}
+function stripTrailingSlash(url) {
+    return url.replace(/\/+$/, '');
+}
+function validatePreviewEnvUrl(value) {
+    const trimmed = stripTrailingSlash(value.trim());
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`--env-url must be a valid URL (got "${value}").`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error('--env-url must not include a username/password component.');
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new Error(`--env-url must be an https preview URL on *.${PREVIEW_DOMAIN} (got "${parsed.protocol}//").`);
+    }
+    if (parsed.pathname !== '' && parsed.pathname !== '/') {
+        throw new Error('--env-url must be an origin URL without a path component.');
+    }
+    if (parsed.search || parsed.hash) {
+        throw new Error('--env-url must not include querystring or hash components.');
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (!host.endsWith(`.${PREVIEW_DOMAIN}`)) {
+        throw new Error(`--env-url must be an https preview URL on *.${PREVIEW_DOMAIN} (got "${parsed.hostname}").`);
+    }
+    const expectedPrefix = `${PREVIEW_PROJECT}-git-`;
+    if (!host.startsWith(expectedPrefix)) {
+        throw new Error(`--env-url must target a ${PREVIEW_PROJECT} preview alias (expected host starting with "${expectedPrefix}", got "${parsed.hostname}").`);
+    }
+    return parsed.origin;
+}
+function isPreviewUrl(url) {
+    try {
+        return new URL(url).hostname.endsWith(`.${PREVIEW_DOMAIN}`);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Thread the Cloudflare WAF bypass header through artifact-studio's HTTP client
+ * via ARTIFACT_STUDIO_EXTRA_HEADERS (read in artifact-studio/src/api.ts). Reads
+ * the secret from PREVIEW_ACCESS_HEADER — the same env var atlas-ui-shot uses.
+ * No-op when the secret isn't set (engineer is expected to be on the VPN).
+ */
+function applyPreviewAccessHeader() {
+    const secret = process.env['PREVIEW_ACCESS_HEADER']?.trim();
+    if (!secret)
+        return;
+    process.env['ARTIFACT_STUDIO_EXTRA_HEADERS'] = JSON.stringify({
+        'x-preview-access': secret,
+    });
+}

package/dist/atlas-client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Minimal authenticated HTTP client for Atlas. Same retry-on-503 contract
+ * as `shared/services/artifact-studio/src/api.ts` so behavior is
+ * consistent across both Sequence CLIs. Token + baseUrl are passed in by
+ * the caller — this file knows nothing about token files or config TOMLs.
+ */
+export interface ClientOptions {
+    baseUrl: string;
+    token: string;
+}
+export declare class AtlasApiError extends Error {
+    readonly status: number;
+    readonly path: string;
+    readonly statusText: string;
+    readonly body: unknown;
+    readonly name = "AtlasApiError";
+    constructor(status: number, message: string, path: string, statusText?: string, body?: unknown);
+}
+export declare function getJson<T>({ baseUrl, token, path, }: ClientOptions & {
+    path: string;
+}): Promise<T>;
+export declare function getJsonOr404<T>({ baseUrl, token, path, }: ClientOptions & {
+    path: string;
+}): Promise<T | null>;
+export declare function postJson<T>({ baseUrl, token, path, body, }: ClientOptions & {
+    path: string;
+    body?: unknown;
+}): Promise<T>;
+export declare function putJson<T>({ baseUrl, token, path, body, }: ClientOptions & {
+    path: string;
+    body?: unknown;
+}): Promise<T>;
+export declare function patchJson<T>({ baseUrl, token, path, body, }: ClientOptions & {
+    path: string;
+    body?: unknown;
+}): Promise<T>;
+export declare function deleteJson<T>({ baseUrl, token, path, body, }: ClientOptions & {
+    path: string;
+    body?: unknown;
+}): Promise<T>;
+/** DELETE for endpoints that return 204 with an empty body (deleteJson would choke on it). */
+export declare function deleteNoContent({ baseUrl, token, path, }: ClientOptions & {
+    path: string;
+}): Promise<void>;