@sequenceholdings/studio-cli 0.1.12 → 0.1.18

package/README.md

@@ -1,7 +1,7 @@
 # `@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
+apps, Managed Functions, Managed Secrets, Data Pipelines stage specs, and platform git repos. Runs from
 any repo against the platform over HTTP — no monorepo checkout required.
 
 ```
@@ -9,13 +9,15 @@ seq-studio process lint
 seq-studio process plan -e <env>
 seq-studio process apply -e <env>
 seq-studio artifact deploy -e <env>
+seq-studio pipeline validate
 seq-studio envs list
 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.
+> (`init`, `lint`, `simulate`, `build`, `bundle inspect`, `pipeline init`,
+> `pipeline validate`) work.
 > Sequence-internal contributors: see `INTERNAL.md` in the monorepo for
 > rollout SOPs, preview environments, and publishing docs.
 
@@ -44,16 +46,20 @@ releases install immediately.)
 
 ## Authenticate
 
-Run the built-in browser login once. `seq-studio` and `seqapi` share the
-resulting tokens at `~/.config/sequence-api/tokens.json`, so logging in with
-either CLI authenticates both.
+Run the built-in browser login. `seq-studio` and `seqapi` share short-lived
+access tokens at `~/.config/sequence-api/tokens.json`, so logging in with either
+CLI authenticates both. Refresh tokens are neither requested nor persisted;
+interactive commands perform a bounded PKCE login again after expiry.
 
 ```bash
-seq-studio login
-seq-studio doctor   # confirms config + auth + authorization
+seq-studio login                              # built-in Sequence environments
+seq-studio envs add bsm-staging <tenant-url>  # one-time tenant registration
+seq-studio login --env bsm-staging            # registered OpCo tenant realm
+seq-studio doctor                             # confirms config + auth + authorization
 ```
 
-Use `seq-studio logout` to remove the shared cached tokens.
+Use `seq-studio logout` to remove the shared Sequence session, or
+`seq-studio logout --env bsm-staging` to remove only that OpCo realm's session.
 
 ### Headless auth (CI) — M2M
 
@@ -62,16 +68,19 @@ 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
+export AUTH0_M2M_CLIENT_SECRET=...              # built-in Sequence environments
+export AUTH0_M2M_CLIENT_SECRET_BSM_STAGING=...  # registered bsm-staging realm
 seq-studio artifact deploy -e <env>
 ```
 
-The secret is read at runtime — never commit it. M2M carries app scopes but
+Registered OpCo environment names are upper-snaked in the variable suffix
+(`bsm-staging` → `BSM_STAGING`). Secrets are read at runtime — never commit them.
+M2M carries app access 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.
+Artifact commands do not accept bearer tokens through argv or environment.
+Use interactive login or the realm-specific M2M secret above.
 
 ## Environments
 
@@ -82,7 +91,7 @@ environment-discovery endpoint and caches the result at
 `~/.config/lattice/environments.json`.
 
 ```bash
-seq-studio login            # or: export AUTH0_M2M_CLIENT_SECRET=...
+seq-studio login            # or use the matching M2M secret described above
 seq-studio envs refresh     # fetch the environments visible to your identity
 seq-studio envs list        # show them (name, URL, source)
 ```
@@ -93,17 +102,23 @@ see depends on who you are — unauthenticated installs get `local` only, and
 authenticated identities get the deployments they're entitled to. Visibility
 is not access control: every request is still authorized server-side.
 
-You can always add or override environments yourself in
-`~/.config/lattice/config.toml` (user entries win over discovered ones):
+You can add or override trusted environments yourself in
+`~/.config/lattice/config.toml` (user entries win over discovered ones).
+Authenticated requests accept only HTTPS origins at `seqholdings.com` or its
+subdomains, plus HTTP loopback origins for local development. The CLI
+revalidates that exact origin immediately before attaching credentials and
+never follows authenticated redirects.
 
 ```toml
+# Must come before any [env.*] table — TOML attaches bare keys to the
+# preceding table, so a trailing default_env is silently ignored.
+default_env = "local"
+
 [env.local]
 url = "http://localhost:5001"
 
 [env.my-atlas]
-url = "https://atlas.example.com"
-
-default_env = "local"
+url = "https://my-atlas.seqholdings.com"
 ```
 
 Pass `--env <name>` (or `-e <name>`) on commands that talk to the platform.
@@ -121,14 +136,43 @@ the artifact folder's `.artifact-studio/config.json` `defaultEnv` (set by
 | `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 apply --repo processes/<name> [--ref <r>] -e <env> [--only <id1,id2>]` | Same as above, but materializes the source from a platform git-service repo. Pinned commit SHA is injected as bundle provenance. Requires `ATLAS_GIT_PAT` (or the target realm's M2M secret for CI) |
 | `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 simulate <id>` | Isolated child-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) |
 
+### Remote source for `apply`
+
+`apply` can deploy a process from the platform git service instead of a local
+checkout:
+
+```bash
+seq-studio process apply --repo processes/my-process -e staging
+seq-studio process apply --repo processes/my-process --ref v1.2.0 -e production
+```
+
+The source is materialized to a temp dir, dependencies are installed from the
+committed `pnpm-lock.yaml` (must be Chainguard-resolved), process definitions
+are discovered, the bundle is built with the pinned commit as provenance, and the
+temp tree is cleaned up — even on error. Only the `processes` namespace is
+accepted; other namespaces (artifacts, managed-functions) are rejected.
+
+Auth: same as `artifact deploy --repo` — `ATLAS_GIT_PAT` for the smart-HTTP
+clone path, or the target realm's M2M secret for CI's JSON materialize path.
+Those credentials remain in the parent CLI and are not forwarded to dependency
+installation or process build tooling. Each install uses fresh temporary
+package-manager caches that are removed after the invocation.
+
+This is ambient-credential isolation, not an OS security sandbox. Build workers
+still run as the caller's uid, so hostile source may inspect other same-uid
+processes or readable files on platforms that permit it (for example, Linux
+`/proc`). Build reviewed source only; use a dedicated ephemeral runner with no
+unrelated credentials when the source is not trusted.
+
 ### Process discovery
 
 `seq-studio` walks the current working directory for any subfolder
@@ -184,14 +228,26 @@ of the pipeline (build → upload) is identical regardless of origin:
 |------|--------|
 | _(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) |
+| `--git-url <url>` | a public, credential-free HTTPS 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.
+provenance. `--repo` needs `-e <env>` + a platform login. M2M/CI builds accept
+only platform-managed `--repo` sources; `--git-url` is interactive-only and
+rejects embedded credentials, query tokens, SSH/file URLs, and Git remote
+helpers. `dev` is local-only.
+
+Artifact builds, dependency installs, process-definition imports, and local
+process simulations run in short-lived children with an allowlisted runtime
+environment and a synthetic home/config directory. Parent bearer tokens, Auth0
+M2M secrets, Doppler tokens, cloud credentials, GitHub tokens, and user config
+files are not inherited. The platform Git Service clone path passes only its
+single scoped PAT to `git` through an ephemeral askpass helper.
+This is a credential-inheritance boundary, not an OS filesystem sandbox:
+child code still runs as the invoking user and must be treated as trusted to
+read files that it names explicitly outside the synthetic home.
 
 ## Pull / clone / deploy — which path?
 
@@ -230,7 +286,7 @@ You can also open **Repositories → Access tokens** / the clone popover’s
 Requires Auth0 login. Same identity as the UI:
 
 ```bash
-seq-studio login
+seq-studio login   # add --env <registered-opco-env> for a tenant realm
 seq-studio auth pat create --name laptop --scopes repo:read,repo:write -e <env>
 # optional: --expires 7d|30d|90d|1y|never  (default 30d)
 # optional: --store-credentials   # git credential approve for the env host
@@ -248,18 +304,48 @@ 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` |
+| `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.
 
+## Pipeline commands
+
+`seq-studio pipeline <sub>` authors and validates Data Pipelines **stage
+specs** — the typed contracts (`<name>.stage.yml`) a Pipeline repo
+(`pipelines/<domain>`) is made of. Validation logic lives in
+`@sequenceholdings/pipeline-spec` (an optional peer, like `@sequenceholdings/orm`);
+install it alongside the CLI to use this family.
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio pipeline init --type ingestion\|transformation\|serving <name> [--dir <dir>]` | Scaffold `<name>.stage.yml` (commented per-kind template) plus a `src/` entrypoint stub (serving stages are declarative — no stub). Refuses to overwrite an existing spec |
+| `seq-studio pipeline validate [dir] [--assets <file\|url>] [--json]` | Run the full offline spec gate: envelope + body validation, `schema_ref` resolution, and repo-level graph validation (reference resolution, single-writer, cycles, column subsets, serving projection checks). Exit 0/1 |
+| `seq-studio pipeline plan --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--json]` | Plan a Pipeline deploy (materialize → SDK/`validateSpecGraph` → compile → live-diff → provision findings). Does **not** run Databricks `bundle validate` (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). `--json` emits the stable plan envelope |
+| `seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha> -e <env> [--approved-by <sub>] [--no-wait]` | Plan then enqueue deploy; Trigger runs `bundle validate` then `bundle deploy` against reviewed bytes. Polls to terminal unless `--no-wait`. Production/banksouth require a pinned 40-hex SHA (client + server) |
+| `seq-studio pipeline run-now --stage <slug> -e <env> [--repo pipelines/<slug>] [--json]` | Run the stage's active job or DLT pipeline immediately and print its Databricks run URL |
+| `seq-studio pipeline promote --stage <slug> --version <v> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]` | Promote a validated version to another environment. Prod/banksouth require `--approved-by` naming the authenticated caller (approvals are self-recorded); `--repo` disambiguates a slug that exists in multiple Pipelines |
+| `seq-studio pipeline rollback --stage <slug> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]` | Redeploy the previously retired deployment's version. Prod/banksouth require `--approved-by` — approvals are explicit even for rollbacks |
+
+`validate` is offline — no network or database. `--assets` supplies a
+registry **asset export** (JSON) so inputs referencing other Pipelines'
+assets resolve; pass a local file or an authenticated URL. `--json` emits a
+stable machine shape (`{ ok, stages, findings[] }` with machine-readable
+finding codes and consumer lists) for CI annotation — the
+`pipeline-verify.yml` workflow runs exactly this on PRs touching
+`pipelines/**`.
+
+For local Atlas development, `-e local` uses the server's isolated `dev`
+deployment target. Plan, deploy, and `run-now` therefore operate on the same
+personal dev Databricks catalog and Lakebase branch configured for local Atlas.
+
 ## Authorization
 
 The CLI carries no permissions of its own: every request is authorized

package/dist/artifact/delegate.d.ts

@@ -7,8 +7,8 @@
  *   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`.
+ *   3. Install an internal token provider so auth is shared with the rest of
+ *      `seq-studio` without exposing the bearer in argv or environment.
  *   4. Forward all remaining argv to `runCli`.
  */
 export declare function runArtifactCommand(sub: string | undefined, rest: string[]): Promise<number>;

package/dist/artifact/delegate.js

@@ -7,11 +7,11 @@
  *   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`.
+ *   3. Install an internal token provider so auth is shared with the rest of
+ *      `seq-studio` without exposing the bearer in argv or environment.
  *   4. Forward all remaining argv to `runCli`.
  */
-import { getAccessToken, M2mTokenError, tryGetAccessToken } from '../auth.js';
+import { getAccessTokenWithMode, M2mTokenError, tryGetAccessTokenWithMode, } from '../auth.js';
 import { readConfig, resolveEnvWithDiscovery } from '../config.js';
 import { fetchCatalog, readCachedCatalog } from '../env-catalog.js';
 import { normalizeShortEnvFlag, readEnvFromArgv } from '../env-flags.js';
@@ -36,11 +36,13 @@ const ARTIFACT_USAGE = `usage:
   discovered after you authenticate).
 
   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
+  repo (--repo <ns>/<name>), or a public HTTPS 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).
+  Interactive --repo builds clone over smart-HTTP and require ATLAS_GIT_PAT
+  (a repo:read PAT — seq-studio auth pat create, or Atlas → Settings → Tokens).
+  Headless M2M builds use JSON materialize and accept only platform-managed
+  --repo sources.
 
   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
@@ -53,23 +55,20 @@ const ARTIFACT_USAGE = `usage:
   Authenticate with: seq-studio login
 `;
 export async function runArtifactCommand(sub, rest) {
+    if (rest.some((arg) => arg === '--token' || arg.startsWith('--token='))) {
+        console.error('seq-studio artifact does not accept bearer tokens via --token. ' +
+            'Use `seq-studio login` interactively or configure the realm-specific ' +
+            'AUTH0_M2M_CLIENT_SECRET for headless automation.');
+        return 1;
+    }
+    // Never pass a legacy bearer environment variable into the embedded package.
+    delete process.env['ARTIFACT_STUDIO_TOKEN'];
     // Older artifact-studio versions exposed nested login/logout commands backed
     // by a separate token file. Keep those commands working, but route them to
     // seq-studio's shared token so every namespace uses the same identity.
     if (sub === 'login' || sub === 'logout') {
         if (rest.length > 0) {
-            if (sub === 'login' && rest.includes('--token')) {
-                // The legacy `artifact login --token <jwt>` persisted a bearer to
-                // artifact-studio's own token file — a store this unification retires.
-                console.error('seq-studio artifact login no longer stores a bearer token.\n' +
-                    'Scripted/headless options:\n' +
-                    '  - pass --token <jwt> directly to the artifact command (deploy/plan/whoami/...)\n' +
-                    '  - export ARTIFACT_STUDIO_TOKEN=<jwt> for the session\n' +
-                    '  - set AUTH0_M2M_CLIENT_SECRET for service-account (M2M) auth in CI');
-            }
-            else {
-                console.error(`seq-studio artifact ${sub} does not accept arguments.`);
-            }
+            console.error(`seq-studio artifact ${sub} does not accept arguments.`);
             return 1;
         }
         const auth = await import('../login.js');
@@ -133,51 +132,22 @@ export async function runArtifactCommand(sub, rest) {
     // without an explicit --env flag — the stored `.artifact-studio/config.json`
     // defaultEnv, `artifact env set <name>` — would otherwise fall back to
     // artifact-studio's built-in local-only map and fail on deployed envs.
-    const { envs } = await readConfig();
-    process.env['ARTIFACT_STUDIO_ENV_URLS'] = JSON.stringify(Object.fromEntries(Object.entries(envs).map(([name, { url }]) => [name, url])));
-    // An explicit `--token <jwt>` is the manual escape hatch and must win over
-    // everything, including a configured-but-failing M2M credential (which
-    // `tryGetAccessToken({ failClosedForM2m: true })` would otherwise turn into
-    // an abort before argv ever reaches artifact-studio). artifact-studio's
-    // `getOptionalToken` checks `flags.token` first, so when it's present we
-    // skip shared-token resolution entirely. Only the two-token `--token <jwt>`
-    // form counts: artifact-studio's parser does not split `--token=<jwt>`.
-    const hasExplicitToken = hasTokenFlag(argvForCli);
+    const routingConfig = await readConfig();
+    process.env['ARTIFACT_STUDIO_ENV_URLS'] = JSON.stringify(Object.fromEntries(Object.entries(routingConfig.envs).map(([name, { url }]) => [name, url])));
     // 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');
-    if (!hasExplicitToken) {
-        // 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 interactive user
-        // token (see ../auth.ts). If neither is available, artifact-studio
-        // commands that need a token surface their own error — we don't force
-        // `seq-studio login` here because some commands (init, validate, build)
-        // work offline.
-        const token = await tryGetAccessToken({ failClosedForM2m: true });
-        if (token) {
-            process.env['ARTIFACT_STUDIO_TOKEN'] = token;
-        }
-        // 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;
-            }
-        });
-    }
+    const { getConfiguredDefaultEnv, runCli: runArtifactStudio, setTokenProvider } = await import('@sequenceholdings/artifact-studio/cli');
+    const authEnvName = resolved?.name ?? (await getConfiguredDefaultEnv());
+    const targetUrl = resolved?.url ??
+        process.env['ARTIFACT_STUDIO_BASE_URL']?.trim() ??
+        (authEnvName ? routingConfig.envs[authEnvName]?.url : undefined);
+    setTokenProvider(({ allowInteractiveLogin }) => allowInteractiveLogin
+        ? getAccessTokenWithMode({ env: authEnvName, targetUrl })
+        : tryGetAccessTokenWithMode({
+            failClosedForM2m: true,
+            env: authEnvName,
+            targetUrl,
+        }));
     return runArtifactStudio([sub, ...argvForCli]);
 }
 /**
@@ -240,18 +210,6 @@ export function extractPreviewFlags(argv) {
     }
     return { rest, prNumber, envUrl };
 }
-/**
- * True when argv carries an explicit two-token `--token <jwt>` that
- * artifact-studio's parser will bind to `flags.token`. `--token=<jwt>` is
- * excluded because that parser stores it as a stray flag and never binds it.
- */
-function hasTokenFlag(argv) {
-    const index = argv.indexOf('--token');
-    if (index === -1)
-        return false;
-    const value = argv[index + 1];
-    return value !== undefined && !value.startsWith('--');
-}
 function splitInlineValue(arg) {
     const eq = arg.indexOf('=');
     if (arg.startsWith('--') && eq !== -1)

package/dist/atlas-client.js

@@ -4,6 +4,7 @@
  * consistent across both Sequence CLIs. Token + baseUrl are passed in by
  * the caller — this file knows nothing about token files or config TOMLs.
  */
+import { authenticatedRequestUrl } from '@sequenceholdings/artifact-studio/deployment-validation';
 import { PREVIEW_DOMAIN } from './preview.js';
 const MAX_503_RETRIES = 5;
 const DEFAULT_RETRY_AFTER_SECONDS = 2;
@@ -34,6 +35,18 @@ async function fetchWith503Retry(input, init) {
         await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
     }
 }
+async function authenticatedFetch({ baseUrl, init = {}, path, token, }) {
+    const url = authenticatedRequestUrl({ baseUrl, path });
+    return fetchWith503Retry(url, {
+        ...init,
+        redirect: 'manual',
+        headers: {
+            ...previewAccessHeaders(baseUrl),
+            ...init.headers,
+            Authorization: `Bearer ${token}`,
+        },
+    });
+}
 function previewAccessHeaders(baseUrl) {
     const secret = process.env.PREVIEW_ACCESS_HEADER?.trim();
     if (!secret)
@@ -89,17 +102,13 @@ async function responseError(response, path) {
     return new AtlasApiError(response.status, message, path, response.statusText, body);
 }
 export async function getJson({ baseUrl, token, path, }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        headers: { ...previewAccessHeaders(baseUrl), Authorization: `Bearer ${token}` },
-    });
+    const response = await authenticatedFetch({ baseUrl, token, path });
     if (!response.ok)
         throw await responseError(response, path);
     return response.json();
 }
 export async function getJsonOr404({ baseUrl, token, path, }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        headers: { ...previewAccessHeaders(baseUrl), Authorization: `Bearer ${token}` },
-    });
+    const response = await authenticatedFetch({ baseUrl, token, path });
     if (response.status === 404)
         return null;
     if (!response.ok)
@@ -107,56 +116,60 @@ export async function getJsonOr404({ baseUrl, token, path, }) {
     return response.json();
 }
 export async function postJson({ baseUrl, token, path, body, }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        method: 'POST',
-        headers: {
-            ...previewAccessHeaders(baseUrl),
-            Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
+    const response = await authenticatedFetch({
+        baseUrl,
+        token,
+        path,
+        init: {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
         },
-        body: body === undefined ? undefined : JSON.stringify(body),
     });
     if (!response.ok)
         throw await responseError(response, path);
     return response.json();
 }
 export async function putJson({ baseUrl, token, path, body, }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        method: 'PUT',
-        headers: {
-            ...previewAccessHeaders(baseUrl),
-            Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
+    const response = await authenticatedFetch({
+        baseUrl,
+        token,
+        path,
+        init: {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
         },
-        body: body === undefined ? undefined : JSON.stringify(body),
     });
     if (!response.ok)
         throw await responseError(response, path);
     return response.json();
 }
 export async function patchJson({ baseUrl, token, path, body, }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        method: 'PATCH',
-        headers: {
-            ...previewAccessHeaders(baseUrl),
-            Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
+    const response = await authenticatedFetch({
+        baseUrl,
+        token,
+        path,
+        init: {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
         },
-        body: body === undefined ? undefined : JSON.stringify(body),
     });
     if (!response.ok)
         throw await responseError(response, path);
     return response.json();
 }
 export async function deleteJson({ baseUrl, token, path, body, }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        method: 'DELETE',
-        headers: {
-            ...previewAccessHeaders(baseUrl),
-            Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
+    const response = await authenticatedFetch({
+        baseUrl,
+        token,
+        path,
+        init: {
+            method: 'DELETE',
+            headers: { 'Content-Type': 'application/json' },
+            body: body === undefined ? undefined : JSON.stringify(body),
         },
-        body: body === undefined ? undefined : JSON.stringify(body),
     });
     if (!response.ok)
         throw await responseError(response, path);
@@ -164,9 +177,11 @@ export async function deleteJson({ baseUrl, token, path, body, }) {
 }
 /** DELETE for endpoints that return 204 with an empty body (deleteJson would choke on it). */
 export async function deleteNoContent({ baseUrl, token, path, }) {
-    const response = await fetchWith503Retry(`${baseUrl}${path}`, {
-        method: 'DELETE',
-        headers: { ...previewAccessHeaders(baseUrl), Authorization: `Bearer ${token}` },
+    const response = await authenticatedFetch({
+        baseUrl,
+        token,
+        path,
+        init: { method: 'DELETE' },
     });
     if (!response.ok)
         throw await responseError(response, path);

package/dist/auth-cmds/commands.d.ts

@@ -1,7 +1,7 @@
 import type { ParsedArgs } from '../process/commands.js';
 declare const PAT_SCOPES: readonly ["repo:read", "repo:write", "repo:admin"];
 type PatScope = (typeof PAT_SCOPES)[number];
-export declare const AUTH_USAGE = "usage:\n  seq-studio auth pat create --name <n> [--scopes repo:read,repo:write] [-e env]\n                             [--expires 7d|30d|90d|1y|never] [--store-credentials]\n  seq-studio auth pat list [-e env]\n  seq-studio auth pat revoke <id> [-e env] [--yes]\n\n  Issue a personal access token for git clone / git push against the platform\n  git service.\n\n  Authenticate with `seq-studio login`, then run `auth pat create`.\n  Alternatively, open Atlas \u2192 Settings \u2192 Tokens:\n    https://<atlas-host>/settings/tokens\n  Sign in, create a token (repo:read / repo:write), copy once, then:\n    export ATLAS_GIT_PAT=<token>\n\n  On create the raw token is printed ONCE \u2014 store it; Atlas cannot re-show it.\n  Git Basic auth: any username (e.g. git), PAT as the password.\n\n  Flags: -e/--env <env>  (see: seq-studio envs list)\n";
+export declare const AUTH_USAGE = "usage:\n  seq-studio auth pat create --name <n> -e <env> [--scopes repo:read,repo:write]\n                             [--expires 7d|30d|90d|1y|never] [--store-credentials]\n  seq-studio auth pat list -e <env>\n  seq-studio auth pat revoke <id> -e <env> [--yes]\n\n  Issue a personal access token for git clone / git push against the platform\n  git service.\n\n  Authenticate with `seq-studio login`, then run `auth pat create -e <env>`.\n  Alternatively, open Atlas \u2192 Settings \u2192 Tokens:\n    https://<atlas-host>/settings/tokens\n  Sign in, create a token (repo:read / repo:write), copy once, then:\n    export ATLAS_GIT_PAT=<token>\n\n  On create the raw token is printed ONCE \u2014 store it; Atlas cannot re-show it.\n  Git Basic auth: any username (e.g. git), PAT as the password.\n\n  Flags: -e/--env <env> (required; see: seq-studio envs list)\n";
 export declare function parsePatScopes(raw: string | undefined): PatScope[];
 /**
  * Map UI-style duration choices to an absolute ISO-8601 expiresAt, or undefined

package/dist/auth-cmds/commands.js

@@ -10,6 +10,7 @@
  */
 import { deleteNoContent, getJson, postJson } from '../atlas-client.js';
 import { printCliError } from '../cli-errors.js';
+import { REQUIRE_EXPLICIT_ENV_MESSAGE } from '../env-flags.js';
 import { buildContext, clientOptions, flagBool, LOG, } from '../functions/commands.js';
 import { readConfig } from '../config.js';
 import { confirmYes } from '../prompt.js';
@@ -38,15 +39,15 @@ function stringFlag(flags, key) {
     return value;
 }
 export const AUTH_USAGE = `usage:
-  seq-studio auth pat create --name <n> [--scopes repo:read,repo:write] [-e env]
+  seq-studio auth pat create --name <n> -e <env> [--scopes repo:read,repo:write]
                              [--expires 7d|30d|90d|1y|never] [--store-credentials]
-  seq-studio auth pat list [-e env]
-  seq-studio auth pat revoke <id> [-e env] [--yes]
+  seq-studio auth pat list -e <env>
+  seq-studio auth pat revoke <id> -e <env> [--yes]
 
   Issue a personal access token for git clone / git push against the platform
   git service.
 
-  Authenticate with \`seq-studio login\`, then run \`auth pat create\`.
+  Authenticate with \`seq-studio login\`, then run \`auth pat create -e <env>\`.
   Alternatively, open Atlas → Settings → Tokens:
     https://<atlas-host>/settings/tokens
   Sign in, create a token (repo:read / repo:write), copy once, then:
@@ -55,7 +56,7 @@ export const AUTH_USAGE = `usage:
   On create the raw token is printed ONCE — store it; Atlas cannot re-show it.
   Git Basic auth: any username (e.g. git), PAT as the password.
 
-  Flags: -e/--env <env>  (see: seq-studio envs list)
+  Flags: -e/--env <env> (required; see: seq-studio envs list)
 `;
 async function authContext(args) {
     if (args.flags.env === true || args.flags.e === true) {
@@ -66,6 +67,10 @@ async function authContext(args) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        // Missing `-e` is actionable on its own — don't bury it under login/PAT
+        // setup advice (that wrap is for real auth/token failures).
+        if (message === REQUIRE_EXPLICIT_ENV_MESSAGE)
+            throw err;
         // buildContext failed before we know the env URL; offer CLI login and
         // render the tokens-page URLs from the environments visible to this
         // identity (third-party / OpCo developers only see their own hosts).
@@ -119,7 +124,7 @@ export function resolveExpiresAt(choice) {
 export async function authPatCreateCommand(args) {
     const name = stringFlag(args.flags, 'name');
     if (!name) {
-        console.error('usage: seq-studio auth pat create --name <n> [--scopes ...] [-e env]');
+        console.error('usage: seq-studio auth pat create --name <n> -e <env> [--scopes ...]');
         return 1;
     }
     if (name.length < 3) {
@@ -193,7 +198,7 @@ export async function authPatListCommand(args) {
 export async function authPatRevokeCommand(args) {
     const id = args.positional[0];
     if (!id) {
-        console.error('usage: seq-studio auth pat revoke <id> [-e env] [--yes]');
+        console.error('usage: seq-studio auth pat revoke <id> -e <env> [--yes]');
         return 1;
     }
     const ctx = await authContext(args);