@sequenceholdings/studio-cli 0.1.13 → 0.1.21

package/dist/functions/commands.d.ts

@@ -1,7 +1,8 @@
+import { type AuthMode } from '../auth.js';
 import { type ResolvedEnv } from '../config.js';
 import type { ParsedArgs } from '../process/commands.js';
 import { type ManagedFunctionManifest } from './manifest.js';
-import { type SourceSpec } from '@sequenceholdings/artifact-studio/source-resolver';
+export { parseFunctionsSourceSelection, parseFunctionsSourceSpec, resolveFunctionSourceDir } from './source-selection.js';
 export declare const LOG = "[seq-studio]";
 export interface FunctionSummary {
     id: string;
@@ -32,9 +33,16 @@ export interface VersionSummary {
 }
 export declare function flagBool(flags: ParsedArgs['flags'], ...keys: string[]): boolean;
 export interface CommandContext {
+    authMode?: AuthMode;
     env: ResolvedEnv;
     token: string;
 }
+export declare function requestedEnvironment(args: ParsedArgs): string | undefined;
+/**
+ * Resolve env + token for Atlas network commands. Requires an explicit
+ * `-e/--env` so partners never hit the built-in `local` default and get an
+ * opaque `fetch failed` (same contract as `functions deploy`).
+ */
 export declare function buildContext(args: ParsedArgs): Promise<CommandContext>;
 export declare function clientOptions(ctx: CommandContext): {
     baseUrl: string;
@@ -42,14 +50,6 @@ export declare function clientOptions(ctx: CommandContext): {
 };
 export declare function readManifestOptional(dir: string): Promise<ManagedFunctionManifest | null>;
 export declare function workDir(args: ParsedArgs): string;
-/**
- * Source selection for build/deploy: --dir (local, default '.'), a platform
- * git-service repo (--repo <ns>/<name>), or any git URL (--git-url <url>);
- * --ref picks a branch/tag/commit. Reuses the artifact-studio resolver —
- * functions name their local dir with --dir rather than a positional, so map
- * it onto the spec parser's positional slot.
- */
-export declare function parseFunctionsSourceSpec(args: ParsedArgs): SourceSpec;
 export declare function resolveOrRegisterFunction({ ctx, slug, title, description, }: {
     ctx: CommandContext;
     slug: string;
@@ -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 <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 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 -e <env> [--yes]        archive function + tear down GCP resources\n                                                      (version history is retained)\n\n  Flags: -e/--env <env|preview:<slug>> (required for network commands; see: seq-studio envs list) \u00B7 --fn <slug> \u00B7 --dir <path>\n         --path <repo-subdirectory>  (remote build/deploy only) select one function in a multi-function repo\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 a public HTTPS git URL (--git-url <url>). --path selects\n  a function directory within a remote repo; omit it for the existing root-manifest\n  layout. --ref selects a branch/tag/commit (default: the repo's default branch).\n  Remote sources record the pinned commit as provenance (never dirty) and NEVER\n  read a repo-committed .env for secret values \u2014 provision secrets server-side\n  or pass a local --from-env-file (resolved against your cwd).\n\n  Interactive --repo builds clone over smart-HTTP and require a repo:read git\n  PAT in ATLAS_GIT_PAT (`seq-studio auth pat create --scopes repo:read`, or\n  Atlas \u2192 Settings \u2192 Tokens). Headless M2M builds use JSON materialize and\n  accept only platform-managed --repo sources. Interactive builds also need\n  --env + seq-studio login to resolve the repo and deploy.\n";
 export declare function runFunctionsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;

package/dist/functions/commands.js

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

package/dist/functions/manifest.d.ts

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

package/dist/functions/manifest.js

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

package/dist/functions/source-selection.d.ts

@@ -0,0 +1,24 @@
+import { type SourceSpec } from '@sequenceholdings/artifact-studio/source-resolver';
+import type { ParsedArgs } from '../process/commands.js';
+export interface FunctionsSourceSelection {
+    spec: SourceSpec;
+    path?: string;
+}
+/**
+ * Functions name their local source with --dir rather than a positional, so
+ * map it onto the shared source parser used by other seq-studio primitives.
+ */
+export declare function parseFunctionsSourceSpec(args: ParsedArgs): SourceSpec;
+/**
+ * Select a managed function within a remote repository. Local callers already
+ * select the function root with --dir, so --path is remote-only.
+ */
+export declare function parseFunctionsSourceSelection(args: ParsedArgs): FunctionsSourceSelection;
+/**
+ * Resolve the selected function root after the repository is materialized.
+ * realpath containment prevents a committed symlink from escaping the repo.
+ */
+export declare function resolveFunctionSourceDir({ repoDir, path, }: {
+    repoDir: string;
+    path?: string;
+}): Promise<string>;

package/dist/functions/source-selection.js

@@ -0,0 +1,67 @@
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { parseSourceSpec, } from '@sequenceholdings/artifact-studio/source-resolver';
+import { isDirectory } from './bundle.js';
+/**
+ * Functions name their local source with --dir rather than a positional, so
+ * map it onto the shared source parser used by other seq-studio primitives.
+ */
+export function parseFunctionsSourceSpec(args) {
+    const dir = typeof args.flags.dir === 'string' ? args.flags.dir : undefined;
+    if (dir !== undefined && (args.flags.repo !== undefined || args.flags['git-url'] !== undefined)) {
+        throw new Error('--dir cannot be combined with --repo / --git-url.');
+    }
+    return parseSourceSpec({ positional: dir === undefined ? [] : [dir], flags: args.flags });
+}
+function validateFunctionRepoPath(path) {
+    const segments = path.split('/');
+    if (path.length === 0 ||
+        path.trim() !== path ||
+        isAbsolute(path) ||
+        path.includes('\\') ||
+        [...path].some((character) => character.charCodeAt(0) < 0x20) ||
+        segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw new Error(`--path must be a canonical relative directory within the repository (got ${JSON.stringify(path)}).`);
+    }
+}
+/**
+ * Select a managed function within a remote repository. Local callers already
+ * select the function root with --dir, so --path is remote-only.
+ */
+export function parseFunctionsSourceSelection(args) {
+    const spec = parseFunctionsSourceSpec(args);
+    const pathFlag = args.flags.path;
+    if (pathFlag === true)
+        throw new Error('--path requires a value.');
+    if (pathFlag === undefined)
+        return { spec };
+    if (spec.kind === 'local') {
+        throw new Error('--path only applies together with --repo or --git-url; use --dir for local source.');
+    }
+    validateFunctionRepoPath(pathFlag);
+    return { spec, path: pathFlag };
+}
+/**
+ * Resolve the selected function root after the repository is materialized.
+ * realpath containment prevents a committed symlink from escaping the repo.
+ */
+export async function resolveFunctionSourceDir({ repoDir, path, }) {
+    if (path === undefined)
+        return repoDir;
+    validateFunctionRepoPath(path);
+    const candidate = resolve(repoDir, path);
+    if (!(await isDirectory(candidate))) {
+        throw new Error(`--path does not name a directory in the repository: ${path}`);
+    }
+    const [canonicalRepoDir, canonicalCandidate] = await Promise.all([
+        realpath(repoDir),
+        realpath(candidate),
+    ]);
+    const relativePath = relative(canonicalRepoDir, canonicalCandidate);
+    if (relativePath === '..' ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)) {
+        throw new Error(`--path must stay within the repository: ${path}`);
+    }
+    return canonicalCandidate;
+}

package/dist/login.d.ts

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

package/dist/login.js

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

package/dist/main.d.ts

@@ -5,10 +5,12 @@
  *   seq-studio process <sub>      manage Lattice processes
  *   seq-studio artifact <sub>     manage Artifact Studio apps
  *   seq-studio functions <sub>    manage Managed Functions
+ *   seq-studio agents <sub>       manage typed agent definitions
  *   seq-studio secrets <sub>      manage org-owned Managed Secrets
  *   seq-studio repos <sub>        manage platform git-service repos
+ *   seq-studio pipeline <sub>     author + validate Data Pipelines stage specs
  *   seq-studio auth <sub>         manage git-service PATs
- *   seq-studio envs <sub>         list/refresh discovered environments
+ *   seq-studio envs <sub>         add/list/refresh environments
  *   seq-studio login              authenticate interactively with Auth0
  *   seq-studio logout             remove cached user tokens
  *   seq-studio doctor             check token + env + writer gate