@sequenceholdings/studio-cli 0.1.24 → 0.1.25

package/README.md

@@ -405,6 +405,27 @@ limits:
 `min_instances` defaults to `0`, cannot exceed `max_instances`, and incurs
 Cloud Run idle-instance charges while warm.
 
+### Invocation IP allowlist
+
+Declare the function-level source-IP restriction in `managed-function.yml`:
+
+```yaml
+invocation:
+  allowed_ip_ranges:
+    - 203.0.113.0/24
+    - 2001:db8::/48
+```
+
+`seq-studio functions build` validates IPv4/IPv6 addresses and CIDRs locally;
+Atlas performs authoritative normalization during upload. `/0` ranges are
+rejected. Omitting `invocation` or declaring `allowed_ip_ranges: []` means
+unrestricted source IPs.
+
+The policy is part of the immutable function version. It becomes live atomically
+when that version activates, a failed deploy leaves the current policy unchanged,
+and promote or rollback restores the selected version's policy. The gateway
+checks a non-empty policy before invocation permissions.
+
 ### Server-owned resource authorization
 
 Some functions expose regulated external resources whose authorization must be
@@ -632,8 +653,8 @@ install it alongside the CLI to use this family.
 |---------|--------------|
 | `seq-studio pipeline init --type ingestion\|transformation\|serving <name> [--dir <dir>]` | Scaffold `<name>.stage.yml` (commented per-kind template) plus a `src/` Databricks-notebook entrypoint stub (begins with `# Databricks notebook source`; serving stages are declarative — no stub). Refuses to overwrite an existing spec |
 | `seq-studio pipeline validate [dir] [--assets <file\|url>] [--orm-contracts <file\|url>] [--json]` | Run the full offline spec gate: envelope + body validation, `schema_ref` resolution, and repo-level graph validation (reference resolution, single-writer, cycles, column subsets, serving projection checks). Auto-loads `orm-contracts.json` from the pipeline dir when present. Exit 0/1 |
-| `seq-studio pipeline plan --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--json]` | Plan a Pipeline deploy (materialize → SDK/`validateSpecGraph` → compile → live-diff → provision findings). Fails closed listing **every** missing target binding (alert channels, workspace, Databricks `source.credential`) plus Data Sync edge-worker machine/operation/`credEnvFamilies` mismatches before registry writes. Does **not** run Databricks `bundle validate` (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). `--json` emits the stable plan envelope |
-| `seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--approved-by <sub>] [--no-wait]` | Plan then enqueue deploy; Trigger runs `bundle validate` then `bundle deploy` against reviewed bytes. Polls to terminal unless `--no-wait`. Targets that require approval need `--approved-by` naming the authenticated caller. |
+| `seq-studio pipeline plan --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--json]` | Enqueue and poll a durable Pipeline plan (materialize → SDK/`validateSpecGraph` → compile → live-diff → provision findings). Fails closed listing **every** missing target binding (alert channels, workspace, Databricks `source.credential`) plus Data Sync edge-worker machine/operation/`credEnvFamilies` mismatches before registry writes. Does **not** run Databricks `bundle validate` (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). `--json` emits the completed stable plan envelope |
+| `seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--approved-by <sub>] [--run-now] [--no-wait]` | Plan then enqueue deploy; Trigger runs `bundle validate` then `bundle deploy` against reviewed bytes. Default is plant-only (jobs are created, not run). `--run-now` runs in-unit producer roots after bundle deploy and waits before serving sync create. Polls to terminal unless `--no-wait`. Targets that require approval need `--approved-by` naming the authenticated caller. |
 | `seq-studio pipeline adopt --stage <slug> --ref <sha\|branch> -e <env> [--target <id>] --native-id <id> --approved-by <you> [--resource-key <key>] [--kind job\|dlt_pipeline] [--old-source-removal-pr <url>] [--repo pipelines/<slug>]` | Bind a live Databricks job/pipeline into the stage without recreation (`bundle deployment bind` on Trigger). Always requires `--approved-by` naming the caller. When the key is still in the monorepo DAB, pass `--old-source-removal-pr` and follow the returned cutover checklist: unbind the old bundle state without deleting the remote, then remove its DAB declaration and add the target-specific adopted-resource entry in the same PR before redeploying. |
 | `seq-studio pipeline unbind --stage <slug> --ref <sha\|branch> -e <env> [--target <id>] --approved-by <you> [--resource-key <key>] [--repo pipelines/<slug>]` | Release an adopted binding on Trigger; the remote object stays live (never deleted) |
 | `seq-studio pipeline run-now --stage <slug> -e <env> [--target <id>] [--repo pipelines/<slug>] [--json]` | Run the stage's active job or DLT pipeline immediately and print its Databricks run URL |
@@ -644,7 +665,7 @@ install it alongside the CLI to use this family.
 pipeline target advertised by that endpoint. It is optional when the alias
 matches a target id or when the endpoint has exactly one target.
 
-Unless `--no-wait` is set, `deploy`, `promote`, and `rollback` report status or
+Unless `--no-wait` is set, `plan`, `deploy`, `promote`, and `rollback` report status or
 status-detail changes while waiting, then emit a 20-second progress heartbeat.
 Terminal output includes the deployment ID and elapsed time; failures include
 the status detail, and any available Trigger run ID is shown. `--json` output

package/dist/auth.d.ts

@@ -53,14 +53,17 @@ export interface SeqapiTokens {
     access_token?: string;
     expires_at?: number;
 }
+interface RealmResolutionOptions {
+    fetchImpl?: typeof fetch;
+    targetUrl?: string;
+}
 /**
  * Resolve the auth realm for an environment name. Undefined, built-ins, and
- * per-PR preview targets map to the shared Sequence realm. Preview URLs are
- * constrained to Sequence's preview domain by the environment resolver. Every
- * other explicit name must have a valid seqapi registry entry; otherwise fail
- * closed so a shared Sequence bearer token can never be sent to a tenant URL.
+ * per-PR preview targets map to the shared Sequence realm, except loopback
+ * targets can advertise the isolated Sequence-staging realm used by contractor
+ * local dev. Every other explicit name must have a valid seqapi registry entry.
  */
-export declare function realmForEnv(envName?: string): Promise<AuthRealm>;
+export declare function realmForEnv(envName?: string, options?: RealmResolutionOptions): Promise<AuthRealm>;
 /** Env var(s) carrying a realm's M2M client secret — the Sequence realm keeps
  * the legacy bare name; OpCo realms use a suffixed name so one shell can hold
  * several credentials unambiguously. Mirrors seqapi's `_m2m_secret_env_names`. */
@@ -153,3 +156,4 @@ export declare function currentIdentitySubject(options?: {
 export declare function loadCachedUserTokens(realmName?: string): Promise<SeqapiTokens | null>;
 export declare function saveTokens(tokens: SeqapiTokens, realmName?: string): Promise<void>;
 export declare function deleteRealmTokens(realmName: string): Promise<void>;
+export {};

package/dist/auth.js

@@ -40,6 +40,12 @@ const AUTH0_M2M_CLIENT_ID = '5TLffZqvLq4ztLDjZhwKVJCpB5VNrWj0';
  * also the implicit realm of the legacy flat fields in tokens.json. */
 export const SEQUENCE_REALM = 'sequence';
 const SEQUENCE_BUILTIN_ENVS = new Set(['local', 'staging', 'production', 'banksouth']);
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
+const SEQUENCE_STAGING_AUTH0_AUDIENCE = 'https://staging.sequence.seqholdings.com/api';
+const TRUSTED_LOOPBACK_AUTH0_AUDIENCES = new Set([
+    AUTH0_AUDIENCE,
+    SEQUENCE_STAGING_AUTH0_AUDIENCE,
+]);
 export function isSequenceAuthEnvName(envName) {
     return (envName === SEQUENCE_REALM ||
         SEQUENCE_BUILTIN_ENVS.has(envName) ||
@@ -76,14 +82,116 @@ export const SEQUENCE_AUTH_REALM = {
 function seqapiConfigPath() {
     return join(seqapiTokenDir(), 'config.json');
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isLoopbackEnvName(envName) {
+    return envName === 'local' || envName.startsWith('local:');
+}
+function loopbackTargetUrl({ configuredTargetUrl, envName, }) {
+    if (configuredTargetUrl)
+        return configuredTargetUrl;
+    return envName === 'local' ? 'http://localhost:5001' : undefined;
+}
+function optionalString({ field, value, }) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    throw new Error(`Local Auth0 discovery returned invalid '${field}'.`);
+}
+function parseDiscoveredAuth0(payload) {
+    const auth0 = isRecord(payload) ? Reflect.get(payload, 'auth0') : undefined;
+    const auth0Record = isRecord(auth0) ? auth0 : {};
+    const domain = Reflect.get(auth0Record, 'domain');
+    const clientId = Reflect.get(auth0Record, 'clientId');
+    const audience = Reflect.get(auth0Record, 'audience');
+    if (typeof domain !== 'string' ||
+        !domain ||
+        typeof clientId !== 'string' ||
+        !clientId ||
+        typeof audience !== 'string' ||
+        !audience) {
+        throw new Error('Local Auth0 discovery returned incomplete required config.');
+    }
+    return {
+        domain,
+        clientId,
+        audience,
+        organization: optionalString({
+            field: 'organization',
+            value: Reflect.get(auth0Record, 'organization'),
+        }),
+        m2mClientId: optionalString({
+            field: 'm2mClientId',
+            value: Reflect.get(auth0Record, 'm2mClientId'),
+        }),
+    };
+}
+async function discoverLoopbackRealm({ envName, fetchImpl = fetch, targetUrl, }) {
+    const baseUrl = validateDeploymentBaseUrl(targetUrl);
+    const hostname = new URL(baseUrl).hostname.toLowerCase();
+    if (!LOOPBACK_HOSTNAMES.has(hostname))
+        return SEQUENCE_AUTH_REALM;
+    let response;
+    try {
+        response = await fetchImpl(`${baseUrl}/api/auth/cli-config`, {
+            redirect: 'error',
+            signal: AbortSignal.timeout(2_000),
+        });
+    }
+    catch {
+        // Preserve the historical realm choice while local Atlas is stopped. The
+        // subsequent API request reports that the local server is unavailable.
+        return SEQUENCE_AUTH_REALM;
+    }
+    if (!response.ok) {
+        throw new Error(`Could not discover Auth0 config for local environment '${envName}': ` +
+            `${baseUrl}/api/auth/cli-config returned HTTP ${response.status}.`);
+    }
+    const payload = await response.json();
+    const { audience, clientId, domain, m2mClientId, organization } = parseDiscoveredAuth0(payload);
+    if (!TRUSTED_LOOPBACK_AUTH0_AUDIENCES.has(audience)) {
+        throw new Error(`Untrusted Auth0 audience '${audience}' for local environment '${envName}'.`);
+    }
+    const trustedDomain = validateAuth0Domain(domain);
+    if (clientId === AUTH0_CLIENT_ID && audience === AUTH0_AUDIENCE) {
+        return SEQUENCE_AUTH_REALM;
+    }
+    return {
+        name: 'local',
+        domain: trustedDomain,
+        clientId,
+        audience,
+        organization,
+        m2mClientId,
+    };
+}
+async function maybeDiscoverLoopbackRealm({ envName, options, }) {
+    if (!envName || !isLoopbackEnvName(envName))
+        return undefined;
+    const targetUrl = loopbackTargetUrl({
+        configuredTargetUrl: options.targetUrl,
+        envName,
+    });
+    if (!targetUrl)
+        return undefined;
+    return discoverLoopbackRealm({
+        envName,
+        fetchImpl: options.fetchImpl,
+        targetUrl,
+    });
+}
 /**
  * Resolve the auth realm for an environment name. Undefined, built-ins, and
- * per-PR preview targets map to the shared Sequence realm. Preview URLs are
- * constrained to Sequence's preview domain by the environment resolver. Every
- * other explicit name must have a valid seqapi registry entry; otherwise fail
- * closed so a shared Sequence bearer token can never be sent to a tenant URL.
+ * per-PR preview targets map to the shared Sequence realm, except loopback
+ * targets can advertise the isolated Sequence-staging realm used by contractor
+ * local dev. Every other explicit name must have a valid seqapi registry entry.
  */
-export async function realmForEnv(envName) {
+export async function realmForEnv(envName, options = {}) {
+    const discoveredRealm = await maybeDiscoverLoopbackRealm({ envName, options });
+    if (discoveredRealm)
+        return discoveredRealm;
     if (!envName || isSequenceAuthEnvName(envName)) {
         return SEQUENCE_AUTH_REALM;
     }
@@ -303,7 +411,12 @@ function validateRealmTarget({ realm, targetUrl, }) {
     try {
         const baseUrl = validateDeploymentBaseUrl(targetUrl);
         if (realm.name !== SEQUENCE_REALM) {
-            validateDeploymentAudience({ audience: realm.audience, baseUrl });
+            const hostname = new URL(baseUrl).hostname.toLowerCase();
+            const isReviewedLoopbackRealm = LOOPBACK_HOSTNAMES.has(hostname) &&
+                TRUSTED_LOOPBACK_AUTH0_AUDIENCES.has(realm.audience);
+            if (!isReviewedLoopbackRealm) {
+                validateDeploymentAudience({ audience: realm.audience, baseUrl });
+            }
         }
     }
     catch (error) {
@@ -312,7 +425,7 @@ function validateRealmTarget({ realm, targetUrl, }) {
     }
 }
 export async function getAccessTokenWithMode(options) {
-    const realm = await realmForEnv(options?.env);
+    const realm = await realmForEnv(options?.env, { targetUrl: options?.targetUrl });
     if (options?.targetUrl)
         validateRealmTarget({ realm, targetUrl: options.targetUrl });
     const forceM2m = authModePrefersM2m();
@@ -377,7 +490,7 @@ export async function tryGetAccessTokenWithMode(options) {
             // Do not replace an invalid tenant registration with the Sequence realm:
             // that could hide a rejected discovery token host or inspect the wrong
             // M2M secret. Config-resolution errors must surface unchanged.
-            const realm = await realmForEnv(options.env);
+            const realm = await realmForEnv(options.env, { targetUrl: options.targetUrl });
             if (process.env[m2mSecretEnvName(realm)]?.trim())
                 throw err;
         }

package/dist/config.d.ts

@@ -24,14 +24,18 @@ export declare function defaultConfig(): LatticeConfig;
  * Read the effective config. Merge precedence (later wins):
  *
  *   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`)
+ *   2. local worktrees discovered from `.wt.env`
+ *   3. the cached discovered catalog (`~/.config/lattice/environments.json`)
+ *   4. user entries in config.toml (an override for `local`, or net-new envs)
+ *   5. OpCo registrations shared with seqapi (`~/.config/sequence-api/config.json`)
  *
  * Registered OpCo routes are authoritative for their names so a lower-trust
  * config.toml override cannot send a tenant token to another origin.
  */
 export declare function readConfig(): Promise<LatticeConfig>;
+export declare function localAuthRealmOptions(envName?: string): Promise<{
+    targetUrl?: string;
+}>;
 /** Write the config to disk, creating the dir if missing. */
 export declare function writeConfig(config: LatticeConfig): Promise<void>;
 export interface ResolvedEnv {

package/dist/config.js

@@ -1,7 +1,9 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
+import { promisify } from 'node:util';
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
 import { M2mTokenError } from './auth.js';
 import { fetchCatalog, readCachedCatalog, } from './env-catalog.js';
@@ -26,7 +28,69 @@ export const PREVIEW_ENV_PREFIX = 'preview:';
 const BUILT_IN_ENV_URLS = {
     local: 'http://localhost:5001',
 };
+const execFileAsync = promisify(execFile);
+const WORKTREE_ENV_PREFIX = 'local:';
+const WORKTREE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
 export const ENV_NAMES = Object.keys(BUILT_IN_ENV_URLS);
+async function atlasPortFromWorktreeEnv(directory) {
+    let text;
+    try {
+        text = await readFile(join(directory, '.wt.env'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    const value = text
+        .split('\n')
+        .map((line) => line.split('=', 2))
+        .find(([key]) => key?.trim() === 'ATLAS_PORT')?.[1]
+        ?.trim();
+    if (!value || !/^\d+$/.test(value))
+        return undefined;
+    const port = Number(value);
+    return port >= 1 && port <= 65_535 ? port : undefined;
+}
+async function worktreeDirectories() {
+    const root = process.env.WT_ROOT ?? join(homedir(), 'studio-worktrees');
+    const directories = [];
+    try {
+        const entries = await readdir(root, { withFileTypes: true });
+        directories.push(...entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => join(root, entry.name)));
+    }
+    catch {
+        // The default worktree root is optional.
+    }
+    try {
+        const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain']);
+        const gitWorktrees = stdout
+            .split('\n')
+            .filter((line) => line.startsWith('worktree '))
+            .map((line) => line.slice('worktree '.length))
+            .slice(1);
+        directories.push(...gitWorktrees);
+    }
+    catch {
+        // Global CLI use outside a git checkout still supports WT_ROOT discovery.
+    }
+    return [...new Set(directories)];
+}
+async function worktreeEnvironmentUrls() {
+    const environments = {};
+    for (const directory of await worktreeDirectories()) {
+        const name = basename(directory);
+        if (!WORKTREE_NAME_PATTERN.test(name))
+            continue;
+        const port = await atlasPortFromWorktreeEnv(directory);
+        if (port === undefined)
+            continue;
+        environments[`${WORKTREE_ENV_PREFIX}${name}`] ??= {
+            url: `http://localhost:${port}`,
+        };
+    }
+    return environments;
+}
 export function globalConfigDir() {
     return join(homedir(), '.config', 'lattice');
 }
@@ -44,15 +108,17 @@ export function defaultConfig() {
  * Read the effective config. Merge precedence (later wins):
  *
  *   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`)
+ *   2. local worktrees discovered from `.wt.env`
+ *   3. the cached discovered catalog (`~/.config/lattice/environments.json`)
+ *   4. user entries in config.toml (an override for `local`, or net-new envs)
+ *   5. OpCo registrations shared with seqapi (`~/.config/sequence-api/config.json`)
  *
  * 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();
+    Object.assign(merged.envs, await worktreeEnvironmentUrls());
     const catalog = await readCachedCatalog();
     if (catalog) {
         merged.tier = catalog.tier;
@@ -80,6 +146,12 @@ export async function readConfig() {
     }
     return merged;
 }
+export async function localAuthRealmOptions(envName) {
+    if (!envName || (envName !== 'local' && !envName.startsWith('local:'))) {
+        return {};
+    }
+    return { targetUrl: (await readConfig()).envs[envName]?.url };
+}
 /** Write the config to disk, creating the dir if missing. */
 export async function writeConfig(config) {
     const path = configPath();

package/dist/envs/commands.js

@@ -14,7 +14,8 @@ const ENVS_USAGE = `usage:
   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.
+  Local worktrees are discovered from their .wt.env files. Custom entries in
+  ${configPath()} are always honored on top.
 `;
 export async function runEnvsCommand(sub, rest) {
     switch (sub) {
@@ -97,11 +98,13 @@ async function listCommand() {
     for (const [name, { url }] of Object.entries(config.envs)) {
         const source = name === 'local' && !discovered.has(name)
             ? 'built-in'
-            : discovered.has(name)
-                ? 'discovered'
-                : registeredNames.has(name)
-                    ? 'registered'
-                    : 'config.toml';
+            : name.startsWith('local:')
+                ? 'worktree'
+                : discovered.has(name)
+                    ? 'discovered'
+                    : registeredNames.has(name)
+                        ? 'registered'
+                        : 'config.toml';
         console.log(`  ${name.padEnd(width)}  ${url}  (${source})`);
     }
     if (config.tier === 'anonymous') {

package/dist/functions/bundle.js

@@ -59,13 +59,13 @@ export async function validateLocalBundle({ rootDir, files, }) {
         if (existsSync(join(rootDir, 'package-lock.json')) || existsSync(join(rootDir, 'yarn.lock'))) {
             issues.push({
                 level: 'warning',
-                message: 'Found a non-pnpm lockfile (package-lock.json / yarn.lock). It is ignored — the deploy worker resolves dependencies against Chainguard, Sequence\'s internal registry. With Chainguard credentials, `pnpm install` produces a pinned lockfile for a faster deploy; without them this is fine as-is.',
+                message: 'Found a non-pnpm lockfile (package-lock.json / yarn.lock). It is ignored; dependencies are resolved server-side at deploy time.',
             });
         }
         else {
             issues.push({
                 level: 'info',
-                message: 'No pnpm-lock.yaml — the deploy worker will resolve dependencies against Chainguard, Sequence\'s internal registry. With Chainguard credentials, `pnpm install` produces a pinned lockfile for a faster deploy; without them this is fine as-is.',
+                message: 'No pnpm-lock.yaml — dependencies are resolved server-side at deploy time.',
             });
         }
     }
@@ -76,7 +76,7 @@ export async function validateLocalBundle({ rootDir, files, }) {
         if (classifyLockfileOrigin(lockfileText) !== 'chainguard') {
             issues.push({
                 level: 'warning',
-                message: 'pnpm-lock.yaml was not resolved against Chainguard — the deploy worker will discard it and re-resolve (slower, and versions may differ). This is expected without Chainguard credentials; with them, regenerate against Chainguard (registry=https://libraries.cgr.dev/javascript/) for a fast, pinned deploy.',
+                message: 'pnpm-lock.yaml cannot be used for this deployment, so dependencies are resolved server-side at deploy time. Resolved versions may differ.',
             });
         }
     }

package/dist/functions/commands.js

@@ -202,6 +202,12 @@ limits:
   max_instances: 3
   invoke_rate_per_minute: 60
 
+# Optional source-IP gate, checked before invocation permissions. Omit or leave
+# empty for unrestricted source IPs.
+# invocation:
+#   allowed_ip_ranges:
+#     - 203.0.113.0/24
+
 # Env-var names the function expects (UPPER_SNAKE_CASE). Values are read
 # from a local .env file at deploy time — they are never committed or bundled.
 secrets: []
@@ -325,10 +331,6 @@ export async function functionsInitCommand(args) {
     console.log('');
     console.log('Next steps (init is only needed when creating a function from scratch):');
     console.log(`  cd ${target}`);
-    console.log('  pnpm install                         # installs deps for local dev + pins versions via Chainguard.');
-    console.log('                                       # Requires Chainguard credentials (Sequence-internal). Without');
-    console.log('                                       # them this 401s — delete the scaffolded .npmrc and install from');
-    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 <env>  # upload, apply secrets, then deploy');
@@ -387,6 +389,15 @@ async function buildFromResolvedSource({ spec, source, }) {
 // ---------------------------------------------------------------------------
 // deploy
 // ---------------------------------------------------------------------------
+function buildInvocationIpPreviewLines({ ranges }) {
+    if (ranges.length === 0) {
+        return [`${LOG}   invocation IPs: unrestricted`];
+    }
+    return [
+        `${LOG}   invocation IPs:`,
+        ...ranges.map((range) => `${LOG}     ${range}`),
+    ];
+}
 async function getFunctionDetail(ctx, functionId) {
     try {
         return await getJson({
@@ -561,7 +572,9 @@ async function deployFromResolvedSource({ args, spec, ctx: earlyCtx, source, })
     preview.push(...buildEgressPreviewLines(LOG, [
         ...manifestEgressHosts(manifest.egress),
         ...manifestEgressIpRanges(manifest.egress),
-    ]));
+    ]), ...buildInvocationIpPreviewLines({
+        ranges: manifest.invocation.allowed_ip_ranges,
+    }));
     if (undeclaredEnvKeys.length > 0) {
         preview.push(`${LOG}   note: .env has ${undeclaredEnvKeys.join(', ')} — not declared in manifest, ignored`);
     }

package/dist/functions/manifest.d.ts

@@ -70,6 +70,9 @@ export declare const managedFunctionManifestSchema: z.ZodObject<{
         max_instances: z.ZodDefault<z.ZodNumber>;
         invoke_rate_per_minute: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    invocation: z.ZodDefault<z.ZodObject<{
+        allowed_ip_ranges: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
     secrets: z.ZodDefault<z.ZodArray<z.ZodString>>;
     egress: z.ZodDefault<z.ZodArray<z.ZodString>>;
     service_account: z.ZodOptional<z.ZodString>;

package/dist/functions/manifest.js

@@ -1,3 +1,4 @@
+import { isIP } from 'node:net';
 import { z } from 'zod';
 /**
  * CLI-side mirror of the server manifest schema at
@@ -515,6 +516,43 @@ const SERVICE_ACCOUNT_REF_RE = /^([a-z][a-z0-9-]{1,98}|[0-9a-fA-F]{8}-[0-9a-fA-F
  * atlas/src/server/services/managed-functions/manifest.ts.
  */
 const GRAPHQL_OPERATION_NAME_RE = /^[_A-Za-z][_0-9A-Za-z]*$/;
+/**
+ * Fast local validation for the declarative invocation policy. Atlas remains
+ * authoritative and canonicalizes network addresses during version upload;
+ * this mirror prevents a malformed bundle from reaching the network.
+ */
+const invocationIpRangeSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .superRefine((value, ctx) => {
+    const parts = value.split('/');
+    if (parts.length > 2) {
+        ctx.addIssue({ code: 'custom', message: `invalid IP address or CIDR range: ${value}` });
+        return;
+    }
+    const [address, prefixText] = parts;
+    const family = isIP(address ?? '');
+    if (family === 0) {
+        ctx.addIssue({ code: 'custom', message: `invalid IP address or CIDR range: ${value}` });
+        return;
+    }
+    if (prefixText === undefined)
+        return;
+    if (!/^\d+$/.test(prefixText)) {
+        ctx.addIssue({ code: 'custom', message: `invalid CIDR prefix: ${value}` });
+        return;
+    }
+    const prefix = Number(prefixText);
+    const maxPrefix = family === 4 ? 32 : 128;
+    if (prefix < 1 || prefix > maxPrefix) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `CIDR prefix must be between 1 and ${maxPrefix}: ${value}`,
+        });
+    }
+});
 export const managedFunctionManifestSchema = z.object({
     schema_version: z.literal(1).default(1),
     function: z.object({
@@ -552,6 +590,16 @@ export const managedFunctionManifestSchema = z.object({
         max_instances: 3,
         invoke_rate_per_minute: 60,
     }),
+    /**
+     * Source-IP gate applied by the Atlas invocation gateway before FGA.
+     * Empty or omitted means unrestricted. The policy is versioned with the
+     * bundle and becomes live atomically with that version.
+     */
+    invocation: z
+        .object({
+        allowed_ip_ranges: z.array(invocationIpRangeSchema).max(64).default([]),
+    })
+        .default({ allowed_ip_ranges: [] }),
     secrets: z
         .array(z.string().regex(SECRET_NAME_RE, 'secret names must be UPPER_SNAKE_CASE'))
         .max(32)

package/dist/login.js

@@ -5,7 +5,7 @@ import { spawn } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { deleteRealmTokens, realmForEnv, saveTokens, seqapiTokenPath, SEQUENCE_AUTH_REALM, SEQUENCE_REALM, verifyTokenMatchesRealm, } from './auth.js';
-import { manualEnvConfigHint } from './config.js';
+import { localAuthRealmOptions, manualEnvConfigHint } from './config.js';
 import { bootstrapUrl, clearCatalog, fetchCatalog } from './env-catalog.js';
 const DEFAULT_REDIRECT_PORT = 5099;
 const DEFAULT_LOGIN_TIMEOUT_MS = 300_000;
@@ -216,7 +216,7 @@ export async function refreshCatalogAfterLogin() {
     console.log(manualEnvConfigHint());
 }
 export async function login(envName) {
-    const realm = await realmForEnv(envName);
+    const realm = await realmForEnv(envName, await localAuthRealmOptions(envName));
     if (envName && realm.name === SEQUENCE_REALM && envName !== SEQUENCE_REALM) {
         // A name that only exists in the Sequence catalog (staging, banksouth…)
         // resolves to the Sequence realm — one login covers all of those. A typo'd
@@ -241,7 +241,7 @@ function legacyArtifactTokenPath() {
     return join(homedir(), '.config', 'sequence-artifact-studio', 'tokens.json');
 }
 export async function logout(envName) {
-    const realm = await realmForEnv(envName);
+    const realm = await realmForEnv(envName, await localAuthRealmOptions(envName));
     await deleteRealmTokens(realm.name);
     if (realm.name === SEQUENCE_REALM) {
         await rm(legacyArtifactTokenPath(), { force: true });

package/dist/pipeline/commands.js

@@ -38,13 +38,17 @@ const PIPELINE_USAGE = `usage:
       module (default export, authoring, or silverlakeAuthoring export name)
 
   seq-studio pipeline plan --repo pipelines/<slug> --ref <sha|branch> -e <env> [--target <id>] [--json]
+      enqueue a durable plan, poll progress, then print the completed
       materialize + SDK/graph + compile + live-diff + provision findings
       (no Databricks CLI / DAB validate on Atlas); exit 1 on destructive findings
 
   seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha|branch> -e <env>
-                            [--target <id>] [--approved-by <sub>] [--no-wait] [--json]
+                            [--target <id>] [--approved-by <sub>] [--run-now] [--no-wait] [--json]
       plan then enqueue Trigger deploy (DAB bundle validate hard-gates before
-      bundle deploy); use a full 40-hex SHA for explicit rollback deployments
+      bundle deploy). Default is plant-only: jobs/pipelines are created, not
+      run. Pass --run-now to run in-unit producer roots after bundle deploy
+      and wait before serving sync create. Use a full 40-hex SHA for explicit
+      rollback deployments
 
   seq-studio pipeline promote --stage <slug> --version <v> -e <env>
                               [--target <id>] [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]

package/dist/pipeline/lifecycle.js

@@ -9,6 +9,7 @@ const LOG = '[seq-studio]';
 const TERMINAL = new Set(['active', 'failed', 'retired']);
 const POLL_INTERVAL_MS = 2000;
 const HEARTBEAT_INTERVAL_MS = 20_000;
+const PLAN_TIMEOUT_MS = 30 * 60 * 1000;
 const FIRST_PARTY_TARGETS = [
     { id: 'dev', label: 'Development', requiresApproval: false },
     { id: 'staging', label: 'Staging', requiresApproval: false },
@@ -56,6 +57,9 @@ function flagString(flags, key) {
         throw new Error(`--${key} requires a value`);
     return value;
 }
+function flagOn(flags, key) {
+    return flags[key] === true || flags[key] === 'true';
+}
 export function deployEnvironmentForEnv(env) {
     return env.name === 'local' ? 'dev' : env.name;
 }
@@ -101,19 +105,17 @@ export async function pipelinePlanCommand(args) {
     }
     let response;
     try {
-        response = await postJson({
+        response = await enqueueAndWaitForPlan({
             baseUrl: env.url,
             token,
-            path: '/api/data-pipelines/pipelines/plan',
-            body: { repo, ref, environment: target.id },
+            repo,
+            ref,
+            environment: target.id,
         });
     }
     catch (error) {
-        if (error instanceof AtlasApiError) {
-            console.error(`${LOG} plan failed: ${error.message}`);
-            return 1;
-        }
-        throw error;
+        console.error(`${LOG} plan failed: ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
     }
     if (json) {
         console.log(JSON.stringify(response, null, 2));
@@ -129,6 +131,7 @@ export async function pipelineDeployCommand(args) {
     const ref = flagString(args.flags, 'ref');
     const deploymentId = flagString(args.flags, 'deployment-id');
     const approvedBy = flagString(args.flags, 'approved-by');
+    const runNow = flagOn(args.flags, 'run-now');
     const { env, token } = await envAndToken(args);
     let target;
     try {
@@ -144,27 +147,33 @@ export async function pipelineDeployCommand(args) {
             // Direct execute of a persisted plan.
             const stageId = flagString(args.flags, 'stage-id');
             if (!stageId) {
-                console.error('usage: seq-studio pipeline deploy --deployment-id <id> --stage-id <id> -e <env> [--target <id>] [--approved-by <sub>] [--no-wait]');
+                console.error('usage: seq-studio pipeline deploy --deployment-id <id> --stage-id <id> -e <env> [--target <id>] [--approved-by <sub>] [--run-now] [--no-wait]');
                 return 1;
             }
             enqueue = await postJson({
                 baseUrl: env.url,
                 token,
                 path: `/api/data-pipelines/stages/${stageId}/deploy`,
-                body: { deploymentId, environment: target.id, ...(approvedBy ? { approvedBy } : {}) },
+                body: {
+                    deploymentId,
+                    environment: target.id,
+                    ...(approvedBy ? { approvedBy } : {}),
+                    runNow,
+                },
             });
         }
         else {
             if (!repo || !ref) {
-                console.error('usage: seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha|branch> -e <env> [--target <id>] [--approved-by <sub>] [--no-wait]');
+                console.error('usage: seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha|branch> -e <env> [--target <id>] [--approved-by <sub>] [--run-now] [--no-wait]');
                 return 1;
             }
             // Plan then deploy the first planning deployment.
-            const plan = await postJson({
+            const plan = await enqueueAndWaitForPlan({
                 baseUrl: env.url,
                 token,
-                path: '/api/data-pipelines/pipelines/plan',
-                body: { repo, ref, environment: target.id },
+                repo,
+                ref,
+                environment: target.id,
             });
             if (plan.plan.hasDestructive) {
                 console.error(`${LOG} plan has destructive findings — refusing to deploy`);
@@ -190,6 +199,7 @@ export async function pipelineDeployCommand(args) {
                     deploymentId: firstId,
                     environment: target.id,
                     ...(approvedBy ? { approvedBy } : {}),
+                    runNow,
                 },
             });
         }
@@ -250,10 +260,20 @@ export async function pipelinePromoteCommand(args) {
         }
         throw error;
     }
-    console.log(`${LOG} enqueued promote ${enqueue.deploymentId}`);
+    console.log(`${LOG} enqueued promote plan ${enqueue.planRequestId} (trigger=${enqueue.triggerRunId ?? 'n/a'})`);
     if (args.flags['no-wait'] === true || args.flags['no-wait'] === 'true')
         return 0;
-    return pollDeployment({ baseUrl: env.url, token, deploymentId: enqueue.deploymentId });
+    const plan = await waitForPlanRequest({
+        baseUrl: env.url,
+        token,
+        planRequestId: enqueue.planRequestId,
+    });
+    const deploymentId = plan.deploymentIds[plan.stageIds.indexOf(stageId)] ?? plan.deploymentIds[0];
+    if (!deploymentId) {
+        console.error(`${LOG} promote plan completed without a deployment id`);
+        return 1;
+    }
+    return pollDeployment({ baseUrl: env.url, token, deploymentId });
 }
 export async function pipelineRunNowCommand(args) {
     const stage = flagString(args.flags, 'stage');
@@ -404,6 +424,63 @@ async function pollDeployment({ baseUrl, token, deploymentId, }) {
     console.error(`${LOG} timed out waiting for deployment ${deploymentId} (${formatElapsed(Date.now() - started)})`);
     return 1;
 }
+async function enqueueAndWaitForPlan({ baseUrl, token, repo, ref, environment, }) {
+    const enqueue = await postJson({
+        baseUrl,
+        token,
+        path: '/api/data-pipelines/pipelines/plan',
+        body: { repo, ref, environment },
+    });
+    console.log(`${LOG} enqueued plan ${enqueue.planRequestId} (trigger=${enqueue.triggerRunId ?? 'n/a'})`);
+    const detail = await waitForPlanRequest({
+        baseUrl,
+        token,
+        planRequestId: enqueue.planRequestId,
+    });
+    if (!detail.plan || !detail.text) {
+        throw new Error(`plan request ${detail.planRequestId} succeeded without a plan result`);
+    }
+    return {
+        plan: detail.plan,
+        deploymentIds: detail.deploymentIds,
+        stageIds: detail.stageIds,
+        text: detail.text,
+    };
+}
+async function waitForPlanRequest({ baseUrl, token, planRequestId, }) {
+    const started = Date.now();
+    let lastStatus = null;
+    let lastLoggedAt = started;
+    while (Date.now() - started < PLAN_TIMEOUT_MS) {
+        const detail = await getJson({
+            baseUrl,
+            token,
+            path: `/api/data-pipelines/plan-requests/${planRequestId}`,
+        });
+        const elapsed = Date.now() - started;
+        const statusLabel = detail.statusDetail
+            ? `${detail.status} — ${detail.statusDetail}`
+            : detail.status;
+        if (detail.status === 'failed') {
+            throw new Error(`plan request ${detail.planRequestId} failed after ${formatElapsed(elapsed)}: ` +
+                `${detail.statusDetail ?? 'unknown error'}`);
+        }
+        if (detail.status === 'succeeded')
+            return detail;
+        if (statusLabel !== lastStatus) {
+            console.log(`${LOG} plan ${detail.planRequestId}: ${statusLabel} (${formatElapsed(elapsed)})`);
+            lastStatus = statusLabel;
+            lastLoggedAt = Date.now();
+        }
+        else if (Date.now() - lastLoggedAt >= HEARTBEAT_INTERVAL_MS) {
+            console.log(`${LOG} plan ${detail.planRequestId}: still ${statusLabel} (${formatElapsed(elapsed)})`);
+            lastLoggedAt = Date.now();
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    throw new Error(`timed out waiting for plan request ${planRequestId} ` +
+        `(${formatElapsed(Date.now() - started)})`);
+}
 export async function pipelineAdoptCommand(args) {
     const stage = flagString(args.flags, 'stage');
     const ref = flagString(args.flags, 'ref');

package/dist/preview.d.ts

@@ -6,10 +6,11 @@
  * hand-editing `~/.config/lattice/config.toml`. See
  * `docs/preview-environments.md` for the full lifecycle.
  *
- * SLUG ALGORITHM — must stay byte-for-byte in sync with the three other
+ * SLUG ALGORITHM — must stay byte-for-byte in sync with the other
  * places that compute the same slug from a branch name:
- *   - `.github/workflows/preview-deploy.yml`  (`sed 's/[^a-zA-Z0-9-]/-/g' | tr '[:upper:]' '[:lower:]'`)
- *   - `atlas/src/server/db.ts:sanitize`        (`replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase()`)
+ *   - `.github/workflows/preview-deploy.yml`  (replace non-alnum, lowercase, trim hyphens)
+ *   - `.github/workflows/trigger-preview.yml` (same bash pipeline)
+ *   - `atlas/src/server/db.ts:sanitize`        (`.replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase().replace(/^-+|-+$/g, '')`)
  *   - `databricks/lakebase/atlas-db/pr-lifecycle.ts:sanitize`
  * Changing it here without changing those produces a host that does NOT
  * match what `preview-deploy.yml` actually deployed.

package/dist/preview.js

@@ -8,10 +8,11 @@ import { promisify } from 'node:util';
  * hand-editing `~/.config/lattice/config.toml`. See
  * `docs/preview-environments.md` for the full lifecycle.
  *
- * SLUG ALGORITHM — must stay byte-for-byte in sync with the three other
+ * SLUG ALGORITHM — must stay byte-for-byte in sync with the other
  * places that compute the same slug from a branch name:
- *   - `.github/workflows/preview-deploy.yml`  (`sed 's/[^a-zA-Z0-9-]/-/g' | tr '[:upper:]' '[:lower:]'`)
- *   - `atlas/src/server/db.ts:sanitize`        (`replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase()`)
+ *   - `.github/workflows/preview-deploy.yml`  (replace non-alnum, lowercase, trim hyphens)
+ *   - `.github/workflows/trigger-preview.yml` (same bash pipeline)
+ *   - `atlas/src/server/db.ts:sanitize`        (`.replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase().replace(/^-+|-+$/g, '')`)
  *   - `databricks/lakebase/atlas-db/pr-lifecycle.ts:sanitize`
  * Changing it here without changing those produces a host that does NOT
  * match what `preview-deploy.yml` actually deployed.
@@ -45,7 +46,7 @@ export const PREVIEW_PROTECTED_SLUGS = [
 export const MAX_LABEL_LENGTH = 63;
 /** Apply the canonical branch → slug transform. */
 export function previewSlug(branchOrSlug) {
-    return branchOrSlug.replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase();
+    return branchOrSlug.replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase().replace(/^-+|-+$/g, '');
 }
 /** The `studio-atlas-git-<slug>` DNS label Vercel assigns the preview. */
 export function previewLabel(slug) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sequenceholdings/studio-cli",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Unified Sequence Studio CLI — `seq-studio init` / `add` / `deploy` (app monorepos), `seq-studio agents`, `seq-studio process` (Lattice), `seq-studio artifact`, `seq-studio functions` / `secrets`, `seq-studio repos`, and `seq-studio auth pat`. Includes Auth0 browser login shared with seqapi.",
   "license": "UNLICENSED",
   "repository": {
@@ -36,13 +36,13 @@
     "README.md"
   ],
   "dependencies": {
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.1",
     "smol-toml": "^1.4.2",
     "tsx": "^4.20.3",
     "zod": "^4.1.13",
-    "@sequenceholdings/artifact-studio": "0.2.1",
-    "@sequenceholdings/lattice": "0.1.2",
-    "@sequenceholdings/agent-spec": "0.1.1"
+    "@sequenceholdings/agent-spec": "0.1.1",
+    "@sequenceholdings/artifact-studio": "0.2.2",
+    "@sequenceholdings/lattice": "0.1.2"
   },
   "peerDependencies": {
     "@sequenceholdings/orm": "0.1.3",
@@ -61,8 +61,8 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0",
     "vitest": "^4.1.5",
-    "@sequenceholdings/pipeline-spec": "0.1.0",
-    "@sequenceholdings/orm": "0.1.3"
+    "@sequenceholdings/orm": "0.1.3",
+    "@sequenceholdings/pipeline-spec": "0.1.0"
   },
   "engines": {
     "node": ">=20"