@sequenceholdings/studio-cli 0.1.9 → 0.1.11

package/dist/auth.js

@@ -1,41 +1,46 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 /**
- * seq-studio is a read-only consumer of the seqapi token file. Tokens
- * are written by `seqapi login` (Python, in `shared/seqapi/seqapi/auth.py`)
- * and shared between every Sequence CLI: same Auth0 tenant, same client
- * id, same audience — so the same access token validates against every
- * Atlas /api/* route.
+ * seq-studio and seqapi share one token file and one Auth0 application:
+ * same tenant, client id, audience, and token shape. Either CLI can log in,
+ * and the resulting access token validates against every Atlas /api/* route.
  *
  * Two token sources, in the SAME precedence order as seqapi's
  * `get_access_token` (`shared/seqapi/seqapi/auth.py`):
  *   1. M2M service account — Auth0 client-credentials grant, used when
  *      `AUTH0_M2M_CLIENT_SECRET` is set. This is the headless path: CI /
- *      cloud agents with no interactive `seqapi login` can still push.
+ *      cloud agents with no interactive login can still push.
  *      (M2M carries app scopes but NO user identity / workspace membership
  *      — see the `atlas-test-access` rule.)
  *   2. Cached user token — read from the seqapi token file and refreshed
  *      via the Auth0 refresh-token grant when near expiry.
  *
- * Refresh is the only write path: when the cached access token is
- * expired and we have a refresh token, we hit Auth0 and update the file
- * with the rotated tokens. This mirrors `seqapi._save_tokens` exactly:
+ * Login and refresh both write the shared file. This mirrors
+ * `seqapi._save_tokens` exactly:
  * same fields, same shape, same 0o600 permissions, atomic write via
  * tmpfile + rename. The M2M token is in-memory only (never persisted).
  */
 // Match `shared/seqapi/seqapi/config.py`. Hard-coded because the seqapi
 // CLI also hard-codes them — there's a single Sequence Auth0 tenant for
 // all Sequence CLIs.
-const AUTH0_DOMAIN = 'dev-n1t8ts403fp8oyxp.us.auth0.com';
-const AUTH0_CLIENT_ID = 'GD9riCDWocfc66odpWBjwBiX43qqAX8r';
-const AUTH0_AUDIENCE = 'https://api.studio.com';
+export const AUTH0_DOMAIN = 'dev-n1t8ts403fp8oyxp.us.auth0.com';
+export const AUTH0_CLIENT_ID = 'GD9riCDWocfc66odpWBjwBiX43qqAX8r';
+export const AUTH0_AUDIENCE = 'https://api.studio.com';
 const AUTH0_M2M_CLIENT_ID = '5TLffZqvLq4ztLDjZhwKVJCpB5VNrWj0';
 // In-memory cache for the M2M token (seconds-based, mirrors seqapi's
 // `_m2m_cache`). Reused while > 60s from expiry to avoid re-minting on every
 // call within a single process (e.g. a long `artifact dev` watch).
 let m2mCache = null;
+/**
+ * A configured M2M credential failed to mint a token. Typed so callers that
+ * normally swallow discovery errors (lazy catalog refresh) can still surface
+ * broken CI credentials instead of a misleading "unknown env" message.
+ */
+export class M2mTokenError extends Error {
+    name = 'M2mTokenError';
+}
 /**
  * Mint an M2M access token via the Auth0 client-credentials grant when
  * `AUTH0_M2M_CLIENT_SECRET` is set. Returns null when the secret is unset
@@ -60,11 +65,11 @@ async function getM2mToken() {
         }),
     });
     if (!response.ok) {
-        throw new Error(`Auth0 M2M token request failed (${response.status}): ${await response.text()}`);
+        throw new M2mTokenError(`Auth0 M2M token request failed (${response.status}): ${await response.text()}`);
     }
     const data = (await response.json());
     if (!data.access_token) {
-        throw new Error('Auth0 M2M response missing access_token');
+        throw new M2mTokenError('Auth0 M2M response missing access_token');
     }
     m2mCache = {
         accessToken: data.access_token,
@@ -81,8 +86,7 @@ export function seqapiTokenPath() {
 export class NotLoggedInError extends Error {
     name = 'NotLoggedInError';
     constructor() {
-        super('Not logged in. Run: seqapi login\n' +
-            'seq-studio does not have its own login flow — it shares tokens with seqapi.\n' +
+        super('Not logged in. Run: seq-studio login\n' +
             'For headless contexts (CI / cloud agents), set AUTH0_M2M_CLIENT_SECRET for ' +
             'service-account (M2M) access instead.');
     }
@@ -117,7 +121,7 @@ export async function getAccessToken() {
         }),
     });
     if (response.status === 401 || response.status === 403) {
-        throw new Error('Refresh token expired or revoked. Re-authenticate with: seqapi login');
+        throw new Error('Refresh token expired or revoked. Re-authenticate with: seq-studio login');
     }
     if (!response.ok) {
         throw new Error(`Auth0 token refresh failed (${response.status}): ${await response.text()}`);
@@ -150,6 +154,38 @@ export async function tryGetAccessToken(options) {
         return null;
     }
 }
+/**
+ * Decode the `sub` claim from a JWT without verification. Verification is the
+ * server's job — this is only used to compare identities locally (e.g. to
+ * bind the cached environment catalog to the identity that fetched it).
+ */
+export function decodeJwtSub(token) {
+    const payload = token.split('.')[1];
+    if (!payload)
+        return null;
+    try {
+        const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        const sub = typeof parsed === 'object' && parsed !== null ? Reflect.get(parsed, 'sub') : null;
+        return typeof sub === 'string' && sub ? sub : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The Auth0 subject the CLI would authenticate as right now, without any
+ * network call: the fixed M2M client subject when the secret is configured,
+ * else the `sub` of the cached user token, else null (anonymous).
+ */
+export async function currentIdentitySubject() {
+    if (process.env.AUTH0_M2M_CLIENT_SECRET?.trim()) {
+        return `${AUTH0_M2M_CLIENT_ID}@clients`;
+    }
+    const tokens = await loadTokens();
+    if (!tokens?.access_token)
+        return null;
+    return decodeJwtSub(tokens.access_token);
+}
 async function loadTokens() {
     const path = seqapiTokenPath();
     if (!existsSync(path))
@@ -161,11 +197,14 @@ async function loadTokens() {
         return null;
     }
 }
-async function saveTokens(tokens) {
+export async function saveTokens(tokens) {
     const path = seqapiTokenPath();
     await mkdir(dirname(path), { recursive: true });
     // Mirror seqapi's atomic-write pattern: write to tmpfile then rename.
     const tmp = path + '.tmp';
     await writeFile(tmp, JSON.stringify(tokens, null, 2), { encoding: 'utf8', mode: 0o600 });
-    await import('node:fs/promises').then((fs) => fs.rename(tmp, path));
+    // writeFile's mode only applies when creating a file. Reset it explicitly in
+    // case a prior interrupted login left a permissive tmp file behind.
+    await chmod(tmp, 0o600);
+    await rename(tmp, path);
 }

package/dist/cli-errors.js

@@ -37,7 +37,7 @@ export function clarifyApplyFailureReason(reason) {
 function nextStepForAtlasError(error) {
     const msg = error.message.toLowerCase();
     if (error.status === 401) {
-        return 'Next step: run `seqapi login` and retry.';
+        return 'Next step: run `seq-studio login` and retry.';
     }
     if (error.status === 403) {
         return 'Next step: confirm `-e` targets the right environment and you have the required access grant.';

package/dist/config.d.ts

@@ -1,8 +1,11 @@
+import { type EnvTier } from './env-catalog.js';
 /**
  * `--env preview:<branch-or-slug>` targets a per-PR Vercel preview deployment
  * without a config.toml entry. The slug after the prefix is run through the
  * canonical branch→slug transform (see `preview.ts`). PR-number resolution and
  * the Cloudflare WAF bypass header live in `artifact/delegate.ts`.
+ * Preview targeting is a Sequence-staff surface — resolveEnv gates it on the
+ * discovered tier.
  */
 export declare const PREVIEW_ENV_PREFIX = "preview:";
 export declare const ENV_NAMES: string[];
@@ -11,19 +14,22 @@ export interface LatticeConfig {
         url: string;
     }>;
     defaultEnv: string;
+    /** Discovered identity tier; `anonymous` when no catalog is cached. */
+    tier: EnvTier;
 }
 export declare function globalConfigDir(): string;
 export declare function configPath(): string;
 export declare function defaultConfig(): LatticeConfig;
 /**
- * Read the config from disk. If the file does not exist, return defaults
- * — no auto-write, since seq-studio should work out of the box without
- * any state on disk. The user can run `seq-studio config init` (future)
- * if they want a customizable file.
+ * Read the effective config. Merge precedence (later wins):
  *
- * User-supplied envs are merged on top of the built-ins, so an override
- * for `local` (say, pointing at a different port) takes effect, and net
- * new envs (e.g. `staging-2`) are picked up.
+ *   1. built-in `local`
+ *   2. the cached discovered catalog (`~/.config/lattice/environments.json`)
+ *   3. user entries in config.toml (an override for `local`, or net-new envs)
+ *
+ * If the config.toml file does not exist, defaults are returned — no
+ * auto-write, since seq-studio should work out of the box without any
+ * state on disk.
  */
 export declare function readConfig(): Promise<LatticeConfig>;
 /** Write the config to disk, creating the dir if missing. */
@@ -33,12 +39,22 @@ export interface ResolvedEnv {
     url: string;
 }
 /**
- * Resolve `--env <name>` against the user's config. Falls back to the
- * config's `defaultEnv` when no name is passed. Throws a clear error
- * when the name does not match any known env so users see a list of
- * what's available rather than a confusing 404 later.
+ * Resolve `--env <name>` against the effective config. Falls back to the
+ * config's `defaultEnv` when no name is passed. Throws a clear error when
+ * the name does not resolve at the caller's tier, listing only the envs
+ * that are actually visible.
  */
 export declare function resolveEnv({ config, requested, }: {
     config: LatticeConfig;
     requested?: string;
 }): ResolvedEnv;
+/**
+ * Async resolveEnv with lazy discovery: when the requested name doesn't
+ * resolve from the current config (built-ins + cached catalog + toml),
+ * refresh the catalog once — a logged-in identity that never ran
+ * `seq-studio envs refresh` (or fresh CI with AUTH0_M2M_CLIENT_SECRET)
+ * gets its environments on first use — then retry.
+ */
+export declare function resolveEnvWithDiscovery({ requested, }: {
+    requested?: string;
+}): Promise<ResolvedEnv>;

package/dist/config.js

@@ -3,25 +3,27 @@ import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { M2mTokenError } from './auth.js';
+import { fetchCatalog, readCachedCatalog, } from './env-catalog.js';
 import { resolvePreviewFromSlug } from './preview.js';
 /**
  * `--env preview:<branch-or-slug>` targets a per-PR Vercel preview deployment
  * without a config.toml entry. The slug after the prefix is run through the
  * canonical branch→slug transform (see `preview.ts`). PR-number resolution and
  * the Cloudflare WAF bypass header live in `artifact/delegate.ts`.
+ * Preview targeting is a Sequence-staff surface — resolveEnv gates it on the
+ * discovered tier.
  */
 export const PREVIEW_ENV_PREFIX = 'preview:';
 /**
- * Environment URLs match the existing seqapi + artifact-studio mapping so
- * an engineer's mental model is the same across all three tools. `local`
- * is the dev / `make dev-all` URL — kept named `local` (not `dev`) so it
- * lines up with `seqapi -e local` and `artifact-studio --env local`.
+ * Only `local` ships in the published package. Additional environments are
+ * discovered per-identity from the authenticated catalog endpoint (see
+ * `env-catalog.ts`) or added by the user in config.toml. `local` is the
+ * dev / `make dev-all` URL — kept named `local` (not `dev`) so it lines up
+ * with `seqapi -e local` and `artifact-studio --env local`.
  */
 const BUILT_IN_ENV_URLS = {
     local: 'http://localhost:5001',
-    staging: 'https://staging.atlas.seqholdings.com',
-    production: 'https://atlas.seqholdings.com',
-    banksouth: 'https://banksouth.seqholdings.com',
 };
 export const ENV_NAMES = Object.keys(BUILT_IN_ENV_URLS);
 export function globalConfigDir() {
@@ -35,24 +37,32 @@ export function defaultConfig() {
     for (const [name, url] of Object.entries(BUILT_IN_ENV_URLS)) {
         envs[name] = { url };
     }
-    return { envs, defaultEnv: 'local' };
+    return { envs, defaultEnv: 'local', tier: 'anonymous' };
 }
 /**
- * Read the config from disk. If the file does not exist, return defaults
- * — no auto-write, since seq-studio should work out of the box without
- * any state on disk. The user can run `seq-studio config init` (future)
- * if they want a customizable file.
+ * Read the effective config. Merge precedence (later wins):
  *
- * User-supplied envs are merged on top of the built-ins, so an override
- * for `local` (say, pointing at a different port) takes effect, and net
- * new envs (e.g. `staging-2`) are picked up.
+ *   1. built-in `local`
+ *   2. the cached discovered catalog (`~/.config/lattice/environments.json`)
+ *   3. user entries in config.toml (an override for `local`, or net-new envs)
+ *
+ * If the config.toml file does not exist, defaults are returned — no
+ * auto-write, since seq-studio should work out of the box without any
+ * state on disk.
  */
 export async function readConfig() {
+    const merged = defaultConfig();
+    const catalog = await readCachedCatalog();
+    if (catalog) {
+        merged.tier = catalog.tier;
+        for (const env of catalog.environments) {
+            merged.envs[env.name] = { url: env.url };
+        }
+    }
     const path = configPath();
     if (!existsSync(path))
-        return defaultConfig();
+        return merged;
     const raw = parseToml(await readFile(path, 'utf8'));
-    const merged = defaultConfig();
     if (raw.env) {
         for (const [name, value] of Object.entries(raw.env)) {
             if (typeof value?.url === 'string') {
@@ -81,15 +91,22 @@ export async function writeConfig(config) {
     lines.push(`default_env = "${config.defaultEnv}"`);
     await writeFile(path, lines.join('\n') + '\n', { encoding: 'utf8', mode: 0o600 });
 }
+/** Shared hint appended to visibility errors at the anonymous/partner tiers. */
+const DISCOVERY_HINT = 'If you expect more environments, authenticate (seq-studio login, or set ' +
+    'AUTH0_M2M_CLIENT_SECRET) and run: seq-studio envs refresh';
 /**
- * Resolve `--env <name>` against the user's config. Falls back to the
- * config's `defaultEnv` when no name is passed. Throws a clear error
- * when the name does not match any known env so users see a list of
- * what's available rather than a confusing 404 later.
+ * Resolve `--env <name>` against the effective config. Falls back to the
+ * config's `defaultEnv` when no name is passed. Throws a clear error when
+ * the name does not resolve at the caller's tier, listing only the envs
+ * that are actually visible.
  */
 export function resolveEnv({ config, requested, }) {
     const name = requested ?? config.defaultEnv;
     if (name.startsWith(PREVIEW_ENV_PREFIX)) {
+        if (config.tier !== 'sequence') {
+            throw new Error(`Preview environments (${PREVIEW_ENV_PREFIX}<branch>) are a Sequence-staff ` +
+                `surface. ${DISCOVERY_HINT}`);
+        }
         const { slug, url } = resolvePreviewFromSlug(name.slice(PREVIEW_ENV_PREFIX.length));
         return { name: `${PREVIEW_ENV_PREFIX}${slug}`, url };
     }
@@ -97,7 +114,40 @@ export function resolveEnv({ config, requested, }) {
     if (!env) {
         const known = Object.keys(config.envs).join(', ');
         throw new Error(`Unknown env "${name}". Known envs: ${known}. ` +
-            `Pass --env <name> or set default_env in ${configPath()}.`);
+            `Pass --env <name> or set default_env in ${configPath()}. ${DISCOVERY_HINT}`);
     }
     return { name, url: env.url };
 }
+/**
+ * Async resolveEnv with lazy discovery: when the requested name doesn't
+ * resolve from the current config (built-ins + cached catalog + toml),
+ * refresh the catalog once — a logged-in identity that never ran
+ * `seq-studio envs refresh` (or fresh CI with AUTH0_M2M_CLIENT_SECRET)
+ * gets its environments on first use — then retry.
+ */
+export async function resolveEnvWithDiscovery({ requested, }) {
+    const config = await readConfig();
+    try {
+        return resolveEnv({ config, requested });
+    }
+    catch (err) {
+        let catalog;
+        try {
+            catalog = await fetchCatalog();
+        }
+        catch (fetchErr) {
+            // A configured-but-broken M2M credential is the real failure — CI must
+            // see the Auth0 error, not a misleading "unknown env" message.
+            if (fetchErr instanceof M2mTokenError)
+                throw fetchErr;
+            // Network/server errors: fall back to whatever is cached, else
+            // surface the original resolve error.
+            catalog = await readCachedCatalog();
+        }
+        if (!catalog)
+            throw err;
+        // Retry against the refreshed catalog; if the name still doesn't
+        // resolve, the retry throws an error rendered from the fresh state.
+        return resolveEnv({ config: await readConfig(), requested });
+    }
+}

package/dist/env-catalog.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Tiered environment discovery.
+ *
+ * The published package ships with only the `local` environment baked in.
+ * Every other deployment URL is *discovered* from the authenticated
+ * `GET /api/platform/environments` endpoint and cached on disk:
+ *
+ *   - `anonymous` — no usable token (or the endpoint rejected it):
+ *     `local` only, no catalog cached.
+ *   - `sequence`  — Sequence staff / trusted M2M: full catalog
+ *     (local, staging, production, banksouth) + preview targeting.
+ *   - `partner`   — any other authenticated identity: local + their
+ *     deployment(s).
+ *
+ * This is a visibility/UX layer, not access control — every deployment
+ * still enforces Auth0 + FGA per request. A user who knows a URL can
+ * always add it to config.toml; the server rejecting their token is the
+ * real gate.
+ *
+ * One bootstrap hostname is baked into the package for the discovery
+ * call itself. All deployments share the same Auth0 audience, so any
+ * identity's token validates there; the endpoint 401s anonymously.
+ */
+export type EnvTier = 'anonymous' | 'sequence' | 'partner';
+export interface CatalogEnvironment {
+    name: string;
+    url: string;
+}
+export interface EnvCatalog {
+    tier: Exclude<EnvTier, 'anonymous'>;
+    environments: CatalogEnvironment[];
+    /** Unix ms timestamp of the successful fetch. */
+    fetchedAt: number;
+    /**
+     * Auth0 `sub` of the identity that fetched this catalog. Reads ignore the
+     * cache when the current identity differs (logout, seqapi re-login as
+     * someone else), so one user's tier never carries over to another.
+     */
+    subject: string;
+}
+/** The host the discovery call goes to. Override for tests / self-hosting. */
+export declare function bootstrapUrl(): string;
+export declare function catalogPath(): string;
+/**
+ * Read the cached catalog from disk. Returns null when missing, malformed,
+ * or fetched by a *different* identity than the one the CLI would
+ * authenticate as right now — callers treat all of those as tier
+ * `anonymous`. The subject check means a logout (token file removed) or a
+ * re-login as someone else invalidates the cache immediately, without
+ * waiting for the next discovery call.
+ */
+export declare function readCachedCatalog(): Promise<EnvCatalog | null>;
+export declare function clearCatalog(): Promise<void>;
+/**
+ * Fetch the environment catalog from the discovery endpoint and cache it.
+ *
+ * Returns the fresh catalog, or null when the caller is effectively
+ * anonymous: no token available, or the endpoint rejected the token
+ * (401/403 — the stale cache is cleared so visibility downgrades too).
+ * Network/server errors leave any existing cache in place and rethrow so
+ * callers can distinguish "offline" from "not authorized".
+ */
+export declare function fetchCatalog(): Promise<EnvCatalog | null>;

package/dist/env-catalog.js

@@ -0,0 +1,111 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { currentIdentitySubject, decodeJwtSub, tryGetAccessToken } from './auth.js';
+const DEFAULT_BOOTSTRAP_URL = 'https://atlas.seqholdings.com';
+/** The host the discovery call goes to. Override for tests / self-hosting. */
+export function bootstrapUrl() {
+    return (process.env['SEQ_STUDIO_DISCOVERY_URL']?.trim().replace(/\/+$/, '') ||
+        DEFAULT_BOOTSTRAP_URL);
+}
+export function catalogPath() {
+    return join(homedir(), '.config', 'lattice', 'environments.json');
+}
+function isValidCatalog(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return ((candidate.tier === 'sequence' || candidate.tier === 'partner') &&
+        Array.isArray(candidate.environments) &&
+        candidate.environments.every((env) => typeof env === 'object' &&
+            env !== null &&
+            typeof env.name === 'string' &&
+            typeof env.url === 'string') &&
+        typeof candidate.fetchedAt === 'number' &&
+        typeof candidate.subject === 'string' &&
+        candidate.subject.length > 0);
+}
+/**
+ * Read the cached catalog from disk. Returns null when missing, malformed,
+ * or fetched by a *different* identity than the one the CLI would
+ * authenticate as right now — callers treat all of those as tier
+ * `anonymous`. The subject check means a logout (token file removed) or a
+ * re-login as someone else invalidates the cache immediately, without
+ * waiting for the next discovery call.
+ */
+export async function readCachedCatalog() {
+    const path = catalogPath();
+    if (!existsSync(path))
+        return null;
+    let catalog;
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        catalog = isValidCatalog(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+    if (!catalog)
+        return null;
+    const subject = await currentIdentitySubject();
+    if (subject === null || subject !== catalog.subject)
+        return null;
+    return catalog;
+}
+async function saveCatalog(catalog) {
+    const path = catalogPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(catalog, null, 2) + '\n', {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+}
+export async function clearCatalog() {
+    await rm(catalogPath(), { force: true });
+}
+/**
+ * Fetch the environment catalog from the discovery endpoint and cache it.
+ *
+ * Returns the fresh catalog, or null when the caller is effectively
+ * anonymous: no token available, or the endpoint rejected the token
+ * (401/403 — the stale cache is cleared so visibility downgrades too).
+ * Network/server errors leave any existing cache in place and rethrow so
+ * callers can distinguish "offline" from "not authorized".
+ */
+export async function fetchCatalog() {
+    // Fail closed when an M2M secret is configured but minting fails, so
+    // headless callers (CI) see the real Auth0 error instead of a silent
+    // downgrade to the anonymous tier.
+    const token = await tryGetAccessToken({ failClosedForM2m: true });
+    if (!token) {
+        await clearCatalog();
+        return null;
+    }
+    const response = await fetch(`${bootstrapUrl()}/api/platform/environments`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (response.status === 401 || response.status === 403) {
+        await clearCatalog();
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`Environment discovery failed (${response.status}) against ${bootstrapUrl()}.`);
+    }
+    const body = (await response.json());
+    if ((body.tier !== 'sequence' && body.tier !== 'partner') ||
+        !Array.isArray(body.environments)) {
+        throw new Error('Environment discovery returned an unexpected response shape.');
+    }
+    const catalog = {
+        tier: body.tier,
+        environments: body.environments,
+        fetchedAt: Date.now(),
+        // Bind the cache to the identity that fetched it. `unknown` never
+        // matches a real subject, so an undecodable token yields a catalog
+        // that works for this invocation but is not trusted from disk later.
+        subject: decodeJwtSub(token) ?? 'unknown',
+    };
+    await saveCatalog(catalog);
+    return catalog;
+}

package/dist/envs/commands.d.ts

@@ -0,0 +1 @@
+export declare function runEnvsCommand(sub: string | undefined, _rest: string[]): Promise<number>;

package/dist/envs/commands.js

@@ -0,0 +1,74 @@
+import { readConfig, configPath } from '../config.js';
+import { bootstrapUrl, fetchCatalog, readCachedCatalog, } from '../env-catalog.js';
+const ENVS_USAGE = `usage:
+  seq-studio envs list      show the environments visible to your identity
+  seq-studio envs refresh   re-fetch the environment catalog for your identity
+
+  The published CLI ships with only the "local" environment. After you
+  authenticate (seq-studio login, or AUTH0_M2M_CLIENT_SECRET for headless use),
+  "envs refresh" discovers the environments your identity may target; the
+  catalog is cached at ~/.config/lattice/environments.json and also refreshes
+  lazily the first time you pass an -e <env> that isn't cached yet.
+
+  Custom entries in ${configPath()} are always honored on top.
+`;
+export async function runEnvsCommand(sub, _rest) {
+    switch (sub) {
+        case 'list':
+            return listCommand();
+        case 'refresh':
+            return refreshCommand();
+        case undefined:
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(ENVS_USAGE);
+            return sub ? 0 : 1;
+        default:
+            console.error(`unknown envs command: ${sub}`);
+            console.error(ENVS_USAGE);
+            return 1;
+    }
+}
+async function listCommand() {
+    const [config, catalog] = await Promise.all([readConfig(), readCachedCatalog()]);
+    const discovered = new Set(catalog?.environments.map((env) => env.name) ?? []);
+    console.log(`tier: ${config.tier}`);
+    if (catalog) {
+        console.log(`catalog fetched: ${new Date(catalog.fetchedAt).toISOString()}`);
+    }
+    console.log('');
+    const width = Math.max(...Object.keys(config.envs).map((name) => name.length));
+    for (const [name, { url }] of Object.entries(config.envs)) {
+        const source = name === 'local' && !discovered.has(name)
+            ? 'built-in'
+            : discovered.has(name)
+                ? 'discovered'
+                : 'config.toml';
+        console.log(`  ${name.padEnd(width)}  ${url}  (${source})`);
+    }
+    if (config.tier === 'anonymous') {
+        console.log('');
+        console.log('Not authenticated — only "local" is visible. Authenticate with ' +
+            '`seq-studio login` (or set AUTH0_M2M_CLIENT_SECRET), then run: seq-studio envs refresh');
+    }
+    return 0;
+}
+async function refreshCommand() {
+    let catalog;
+    try {
+        catalog = await fetchCatalog();
+    }
+    catch (err) {
+        console.error(`envs refresh: FAIL — ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    if (!catalog) {
+        console.log(`Not authenticated against ${bootstrapUrl()} — catalog cleared; only ` +
+            '"local" (plus any config.toml entries) is visible.\n' +
+            'Authenticate with `seq-studio login` (or set AUTH0_M2M_CLIENT_SECRET) and retry.');
+        return 0;
+    }
+    console.log(`tier: ${catalog.tier} — ${catalog.environments.length} environment(s) cached.`);
+    return listCommand();
+}

package/dist/functions/commands.d.ts

@@ -82,5 +82,5 @@ export declare function functionsRollbackCommand(args: ParsedArgs): Promise<numb
 /** Minimal dotenv parser — KEY=VALUE lines, quotes stripped, comments skipped. */
 export declare function parseDotenv(content: string): Record<string, string>;
 export declare function functionsDeleteCommand(args: ParsedArgs): Promise<number>;
-export declare const FUNCTIONS_USAGE = "usage:\n  seq-studio functions init <dir>                     scaffold manifest + TypeScript hello-world handler\n  seq-studio functions build [--dir d]                local pre-flight (manifest, lockfile, size)\n  seq-studio functions deploy [-e env] [-m msg]       preview + confirm secrets + upload and deploy\n  seq-studio functions list [-e env] [--match-local]  functions visible on the environment\n  seq-studio functions show [-e env] [--fn slug]      detail for one function (versions, secrets)\n  seq-studio functions logs [-e env] [--limit N] [--since t]  Cloud Logging snapshot (reader-gated)\n  seq-studio functions promote <version> [-e env]     make a version live\n  seq-studio functions rollback [<version>] [-e env]  redeploy a prior version\n  seq-studio functions delete [--yes]                 archive function + tear down GCP resources\n                                                      (version history is retained)\n\n  Flags: -e/--env <local|staging|production|banksouth|preview:<slug>> \u00B7 --fn <slug> \u00B7 --dir <path>\n         --from-env-file <path>  (default: .env) source file for secret values\n         --no-wait \u00B7 --yes\n         --no-provision  (deploy) update-only: error instead of registering a new\n                         shell, writing secret values, or attaching secrets (CI sweep)\n\n  Source for build/deploy: a local --dir (default .), a platform git-service\n  repo (--repo <ns>/<name>), or any git URL (--git-url <url>). --ref selects a\n  branch/tag/commit (default: the repo's default branch). Remote sources record\n  the pinned commit as provenance (never dirty) and NEVER read a repo-committed\n  .env for secret values \u2014 provision secrets server-side or pass a local\n  --from-env-file (resolved against your cwd).\n\n  --repo clones over smart-HTTP and REQUIRES a git PAT in ATLAS_GIT_PAT\n  (repo:read scope \u2014 `seq-studio auth pat create --scopes repo:read`, or\n  Atlas \u2192 Settings \u2192 Tokens). It's the same token you clone the repo with;\n  --env + seqapi login are still needed to resolve the repo and deploy.\n";
+export declare const FUNCTIONS_USAGE = "usage:\n  seq-studio functions init <dir>                     scaffold manifest + TypeScript hello-world handler\n  seq-studio functions build [--dir d]                local pre-flight (manifest, lockfile, size)\n  seq-studio functions deploy [-e env] [-m msg]       preview + confirm secrets + upload and deploy\n  seq-studio functions list [-e env] [--match-local]  functions visible on the environment\n  seq-studio functions show [-e env] [--fn slug]      detail for one function (versions, secrets)\n  seq-studio functions logs [-e env] [--limit N] [--since t]  Cloud Logging snapshot (reader-gated)\n  seq-studio functions promote <version> [-e env]     make a version live\n  seq-studio functions rollback [<version>] [-e env]  redeploy a prior version\n  seq-studio functions delete [--yes]                 archive function + tear down GCP resources\n                                                      (version history is retained)\n\n  Flags: -e/--env <env|preview:<slug>> (see: seq-studio envs list) \u00B7 --fn <slug> \u00B7 --dir <path>\n         --from-env-file <path>  (default: .env) source file for secret values\n         --no-wait \u00B7 --yes\n         --no-provision  (deploy) update-only: error instead of registering a new\n                         shell, writing secret values, or attaching secrets (CI sweep)\n\n  Source for build/deploy: a local --dir (default .), a platform git-service\n  repo (--repo <ns>/<name>), or any git URL (--git-url <url>). --ref selects a\n  branch/tag/commit (default: the repo's default branch). Remote sources record\n  the pinned commit as provenance (never dirty) and NEVER read a repo-committed\n  .env for secret values \u2014 provision secrets server-side or pass a local\n  --from-env-file (resolved against your cwd).\n\n  --repo clones over smart-HTTP and REQUIRES a git PAT in ATLAS_GIT_PAT\n  (repo:read scope \u2014 `seq-studio auth pat create --scopes repo:read`, or\n  Atlas \u2192 Settings \u2192 Tokens). It's the same token you clone the repo with;\n  --env + seq-studio login are still needed to resolve the repo and deploy.\n";
 export declare function runFunctionsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;