@sequenceholdings/studio-cli 0.1.12 → 0.1.18

package/dist/config.js

@@ -5,6 +5,7 @@ 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 { readRegisteredEnvironmentUrls } from './env-registry.js';
 import { resolvePreviewFromSlug } from './preview.js';
 /**
  * `--env preview:<branch-or-slug>` targets a per-PR Vercel preview deployment
@@ -45,10 +46,10 @@ export function defaultConfig() {
  *   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)
+ *   4. OpCo registrations shared with seqapi (`~/.config/sequence-api/config.json`)
  *
- * 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.
+ * Registered OpCo routes are authoritative for their names so a lower-trust
+ * config.toml override cannot send a tenant token to another origin.
  */
 export async function readConfig() {
     const merged = defaultConfig();
@@ -60,18 +61,22 @@ export async function readConfig() {
         }
     }
     const path = configPath();
-    if (!existsSync(path))
-        return merged;
-    const raw = parseToml(await readFile(path, 'utf8'));
-    if (raw.env) {
-        for (const [name, value] of Object.entries(raw.env)) {
-            if (typeof value?.url === 'string') {
-                merged.envs[name] = { url: value.url };
+    if (existsSync(path)) {
+        const raw = parseToml(await readFile(path, 'utf8'));
+        if (raw.env) {
+            for (const [name, value] of Object.entries(raw.env)) {
+                if (typeof value?.url === 'string') {
+                    merged.envs[name] = { url: value.url };
+                }
             }
         }
+        if (typeof raw.default_env === 'string') {
+            merged.defaultEnv = raw.default_env;
+        }
     }
-    if (typeof raw.default_env === 'string') {
-        merged.defaultEnv = raw.default_env;
+    const registered = await readRegisteredEnvironmentUrls();
+    for (const [name, value] of Object.entries(registered)) {
+        merged.envs[name] = value;
     }
     return merged;
 }
@@ -82,18 +87,40 @@ export async function writeConfig(config) {
     // smol-toml's stringify can't accept arbitrary nested keys via the
     // `env.<name>` syntax directly; we build it manually for stable
     // ordering and clean output.
-    const lines = [];
+    //
+    // `default_env` MUST come before any `[env.*]` table. In TOML, a bare
+    // key after a table header belongs to that table — putting it last
+    // would silently attach it to the final `[env.*]` and `readConfig`
+    // (which only reads top-level `default_env`) would ignore it.
+    const lines = [`default_env = "${config.defaultEnv}"`, ''];
     for (const [name, value] of Object.entries(config.envs)) {
         lines.push(`[env.${name}]`);
         lines.push(`url = ${stringifyToml({ url: value.url }).trim().replace(/^url = /, '')}`);
         lines.push('');
     }
-    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';
+/**
+ * Copy-pasteable fallback when the discovery catalog is unavailable.
+ *
+ * The `[env.*]` table is safe to append to an existing config.toml. We
+ * intentionally omit `default_env` from the snippet — appending it after
+ * an existing `[env.*]` table would scope it into that table (TOML bare-key
+ * rule) and silently no-op. Callers who want a default should put
+ * `default_env = "..."` at the top of the file, before any table.
+ */
+export function manualEnvConfigHint() {
+    return (`Or add an environment manually in ${configPath()} (append-safe):\n` +
+        `\n` +
+        `  [env.my-env]\n` +
+        `  url = "https://my-atlas.seqholdings.com"\n` +
+        `\n` +
+        `To make it the default, put \`default_env = "my-env"\` at the TOP of ` +
+        `that file — before any [env.*] table.`);
+}
 /**
  * Resolve `--env <name>` against the effective config. Falls back to the
  * config's `defaultEnv` when no name is passed. Throws a clear error when

package/dist/env-catalog.js

@@ -2,6 +2,7 @@ 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 { authenticatedRequestUrl } from '@sequenceholdings/artifact-studio/deployment-validation';
 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. */
@@ -74,23 +75,32 @@ export async function clearCatalog() {
  * callers can distinguish "offline" from "not authorized".
  */
 export async function fetchCatalog() {
+    const targetUrl = bootstrapUrl();
+    const requestUrl = authenticatedRequestUrl({
+        baseUrl: targetUrl,
+        path: '/api/platform/environments',
+    });
     // 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 });
+    const token = await tryGetAccessToken({
+        failClosedForM2m: true,
+        targetUrl,
+    });
     if (!token) {
         await clearCatalog();
         return null;
     }
-    const response = await fetch(`${bootstrapUrl()}/api/platform/environments`, {
+    const response = await fetch(requestUrl, {
         headers: { Authorization: `Bearer ${token}` },
+        redirect: 'manual',
     });
     if (response.status === 401 || response.status === 403) {
         await clearCatalog();
         return null;
     }
     if (!response.ok) {
-        throw new Error(`Environment discovery failed (${response.status}) against ${bootstrapUrl()}.`);
+        throw new Error(`Environment discovery failed (${response.status}) against ${targetUrl}.`);
     }
     const body = (await response.json());
     if ((body.tier !== 'sequence' && body.tier !== 'partner') ||

package/dist/env-flags.d.ts

@@ -3,6 +3,8 @@
  * CLIs only recognize the two-token `--env <value>` form, so every `-e value`
  * / `-e=value` / `--env=value` spelling is rewritten before forwarding.
  */
+/** Shared copy for network commands that must not silently fall back to `local`. */
+export declare const REQUIRE_EXPLICIT_ENV_MESSAGE = "You must specify an environment you have access to with `-e <env>`. Run `seq-studio envs list` to see available environments.";
 export declare function normalizeShortEnvFlag(argv: readonly string[]): string[];
 /** Only valid AFTER normalizeShortEnvFlag — recognizes the two-token form. */
 export declare function readEnvFromArgv(rest: readonly string[]): string | undefined;

package/dist/env-flags.js

@@ -3,6 +3,8 @@
  * CLIs only recognize the two-token `--env <value>` form, so every `-e value`
  * / `-e=value` / `--env=value` spelling is rewritten before forwarding.
  */
+/** Shared copy for network commands that must not silently fall back to `local`. */
+export const REQUIRE_EXPLICIT_ENV_MESSAGE = 'You must specify an environment you have access to with `-e <env>`. Run `seq-studio envs list` to see available environments.';
 export function normalizeShortEnvFlag(argv) {
     const out = [];
     for (let i = 0; i < argv.length; i++) {

package/dist/env-registry.d.ts

@@ -0,0 +1,27 @@
+interface DiscoveredRealm {
+    domain: string;
+    clientId: string;
+    audience: string;
+    organization?: string;
+    m2mClientId?: string;
+}
+interface RegistrationResult {
+    name: string;
+    baseUrl: string;
+    replacing: boolean;
+    realm: DiscoveredRealm;
+}
+export declare function seqapiConfigPath(): string;
+export declare function readRegisteredEnvironmentUrls({ configFile, }?: {
+    configFile?: string;
+}): Promise<Record<string, {
+    url: string;
+}>>;
+export declare function registerEnvironment({ baseUrl: rawBaseUrl, clearCredentials, configFile, fetchImpl, name: rawName, }: {
+    baseUrl: string;
+    clearCredentials?: (name: string) => Promise<void>;
+    configFile?: string;
+    fetchImpl?: typeof fetch;
+    name: string;
+}): Promise<RegistrationResult>;
+export {};

package/dist/env-registry.js

@@ -0,0 +1,204 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { validateDeploymentAudience, validateDeploymentBaseUrl, } from '@sequenceholdings/artifact-studio/deployment-validation';
+import { deleteRealmTokens, isSequenceAuthEnvName, validateAuth0Domain, } from './auth.js';
+import { withCrossProcessFileLock } from './file-lock.js';
+const DISCOVERY_PATH = '/api/auth/cli-config';
+const ENV_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasErrorCode(error, code) {
+    return error instanceof Error && Reflect.get(error, 'code') === code;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+export function seqapiConfigPath() {
+    return join(homedir(), '.config', 'sequence-api', 'config.json');
+}
+function validateEnvironmentName(input) {
+    const name = input.toLowerCase();
+    if (!ENV_NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid environment name '${input}': use lowercase letters, digits, and hyphens.`);
+    }
+    if (isSequenceAuthEnvName(name)) {
+        throw new Error(`'${name}' is a reserved built-in environment name.`);
+    }
+    return name;
+}
+async function discoverRealm({ baseUrl, fetchImpl, }) {
+    const url = `${baseUrl}${DISCOVERY_PATH}`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            redirect: 'manual',
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${url}: ${error instanceof Error ? error.message : error}`, {
+            cause: error,
+        });
+    }
+    if (response.status >= 300 && response.status < 400) {
+        throw new Error(`${url} redirected to ${JSON.stringify(response.headers.get('location'))}; ` +
+            'CLI discovery redirects are not allowed.');
+    }
+    if (response.status === 404) {
+        throw new Error(`${url} returned 404 — this deployment does not expose the CLI discovery endpoint yet.`);
+    }
+    if (!response.ok) {
+        throw new Error(`${url} returned HTTP ${response.status}: ${(await response.text()).slice(0, 300)}`);
+    }
+    let data;
+    try {
+        data = await response.json();
+    }
+    catch (error) {
+        throw new Error(`${url} did not return JSON.`, { cause: error });
+    }
+    const auth0 = isRecord(data) ? Reflect.get(data, 'auth0') : undefined;
+    if (!isRecord(auth0)) {
+        throw new Error(`${url} response is missing auth0 configuration.`);
+    }
+    const domain = optionalString(Reflect.get(auth0, 'domain'));
+    const clientId = optionalString(Reflect.get(auth0, 'clientId'));
+    const audience = optionalString(Reflect.get(auth0, 'audience'));
+    const missing = [
+        !domain ? 'domain' : null,
+        !clientId ? 'clientId' : null,
+        !audience ? 'audience' : null,
+    ].filter((key) => key !== null);
+    if (missing.length > 0 || !domain || !clientId || !audience) {
+        throw new Error(`${url} response is missing auth0.{${missing.join(', ')}}.`);
+    }
+    return {
+        domain: validateAuth0Domain(domain),
+        clientId,
+        audience: validateDeploymentAudience({ audience, baseUrl }),
+        organization: optionalString(Reflect.get(auth0, 'organization')),
+        m2mClientId: optionalString(Reflect.get(auth0, 'm2mClientId')),
+    };
+}
+async function loadConfig(configFile) {
+    try {
+        const parsed = JSON.parse(await readFile(configFile, 'utf8'));
+        if (!isRecord(parsed))
+            throw new Error('root value must be an object');
+        return parsed;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return {};
+        throw new Error(`Could not read tenant auth registry ${configFile}.`, { cause: error });
+    }
+}
+export async function readRegisteredEnvironmentUrls({ configFile = seqapiConfigPath(), } = {}) {
+    let config;
+    try {
+        config = await loadConfig(configFile);
+    }
+    catch {
+        // Aggregate routing degrades to built-ins/catalog/config.toml when the
+        // registry is corrupt. Explicit auth use still fails loudly in realmForEnv.
+        return {};
+    }
+    const stored = Reflect.get(config, 'environments');
+    if (!isRecord(stored))
+        return {};
+    const valid = {};
+    for (const [name, value] of Object.entries(stored)) {
+        try {
+            if (validateEnvironmentName(name) !== name || !isRecord(value))
+                continue;
+            const auth0 = Reflect.get(value, 'auth0');
+            const rawUrl = Reflect.get(value, 'url');
+            if (!isRecord(auth0) || typeof rawUrl !== 'string')
+                continue;
+            const domain = optionalString(Reflect.get(auth0, 'domain'));
+            const clientId = optionalString(Reflect.get(auth0, 'client_id'));
+            const audience = optionalString(Reflect.get(auth0, 'audience'));
+            if (!domain || !clientId || !audience)
+                continue;
+            validateAuth0Domain(domain);
+            const url = validateDeploymentBaseUrl(rawUrl);
+            validateDeploymentAudience({ audience, baseUrl: url });
+            valid[name] = { url };
+        }
+        catch {
+            // Aggregate routing skips malformed entries; explicit auth use still
+            // fails closed with a detailed error from realmForEnv.
+        }
+    }
+    return valid;
+}
+async function writeConfig(configFile, config) {
+    await mkdir(dirname(configFile), { recursive: true });
+    const temporary = `${configFile}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(config, null, 2) + '\n', {
+            encoding: 'utf8',
+            mode: 0o600,
+            flag: 'wx',
+        });
+        await rename(temporary, configFile);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function clearImpersonationForEnv({ configFile, name, }) {
+    const impersonationFile = join(dirname(configFile), 'impersonation.json');
+    try {
+        const parsed = JSON.parse(await readFile(impersonationFile, 'utf8'));
+        const env = isRecord(parsed) ? Reflect.get(parsed, 'env') : undefined;
+        if (env === undefined || env === null || env === name) {
+            await rm(impersonationFile, { force: true });
+        }
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'ENOENT'))
+            throw error;
+    }
+}
+async function clearEnvironmentCredentials({ configFile, name, }) {
+    await deleteRealmTokens(name);
+    await clearImpersonationForEnv({ configFile, name });
+}
+export async function registerEnvironment({ baseUrl: rawBaseUrl, clearCredentials, configFile = seqapiConfigPath(), fetchImpl = fetch, name: rawName, }) {
+    const name = validateEnvironmentName(rawName);
+    const baseUrl = validateDeploymentBaseUrl(rawBaseUrl);
+    const realm = await discoverRealm({ baseUrl, fetchImpl });
+    // Lock ordering contract: credential cleanup may acquire tokens.json.lock
+    // while this is held; token-file code must never acquire config.json.lock.
+    const replacing = await withCrossProcessFileLock({
+        path: configFile,
+        operation: async () => {
+            const config = await loadConfig(configFile);
+            const existingEnvironments = Reflect.get(config, 'environments');
+            const environments = isRecord(existingEnvironments) ? { ...existingEnvironments } : {};
+            const isReplacement = Reflect.has(environments, name);
+            // Clear unconditionally: a manually removed or partially written
+            // registration can leave orphaned credentials even when no entry exists.
+            await (clearCredentials
+                ? clearCredentials(name)
+                : clearEnvironmentCredentials({ configFile, name }));
+            environments[name] = {
+                url: baseUrl,
+                auth0: {
+                    domain: realm.domain,
+                    client_id: realm.clientId,
+                    audience: realm.audience,
+                    organization: realm.organization ?? null,
+                    m2m_client_id: realm.m2mClientId ?? null,
+                },
+            };
+            await writeConfig(configFile, { ...config, environments });
+            return isReplacement;
+        },
+    });
+    return { name, baseUrl, replacing, realm };
+}

package/dist/envs/commands.d.ts

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

package/dist/envs/commands.js

@@ -1,8 +1,12 @@
-import { readConfig, configPath } from '../config.js';
+import { tryGetAccessToken } from '../auth.js';
+import { readConfig, configPath, manualEnvConfigHint } from '../config.js';
+import { readRegisteredEnvironmentUrls, registerEnvironment, } from '../env-registry.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
+  seq-studio envs add <name> <url>
+                            register an OpCo deployment from public discovery
 
   The published CLI ships with only the "local" environment. After you
   authenticate (seq-studio login, or AUTH0_M2M_CLIENT_SECRET for headless use),
@@ -12,8 +16,10 @@ const ENVS_USAGE = `usage:
 
   Custom entries in ${configPath()} are always honored on top.
 `;
-export async function runEnvsCommand(sub, _rest) {
+export async function runEnvsCommand(sub, rest) {
     switch (sub) {
+        case 'add':
+            return addCommand(rest);
         case 'list':
             return listCommand();
         case 'refresh':
@@ -30,9 +36,58 @@ export async function runEnvsCommand(sub, _rest) {
             return 1;
     }
 }
+async function addCommand(rest) {
+    const [name, baseUrl, ...extra] = rest;
+    if (!name || !baseUrl || extra.length > 0) {
+        console.error('usage: seq-studio envs add <name> <url>');
+        return 1;
+    }
+    try {
+        const registration = await registerEnvironment({ name, baseUrl });
+        const verb = registration.replacing ? 'Updated' : 'Registered';
+        console.log(`${verb} environment '${registration.name}' -> ${registration.baseUrl}`);
+        console.log(`  auth0 domain:   ${registration.realm.domain}`);
+        console.log(`  audience:       ${registration.realm.audience}`);
+        console.log(`  organization:   ${registration.realm.organization ?? '(none)'}`);
+        if (registration.realm.m2mClientId) {
+            const suffix = registration.name.toUpperCase().replaceAll('-', '_');
+            console.log(`  m2m client:     ${registration.realm.m2mClientId} ` +
+                `(headless: export AUTH0_M2M_CLIENT_SECRET_${suffix}=...)`);
+        }
+        console.log(`Next: seq-studio login --env ${registration.name}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(`envs add: FAIL — ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
+/**
+ * Tier `anonymous` means "no catalog cached", not necessarily "no token".
+ * Shared by list + refresh so they don't contradict each other.
+ */
+async function printNoCatalogGuidance(log = console.log) {
+    const token = await tryGetAccessToken();
+    log('');
+    if (token) {
+        log(`Logged in, but no environment catalog is cached against ${bootstrapUrl()} — ` +
+            'only "local" (plus any config.toml entries) is visible. Run: seq-studio envs refresh');
+    }
+    else {
+        log('Not authenticated — only "local" is visible. Authenticate with ' +
+            '`seq-studio login` (or set AUTH0_M2M_CLIENT_SECRET), then run: seq-studio envs refresh');
+    }
+    log('');
+    log(manualEnvConfigHint());
+}
 async function listCommand() {
-    const [config, catalog] = await Promise.all([readConfig(), readCachedCatalog()]);
+    const [config, catalog, registered] = await Promise.all([
+        readConfig(),
+        readCachedCatalog(),
+        readRegisteredEnvironmentUrls(),
+    ]);
     const discovered = new Set(catalog?.environments.map((env) => env.name) ?? []);
+    const registeredNames = new Set(Object.keys(registered));
     console.log(`tier: ${config.tier}`);
     if (catalog) {
         console.log(`catalog fetched: ${new Date(catalog.fetchedAt).toISOString()}`);
@@ -44,13 +99,13 @@ async function listCommand() {
             ? 'built-in'
             : discovered.has(name)
                 ? 'discovered'
-                : 'config.toml';
+                : registeredNames.has(name)
+                    ? 'registered'
+                    : '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');
+        await printNoCatalogGuidance();
     }
     return 0;
 }
@@ -61,12 +116,12 @@ async function refreshCommand() {
     }
     catch (err) {
         console.error(`envs refresh: FAIL — ${err instanceof Error ? err.message : String(err)}`);
+        console.error('');
+        console.error(manualEnvConfigHint());
         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.');
+        await printNoCatalogGuidance();
         return 0;
     }
     console.log(`tier: ${catalog.tier} — ${catalog.environments.length} environment(s) cached.`);

package/dist/file-lock.d.ts

@@ -0,0 +1,5 @@
+export declare function tryReapStaleLock(lockPath: string, observedOwner: string): Promise<void>;
+export declare function withCrossProcessFileLock<T>({ operation, path, }: {
+    operation: () => Promise<T>;
+    path: string;
+}): Promise<T>;