@sequenceholdings/studio-cli 0.1.12 → 0.1.18

package/dist/process/lint.js

@@ -10,6 +10,7 @@
  *     but on_timeout_edge_id is unset, warn
  */
 import { readFileSync } from 'node:fs';
+import { forEachSerializedNode, } from '@sequenceholdings/lattice/bundle';
 import { parallelSubNodes, validateEmailReminders } from '@sequenceholdings/lattice/define';
 export async function lintProcesses(input) {
     const errors = [];
@@ -67,7 +68,7 @@ export async function lintProcesses(input) {
             }
         }
         for (const node of p.nodes) {
-            await lintNodeContract(p.id, node, errors, warnings, input.loadAgentSchemaEdgeIdEnum);
+            await lintNodeContract(p.id, node, errors, warnings, input.loadAgentSchemaEdgeIdEnum, input.suppressUnavailableAgentWarnings ?? false);
         }
         // Closure-scope check: mappers / fn / join / fan_out / output are
         // serialized via `.toString()` and run in a vm with NOTHING from the
@@ -213,10 +214,10 @@ function lintSandboxClosures(processId, node, importedNames, warnings) {
  * edge_id-contract checks as a top-level node) and lints the `join` reducer's
  * own edge_id returns against the parallel node's outgoing_edges.
  */
-async function lintNodeContract(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum) {
+async function lintNodeContract(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings) {
     switch (node.kind) {
         case 'agent':
-            await lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum);
+            await lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings);
             break;
         case 'human':
             lintHuman(processId, node, errors, warnings);
@@ -225,7 +226,7 @@ async function lintNodeContract(processId, node, errors, warnings, loadAgentSche
             const parallel = node;
             lintParallelJoin(processId, parallel, errors, warnings);
             for (const { node: sub } of parallelSubNodes(parallel)) {
-                await lintNodeContract(processId, sub, errors, warnings, loadAgentSchemaEdgeIdEnum);
+                await lintNodeContract(processId, sub, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings);
             }
             break;
         }
@@ -335,28 +336,74 @@ function lintSubprocessOutput(processId, node, errors, warnings) {
     }
 }
 const EDGE_ID_LITERAL_RE = /\bedge_id\s*:\s*['"`]([^'"`]+)['"`]/g;
-async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum) {
-    const allEdgeIds = node.outgoing_edges.map((e) => e.id);
-    // The reset edge (taken out-of-band by the reset intervention, never chosen
-    // by the agent) must exist on the node but is excluded from the agent's
-    // edge_id contract — same way a human node's on_timeout_edge_id is an
-    // orchestration-only edge. Validate membership, then verify the agent's
-    // edge_id enum against the REAL (non-reset) edges only.
-    if (node.on_reset_edge_id) {
-        if (!allEdgeIds.includes(node.on_reset_edge_id)) {
-            errors.push({
-                process_id: processId,
-                node_id: node.id,
-                message: `on_reset_edge_id "${node.on_reset_edge_id}" is not in outgoing_edges`,
-            });
-        }
+export async function lintSerializedAgentContracts({ bundle, loadAgentSchemaEdgeIdEnum, includeStaticValidation = true, }) {
+    const errors = [];
+    const warnings = [];
+    const pending = [];
+    for (const process of bundle.processes) {
+        forEachSerializedNode(process.nodes, (node) => {
+            const contract = serializedAgentContract(node);
+            if (!contract)
+                return;
+            pending.push(lintAgentContract({
+                processId: process.id,
+                nodeId: node.id,
+                ...contract,
+                errors,
+                warnings,
+                loadAgentSchemaEdgeIdEnum,
+                suppressUnavailableAgentWarnings: false,
+                includeStaticValidation,
+            }));
+        });
     }
-    const outgoingIds = allEdgeIds.filter((id) => id !== node.on_reset_edge_id);
+    await Promise.all(pending);
+    return { errors, warnings };
+}
+function serializedAgentContract(node) {
+    if (node.kind !== 'agent' || !isUnknownRecord(node.metadata))
+        return null;
+    const agentId = node.metadata.agent_id;
+    if (typeof agentId !== 'string')
+        return null;
+    const onResetEdgeId = node.metadata.on_reset_edge_id;
+    return {
+        agentId,
+        allEdgeIds: node.outgoing_edges.map((edge) => edge.id),
+        ...(typeof onResetEdgeId === 'string' ? { onResetEdgeId } : {}),
+    };
+}
+function isUnknownRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings) {
+    await lintAgentContract({
+        processId,
+        nodeId: node.id,
+        agentId: node.agent.id,
+        allEdgeIds: node.outgoing_edges.map((edge) => edge.id),
+        onResetEdgeId: node.on_reset_edge_id,
+        errors,
+        warnings,
+        loadAgentSchemaEdgeIdEnum,
+        suppressUnavailableAgentWarnings,
+        includeStaticValidation: true,
+    });
+}
+async function lintAgentContract({ processId, nodeId, agentId, allEdgeIds, onResetEdgeId, errors, warnings, loadAgentSchemaEdgeIdEnum, suppressUnavailableAgentWarnings, includeStaticValidation, }) {
+    if (includeStaticValidation && onResetEdgeId && !allEdgeIds.includes(onResetEdgeId)) {
+        errors.push({
+            process_id: processId,
+            node_id: nodeId,
+            message: `on_reset_edge_id "${onResetEdgeId}" is not in outgoing_edges`,
+        });
+    }
+    const outgoingIds = allEdgeIds.filter((id) => id !== onResetEdgeId);
     if (!loadAgentSchemaEdgeIdEnum) {
-        if (outgoingIds.length > 1) {
+        if (outgoingIds.length > 1 && !suppressUnavailableAgentWarnings) {
             warnings.push({
                 process_id: processId,
-                node_id: node.id,
+                node_id: nodeId,
                 message: `agent node has ${outgoingIds.length} outgoing edges; agent output schema vs outgoing_edges contract not verified (no agent registry loader available)`,
             });
         }
@@ -364,21 +411,21 @@ async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeI
     }
     let enumValues;
     try {
-        enumValues = await loadAgentSchemaEdgeIdEnum(node.agent.id);
+        enumValues = await loadAgentSchemaEdgeIdEnum(agentId);
     }
     catch (err) {
         warnings.push({
             process_id: processId,
-            node_id: node.id,
-            message: `could not load agent definition "${node.agent.id}" to verify output contract: ${err instanceof Error ? err.message : String(err)} (run with DB access to enable full check)`,
+            node_id: nodeId,
+            message: `could not load agent definition "${agentId}" to verify output contract: ${err instanceof Error ? err.message : String(err)} (run with DB access to enable full check)`,
         });
         return;
     }
     if (enumValues === 'not-found') {
         errors.push({
             process_id: processId,
-            node_id: node.id,
-            message: `agent "${node.agent.id}" not found in the target env — sync/seed the agent registry before applying`,
+            node_id: nodeId,
+            message: `agent "${agentId}" not found in the target env — sync/seed the agent registry before applying`,
         });
         return;
     }
@@ -397,22 +444,71 @@ async function lintAgent(processId, node, errors, warnings, loadAgentSchemaEdgeI
     if (missing.length > 0 || extra.length > 0) {
         errors.push({
             process_id: processId,
-            node_id: node.id,
-            message: `agent "${node.agent.id}" edge_id enum mismatch — missing: [${missing.join(', ')}], extra: [${extra.join(', ')}]; expected exactly: [${outgoingIds.join(', ')}]`,
+            node_id: nodeId,
+            message: `agent "${agentId}" edge_id enum mismatch — missing: [${missing.join(', ')}], extra: [${extra.join(', ')}]; expected exactly: [${outgoingIds.join(', ')}]`,
         });
     }
 }
+/**
+ * Matches an undecided-sentinel return in a serialized join source: the
+ * literal `{ undecided: true }` (the correct authored form — reducers run in
+ * a vm with no module imports in scope) or a `JOIN_UNDECIDED` reference
+ * (recognized so the eager no-sentinel warning doesn't double-fire on top of
+ * the closure-scope warning that already flags the out-of-scope import).
+ */
+const UNDECIDED_SENTINEL_RE = /\bundecided\s*:\s*true\b|\bJOIN_UNDECIDED\b/;
 /**
  * Lint a parallel node's `join` reducer the way we lint automation fns:
  * scan the serialized source for literal `edge_id: '…'` returns and confirm
  * each is in the parallel node's own outgoing_edges. The reducer chooses the
  * parallel node's exit edge, so a typo there is a routing bug the orchestrator
  * would only surface at run time.
+ *
+ * join_mode checks: a BARRIER join returning the `{undecided: true}` sentinel
+ * is an authoring error (the runner fails the block at runtime), and an EAGER
+ * join that never returns the sentinel decides on the first settlement —
+ * legal but suspicious, so it warns. No static engine check is possible for
+ * eager blocks: the execution engine is chosen per RUN (`{"engine": ...}` +
+ * environment rollout policy), not per process — the Trigger-only limitation
+ * is enforced at runtime (an eager block on a Temporal run fails with a clear
+ * unsupported error at branch resolution).
  */
 function lintParallelJoin(processId, node, errors, warnings) {
     const join = node.join;
     const source = typeof join === 'function' ? join.toString() : '';
     const outgoingIds = new Set(node.outgoing_edges.map((e) => e.id));
+    const joinMode = node.join_mode ?? 'barrier';
+    const returnsUndecided = UNDECIDED_SENTINEL_RE.test(source);
+    if (joinMode === 'eager') {
+        if (typeof join !== 'function') {
+            // defineParallelNode already rejects this; belt-and-suspenders for
+            // hand-built definitions that bypassed the SDK constructor.
+            errors.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `join_mode 'eager' requires an explicit join reducer`,
+            });
+        }
+        if (!returnsUndecided) {
+            warnings.push({
+                process_id: processId,
+                node_id: node.id,
+                message: `join_mode is 'eager' but the join source never returns the ` +
+                    `{undecided: true} sentinel — the block will decide on the FIRST ` +
+                    `branch settlement; confirm that is intended`,
+            });
+        }
+    }
+    else if (returnsUndecided) {
+        errors.push({
+            process_id: processId,
+            node_id: node.id,
+            message: `parallel join returns the {undecided: true} sentinel but join_mode ` +
+                `is 'barrier' (the default) — the sentinel is only meaningful with ` +
+                `join_mode: 'eager'; at runtime the block FAILS when a barrier join ` +
+                `returns it`,
+        });
+    }
     const literals = new Set();
     for (const match of source.matchAll(EDGE_ID_LITERAL_RE)) {
         if (match[1])

package/dist/process/repo-install.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Remote-install helper for `process apply --repo`. Installs dependencies
+ * in a materialized process repo so `tsx` can import `process.ts` modules.
+ *
+ * Re-uses the artifact-studio trusted-install pipeline:
+ *   1. Require `package.json` and `pnpm-lock.yaml` (no floating installs)
+ *   2. Strip install-control files (.npmrc, pnpm-workspace.yaml, pnpm hooks)
+ *   3. Full trust validation: registry-only specs, no patches, no symlinks,
+ *      Chainguard lockfile with repo/commit/directory/tarball checks
+ *   4. Run pinned pnpm with frozen lockfile, ignore-scripts, prod-only
+ */
+/**
+ * Install dependencies in a materialized remote process repo. Process repos
+ * deployed from git-service must carry a `package.json` (process.ts files
+ * import `@sequenceholdings/lattice/define` and the module won't resolve
+ * without node_modules) and a Chainguard-resolved `pnpm-lock.yaml`.
+ *
+ * Throws when either file is missing or when the tree fails the full
+ * trusted-install validation.
+ */
+export declare function prepareProcessBuildRoot(dir: string): Promise<void>;

package/dist/process/repo-install.js

@@ -0,0 +1,99 @@
+/**
+ * Remote-install helper for `process apply --repo`. Installs dependencies
+ * in a materialized process repo so `tsx` can import `process.ts` modules.
+ *
+ * Re-uses the artifact-studio trusted-install pipeline:
+ *   1. Require `package.json` and `pnpm-lock.yaml` (no floating installs)
+ *   2. Strip install-control files (.npmrc, pnpm-workspace.yaml, pnpm hooks)
+ *   3. Full trust validation: registry-only specs, no patches, no symlinks,
+ *      Chainguard lockfile with repo/commit/directory/tarball checks
+ *   4. Run pinned pnpm with frozen lockfile, ignore-scripts, prod-only
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createScrubbedChildEnv } from '@sequenceholdings/artifact-studio/child-environment';
+import { ARTIFACT_BUILD_PNPM, buildControlledArtifactNpmrc, } from '@sequenceholdings/artifact-studio/prepare-build';
+import { stripInstallControlFiles } from '@sequenceholdings/artifact-studio/sanitize-remote-tree';
+import { ArtifactInstallTrustError, assertTrustedArtifactInstallTree, } from '@sequenceholdings/artifact-studio/trusted-install';
+class ProcessInstallError extends Error {
+    name = 'ProcessInstallError';
+}
+/**
+ * Install dependencies in a materialized remote process repo. Process repos
+ * deployed from git-service must carry a `package.json` (process.ts files
+ * import `@sequenceholdings/lattice/define` and the module won't resolve
+ * without node_modules) and a Chainguard-resolved `pnpm-lock.yaml`.
+ *
+ * Throws when either file is missing or when the tree fails the full
+ * trusted-install validation.
+ */
+export async function prepareProcessBuildRoot(dir) {
+    if (!existsSync(join(dir, 'package.json'))) {
+        throw new ProcessInstallError('Remote process repos must include a package.json with @sequenceholdings/lattice as a dependency.');
+    }
+    if (!existsSync(join(dir, 'pnpm-lock.yaml'))) {
+        throw new ProcessInstallError('Remote process deploy requires pnpm-lock.yaml — run `pnpm install` locally and commit the lockfile.');
+    }
+    const stripped = stripInstallControlFiles(dir);
+    if (stripped.length > 0) {
+        console.warn(`[seq-studio] stripped install-control files from remote tree: ${stripped.join(', ')}`);
+    }
+    try {
+        assertTrustedArtifactInstallTree(dir);
+    }
+    catch (error) {
+        if (error instanceof ArtifactInstallTrustError) {
+            throw new ProcessInstallError(`Remote process repo is not trusted for install: ${error.message}`);
+        }
+        throw error;
+    }
+    await rm(join(dir, 'node_modules'), { recursive: true, force: true });
+    const configDir = await mkdtemp(join(tmpdir(), 'process-pnpm-'));
+    const controlledNpmrc = join(configDir, '.npmrc');
+    const homeDir = join(configDir, 'home');
+    // Keep package-manager writes scoped to this install. A persistent cache
+    // would be writable by the untrusted source install and could poison later
+    // process builds that run under the same uid.
+    const npmCache = join(configDir, 'npm-cache');
+    const pnpmStore = join(configDir, 'pnpm-store');
+    const userNpmrcPath = process.env.npm_config_userconfig ?? join(homedir(), '.npmrc');
+    console.log(`[seq-studio] installing process dependencies (frozen lockfile, prod only) via ${ARTIFACT_BUILD_PNPM}…`);
+    try {
+        await mkdir(homeDir, { recursive: true });
+        await writeFile(controlledNpmrc, buildControlledArtifactNpmrc(userNpmrcPath), { mode: 0o600 });
+        const spawnOpts = {
+            cwd: configDir,
+            stdio: 'inherit',
+            env: createScrubbedChildEnv({
+                homeDir,
+                additionalEnv: {
+                    npm_config_userconfig: controlledNpmrc,
+                    npm_config_cache: npmCache,
+                },
+            }),
+        };
+        execFileSync('npx', [
+            '--yes',
+            ARTIFACT_BUILD_PNPM,
+            '--dir',
+            dir,
+            'install',
+            '--frozen-lockfile',
+            '--ignore-scripts',
+            '--prod',
+            '--store-dir',
+            pnpmStore,
+        ], spawnOpts);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new ProcessInstallError(`process dependency install failed (${ARTIFACT_BUILD_PNPM}). ` +
+            `Run \`pnpm install\` locally and commit pnpm-lock.yaml. (${detail})`);
+    }
+    finally {
+        await rm(configDir, { recursive: true, force: true });
+    }
+}

package/dist/process/simulate.js

@@ -10,7 +10,7 @@
  *   - Stubs automation runner identically — native handlers live in the
  *     Atlas image and can't execute here
  */
-import { DEFAULT_MAX_FANOUT_WIDTH, } from '@sequenceholdings/lattice/define';
+import { DEFAULT_MAX_FANOUT_WIDTH, isJoinUndecided, } from '@sequenceholdings/lattice/define';
 import { extractOutputState, mergeRunState } from '@sequenceholdings/lattice';
 const DEFAULT_MAX_ITERATIONS = 1000;
 const DEFAULT_MAX_REVISITS = 100;
@@ -246,7 +246,20 @@ async function simulateParallel(args, node) {
             item: br.item,
         });
     }
+    // The simulator settles every branch before joining, so an EAGER join sees
+    // the all-settled case (its incremental undecided passes aren't modelled —
+    // simulate verifies topology/routing, not settlement timing). In that case
+    // the eager contract requires a decision; surface a sentinel return as the
+    // same clear error the runtime raises instead of a confusing edge failure.
     const joinOutput = node.join(results, args.ctx);
+    if (isJoinUndecided(joinOutput)) {
+        throw new Error(node.join_mode === 'eager'
+            ? `parallel node "${node.id}": eager join returned {undecided: true} with ` +
+                `every branch settled — an eager join must decide once nothing is pending`
+            : `parallel node "${node.id}": join returned the {undecided: true} sentinel ` +
+                `but join_mode is 'barrier' — the sentinel is only meaningful with ` +
+                `join_mode: 'eager'`);
+    }
     return foldBranchState(joinOutput, results);
 }
 /**

package/dist/repos/commands.d.ts

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

package/dist/repos/commands.js

@@ -25,6 +25,7 @@ import { resolveGitPatFromEnv, runGitClone, } from './git-clone.js';
 import { formatPatSetupHint } from '../pat-hints.js';
 import { tryGetAccessToken } from '../auth.js';
 import { resolveEnvWithDiscovery } from '../config.js';
+import { REQUIRE_EXPLICIT_ENV_MESSAGE } from '../env-flags.js';
 const PAGE_SIZE = 200;
 // ---------------------------------------------------------------------------
 // Helpers
@@ -158,7 +159,7 @@ export async function reposNamespacesCommand(args) {
     const ctx = await reposContext(args);
     if (action === 'create') {
         if (!slug) {
-            console.error('usage: seq-studio repos namespaces create <slug> [-e env]');
+            console.error('usage: seq-studio repos namespaces create <slug> -e <env>');
             return 1;
         }
         const created = await postJson({
@@ -358,7 +359,7 @@ export async function reposCloneCommand(args, deps = {}) {
     // <ns>/<name> path — needs Auth0 for resolveRepo (JSON API) whether or not
     // we then use smart-HTTP. Without Auth0, point users at --url from the UI.
     if (!positional) {
-        console.error('usage: seq-studio repos clone <ns>/<name> | --url <clone-url> | --id <uuid> [-e env] [--ref r] [--out dir]');
+        console.error('usage: seq-studio repos clone <ns>/<name> | --url <clone-url> | --id <uuid> -e <env> [--ref r] [--out dir]');
         return 1;
     }
     const { namespace, name } = parseRepoPath(positional);
@@ -418,6 +419,10 @@ async function resolveEnvOnly(args) {
     }
     const requested = (typeof args.flags.env === 'string' ? args.flags.env : undefined) ??
         (typeof args.flags.e === 'string' ? args.flags.e : undefined);
+    // Same contract as buildContext: never silently fall back to `local`.
+    if (!requested) {
+        throw new Error(REQUIRE_EXPLICIT_ENV_MESSAGE);
+    }
     return resolveEnvWithDiscovery({ requested });
 }
 /**
@@ -488,20 +493,20 @@ export async function reposDeleteCommand(args) {
 // Router
 // ---------------------------------------------------------------------------
 export const REPOS_USAGE = `usage:
-  seq-studio repos list [-e env] [--namespace <slug>] [--mine]      repos visible on the environment
-  seq-studio repos namespaces [create <slug>] [-e env]              list or create namespaces
-  seq-studio repos show <ns>/<name> [-e env]                        repo detail (branches, clone URL)
-  seq-studio repos create <ns>/<name> [-e env] [--default-branch b] create an empty repo
-  seq-studio repos clone <ns>/<name> [-e env] [--ref r] [--out dir] [--force]
-  seq-studio repos clone --url <https://…/repos/<id>/git> [-e env] [--ref r] [--out dir]
-  seq-studio repos clone --id <uuid> [-e env] [--ref r] [--out dir]
+  seq-studio repos list -e <env> [--namespace <slug>] [--mine]      repos visible on the environment
+  seq-studio repos namespaces [create <slug>] -e <env>              list or create namespaces
+  seq-studio repos show <ns>/<name> -e <env>                        repo detail (branches, clone URL)
+  seq-studio repos create <ns>/<name> -e <env> [--default-branch b] create an empty repo
+  seq-studio repos clone <ns>/<name> -e <env> [--ref r] [--out dir] [--force]
+  seq-studio repos clone --url <https://…/repos/<id>/git> -e <env> [--ref r] [--out dir]
+  seq-studio repos clone --id <uuid> -e <env> [--ref r] [--out dir]
                                                                     smart-HTTP when ATLAS_GIT_PAT is set;
                                                                     otherwise JSON materialize (<ns>/<name>)
-  seq-studio repos pull <ns>/<name> [-e env] [--ref r] [--out dir] [--force]
+  seq-studio repos pull <ns>/<name> -e <env> [--ref r] [--out dir] [--force]
                                                                     materialize the tree at a ref (JSON API)
-  seq-studio repos delete <ns>/<name> [-e env] [--yes]              delete a repo (confirm prompt)
+  seq-studio repos delete <ns>/<name> -e <env> [--yes]              delete a repo (confirm prompt)
 
-  Flags: -e/--env <env>  (see: seq-studio envs list)
+  Flags: -e/--env <env> (required; see: seq-studio envs list)
 
   clone prefers real git clone (PAT via askpass — never written into the remote
   URL). Without ATLAS_GIT_PAT, <ns>/<name> falls back to the JSON API and prints

package/dist/secrets/commands.d.ts

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

package/dist/secrets/commands.js

@@ -128,7 +128,7 @@ async function functionExistsBySlugEventually({ ctx, slug, attempts = 3, retryDe
 export async function secretsCreateCommand(args) {
     const name = args.positional[0];
     if (!name) {
-        console.error('usage: seq-studio secrets create <NAME> [-e env] [--description text]');
+        console.error('usage: seq-studio secrets create <NAME> -e <env> [--description text]');
         return 1;
     }
     const ctx = await buildContext(args);
@@ -150,7 +150,7 @@ export async function secretsCreateCommand(args) {
 export async function secretsSetCommand(args) {
     const name = args.positional[0];
     if (!name) {
-        console.error('usage: seq-studio secrets set <NAME> [-e env]');
+        console.error('usage: seq-studio secrets set <NAME> -e <env>');
         return 1;
     }
     const ctx = await buildContext(args);
@@ -194,7 +194,7 @@ export async function secretsAttachCommand(args) {
     const name = args.positional[0];
     const fnSlug = typeof args.flags.fn === 'string' ? args.flags.fn : args.positional[1];
     if (!name || !fnSlug) {
-        console.error('usage: seq-studio secrets attach <NAME> --fn <slug> [--env-var NAME]');
+        console.error('usage: seq-studio secrets attach <NAME> --fn <slug> -e <env> [--env-var NAME]');
         return 1;
     }
     const ctx = await buildContext(args);
@@ -229,7 +229,7 @@ export async function secretsDetachCommand(args) {
     const name = args.positional[0];
     const fnSlug = typeof args.flags.fn === 'string' ? args.flags.fn : args.positional[1];
     if (!name || !fnSlug) {
-        console.error('usage: seq-studio secrets detach <NAME> --fn <slug>');
+        console.error('usage: seq-studio secrets detach <NAME> --fn <slug> -e <env>');
         return 1;
     }
     const ctx = await buildContext(args);
@@ -284,7 +284,7 @@ function resolveApplyKeys({ parsed, manifest, explicitKeys, applyAll, }) {
 export async function secretsApplyCommand(args) {
     const fromEnvFile = args.flags['from-env-file'];
     if (typeof fromEnvFile !== 'string') {
-        console.error('usage: seq-studio secrets apply --from-env-file .env [-e env] [--yes]');
+        console.error('usage: seq-studio secrets apply --from-env-file .env -e <env> [--yes]');
         return 1;
     }
     const dir = workDir(args);
@@ -464,7 +464,7 @@ async function attachedFunctionSlugs(ctx, secretId) {
 export async function secretsVersionsCommand(args) {
     const name = args.positional[0];
     if (!name) {
-        console.error('usage: seq-studio secrets versions <NAME> [-e env]');
+        console.error('usage: seq-studio secrets versions <NAME> -e <env>');
         return 1;
     }
     const ctx = await buildContext(args);
@@ -492,7 +492,7 @@ export async function secretsVersionsCommand(args) {
 export async function secretsSetDefaultCommand(args) {
     const name = args.positional[0];
     if (!name) {
-        console.error('usage: seq-studio secrets set-default <NAME> [version] [-e env] [--yes]');
+        console.error('usage: seq-studio secrets set-default <NAME> [version] -e <env> [--yes]');
         return 1;
     }
     const ctx = await buildContext(args);
@@ -558,7 +558,7 @@ export async function secretsPinCommand(args) {
     const name = args.positional[0];
     const fnSlug = typeof args.flags.fn === 'string' ? args.flags.fn : undefined;
     if (!name || !fnSlug) {
-        console.error('usage: seq-studio secrets pin <NAME> --fn <slug> [version] [--unpin] [-e env] [--yes] [--no-redeploy]');
+        console.error('usage: seq-studio secrets pin <NAME> --fn <slug> [version] [--unpin] -e <env> [--yes] [--no-redeploy]');
         return 1;
     }
     const ctx = await buildContext(args);
@@ -643,22 +643,22 @@ export async function secretsPinCommand(args) {
 // dispatcher
 // ---------------------------------------------------------------------------
 export const SECRETS_USAGE = `usage:
-  seq-studio secrets create <NAME> [--description text]   register an org-owned secret
-  seq-studio secrets set <NAME>                             set the shared default value (write-only)
-  seq-studio secrets list [-e env]                          secrets you can see (never values)
-  seq-studio secrets attach <NAME> --fn <slug>              mount default on a function env var
-  seq-studio secrets detach <NAME> --fn <slug>              remove attachment
-  seq-studio secrets apply --from-env-file .env [-e env]    push defaults + attach (keys default from manifest)
-  seq-studio secrets versions <NAME>                        value version history (never values)
-  seq-studio secrets set-default <NAME> [version]           point the default at a prior version (editor)
-  seq-studio secrets pin <NAME> --fn <slug> [version]       pin one function to a version (sticky; --unpin clears)
+  seq-studio secrets create <NAME> -e <env> [--description text]   register an org-owned secret
+  seq-studio secrets set <NAME> -e <env>                             set the shared default value (write-only)
+  seq-studio secrets list -e <env>                                   secrets you can see (never values)
+  seq-studio secrets attach <NAME> --fn <slug> -e <env>              mount default on a function env var
+  seq-studio secrets detach <NAME> --fn <slug> -e <env>              remove attachment
+  seq-studio secrets apply --from-env-file .env -e <env>             push defaults + attach (keys default from manifest)
+  seq-studio secrets versions <NAME> -e <env>                        value version history (never values)
+  seq-studio secrets set-default <NAME> [version] -e <env>           point the default at a prior version (editor)
+  seq-studio secrets pin <NAME> --fn <slug> [version] -e <env>       pin one function to a version (sticky; --unpin clears)
 
   Note: for the common deploy loop, secrets declared in managed-function.yml are
   reconciled automatically by \`seq-studio functions deploy\` using a local .env.
   Use \`secrets\` commands for CI (no .env), bulk/multi-function ops, or write-only
   value changes without a redeploy.
 
-  Flags: -e/--env <env>  (see: seq-studio envs list)
+  Flags: -e/--env <env> (required; see: seq-studio envs list)
          --fn <slug> · --env-var <NAME> · --yes
          --functions <f1,f2> · --keys <K1,K2> · --all (override key selection)
          set-default: [version|version-row-id] (defaults to the most recent non-default) · --yes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sequenceholdings/studio-cli",
-  "version": "0.1.12",
+  "version": "0.1.18",
   "description": "Unified Sequence Studio CLI — `seq-studio process` (Lattice), `seq-studio artifact` (Artifact Studio), `seq-studio functions` / `secrets`, `seq-studio repos` (platform git-service), and `seq-studio auth pat` (git-service PATs). Includes Auth0 browser login shared with seqapi.",
   "license": "UNLICENSED",
   "repository": {
@@ -40,15 +40,19 @@
     "smol-toml": "^1.4.2",
     "tsx": "^4.20.3",
     "zod": "^4.1.13",
-    "@sequenceholdings/artifact-studio": "0.1.11",
-    "@sequenceholdings/lattice": "0.1.1"
+    "@sequenceholdings/artifact-studio": "0.1.15",
+    "@sequenceholdings/lattice": "0.1.2"
   },
   "peerDependencies": {
+    "@sequenceholdings/pipeline-spec": "0.1.0",
     "@sequenceholdings/orm": "0.1.1"
   },
   "peerDependenciesMeta": {
     "@sequenceholdings/orm": {
       "optional": true
+    },
+    "@sequenceholdings/pipeline-spec": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -56,7 +60,8 @@
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0",
     "vitest": "^4.1.5",
-    "@sequenceholdings/orm": "0.1.1"
+    "@sequenceholdings/orm": "0.1.1",
+    "@sequenceholdings/pipeline-spec": "0.1.0"
   },
   "engines": {
     "node": ">=20"