@sequenceholdings/studio-cli 0.1.13 → 0.1.18

package/dist/functions/commands.js

@@ -6,10 +6,11 @@ import { promisify } from 'node:util';
 import { createInterface } from 'node:readline';
 import { Writable } from 'node:stream';
 import { load as parseYaml } from 'js-yaml';
-import { getAccessToken } from '../auth.js';
+import { getAccessTokenWithMode, tryGetAccessTokenWithMode } from '../auth.js';
 import { resolveEnvWithDiscovery } from '../config.js';
 import { AtlasApiError, deleteJson, getJson, postJson } from '../atlas-client.js';
 import { clarifyApplyFailureReason, printCliError } from '../cli-errors.js';
+import { REQUIRE_EXPLICIT_ENV_MESSAGE } from '../env-flags.js';
 import { confirmYes } from '../prompt.js';
 import { collectBundleFiles, isDirectory, validateLocalBundle, } from './bundle.js';
 import { managedFunctionManifestSchema, MF_MANIFEST_FILENAME, manifestEgressHosts, manifestEgressIpRanges, } from './manifest.js';
@@ -23,15 +24,48 @@ const POLL_TIMEOUT_MS = 20 * 60 * 1000;
 export function flagBool(flags, ...keys) {
     return keys.some((key) => flags[key] === true || flags[key] === 'true');
 }
+export function requestedEnvironment(args) {
+    return ((typeof args.flags.env === 'string' ? args.flags.env : undefined) ??
+        (typeof args.flags.e === 'string' ? args.flags.e : undefined));
+}
+/**
+ * Resolve env + token for Atlas network commands. Requires an explicit
+ * `-e/--env` so partners never hit the built-in `local` default and get an
+ * opaque `fetch failed` (same contract as `functions deploy`).
+ */
 export async function buildContext(args) {
-    const requested = (typeof args.flags.env === 'string' ? args.flags.env : undefined) ??
-        (typeof args.flags.e === 'string' ? args.flags.e : undefined);
+    const requested = requestedEnvironment(args);
+    if (!requested) {
+        throw new Error(REQUIRE_EXPLICIT_ENV_MESSAGE);
+    }
     const env = await resolveEnvWithDiscovery({ requested });
-    const token = await getAccessToken();
-    return { env, token };
+    const auth = await getAccessTokenWithMode({ env: env.name, targetUrl: env.url });
+    return { authMode: auth.authMode, env, token: auth.token };
 }
 export function clientOptions(ctx) {
-    return { baseUrl: ctx.env.url, token: ctx.token };
+    return {
+        baseUrl: ctx.env.url,
+        token: ctx.token,
+    };
+}
+function sourceClientOptions(ctx) {
+    return {
+        ...(ctx.authMode ? { authMode: ctx.authMode } : {}),
+        ...clientOptions(ctx),
+    };
+}
+async function buildSourceOptions({ args, spec, }) {
+    if (spec.kind === 'git-service') {
+        return sourceClientOptions(await buildContext(args));
+    }
+    if (spec.kind === 'git-url') {
+        const auth = await tryGetAccessTokenWithMode({
+            failClosedForM2m: true,
+            env: requestedEnvironment(args),
+        });
+        return auth ? { authMode: auth.authMode } : {};
+    }
+    return {};
 }
 export async function readManifestOptional(dir) {
     const path = join(dir, MF_MANIFEST_FILENAME);
@@ -316,9 +350,10 @@ export async function functionsInitCommand(args) {
 // ---------------------------------------------------------------------------
 export async function functionsBuildCommand(args) {
     const spec = parseFunctionsSourceSpec(args);
-    // Local and git-url sources build offline; only a git-service repo needs
-    // the target environment + token to fetch its tree.
-    const remote = spec.kind === 'git-service' ? clientOptions(await buildContext(args)) : {};
+    // A public git URL needs no bearer token, but optional auth resolution still
+    // identifies a selected M2M principal so policy can reject arbitrary CI
+    // input before cloning. Local builds remain completely offline.
+    const remote = await buildSourceOptions({ args, spec });
     const source = await resolveArtifactSource(spec, remote);
     try {
         return await buildFromResolvedSource({ spec, source });
@@ -376,13 +411,19 @@ async function getFunctionDetail(ctx, functionId) {
     }
 }
 export async function functionsDeployCommand(args) {
+    // Fail before source resolution / auth so a missing `-e` never becomes
+    // `fetch failed` against localhost. `buildContext` enforces the same rule.
+    if (!requestedEnvironment(args)) {
+        console.error(`${LOG} ${REQUIRE_EXPLICIT_ENV_MESSAGE}`);
+        return 1;
+    }
     const spec = parseFunctionsSourceSpec(args);
-    // Only a --repo source needs env + auth up front — materializing it fetches
-    // the tree from the target environment's git service. Local / git-url
-    // sources defer auth until after local validation, so bad input (missing
-    // manifest, bad --from-env-file) fails fast instead of failing on auth.
-    const ctx = spec.kind === 'git-service' ? await buildContext(args) : null;
-    const source = await resolveArtifactSource(spec, ctx ? clientOptions(ctx) : {});
+    // Remote deploys resolve auth up front: --repo needs it to fetch the tree,
+    // while --git-url must reject a selected M2M principal before cloning.
+    // Local sources still defer auth until after validation so malformed local
+    // input fails before any login/network work.
+    const ctx = spec.kind !== 'local' ? await buildContext(args) : null;
+    const source = await resolveArtifactSource(spec, ctx ? sourceClientOptions(ctx) : {});
     try {
         return await deployFromResolvedSource({ args, spec, ctx, source });
     }
@@ -837,7 +878,7 @@ async function listVersions(ctx, functionId) {
 export async function functionsPromoteCommand(args) {
     const versionName = args.positional[0];
     if (!versionName) {
-        console.error('usage: seq-studio functions promote <version> [-e env] [--fn slug]');
+        console.error('usage: seq-studio functions promote <version> -e <env> [--fn slug]');
         return 1;
     }
     const ctx = await buildContext(args);
@@ -932,32 +973,33 @@ export async function functionsDeleteCommand(args) {
 export const FUNCTIONS_USAGE = `usage:
   seq-studio functions init <dir>                     scaffold manifest + TypeScript hello-world handler
   seq-studio functions build [--dir d]                local pre-flight (manifest, lockfile, size)
-  seq-studio functions deploy [-e env] [-m msg]       preview + confirm secrets + upload and deploy
-  seq-studio functions list [-e env] [--match-local]  functions visible on the environment
-  seq-studio functions show [-e env] [--fn slug]      detail for one function (versions, secrets)
-  seq-studio functions logs [-e env] [--limit N] [--since t]  Cloud Logging snapshot (reader-gated)
-  seq-studio functions promote <version> [-e env]     make a version live
-  seq-studio functions rollback [<version>] [-e env]  redeploy a prior version
-  seq-studio functions delete [--yes]                 archive function + tear down GCP resources
+  seq-studio functions deploy -e <env> [-m msg]       preview + confirm secrets + upload and deploy
+  seq-studio functions list -e <env> [--match-local]  functions visible on the environment
+  seq-studio functions show -e <env> [--fn slug]      detail for one function (versions, secrets)
+  seq-studio functions logs -e <env> [--limit N] [--since t]  Cloud Logging snapshot (reader-gated)
+  seq-studio functions promote <version> -e <env>     make a version live
+  seq-studio functions rollback [<version>] -e <env>  redeploy a prior version
+  seq-studio functions delete -e <env> [--yes]        archive function + tear down GCP resources
                                                       (version history is retained)
 
-  Flags: -e/--env <env|preview:<slug>> (see: seq-studio envs list) · --fn <slug> · --dir <path>
+  Flags: -e/--env <env|preview:<slug>> (required for network commands; see: seq-studio envs list) · --fn <slug> · --dir <path>
          --from-env-file <path>  (default: .env) source file for secret values
          --no-wait · --yes
          --no-provision  (deploy) update-only: error instead of registering a new
                          shell, writing secret values, or attaching secrets (CI sweep)
 
   Source for build/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). Remote sources record
   the pinned commit as provenance (never dirty) and NEVER read a repo-committed
   .env for secret values — provision secrets server-side or pass a local
   --from-env-file (resolved against your cwd).
 
-  --repo clones over smart-HTTP and REQUIRES a git PAT in ATLAS_GIT_PAT
-  (repo:read scope — \`seq-studio auth pat create --scopes repo:read\`, or
-  Atlas → Settings → Tokens). It's the same token you clone the repo with;
-  --env + seq-studio login are still needed to resolve the repo and deploy.
+  Interactive --repo builds clone over smart-HTTP and require a repo:read git
+  PAT in ATLAS_GIT_PAT (\`seq-studio auth pat create --scopes repo:read\`, or
+  Atlas → Settings → Tokens). Headless M2M builds use JSON materialize and
+  accept only platform-managed --repo sources. Interactive builds also need
+  --env + seq-studio login to resolve the repo and deploy.
 `;
 export async function runFunctionsCommand(sub, args) {
     try {

package/dist/functions/manifest.d.ts

@@ -57,6 +57,7 @@ export declare const managedFunctionManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
     secrets: z.ZodDefault<z.ZodArray<z.ZodString>>;
     egress: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    service_account: z.ZodOptional<z.ZodString>;
     input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     output_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     capabilities: z.ZodDefault<z.ZodObject<{

package/dist/functions/manifest.js

@@ -488,6 +488,11 @@ function validateCapabilityGates({ gates, uses, roles, }) {
     }
     return errors;
 }
+/**
+ * Platform service-account reference: slug (strictly lowercase) or uuid id.
+ * Mirrors atlas/src/server/services/managed-functions/manifest.ts.
+ */
+const SERVICE_ACCOUNT_REF_RE = /^([a-z][a-z0-9-]{1,98}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/;
 export const managedFunctionManifestSchema = z.object({
     schema_version: z.literal(1).default(1),
     function: z.object({
@@ -538,6 +543,17 @@ export const managedFunctionManifestSchema = z.object({
         }
     })
         .default([]),
+    /**
+     * The platform service account this function ACTS AS for ORM data access
+     * (slug or id). Required whenever `capabilities.data` reaches a namespace,
+     * rejected otherwise. Resolved and authorized server-side at activation —
+     * the deploy actor must hold `actor` on the account when the attachment
+     * changes. Mirrors atlas/src/server/services/managed-functions/manifest.ts.
+     */
+    service_account: z
+        .string()
+        .regex(SERVICE_ACCOUNT_REF_RE, 'service_account must be a platform service-account slug (lowercase alphanumeric with hyphens) or uuid')
+        .optional(),
     input_schema: z.record(z.string(), z.unknown()).optional(),
     output_schema: z.record(z.string(), z.unknown()).optional(),
     /**
@@ -583,4 +599,24 @@ export const managedFunctionManifestSchema = z.object({
     })) {
         ctx.addIssue({ code: 'custom', message, path: ['capabilities', 'gates'] });
     }
+    // A namespace is "reached" when its block declares at least one table,
+    // action, or raw query — the same rule the server's floor reconciliation
+    // uses (readManifestDataNamespaces).
+    const reachesData = Object.values(manifest.capabilities.data).some((block) => block.tables.length > 0 || block.actions.length > 0 || block.query);
+    if (reachesData && manifest.service_account === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'capabilities.data requires a top-level service_account — the platform service ' +
+                'account this function acts as for ORM data access (a platform operator creates ' +
+                'the account; the deployer needs the actor role on it)',
+            path: ['service_account'],
+        });
+    }
+    if (!reachesData && manifest.service_account !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'service_account is only used for ORM data access — declare capabilities.data or remove it',
+            path: ['service_account'],
+        });
+    }
 });

package/dist/login.d.ts

@@ -1,18 +1,23 @@
+import { type AuthRealm } from './auth.js';
 interface LoginOptions {
     port?: number;
     timeoutMs?: number;
     fetchImpl?: typeof fetch;
     now?: () => number;
     openBrowser?: (authorizationUrl: string) => void | Promise<void>;
+    /** Auth0 login context — the Sequence realm by default, or a registered
+     * OpCo environment's realm (`seq-studio envs add`), which pins the Auth0
+     * Organization so the token carries the org context tenant APIs require. */
+    realm?: AuthRealm;
 }
 export declare function openSystemBrowser(authorizationUrl: string): Promise<void>;
-export declare function loginWithPkce({ fetchImpl, now, openBrowser, port, timeoutMs, }: LoginOptions): Promise<void>;
+export declare function loginWithPkce({ fetchImpl, now, openBrowser, port, realm, timeoutMs, }: LoginOptions): Promise<string>;
 /**
  * Best-effort catalog refresh after a successful login. Drop the old cache
  * first so a prior identity's tier never lingers; discovery failures must not
  * fail login. Exported for unit tests.
  */
 export declare function refreshCatalogAfterLogin(): Promise<void>;
-export declare function login(): Promise<void>;
-export declare function logout(): Promise<void>;
+export declare function login(envName?: string): Promise<void>;
+export declare function logout(envName?: string): Promise<void>;
 export {};

package/dist/login.js

@@ -4,7 +4,7 @@ import { createServer } from 'node:http';
 import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { AUTH0_AUDIENCE, AUTH0_CLIENT_ID, AUTH0_DOMAIN, saveTokens, seqapiTokenPath, } from './auth.js';
+import { deleteRealmTokens, realmForEnv, saveTokens, seqapiTokenPath, SEQUENCE_AUTH_REALM, SEQUENCE_REALM, verifyTokenMatchesRealm, } from './auth.js';
 import { manualEnvConfigHint } from './config.js';
 import { bootstrapUrl, clearCatalog, fetchCatalog } from './env-catalog.js';
 const DEFAULT_REDIRECT_PORT = 5099;
@@ -22,16 +22,18 @@ function configuredPort() {
     }
     return port;
 }
-function authorizationUrl({ challenge, redirectUri, state, }) {
-    const url = new URL(`https://${AUTH0_DOMAIN}/authorize`);
+function authorizationUrl({ challenge, realm, redirectUri, state, }) {
+    const url = new URL(`https://${realm.domain}/authorize`);
     url.searchParams.set('response_type', 'code');
-    url.searchParams.set('client_id', AUTH0_CLIENT_ID);
+    url.searchParams.set('client_id', realm.clientId);
     url.searchParams.set('redirect_uri', redirectUri);
-    url.searchParams.set('scope', 'openid profile email offline_access');
-    url.searchParams.set('audience', AUTH0_AUDIENCE);
+    url.searchParams.set('scope', 'openid profile email');
+    url.searchParams.set('audience', realm.audience);
     url.searchParams.set('code_challenge', challenge);
     url.searchParams.set('code_challenge_method', 'S256');
     url.searchParams.set('state', state);
+    if (realm.organization)
+        url.searchParams.set('organization', realm.organization);
     return url.toString();
 }
 export async function openSystemBrowser(authorizationUrl) {
@@ -142,21 +144,16 @@ function parseTokenResponse(value) {
         throw new Error('Auth0 token response was not an object.');
     }
     const accessToken = Reflect.get(value, 'access_token');
-    const refreshToken = Reflect.get(value, 'refresh_token');
     const expiresIn = Reflect.get(value, 'expires_in');
     if (typeof accessToken !== 'string' || !accessToken) {
         throw new Error('Auth0 token response missing access_token.');
     }
-    if (typeof refreshToken !== 'string' || !refreshToken) {
-        throw new Error('No refresh token returned. Ensure Auth0 offline access is enabled.');
-    }
     return {
         accessToken,
-        refreshToken,
         expiresIn: typeof expiresIn === 'number' ? expiresIn : 86_400,
     };
 }
-export async function loginWithPkce({ fetchImpl = fetch, now = Date.now, openBrowser = openSystemBrowser, port = configuredPort(), timeoutMs = DEFAULT_LOGIN_TIMEOUT_MS, }) {
+export async function loginWithPkce({ fetchImpl = fetch, now = Date.now, openBrowser = openSystemBrowser, port = configuredPort(), realm = SEQUENCE_AUTH_REALM, timeoutMs = DEFAULT_LOGIN_TIMEOUT_MS, }) {
     const verifier = base64Url(randomBytes(32));
     const challenge = base64Url(createHash('sha256').update(verifier).digest());
     const state = base64Url(randomBytes(32));
@@ -165,20 +162,21 @@ export async function loginWithPkce({ fetchImpl = fetch, now = Date.now, openBro
         port,
         timeoutMs,
         onListening: (redirectUri) => {
-            const url = authorizationUrl({ challenge, redirectUri, state });
-            console.error(`Opening browser for Sequence login. If it does not open, visit:\n${url}`);
+            const url = authorizationUrl({ challenge, realm, redirectUri, state });
+            console.error(`Opening browser for Sequence login [${realm.name}]. If it does not open, visit:\n${url}`);
             void Promise.resolve(openBrowser(url)).catch((error) => {
                 const message = error instanceof Error ? error.message : String(error);
                 console.error(`Could not open a browser automatically: ${message}`);
             });
         },
     });
-    const tokenResponse = await fetchImpl(`https://${AUTH0_DOMAIN}/oauth/token`, {
+    const tokenResponse = await fetchImpl(`https://${realm.domain}/oauth/token`, {
         method: 'POST',
+        redirect: 'manual',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({
             grant_type: 'authorization_code',
-            client_id: AUTH0_CLIENT_ID,
+            client_id: realm.clientId,
             code: callback.code,
             redirect_uri: callback.redirectUri,
             code_verifier: verifier,
@@ -188,11 +186,12 @@ export async function loginWithPkce({ fetchImpl = fetch, now = Date.now, openBro
         throw new Error(`Auth0 token exchange failed (${tokenResponse.status}): ${await tokenResponse.text()}`);
     }
     const tokens = parseTokenResponse(await tokenResponse.json());
+    verifyTokenMatchesRealm({ accessToken: tokens.accessToken, realm });
     await saveTokens({
         access_token: tokens.accessToken,
-        refresh_token: tokens.refreshToken,
         expires_at: now() / 1_000 + tokens.expiresIn,
-    });
+    }, realm.name);
+    return tokens.accessToken;
 }
 /**
  * Best-effort catalog refresh after a successful login. Drop the old cache
@@ -216,26 +215,39 @@ export async function refreshCatalogAfterLogin() {
         'run: seq-studio envs refresh');
     console.log(manualEnvConfigHint());
 }
-export async function login() {
-    await loginWithPkce({});
-    console.log(`Authenticated. Tokens saved to ${seqapiTokenPath()}.`);
-    await refreshCatalogAfterLogin();
+export async function login(envName) {
+    const realm = await realmForEnv(envName);
+    if (envName && realm.name === SEQUENCE_REALM && envName !== SEQUENCE_REALM) {
+        // A name that only exists in the Sequence catalog (staging, banksouth…)
+        // resolves to the Sequence realm — one login covers all of those. A typo'd
+        // OpCo name would silently do a Sequence login otherwise, so say which
+        // realm we're using.
+        console.error(`'${envName}' uses the shared Sequence login ` +
+            '(register OpCo environments with: seq-studio envs add <name> <url>).');
+    }
+    await loginWithPkce({ realm });
+    console.log(`Authenticated [${realm.name}]. Short-lived access token saved to ${seqapiTokenPath()}.`);
+    // The environment catalog is a Sequence-deployment surface; OpCo realm
+    // logins target a single known deployment and have nothing to discover.
+    if (realm.name === SEQUENCE_REALM) {
+        await refreshCatalogAfterLogin();
+    }
 }
 /**
- * Pre-unification artifact-studio token file. `seq-studio artifact` commands
- * still fall back to it (artifact-studio's `getAccessToken` →
- * `readTokenConfig`, see shared/services/artifact-studio/src/config.ts), so
- * logout must clear it too or artifact commands would stay authenticated
- * after a successful logout.
+ * Pre-unification artifact-studio token file. New builds never read it, but
+ * logout still removes it so legacy bearer material does not linger on disk.
  */
 function legacyArtifactTokenPath() {
     return join(homedir(), '.config', 'sequence-artifact-studio', 'tokens.json');
 }
-export async function logout() {
-    await rm(seqapiTokenPath(), { force: true });
-    await rm(legacyArtifactTokenPath(), { force: true });
-    // Drop the cached environment catalog so visibility downgrades with the
-    // identity — a logged-out terminal must not keep the old tier's env list.
-    await clearCatalog();
-    console.log('Logged out of seq-studio and seqapi.');
+export async function logout(envName) {
+    const realm = await realmForEnv(envName);
+    await deleteRealmTokens(realm.name);
+    if (realm.name === SEQUENCE_REALM) {
+        await rm(legacyArtifactTokenPath(), { force: true });
+        // The environment catalog belongs to the Sequence identity; tenant logout
+        // must not discard a still-authenticated Sequence user's cached tier.
+        await clearCatalog();
+    }
+    console.log(`Logged out [${realm.name}] from seq-studio and seqapi.`);
 }

package/dist/main.d.ts

@@ -7,8 +7,9 @@
  *   seq-studio functions <sub>    manage Managed Functions
  *   seq-studio secrets <sub>      manage org-owned Managed Secrets
  *   seq-studio repos <sub>        manage platform git-service repos
+ *   seq-studio pipeline <sub>     author + validate Data Pipelines stage specs
  *   seq-studio auth <sub>         manage git-service PATs
- *   seq-studio envs <sub>         list/refresh discovered environments
+ *   seq-studio envs <sub>         add/list/refresh environments
  *   seq-studio login              authenticate interactively with Auth0
  *   seq-studio logout             remove cached user tokens
  *   seq-studio doctor             check token + env + writer gate

package/dist/main.js

@@ -7,8 +7,9 @@
  *   seq-studio functions <sub>    manage Managed Functions
  *   seq-studio secrets <sub>      manage org-owned Managed Secrets
  *   seq-studio repos <sub>        manage platform git-service repos
+ *   seq-studio pipeline <sub>     author + validate Data Pipelines stage specs
  *   seq-studio auth <sub>         manage git-service PATs
- *   seq-studio envs <sub>         list/refresh discovered environments
+ *   seq-studio envs <sub>         add/list/refresh environments
  *   seq-studio login              authenticate interactively with Auth0
  *   seq-studio logout             remove cached user tokens
  *   seq-studio doctor             check token + env + writer gate
@@ -24,11 +25,12 @@ const TOP_LEVEL_USAGE = `usage:
   seq-studio functions <sub> [args]  init | build | deploy | list | show | logs | promote | rollback | delete
   seq-studio secrets <sub> [args]    create | set | list | attach | detach | apply
   seq-studio repos <sub> [args]      list | namespaces | show | create | clone | pull | delete
+  seq-studio pipeline <sub> [args]   init | validate — Data Pipelines stage specs
   seq-studio auth <sub> [args]       pat create | pat list | pat revoke
   seq-studio orm <sub> [args]        init | validate | plan | apply
-  seq-studio envs <sub>              list | refresh — environments visible to your identity
-  seq-studio login                   authenticate in the browser
-  seq-studio logout                  remove cached user tokens
+  seq-studio envs <sub>              add | list | refresh environments
+  seq-studio login [--env <name>]    authenticate in the browser
+  seq-studio logout [--env <name>]   remove one realm's cached user tokens
   seq-studio doctor [-e <env>]       diagnose config, auth, and writer gate
   seq-studio version                 print the installed version
   seq-studio help                    show this message
@@ -87,13 +89,19 @@ export async function run(argv = process.argv.slice(2)) {
             const { runOrmCommand } = await import('./orm/delegate.js');
             return runOrmCommand(sub, rest);
         }
+        case 'pipeline': {
+            // Lazy import keeps doctor/process from pulling in @sequenceholdings/pipeline-spec
+            // (an optional peer, same posture as @sequenceholdings/orm).
+            const { runPipelineCommand } = await import('./pipeline/commands.js');
+            return runPipelineCommand(sub, parseArgs(rest));
+        }
         case 'envs': {
             const { runEnvsCommand } = await import('./envs/commands.js');
             return runEnvsCommand(sub, rest);
         }
         case 'login':
         case 'logout':
-            return runSessionCommand({ argument: sub, command: namespace });
+            return runSessionCommand({ args: [sub, ...rest].filter((a) => Boolean(a)), command: namespace });
         case 'version':
         case '--version':
         case '-v': {
@@ -109,17 +117,32 @@ export async function run(argv = process.argv.slice(2)) {
             return 1;
     }
 }
-async function runSessionCommand({ argument, command, }) {
-    if (argument === 'help' || argument === '--help' || argument === '-h') {
-        console.log(`usage: seq-studio ${command}`);
+async function runSessionCommand({ args, command, }) {
+    const usage = `usage: seq-studio ${command} [--env <name>]`;
+    if (args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+        console.log(usage);
         return 0;
     }
-    if (argument) {
-        console.error(`seq-studio ${command} does not accept arguments.`);
-        return 1;
+    let envName;
+    if (args.length > 0) {
+        const flags = parseArgs(args).flags;
+        envName =
+            (typeof flags.env === 'string' ? flags.env : undefined) ??
+                (typeof flags.e === 'string' ? flags.e : undefined);
+        if (!envName) {
+            console.error(usage);
+            return 1;
+        }
     }
     const auth = await import('./login.js');
-    await auth[command]();
+    if (command === 'logout') {
+        await auth.logout(envName);
+    }
+    else {
+        // An OpCo env name (registered via `seq-studio envs add` or `seqapi env add`)
+        // logs into that environment's Auth0 realm; omitted or a built-in name uses Sequence.
+        await auth.login(envName);
+    }
     return 0;
 }
 async function runProcessNamespace(sub, rest) {

package/dist/orm/delegate.js

@@ -8,6 +8,9 @@
 import { getAccessToken, tryGetAccessToken } from '../auth.js';
 import { resolveEnvWithDiscovery } from '../config.js';
 import { normalizeShortEnvFlag, readEnvFromArgv } from '../env-flags.js';
+import { REQUIRE_EXPLICIT_ENV_MESSAGE } from '../env-flags.js';
+/** ORM subcommands that talk to Atlas — must not silently target `local`. */
+const ORM_NETWORK_SUBS = new Set(['plan', 'apply']);
 const ORM_USAGE = `usage:
   seq-studio orm init <dir>            scaffold a namespace directory
   seq-studio orm validate [dir]        parse + validate definitions and verify committed migrations are in sync
@@ -38,11 +41,21 @@ export async function runOrmCommand(sub, rest) {
     }
     const normalized = normalizeShortEnvFlag(rest);
     const requested = readEnvFromArgv(normalized);
+    if (ORM_NETWORK_SUBS.has(sub) && !requested) {
+        console.error(`[seq-studio] ${REQUIRE_EXPLICIT_ENV_MESSAGE}`);
+        return 1;
+    }
+    let targetUrl;
     if (requested) {
         const resolved = await resolveEnvWithDiscovery({ requested });
+        targetUrl = resolved.url;
         process.env['SEQUENCE_ORM_BASE_URL'] = resolved.url;
     }
-    const token = await tryGetAccessToken({ failClosedForM2m: true });
+    const token = await tryGetAccessToken({
+        failClosedForM2m: true,
+        env: requested,
+        targetUrl,
+    });
     if (token)
         process.env['SEQUENCE_ORM_TOKEN'] = token;
     // Lazy import keeps `process`/`doctor` from pulling in the orm package.
@@ -70,7 +83,7 @@ export async function runOrmCommand(sub, rest) {
     const { runCli, setTokenProvider } = ormCli;
     setTokenProvider(async () => {
         try {
-            return await getAccessToken();
+            return await getAccessToken({ env: requested, targetUrl });
         }
         catch {
             return null;

package/dist/pat-hints.js

@@ -21,7 +21,7 @@ export function formatPatSetupHint({ envUrl, envName, indent = '  ', }) {
         `${indent}  2. New token → scopes repo:read (add repo:write for push) → copy once`,
         `${indent}  3. export ATLAS_GIT_PAT=<token>`,
         `${indent}  4. Copy the clone URL from Repositories → Clone, then:`,
-        `${indent}       ATLAS_GIT_PAT=<token> seq-studio repos clone --url <https://…/repos/<id>/git>`,
-        `${indent}     (or: seq-studio repos clone <ns>/<name>)`,
+        `${indent}       ATLAS_GIT_PAT=<token> seq-studio repos clone --url <https://…/repos/<id>/git> -e ${envName}`,
+        `${indent}     (or: seq-studio repos clone <ns>/<name> -e ${envName})`,
     ];
 }

package/dist/pipeline/commands.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `seq-studio pipeline <sub>` — the Data Pipelines authoring interface.
+ *
+ * `init` scaffolds a typed stage spec (`<name>.stage.yml` + entrypoint stub);
+ * `validate` runs the full offline SDK gate (envelope + body + schema_ref
+ * resolution + graph validation) over a Pipeline directory. Both are also the
+ * CI gate for `pipelines/**` repos (`.github/workflows/pipeline-verify.yml`).
+ *
+ * All schema logic lives in @sequenceholdings/pipeline-spec (single source of truth) —
+ * this module only handles argv, filesystem scaffolding, and output shaping.
+ * The SDK is lazy-imported like `@sequenceholdings/orm` so public installs of
+ * the CLI without the package get a clear install hint instead of a crash.
+ */
+import type { ParsedArgs } from '../process/commands.js';
+/**
+ * Same classification as the orm delegate: is the pipeline-spec package
+ * itself absent (installable) or did one of its dependencies fail to load?
+ */
+export declare function isPipelineSpecMissing(message: string): boolean;
+export declare function pipelineInitCommand(args: ParsedArgs): Promise<number>;
+interface ValidateReportFinding {
+    readonly severity: 'error' | 'warning';
+    readonly code: string;
+    readonly message: string;
+    readonly stage?: string;
+    readonly asset?: string;
+    readonly consumers?: readonly string[];
+    readonly suggestions?: readonly string[];
+    readonly cycle_path?: readonly string[];
+    readonly file?: string;
+    readonly path?: string;
+}
+/** The stable machine shape `--json` emits (consumed by CI annotations). */
+export interface ValidateReport {
+    readonly ok: boolean;
+    readonly dir: string;
+    readonly stages: readonly string[];
+    readonly findings: readonly ValidateReportFinding[];
+}
+interface ExternalAssetsRequest {
+    readonly url: string;
+    readonly init: {
+        readonly headers: Record<string, string>;
+        readonly redirect: 'manual';
+    };
+}
+export declare function buildExternalAssetsRequest({ source, knownOrigins, token, }: {
+    source: string;
+    knownOrigins: readonly string[];
+    token: string | null;
+}): ExternalAssetsRequest;
+/** Trusted origins of every environment the CLI knows about. */
+export declare function configuredEnvOrigins(envs: Readonly<Record<string, {
+    url: string;
+}>>): string[];
+export declare function pipelineValidateCommand(args: ParsedArgs): Promise<number>;
+export declare function runPipelineCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;
+export {};