@sequenceholdings/studio-cli 0.1.10 → 0.1.12

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 + seq-studio 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>;

package/dist/functions/commands.js

@@ -7,7 +7,7 @@ import { createInterface } from 'node:readline';
 import { Writable } from 'node:stream';
 import { load as parseYaml } from 'js-yaml';
 import { getAccessToken } from '../auth.js';
-import { readConfig, resolveEnv } from '../config.js';
+import { resolveEnvWithDiscovery } from '../config.js';
 import { AtlasApiError, deleteJson, getJson, postJson } from '../atlas-client.js';
 import { clarifyApplyFailureReason, printCliError } from '../cli-errors.js';
 import { confirmYes } from '../prompt.js';
@@ -24,10 +24,9 @@ export function flagBool(flags, ...keys) {
     return keys.some((key) => flags[key] === true || flags[key] === 'true');
 }
 export async function buildContext(args) {
-    const config = await readConfig();
     const requested = (typeof args.flags.env === 'string' ? args.flags.env : undefined) ??
         (typeof args.flags.e === 'string' ? args.flags.e : undefined);
-    const env = resolveEnv({ config, requested });
+    const env = await resolveEnvWithDiscovery({ requested });
     const token = await getAccessToken();
     return { env, token };
 }
@@ -309,7 +308,7 @@ export async function functionsInitCommand(args) {
     console.log('                                       # public npm instead (the deploy worker re-resolves server-side).');
     console.log('  seq-studio functions build           # local pre-flight checks');
     console.log('  # Add secret names to managed-function.yml (secrets: [MY_SECRET]) and values to .env');
-    console.log('  seq-studio functions deploy -e staging  # upload, apply secrets, then deploy');
+    console.log('  seq-studio functions deploy -e <env>  # upload, apply secrets, then deploy');
     return 0;
 }
 // ---------------------------------------------------------------------------
@@ -942,7 +941,7 @@ export const FUNCTIONS_USAGE = `usage:
   seq-studio functions delete [--yes]                 archive function + tear down GCP resources
                                                       (version history is retained)
 
-  Flags: -e/--env <local|staging|production|banksouth|preview:<slug>> · --fn <slug> · --dir <path>
+  Flags: -e/--env <env|preview:<slug>> (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

package/dist/login.js

@@ -5,6 +5,7 @@ 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 { clearCatalog, fetchCatalog } from './env-catalog.js';
 const DEFAULT_REDIRECT_PORT = 5099;
 const DEFAULT_LOGIN_TIMEOUT_MS = 300_000;
 function base64Url(input) {
@@ -195,6 +196,22 @@ export async function loginWithPkce({ fetchImpl = fetch, now = Date.now, openBro
 export async function login() {
     await loginWithPkce({});
     console.log(`Authenticated. Tokens saved to ${seqapiTokenPath()}.`);
+    // Refresh the environment catalog for the new identity immediately, so a
+    // previously cached catalog from another identity (or tier) never lingers
+    // past a login. Drop the old cache first — if the refresh below fails, the
+    // prior identity's catalog must not survive the login either.
+    // Best-effort: discovery being unreachable must not fail login.
+    await clearCatalog();
+    try {
+        const catalog = await fetchCatalog();
+        if (catalog) {
+            console.log(`Environment catalog refreshed (tier: ${catalog.tier}, ` +
+                `${catalog.environments.length} environment(s)).`);
+        }
+    }
+    catch {
+        console.log('Could not refresh the environment catalog — run: seq-studio envs refresh');
+    }
 }
 /**
  * Pre-unification artifact-studio token file. `seq-studio artifact` commands
@@ -209,5 +226,8 @@ function legacyArtifactTokenPath() {
 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.');
 }

package/dist/main.d.ts

@@ -8,6 +8,7 @@
  *   seq-studio secrets <sub>      manage org-owned Managed Secrets
  *   seq-studio repos <sub>        manage platform git-service repos
  *   seq-studio auth <sub>         manage git-service PATs
+ *   seq-studio envs <sub>         list/refresh discovered 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

@@ -8,6 +8,7 @@
  *   seq-studio secrets <sub>      manage org-owned Managed Secrets
  *   seq-studio repos <sub>        manage platform git-service repos
  *   seq-studio auth <sub>         manage git-service PATs
+ *   seq-studio envs <sub>         list/refresh discovered environments
  *   seq-studio login              authenticate interactively with Auth0
  *   seq-studio logout             remove cached user tokens
  *   seq-studio doctor             check token + env + writer gate
@@ -25,13 +26,16 @@ const TOP_LEVEL_USAGE = `usage:
   seq-studio repos <sub> [args]      list | namespaces | show | create | clone | pull | delete
   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 doctor [-e <env>]       diagnose config, auth, and writer gate
+  seq-studio version                 print the installed version
   seq-studio help                    show this message
 
   Authenticate with: seq-studio login
-  Env URLs come from ~/.config/lattice/config.toml (built-ins: local, staging, production, banksouth).
+  Built-in env: local. Authenticated identities discover more via
+  \`seq-studio envs refresh\`; custom entries live in ~/.config/lattice/config.toml.
 `;
 const PROCESS_USAGE = `usage:
   seq-studio process init <dir>
@@ -82,9 +86,20 @@ export async function run(argv = process.argv.slice(2)) {
             const { runOrmCommand } = await import('./orm/delegate.js');
             return runOrmCommand(sub, rest);
         }
+        case 'envs': {
+            const { runEnvsCommand } = await import('./envs/commands.js');
+            return runEnvsCommand(sub, rest);
+        }
         case 'login':
         case 'logout':
             return runSessionCommand({ argument: sub, command: namespace });
+        case 'version':
+        case '--version':
+        case '-v': {
+            const { currentVersion } = await import('./update-check.js');
+            console.log(currentVersion());
+            return 0;
+        }
         case 'doctor':
             return doctorCommand(parseArgs([sub, ...rest].filter(Boolean)));
         default:

package/dist/orm/delegate.js

@@ -6,16 +6,17 @@
  * SEQUENCE_ORM_BASE_URL, share the seqapi token, forward argv.
  */
 import { getAccessToken, tryGetAccessToken } from '../auth.js';
-import { readConfig, resolveEnv } from '../config.js';
+import { resolveEnvWithDiscovery } from '../config.js';
 import { normalizeShortEnvFlag, readEnvFromArgv } from '../env-flags.js';
 const ORM_USAGE = `usage:
   seq-studio orm init <dir>            scaffold a namespace directory
-  seq-studio orm validate [dir]        parse + validate definitions, print the content hash
+  seq-studio orm validate [dir]        parse + validate definitions and verify committed migrations are in sync
   seq-studio orm plan [dir] -e <env>   compile definitions and diff against the registry
-  seq-studio orm diff [dir]            write the next committed migration (--check verifies, --allow-destructive consents)
-  seq-studio orm apply [dir] -e <env>  register the definitions and apply them to the env
+  seq-studio orm apply [dir] -e <env>  author the migration, register, apply, and refresh types.gen.ts (the everyday command)
+  seq-studio orm diff [dir]            write/verify the committed migration standalone (--check is the offline CI gate; --allow-destructive consents)
 
-  Built-in envs: local, staging, production, banksouth.
+  Environments: see \`seq-studio envs list\` (built-in: local; more are
+  discovered after you authenticate).
   Authenticate with: seq-studio login
 `;
 export async function runOrmCommand(sub, rest) {
@@ -26,8 +27,7 @@ export async function runOrmCommand(sub, rest) {
     const normalized = normalizeShortEnvFlag(rest);
     const requested = readEnvFromArgv(normalized);
     if (requested) {
-        const config = await readConfig();
-        const resolved = resolveEnv({ config, requested });
+        const resolved = await resolveEnvWithDiscovery({ requested });
         process.env['SEQUENCE_ORM_BASE_URL'] = resolved.url;
     }
     const token = await tryGetAccessToken({ failClosedForM2m: true });

package/dist/process/commands.js

@@ -12,7 +12,7 @@ import { forEachSerializedNode, } from '@sequenceholdings/lattice/bundle';
 import { getJson, getJsonOr404, postJson, AtlasApiError } from '../atlas-client.js';
 import { generateProcessFiles } from './codegen.js';
 import { getAccessToken, NotLoggedInError } from '../auth.js';
-import { ENV_NAMES, readConfig, resolveEnv } from '../config.js';
+import { readConfig, resolveEnvWithDiscovery } from '../config.js';
 import { buildBundleFromProcesses, summarizeBundle } from './build.js';
 import { buildResolveProcessPinFromEnv } from './resolve-process-pin.js';
 import { loadBundleForPublish } from './local-bundle.js';
@@ -92,9 +92,8 @@ const SHORT_FLAG_ALIASES = {
     '-o': 'out',
 };
 async function getEnvAndToken(args) {
-    const config = await readConfig();
     const requested = typeof args.flags.env === 'string' ? args.flags.env : undefined;
-    const env = resolveEnv({ config, requested });
+    const env = await resolveEnvWithDiscovery({ requested });
     let token;
     try {
         token = await getAccessToken();
@@ -667,16 +666,16 @@ export async function doctorCommand(args) {
     }
     else {
         lines.push(`config: ok — default_env=${config.defaultEnv}, envs=${Object.keys(config.envs).join(',')}`);
+        lines.push(`tier: ${config.tier}` +
+            (config.tier === 'anonymous'
+                ? ' — authenticate and run `seq-studio envs refresh` to discover more environments'
+                : ''));
     }
     const requested = typeof args.flags.env === 'string' ? args.flags.env : undefined;
-    if (requested && !ENV_NAMES.includes(requested) && config && !(requested in config.envs)) {
-        lines.push(`env "${requested}": FAIL — not in built-ins (${ENV_NAMES.join(',')}) or config`);
-        ok = false;
-    }
     let env = null;
     if (config) {
         try {
-            env = resolveEnv({ config, requested });
+            env = await resolveEnvWithDiscovery({ requested });
             lines.push(`env: ok — ${env.name} (${env.url})`);
         }
         catch (err) {

package/dist/repos/commands.d.ts

@@ -45,5 +45,5 @@ export declare function reposCloneCommand(args: ParsedArgs, deps?: {
  */
 export declare function normalizeCloneUrl(raw: string, env: ResolvedEnv): string;
 export declare function reposDeleteCommand(args: ParsedArgs): Promise<number>;
-export declare const REPOS_USAGE = "usage:\n  seq-studio repos list [-e env] [--namespace <slug>] [--mine]      repos visible on the environment\n  seq-studio repos namespaces [create <slug>] [-e env]              list or create namespaces\n  seq-studio repos show <ns>/<name> [-e env]                        repo detail (branches, clone URL)\n  seq-studio repos create <ns>/<name> [-e env] [--default-branch b] create an empty repo\n  seq-studio repos clone <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n  seq-studio repos clone --url <https://\u2026/repos/<id>/git> [-e env] [--ref r] [--out dir]\n  seq-studio repos clone --id <uuid> [-e env] [--ref r] [--out dir]\n                                                                    smart-HTTP when ATLAS_GIT_PAT is set;\n                                                                    otherwise JSON materialize (<ns>/<name>)\n  seq-studio repos pull <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n                                                                    materialize the tree at a ref (JSON API)\n  seq-studio repos delete <ns>/<name> [-e env] [--yes]              delete a repo (confirm prompt)\n\n  Flags: -e/--env <local|staging|production|banksouth>\n\n  clone prefers real git clone (PAT via askpass \u2014 never written into the remote\n  URL). Without ATLAS_GIT_PAT, <ns>/<name> falls back to the JSON API and prints\n  how to get a PAT (seq-studio or Atlas UI /settings/tokens).\n  PAT without Auth0 login: use --url from Repositories \u2192 Clone (or --id <uuid>).\n  --ref accepts a branch, tag, or commit SHA (SHA \u2192 clone then checkout).\n\n  Authenticate JSON API calls with: seq-studio login\n  Authenticate git clone/push with: ATLAS_GIT_PAT (from Atlas Settings \u2192 Tokens)\n";
+export declare const REPOS_USAGE = "usage:\n  seq-studio repos list [-e env] [--namespace <slug>] [--mine]      repos visible on the environment\n  seq-studio repos namespaces [create <slug>] [-e env]              list or create namespaces\n  seq-studio repos show <ns>/<name> [-e env]                        repo detail (branches, clone URL)\n  seq-studio repos create <ns>/<name> [-e env] [--default-branch b] create an empty repo\n  seq-studio repos clone <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n  seq-studio repos clone --url <https://\u2026/repos/<id>/git> [-e env] [--ref r] [--out dir]\n  seq-studio repos clone --id <uuid> [-e env] [--ref r] [--out dir]\n                                                                    smart-HTTP when ATLAS_GIT_PAT is set;\n                                                                    otherwise JSON materialize (<ns>/<name>)\n  seq-studio repos pull <ns>/<name> [-e env] [--ref r] [--out dir] [--force]\n                                                                    materialize the tree at a ref (JSON API)\n  seq-studio repos delete <ns>/<name> [-e env] [--yes]              delete a repo (confirm prompt)\n\n  Flags: -e/--env <env>  (see: seq-studio envs list)\n\n  clone prefers real git clone (PAT via askpass \u2014 never written into the remote\n  URL). Without ATLAS_GIT_PAT, <ns>/<name> falls back to the JSON API and prints\n  how to get a PAT (seq-studio or Atlas UI /settings/tokens).\n  PAT without Auth0 login: use --url from Repositories \u2192 Clone (or --id <uuid>).\n  --ref accepts a branch, tag, or commit SHA (SHA \u2192 clone then checkout).\n\n  Authenticate JSON API calls with: seq-studio login\n  Authenticate git clone/push with: ATLAS_GIT_PAT (from Atlas Settings \u2192 Tokens)\n";
 export declare function runReposCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;

package/dist/repos/commands.js

@@ -24,7 +24,7 @@ import { buildContext, clientOptions, flagBool, LOG, } from '../functions/comman
 import { resolveGitPatFromEnv, runGitClone, } from './git-clone.js';
 import { formatPatSetupHint } from '../pat-hints.js';
 import { tryGetAccessToken } from '../auth.js';
-import { readConfig, resolveEnv } from '../config.js';
+import { resolveEnvWithDiscovery } from '../config.js';
 const PAGE_SIZE = 200;
 // ---------------------------------------------------------------------------
 // Helpers
@@ -60,7 +60,7 @@ export function stringFlag(flags, key) {
  */
 async function reposContext(args) {
     if (args.flags.env === true || args.flags.e === true) {
-        throw new Error('-e/--env requires a value (local|staging|production|banksouth|preview:<slug>).');
+        throw new Error('-e/--env requires a value — see: seq-studio envs list.');
     }
     const ctx = await buildContext(args);
     const secret = process.env.PREVIEW_ACCESS_HEADER?.trim();
@@ -414,12 +414,11 @@ export async function reposCloneCommand(args, deps = {}) {
 /** Resolve -e/--env without requiring Auth0 (for PAT-only --url/--id clones). */
 async function resolveEnvOnly(args) {
     if (args.flags.env === true || args.flags.e === true) {
-        throw new Error('-e/--env requires a value (local|staging|production|banksouth|preview:<slug>).');
+        throw new Error('-e/--env requires a value — see: seq-studio envs list.');
     }
-    const config = await readConfig();
     const requested = (typeof args.flags.env === 'string' ? args.flags.env : undefined) ??
         (typeof args.flags.e === 'string' ? args.flags.e : undefined);
-    return resolveEnv({ config, requested });
+    return resolveEnvWithDiscovery({ requested });
 }
 /**
  * Validate clone URL shape and that the origin matches the resolved Atlas env
@@ -502,7 +501,7 @@ export const REPOS_USAGE = `usage:
                                                                     materialize the tree at a ref (JSON API)
   seq-studio repos delete <ns>/<name> [-e env] [--yes]              delete a repo (confirm prompt)
 
-  Flags: -e/--env <local|staging|production|banksouth>
+  Flags: -e/--env <env>  (see: seq-studio envs list)
 
   clone prefers real git clone (PAT via askpass — never written into the remote
   URL). Without ATLAS_GIT_PAT, <ns>/<name> falls back to the JSON API and prints

package/dist/secrets/commands.d.ts

@@ -20,5 +20,5 @@ export declare function secretsSetDefaultCommand(args: ParsedArgs): Promise<numb
  * UI: pin + redeploy the function's active version / pin only / cancel.
  */
 export declare function secretsPinCommand(args: ParsedArgs): Promise<number>;
-export declare const SECRETS_USAGE = "usage:\n  seq-studio secrets create <NAME> [--description text]   register an org-owned secret\n  seq-studio secrets set <NAME>                             set the shared default value (write-only)\n  seq-studio secrets list [-e env]                          secrets you can see (never values)\n  seq-studio secrets attach <NAME> --fn <slug>              mount default on a function env var\n  seq-studio secrets detach <NAME> --fn <slug>              remove attachment\n  seq-studio secrets apply --from-env-file .env [-e env]    push defaults + attach (keys default from manifest)\n  seq-studio secrets versions <NAME>                        value version history (never values)\n  seq-studio secrets set-default <NAME> [version]           point the default at a prior version (editor)\n  seq-studio secrets pin <NAME> --fn <slug> [version]       pin one function to a version (sticky; --unpin clears)\n\n  Note: for the common deploy loop, secrets declared in managed-function.yml are\n  reconciled automatically by `seq-studio functions deploy` using a local .env.\n  Use `secrets` commands for CI (no .env), bulk/multi-function ops, or write-only\n  value changes without a redeploy.\n\n  Flags: -e/--env <local|staging|production|banksouth>\n         --fn <slug> \u00B7 --env-var <NAME> \u00B7 --yes\n         --functions <f1,f2> \u00B7 --keys <K1,K2> \u00B7 --all (override key selection)\n         set-default: [version|version-row-id] (defaults to the most recent non-default) \u00B7 --yes\n         pin: [version|version-row-id] (defaults to the current default) \u00B7 --unpin \u00B7 --yes (redeploy) \u00B7 --yes --no-redeploy\n";
+export declare const SECRETS_USAGE = "usage:\n  seq-studio secrets create <NAME> [--description text]   register an org-owned secret\n  seq-studio secrets set <NAME>                             set the shared default value (write-only)\n  seq-studio secrets list [-e env]                          secrets you can see (never values)\n  seq-studio secrets attach <NAME> --fn <slug>              mount default on a function env var\n  seq-studio secrets detach <NAME> --fn <slug>              remove attachment\n  seq-studio secrets apply --from-env-file .env [-e env]    push defaults + attach (keys default from manifest)\n  seq-studio secrets versions <NAME>                        value version history (never values)\n  seq-studio secrets set-default <NAME> [version]           point the default at a prior version (editor)\n  seq-studio secrets pin <NAME> --fn <slug> [version]       pin one function to a version (sticky; --unpin clears)\n\n  Note: for the common deploy loop, secrets declared in managed-function.yml are\n  reconciled automatically by `seq-studio functions deploy` using a local .env.\n  Use `secrets` commands for CI (no .env), bulk/multi-function ops, or write-only\n  value changes without a redeploy.\n\n  Flags: -e/--env <env>  (see: seq-studio envs list)\n         --fn <slug> \u00B7 --env-var <NAME> \u00B7 --yes\n         --functions <f1,f2> \u00B7 --keys <K1,K2> \u00B7 --all (override key selection)\n         set-default: [version|version-row-id] (defaults to the most recent non-default) \u00B7 --yes\n         pin: [version|version-row-id] (defaults to the current default) \u00B7 --unpin \u00B7 --yes (redeploy) \u00B7 --yes --no-redeploy\n";
 export declare function runSecretsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;

package/dist/secrets/commands.js

@@ -658,7 +658,7 @@ export const SECRETS_USAGE = `usage:
   Use \`secrets\` commands for CI (no .env), bulk/multi-function ops, or write-only
   value changes without a redeploy.
 
-  Flags: -e/--env <local|staging|production|banksouth>
+  Flags: -e/--env <env>  (see: seq-studio envs list)
          --fn <slug> · --env-var <NAME> · --yes
          --functions <f1,f2> · --keys <K1,K2> · --all (override key selection)
          set-default: [version|version-row-id] (defaults to the most recent non-default) · --yes

package/dist/update-check-refresh.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/update-check-refresh.js

@@ -0,0 +1,9 @@
+/**
+ * Detached background entry spawned by maybeNotifyUpdate() when the update
+ * cache is stale. Polls the npm registry once and persists the result so
+ * the *next* command can print the notice without any foreground network.
+ */
+import { refreshUpdateCache } from './update-check.js';
+refreshUpdateCache().catch(() => {
+    // Best-effort: nothing to report to — the parent process is long gone.
+});

package/dist/update-check.d.ts

@@ -0,0 +1,27 @@
+/** The version of this installed package (dist/../package.json). */
+export declare function currentVersion(): string;
+export declare function updateCheckCachePath(): string;
+/** Exclusive-create marker that makes "who spawns the refresh?" atomic. */
+export declare function updateCheckClaimPath(): string;
+/**
+ * True when `candidate` is a strictly newer semver than `current`.
+ * Prerelease suffixes are ignored — the published channel is plain
+ * major.minor.patch and this only drives a notice, not resolution.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+/**
+ * Poll the registry and persist the result. Runs in the detached background
+ * process (see update-check-refresh.ts) — never on a command's exit path.
+ * Failed fetches still record `lastCheckedAt` (keeping any previously known
+ * version) so attempts are throttled to once per interval either way. The
+ * cache file is written *only* here, so a foreground path can never clobber
+ * a fresher result. Releases the spawn claim when done.
+ */
+export declare function refreshUpdateCache(): Promise<void>;
+/**
+ * Print a strong upgrade recommendation to stderr when the cached registry
+ * state says a newer version is published, and kick off a detached refresh
+ * when the cache is stale. Reads only local state — adds no network latency
+ * to the command. Never throws.
+ */
+export declare function maybeNotifyUpdate(): Promise<void>;