@sequenceholdings/studio-cli 0.1.9

package/dist/functions/commands.js

@@ -0,0 +1,999 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { basename, isAbsolute, join, resolve } from 'node:path';
+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 { readConfig, resolveEnv } from '../config.js';
+import { AtlasApiError, deleteJson, getJson, postJson } from '../atlas-client.js';
+import { clarifyApplyFailureReason, printCliError } from '../cli-errors.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 { buildSecretPreviewLines, classifySecrets, } from './secret-reconcile.js';
+const execFileAsync = promisify(execFile);
+export const LOG = '[seq-studio]';
+const POLL_INTERVAL_MS = 5_000;
+const POLL_TIMEOUT_MS = 20 * 60 * 1000;
+export function flagBool(flags, ...keys) {
+    return keys.some((key) => flags[key] === true || flags[key] === 'true');
+}
+export async function buildContext(args) {
+    const config = await readConfig();
+    const requested = (typeof args.flags.env === 'string' ? args.flags.env : undefined) ??
+        (typeof args.flags.e === 'string' ? args.flags.e : undefined);
+    const env = resolveEnv({ config, requested });
+    const token = await getAccessToken();
+    return { env, token };
+}
+export function clientOptions(ctx) {
+    return { baseUrl: ctx.env.url, token: ctx.token };
+}
+export async function readManifestOptional(dir) {
+    const path = join(dir, MF_MANIFEST_FILENAME);
+    if (!existsSync(path))
+        return null;
+    const raw = parseYaml(await readFile(path, 'utf8'));
+    return managedFunctionManifestSchema.parse(raw);
+}
+async function readManifest(dir) {
+    const manifest = await readManifestOptional(dir);
+    if (!manifest) {
+        throw new Error(`No ${MF_MANIFEST_FILENAME} in ${dir}. Run \`seq-studio functions init\` to scaffold one, or pass --dir.`);
+    }
+    return manifest;
+}
+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);
+    if (manifest)
+        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.`);
+}
+/**
+ * Resolve the target function: --fn <slug> wins, else the manifest in the
+ * working directory names it. Returns null when it doesn't exist remotely.
+ */
+async function resolveFunction({ ctx, args, required = true, }) {
+    let slug = typeof args.flags.fn === 'string' ? args.flags.fn : undefined;
+    if (!slug) {
+        const manifest = await readManifest(workDir(args));
+        slug = manifest.function.id;
+    }
+    const { functions } = await getJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions?slug=${encodeURIComponent(slug)}`,
+    });
+    const fn = functions.find((f) => f.slug === slug) ?? null;
+    if (!fn && required) {
+        throw new Error(`Managed function "${slug}" not found on ${ctx.env.name} (or you don't have access). Run \`seq-studio functions list -e ${ctx.env.name}\` to see what exists.`);
+    }
+    return fn;
+}
+export async function resolveOrRegisterFunction({ ctx, slug, title, description, }) {
+    const { functions } = await getJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions?slug=${encodeURIComponent(slug)}`,
+    });
+    const existing = functions.find((f) => f.slug === slug);
+    if (existing)
+        return { fn: existing, created: false };
+    const created = await postJson({
+        ...clientOptions(ctx),
+        path: '/api/managed-functions',
+        body: {
+            slug,
+            title,
+            description: description ?? null,
+        },
+    });
+    return { fn: created.function, created: true };
+}
+export function predictNextVersion(latest) {
+    const parsed = latest ? Number.parseInt(latest.replace(/^v/, ''), 10) : 0;
+    return `v${(Number.isFinite(parsed) ? parsed : 0) + 1}`;
+}
+async function gitMetadata(dir) {
+    try {
+        const [commit, branch, status] = await Promise.all([
+            execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: dir }),
+            execFileAsync('git', ['branch', '--show-current'], { cwd: dir }),
+            execFileAsync('git', ['status', '--porcelain'], { cwd: dir }),
+        ]);
+        return {
+            gitCommit: commit.stdout.trim() || null,
+            gitBranch: branch.stdout.trim() || null,
+            gitDirty: status.stdout.trim().length > 0,
+        };
+    }
+    catch {
+        return { gitCommit: null, gitBranch: null, gitDirty: null };
+    }
+}
+/** Prompt on the TTY with echo suppressed — secret values are never displayed. */
+export async function promptHidden(question) {
+    if (!process.stdin.isTTY) {
+        // Piped stdin: read it all (`echo "$VALUE" | seq-studio secrets set KEY`).
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        return Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
+    }
+    const muted = new Writable({
+        write(_chunk, _encoding, callback) {
+            callback();
+        },
+    });
+    const rl = createInterface({ input: process.stdin, output: muted, terminal: true });
+    process.stderr.write(question);
+    const answer = await new Promise((resolvePrompt) => {
+        rl.question('', (value) => resolvePrompt(value));
+    });
+    rl.close();
+    process.stderr.write('\n');
+    return answer;
+}
+export function printError(error) {
+    printCliError(error);
+}
+// ---------------------------------------------------------------------------
+// init
+// ---------------------------------------------------------------------------
+const TEMPLATE_MANIFEST = (id) => `schema_version: 1
+
+function:
+  id: ${id}
+  title: ${id}
+  description: Describe what this function does.
+
+runtime: nodejs20
+entrypoint: handler
+
+limits:
+  memory_mb: 256
+  timeout_seconds: 60
+  max_instances: 3
+  invoke_rate_per_minute: 60
+
+# 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: []
+
+# JSON Schema for the invoke payload — Chat agents read this to know the shape.
+input_schema:
+  type: object
+  properties:
+    name:
+      type: string
+  required: [name]
+
+output_schema:
+  type: object
+  properties:
+    message:
+      type: string
+`;
+const TEMPLATE_HANDLER = `import { http, type Request, type Response } from '@google-cloud/functions-framework'
+
+// The entrypoint named in managed-function.yml. Atlas proxies authorized
+// POSTs here with a JSON body matching input_schema. Shared secrets are
+// env-mounted at deploy time — read them via process.env.<NAME>.
+http('handler', (req: Request, res: Response) => {
+  const { name } = (req.body ?? {}) as { name?: string }
+  res.json({ message: \`Hello, \${name ?? 'world'}!\` })
+})
+`;
+// TypeScript is compiled server-side by the deploy worker (\`tsc\` runs with
+// devDependencies installed, then the tree is pruned to \`--prod\`), so the
+// bundle ships \`index.ts\` and the worker emits the \`dist/index.js\` that
+// \`main\` points at. \`outDir\`/\`rootDir\` keep that output predictable.
+const TEMPLATE_TSCONFIG = JSON.stringify({
+    compilerOptions: {
+        target: 'es2022',
+        module: 'commonjs',
+        moduleResolution: 'node',
+        outDir: 'dist',
+        rootDir: '.',
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        resolveJsonModule: true,
+    },
+    include: ['index.ts'],
+    exclude: ['node_modules', 'dist'],
+}, null, 2) + '\n';
+const TEMPLATE_PACKAGE_JSON = (id) => JSON.stringify({
+    name: id,
+    version: '0.0.1',
+    private: true,
+    // The deploy worker compiles index.ts -> dist/index.js; `main` points at
+    // the compiled output Cloud Functions loads.
+    main: 'dist/index.js',
+    scripts: {
+        build: 'tsc',
+    },
+    dependencies: {
+        '@google-cloud/functions-framework': '^3.4.0',
+    },
+    devDependencies: {
+        '@types/node': '^20.11.0',
+        typescript: '^5.6.0',
+    },
+}, null, 2) + '\n';
+const TEMPLATE_GITIGNORE = `node_modules/
+dist/
+.env
+.env.*
+*.log
+`;
+// Local-only: makes `pnpm install` resolve against Chainguard so the lockfile
+// matches what the deploy worker installs from (the fast, version-pinned
+// path). Auth comes from your ~/.npmrc (scripts/chainguard-bootstrap). This
+// file is NEVER bundled — collectBundleFiles excludes it and the server
+// rejects it; the deploy worker pins the registry itself. Authors without
+// Chainguard credentials can delete it and install from public npm — see the
+// comment written into the scaffolded file.
+const TEMPLATE_NPMRC = `# Pins installs to Chainguard, Sequence's internal package registry, so your
+# lockfile matches what the deploy worker installs (fast, version-pinned
+# deploys). Requires Chainguard credentials in ~/.npmrc (Sequence engineers:
+# scripts/chainguard-bootstrap).
+#
+# No Chainguard credentials? \`pnpm install\` will fail with a 401 — DELETE THIS
+# FILE and install from public npm instead. That is safe: the deploy worker
+# always re-resolves dependencies against Chainguard server-side, and this
+# file is never included in the deployed bundle either way.
+registry=https://libraries.cgr.dev/javascript/
+//libraries.cgr.dev/javascript/:always-auth=true
+//libraries.cgr.dev/javascript-upstream/:always-auth=true
+`;
+export async function functionsInitCommand(args) {
+    const target = args.positional[0];
+    if (!target) {
+        console.error('usage: seq-studio functions init <dir>');
+        return 1;
+    }
+    const dir = resolve(target);
+    // Derive the slug from the resolved directory name so `init .` and
+    // trailing-slash paths work (the raw argument would yield an empty id).
+    const id = basename(dir)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!id) {
+        console.error(`${LOG} could not derive a function id from "${target}" — the directory name needs at least one alphanumeric character.`);
+        return 1;
+    }
+    if (existsSync(join(dir, MF_MANIFEST_FILENAME))) {
+        console.error(`${LOG} ${dir} already contains ${MF_MANIFEST_FILENAME}`);
+        return 1;
+    }
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, MF_MANIFEST_FILENAME), TEMPLATE_MANIFEST(id));
+    await writeFile(join(dir, 'index.ts'), TEMPLATE_HANDLER);
+    await writeFile(join(dir, 'tsconfig.json'), TEMPLATE_TSCONFIG);
+    await writeFile(join(dir, 'package.json'), TEMPLATE_PACKAGE_JSON(id));
+    await writeFile(join(dir, '.gitignore'), TEMPLATE_GITIGNORE);
+    await writeFile(join(dir, '.npmrc'), TEMPLATE_NPMRC);
+    console.log(`${LOG} scaffolded managed function "${id}" (TypeScript) in ${dir}`);
+    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 staging  # upload, apply secrets, then deploy');
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// 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 source = await resolveArtifactSource(spec, remote);
+    try {
+        return await buildFromResolvedSource({ spec, source });
+    }
+    finally {
+        await source.cleanup();
+    }
+}
+async function buildFromResolvedSource({ spec, source, }) {
+    const dir = source.dir;
+    if (!(await isDirectory(dir))) {
+        console.error(`${LOG} not a directory: ${dir}`);
+        return 1;
+    }
+    const manifest = await readSourceManifest(dir, spec);
+    const { files, excludedEnvFiles } = await collectBundleFiles(dir);
+    const issues = await validateLocalBundle({ rootDir: dir, files });
+    console.log(`${LOG} function:   ${manifest.function.id} (${manifest.function.title})`);
+    console.log(`${LOG} runtime:    ${manifest.runtime}, entrypoint: ${manifest.entrypoint}`);
+    console.log(`${LOG} files:      ${files.length}`);
+    console.log(`${LOG} secrets:    ${manifest.secrets.length > 0 ? manifest.secrets.join(', ') : '(none declared)'}`);
+    console.log(`${LOG} egress:     ${formatEgressSummary([
+        ...manifestEgressHosts(manifest.egress),
+        ...manifestEgressIpRanges(manifest.egress),
+    ])}`);
+    for (const excluded of excludedEnvFiles) {
+        console.warn(`${LOG} excluded ${excluded} — dotenv files never enter bundles; use .env as a value source for \`seq-studio functions deploy\``);
+    }
+    for (const issue of issues) {
+        const log = issue.level === 'error' ? console.error : issue.level === 'warning' ? console.warn : console.log;
+        log(`${LOG} ${issue.level}: ${issue.message}`);
+    }
+    const errors = issues.filter((i) => i.level === 'error');
+    if (errors.length > 0) {
+        console.error(`${LOG} build check failed (${errors.length} error${errors.length === 1 ? '' : 's'})`);
+        return 1;
+    }
+    console.log(`${LOG} bundle OK — next: \`functions deploy\` (reads .env and reconciles secrets automatically)`);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// deploy
+// ---------------------------------------------------------------------------
+async function getFunctionDetail(ctx, functionId) {
+    try {
+        return await getJson({
+            ...clientOptions(ctx),
+            path: `/api/managed-functions/${functionId}`,
+        });
+    }
+    catch (error) {
+        if (error instanceof AtlasApiError && error.status === 404)
+            return null;
+        throw error;
+    }
+}
+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) : {});
+    try {
+        return await deployFromResolvedSource({ args, spec, ctx, source });
+    }
+    finally {
+        await source.cleanup();
+    }
+}
+async function deployFromResolvedSource({ args, spec, ctx: earlyCtx, source, }) {
+    const dir = source.dir;
+    const manifest = await readSourceManifest(dir, spec);
+    const { files, excludedEnvFiles } = await collectBundleFiles(dir);
+    for (const excluded of excludedEnvFiles) {
+        console.warn(`${LOG} excluded ${excluded} — dotenv files never enter bundles`);
+    }
+    const issues = await validateLocalBundle({ rootDir: dir, files });
+    const errors = issues.filter((i) => i.level === 'error');
+    for (const issue of issues) {
+        const log = issue.level === 'error' ? console.error : issue.level === 'warning' ? console.warn : console.log;
+        log(`${LOG} ${issue.level}: ${issue.message}`);
+    }
+    if (errors.length > 0)
+        return 1;
+    // Read the local .env for secret value sourcing.
+    // An explicitly supplied --from-env-file must exist; the default .env is
+    // optional (CI path: values must already exist server-side). For a remote
+    // source (--repo / --git-url) there is no implicit .env — repo contents are
+    // never used as secret-value sources — and a relative --from-env-file
+    // resolves against the invoking cwd, not the materialized temp tree.
+    const envFileFlag = typeof args.flags['from-env-file'] === 'string' ? args.flags['from-env-file'] : null;
+    const envFilePath = envFileFlag
+        ? isAbsolute(envFileFlag)
+            ? envFileFlag
+            : resolve(spec.kind === 'local' ? dir : process.cwd(), envFileFlag)
+        : spec.kind === 'local'
+            ? join(dir, '.env')
+            : null;
+    let envValues = {};
+    if (envFileFlag) {
+        if (!envFilePath || !existsSync(envFilePath)) {
+            console.error(`${LOG} --from-env-file: file not found: ${envFilePath}`);
+            return 1;
+        }
+        envValues = parseDotenv(await readFile(envFilePath, 'utf8'));
+    }
+    else if (envFilePath && existsSync(envFilePath)) {
+        envValues = parseDotenv(await readFile(envFilePath, 'utf8'));
+    }
+    // A --repo source authenticated before materialization; local / git-url
+    // sources authenticate only now, after local validation passed.
+    const ctx = earlyCtx ?? (await buildContext(args));
+    const slug = manifest.function.id;
+    const { functions } = await getJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions?slug=${encodeURIComponent(slug)}`,
+    });
+    const existingShell = functions.find((f) => f.slug === slug) ?? null;
+    const shellAction = existingShell
+        ? `existing shell on ${ctx.env.name}`
+        : `will register new shell on ${ctx.env.name}`;
+    let versions = [];
+    if (existingShell) {
+        try {
+            versions = await listVersions(ctx, existingShell.id);
+        }
+        catch (error) {
+            if (error instanceof AtlasApiError && error.status === 404) {
+                versions = [];
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    const latestVersion = versions[0]?.version;
+    const nextVersion = predictNextVersion(latestVersion);
+    const deployMessage = (typeof args.flags.message === 'string' ? args.flags.message : undefined) ??
+        (typeof args.flags.m === 'string' ? args.flags.m : undefined) ??
+        null;
+    // Local deploys record best-effort working-tree provenance; remote sources
+    // carry the resolver's pinned commit (gitCommit = resolved SHA, never dirty).
+    const git = spec.kind === 'local' ? await gitMetadata(dir) : source.provenance;
+    // Classify each declared secret so the deploy preview and reconcile step
+    // know exactly what action to take for each one.
+    let classification = null;
+    if (manifest.secrets.length > 0) {
+        const { secrets: serverSecrets } = await getJson({
+            ...clientOptions(ctx),
+            path: '/api/managed-secrets',
+        });
+        const serverInfoByName = new Map(serverSecrets.map((s) => [
+            s.name,
+            { id: s.id, hasDefaultValue: s.hasDefaultValue, attachmentCount: s.attachmentCount },
+        ]));
+        // Build envVar → secretId map so the classifier can detect when an env
+        // var is already attached to a *different* secret and not skip reconcile.
+        const attachedByEnvVar = new Map();
+        if (existingShell) {
+            const detail = await getFunctionDetail(ctx, existingShell.id);
+            for (const a of detail?.attachments ?? []) {
+                if (a.secretId)
+                    attachedByEnvVar.set(a.envVarName, a.secretId);
+            }
+        }
+        classification = classifySecrets({
+            manifestSecrets: manifest.secrets,
+            envValues,
+            serverInfoByName,
+            attachedByEnvVar,
+        });
+        // Hard-stop before any writes if any declared secret cannot be satisfied.
+        if (classification.blocked.length > 0) {
+            for (const c of classification.blocked) {
+                console.error(`${LOG} secret "${c.name}" is declared but has no value — ` +
+                    `add it to .env, run \`seq-studio secrets set ${c.name} -e ${ctx.env.name}\`, or set it in the Sequence app`);
+            }
+            console.error(`${LOG} resolve the above before deploying`);
+            return 1;
+        }
+    }
+    // Surface .env keys that aren't in the manifest so users know they're ignored.
+    const undeclaredEnvKeys = Object.keys(envValues).filter((k) => envValues[k]?.length && !manifest.secrets.includes(k));
+    const preview = [
+        `${LOG} deploy preview:`,
+        `${LOG}   environment:    ${ctx.env.name}`,
+        `${LOG}   function:       ${slug} (${manifest.function.title})`,
+        `${LOG}   shell:          ${shellAction}`,
+        `${LOG}   version:        ${nextVersion}`,
+        `${LOG}   bundle files:   ${files.length}`,
+    ];
+    if (deployMessage)
+        preview.push(`${LOG}   message:        ${deployMessage}`);
+    if (git.gitCommit) {
+        preview.push(`${LOG}   git:            ${git.gitBranch ?? '?'}@${git.gitCommit.slice(0, 8)}${git.gitDirty ? ' (dirty)' : ''}`);
+    }
+    if (classification) {
+        preview.push(...buildSecretPreviewLines(LOG, classification.secrets));
+        if (classification.secrets.some((c) => c.category === 'OVERWRITE')) {
+            preview.push(`${LOG}   note: overwriting a shared default changes it for all attached functions`);
+        }
+    }
+    else {
+        preview.push(`${LOG}   secrets: (none declared)`);
+    }
+    preview.push(...buildEgressPreviewLines(LOG, [
+        ...manifestEgressHosts(manifest.egress),
+        ...manifestEgressIpRanges(manifest.egress),
+    ]));
+    if (undeclaredEnvKeys.length > 0) {
+        preview.push(`${LOG}   note: .env has ${undeclaredEnvKeys.join(', ')} — not declared in manifest, ignored`);
+    }
+    // --no-provision (the CI sweep): update-only deploy. Anything that would
+    // create or reconcile state beyond the version upload — registering a new
+    // shell, writing secret values, attaching secrets — is an error instead of
+    // a write: those routes stay per-principal FGA-gated (no trusted-M2M path),
+    // and first-time wiring is deliberately a human step. See
+    // atlas/processes/ROLLOUT.md.
+    if (flagBool(args.flags, 'no-provision')) {
+        const problems = [];
+        if (!existingShell) {
+            problems.push(`function "${slug}" is not registered on ${ctx.env.name} — run ` +
+                `\`seq-studio functions deploy -e ${ctx.env.name}\` once with your own login (seqapi login) to register it`);
+        }
+        for (const c of classification?.secrets ?? []) {
+            if (c.category === 'UPLOAD_NEW' || c.category === 'OVERWRITE') {
+                problems.push(`secret "${c.name}" would be written from a local value — provision it server-side first: ` +
+                    `\`seq-studio secrets set ${c.name} -e ${ctx.env.name}\``);
+            }
+            else if (c.category === 'USE_EXISTING' && !c.attachedToFn) {
+                problems.push(`secret "${c.name}" exists but is not attached to ${slug} — attach it once: ` +
+                    `\`seq-studio secrets attach ${c.name} --fn ${slug} -e ${ctx.env.name}\``);
+            }
+        }
+        if (problems.length > 0) {
+            for (const problem of problems)
+                console.error(`${LOG} --no-provision: ${problem}`);
+            console.error(`${LOG} resolve the above (human one-time wiring), then re-run the deploy`);
+            return 1;
+        }
+    }
+    const confirmed = flagBool(args.flags, 'yes');
+    const ok = await confirmYes({ preview, confirmed });
+    if (!ok)
+        return 1;
+    // Ensure the function shell exists before reconciling secrets (which need the fn id).
+    let fn = existingShell;
+    let createdShell = false;
+    if (!fn) {
+        console.log(`${LOG} registering new managed function "${slug}" on ${ctx.env.name}`);
+        const registered = await resolveOrRegisterFunction({
+            ctx,
+            slug,
+            title: manifest.function.title,
+            description: manifest.function.description ?? null,
+        });
+        fn = registered.fn;
+        createdShell = registered.created;
+    }
+    // Reconcile secrets after confirm and after the shell exists.
+    if (classification) {
+        // UPLOAD_NEW + OVERWRITE: delegate to /apply which handles create/set/attach atomically.
+        const applyEntries = classification.secrets
+            .filter((c) => c.category === 'UPLOAD_NEW' || c.category === 'OVERWRITE')
+            .map((c) => ({ name: c.name, value: envValues[c.name] ?? '' }));
+        if (applyEntries.length > 0) {
+            console.log(`${LOG} applying ${applyEntries.length} secret(s) to ${ctx.env.name}…`);
+            const result = await postJson({
+                ...clientOptions(ctx),
+                path: '/api/managed-secrets/apply',
+                body: { entries: applyEntries, functionSlugs: [slug] },
+            });
+            if (result.summary.failed > 0) {
+                for (const row of result.failed) {
+                    console.error(`${LOG} secret "${row.secret}": ${clarifyApplyFailureReason(row.reason)}`);
+                }
+                console.error(`${LOG} could not apply all secrets — resolve the above before deploying`);
+                return 1;
+            }
+        }
+        // USE_EXISTING not yet attached: attach only (no value change).
+        const toAttach = classification.secrets.filter((c) => c.category === 'USE_EXISTING' && !c.attachedToFn && c.secretId !== null);
+        for (const c of toAttach) {
+            console.log(`${LOG} attaching existing secret "${c.name}" to ${slug}…`);
+            try {
+                await postJson({
+                    ...clientOptions(ctx),
+                    path: `/api/managed-secrets/${c.secretId}/attachments`,
+                    body: { functionId: fn.id, envVarName: c.name },
+                });
+            }
+            catch (error) {
+                if (error instanceof AtlasApiError && error.status === 409) {
+                    console.error(`${LOG} secret "${c.name}": env var is already attached to a different managed secret — ` +
+                        `detach the conflicting attachment first: \`seq-studio secrets detach <NAME> --fn ${slug} -e ${ctx.env.name}\``);
+                    return 1;
+                }
+                throw error;
+            }
+        }
+    }
+    if (git.gitDirty) {
+        console.warn(`${LOG} working tree is dirty — recording gitDirty=true on this version`);
+    }
+    console.log(`${LOG} uploading bundle (${files.length} files) to ${ctx.env.name}…`);
+    let version;
+    try {
+        ;
+        ({ version } = await postJson({
+            ...clientOptions(ctx),
+            path: `/api/managed-functions/${fn.id}/versions`,
+            body: {
+                manifest,
+                files,
+                version: nextVersion,
+                deployMessage,
+                ...git,
+            },
+        }));
+    }
+    catch (error) {
+        if (error instanceof AtlasApiError && error.status === 409) {
+            console.error(`${LOG} version ${nextVersion} already exists — another deploy may have raced. Re-run deploy to allocate the next version.`);
+            return 1;
+        }
+        throw error;
+    }
+    if (createdShell) {
+        console.log(`${LOG} registered shell for "${slug}"`);
+    }
+    console.log(`${LOG} version ${version.version} uploaded — building (server-side install + Cloud Functions deploy)`);
+    if (args.flags['no-wait']) {
+        console.log(`${LOG} not waiting (--no-wait). Poll with: seq-studio functions list -e ${ctx.env.name}`);
+        return 0;
+    }
+    return pollVersion({
+        ctx,
+        functionId: fn.id,
+        versionId: version.id,
+        egressNote: manifestEgressHosts(manifest.egress).length > 0 ||
+            manifestEgressIpRanges(manifest.egress).length > 0,
+    });
+}
+export async function pollVersion({ ctx, functionId, versionId, egressNote = false, }) {
+    const deadline = Date.now() + POLL_TIMEOUT_MS;
+    let lastStatus = '';
+    for (;;) {
+        const { version } = await getJson({
+            ...clientOptions(ctx),
+            path: `/api/managed-functions/${functionId}/versions/${versionId}`,
+        });
+        if (version.status !== lastStatus) {
+            lastStatus = version.status;
+            console.log(`${LOG} status: ${version.status}`);
+        }
+        if (version.status === 'deployed') {
+            console.log(`${LOG} ✓ ${version.version} is live`);
+            if (egressNote) {
+                console.log(egressPropagationNote(LOG));
+            }
+            return 0;
+        }
+        if (version.status === 'failed') {
+            console.error(`${LOG} ✗ deploy failed: ${version.statusDetail ?? 'unknown error'}`);
+            return 1;
+        }
+        if (Date.now() > deadline) {
+            console.error(`${LOG} timed out waiting for deploy (still "${version.status}")`);
+            return 1;
+        }
+        await new Promise((resolveSleep) => setTimeout(resolveSleep, POLL_INTERVAL_MS));
+    }
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+export async function functionsListCommand(args) {
+    const ctx = await buildContext(args);
+    const { functions } = await getJson({
+        ...clientOptions(ctx),
+        path: '/api/managed-functions',
+    });
+    if (flagBool(args.flags, 'match-local')) {
+        const dir = workDir(args);
+        let manifest = null;
+        try {
+            manifest = await readManifestOptional(dir);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            console.warn(`${LOG} --match-local: invalid ${MF_MANIFEST_FILENAME} in ${dir}: ${detail}`);
+        }
+        if (manifest) {
+            const localSlug = manifest.function.id;
+            const match = functions.find((f) => f.slug === localSlug);
+            console.log(`${LOG} local manifest function.id "${localSlug}": ${match ? `exists on ${ctx.env.name}` : `not found on ${ctx.env.name}`}`);
+        }
+        else if (!existsSync(join(dir, MF_MANIFEST_FILENAME))) {
+            console.warn(`${LOG} --match-local: no ${MF_MANIFEST_FILENAME} in ${dir}`);
+        }
+    }
+    if (functions.length === 0) {
+        console.log(`${LOG} no managed functions visible on ${ctx.env.name}`);
+        return 0;
+    }
+    console.log(`${LOG} ${functions.length} function${functions.length === 1 ? '' : 's'} on ${ctx.env.name}:`);
+    for (const fn of functions) {
+        const state = fn.deployed ? 'deployed' : 'not deployed';
+        const redeploy = fn.secretsNeedDeploy ? ', secrets pending redeploy' : '';
+        const access = fn.currentUserAccess ?? (fn.canInvoke ? 'invoke-only' : 'none');
+        console.log(`  ${fn.slug}  id=${fn.id}  [${state}${redeploy}]  access=${access}  ${fn.title}`);
+    }
+    return 0;
+}
+async function printFunctionShowDetails({ ctx, fn, }) {
+    const versions = await listVersions(ctx, fn.id);
+    const active = versions.find((v) => v.isActive);
+    if (active) {
+        console.log(`  active:     ${active.version} (${active.status})`);
+    }
+    const recent = versions.slice(0, 5);
+    if (recent.length > 0) {
+        console.log(`${LOG} recent versions:`);
+        for (const v of recent) {
+            const marker = v.isActive ? ' (active)' : '';
+            console.log(`    ${v.version}  [${v.status}]${marker}`);
+        }
+    }
+    const detail = await getFunctionDetail(ctx, fn.id);
+    if (detail && detail.attachments.length > 0) {
+        console.log(`${LOG} attached secrets:`);
+        for (const row of detail.attachments) {
+            const mounted = row.deployed ? 'mounted' : 'pending redeploy';
+            console.log(`    ${row.envVarName}  [${mounted}]`);
+        }
+    }
+    printFunctionEgressHosts({
+        log: LOG,
+        hosts: detail?.function.egressHosts ?? fn.egressHosts ?? [],
+        ipRanges: detail?.function.egressIpRanges ?? fn.egressIpRanges ?? [],
+        egressEnforced: detail?.function.egressEnforced ?? fn.egressEnforced ?? false,
+    });
+}
+export async function functionsShowCommand(args) {
+    const ctx = await buildContext(args);
+    const fn = await resolveFunction({ ctx, args, required: true });
+    if (!fn)
+        return 1;
+    console.log(`${LOG} function on ${ctx.env.name}:`);
+    console.log(`  id:         ${fn.id}`);
+    console.log(`  slug:       ${fn.slug}`);
+    console.log(`  title:      ${fn.title}`);
+    console.log(`  deployed:   ${fn.deployed ? 'yes' : 'no'}`);
+    if (fn.currentUserAccess) {
+        console.log(`  access:     ${fn.currentUserAccess}`);
+        if (fn.secretsNeedDeploy) {
+            console.log(`  secrets:    pending redeploy`);
+        }
+    }
+    else if (fn.canInvoke) {
+        console.log(`  access:     invoke-only`);
+    }
+    if (fn.currentUserAccess) {
+        try {
+            await printFunctionShowDetails({ ctx, fn });
+        }
+        catch (error) {
+            printError(error);
+            return 1;
+        }
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// logs
+// ---------------------------------------------------------------------------
+export async function functionsLogsCommand(args) {
+    const ctx = await buildContext(args);
+    const fn = (await resolveFunction({ ctx, args }));
+    const limit = typeof args.flags.limit === 'string' ? Number(args.flags.limit) : 100;
+    const since = typeof args.flags.since === 'string' ? args.flags.since : undefined;
+    const query = new URLSearchParams({ limit: String(limit) });
+    if (since)
+        query.set('since', since);
+    const { entries } = await getJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions/${fn.id}/logs?${query.toString()}`,
+    });
+    if (entries.length === 0) {
+        console.log(`${LOG} no log entries for ${fn.slug}`);
+        return 0;
+    }
+    // Cloud Logging returns newest-first; print oldest-first for readability.
+    for (const entry of [...entries].reverse()) {
+        console.log(`${entry.timestamp} ${entry.severity.padEnd(8)} ${entry.message}`);
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// promote / rollback
+// ---------------------------------------------------------------------------
+export async function resolveLiveActiveVersionId(ctx, functionId) {
+    const versions = await listVersions(ctx, functionId);
+    return versions.find((v) => v.isActive)?.id ?? null;
+}
+async function listVersions(ctx, functionId) {
+    const { versions } = await getJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions/${functionId}/versions`,
+    });
+    return versions;
+}
+export async function functionsPromoteCommand(args) {
+    const versionName = args.positional[0];
+    if (!versionName) {
+        console.error('usage: seq-studio functions promote <version> [-e env] [--fn slug]');
+        return 1;
+    }
+    const ctx = await buildContext(args);
+    const fn = (await resolveFunction({ ctx, args }));
+    const versions = await listVersions(ctx, fn.id);
+    const target = versions.find((v) => v.version === versionName);
+    if (!target) {
+        console.error(`${LOG} version "${versionName}" not found. Known: ${versions.map((v) => v.version).join(', ')}`);
+        return 1;
+    }
+    console.log(`${LOG} promoting ${fn.slug} ${target.version}…`);
+    await postJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions/${fn.id}/versions/${target.id}/promote`,
+    });
+    // The target version's manifest (and therefore its egress) isn't in the
+    // summary, so always surface the propagation hint after the flip.
+    return pollVersion({ ctx, functionId: fn.id, versionId: target.id, egressNote: true });
+}
+export async function functionsRollbackCommand(args) {
+    const ctx = await buildContext(args);
+    const fn = (await resolveFunction({ ctx, args }));
+    const versions = await listVersions(ctx, fn.id);
+    let target;
+    const versionName = args.positional[0];
+    if (versionName) {
+        target = versions.find((v) => v.version === versionName);
+        if (!target) {
+            console.error(`${LOG} version "${versionName}" not found. Known: ${versions.map((v) => v.version).join(', ')}`);
+            return 1;
+        }
+    }
+    else {
+        // No explicit target: the most recent previously-deployed version
+        // that isn't the active one.
+        target = versions.find((v) => !v.isActive && v.deployedAt !== null);
+        if (!target) {
+            console.error(`${LOG} no prior deployed version to roll back to`);
+            return 1;
+        }
+    }
+    console.log(`${LOG} rolling back ${fn.slug} to ${target.version}…`);
+    await postJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions/${fn.id}/versions/${target.id}/rollback`,
+    });
+    // Same as promote: the target manifest's egress isn't known here.
+    return pollVersion({ ctx, functionId: fn.id, versionId: target.id, egressNote: true });
+}
+// ---------------------------------------------------------------------------
+// secrets
+// ---------------------------------------------------------------------------
+/** Minimal dotenv parser — KEY=VALUE lines, quotes stripped, comments skipped. */
+export function parseDotenv(content) {
+    const out = {};
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim().replace(/^export\s+/, '');
+        let value = line.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key)
+            out[key] = value;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// delete
+// ---------------------------------------------------------------------------
+export async function functionsDeleteCommand(args) {
+    const ctx = await buildContext(args);
+    const fn = (await resolveFunction({ ctx, args }));
+    if (!args.flags.yes) {
+        console.error(`${LOG} this archives "${fn.slug}" on ${ctx.env.name} and tears down its Cloud Function, service account, and source bundles (history is retained).\n` +
+            `${LOG} re-run with --yes to confirm`);
+        return 1;
+    }
+    await deleteJson({ ...clientOptions(ctx), path: `/api/managed-functions/${fn.id}` });
+    console.log(`${LOG} archived ${fn.slug} on ${ctx.env.name}`);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// dispatcher
+// ---------------------------------------------------------------------------
+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
+                                                      (version history is retained)
+
+  Flags: -e/--env <local|staging|production|banksouth|preview:<slug>> · --fn <slug> · --dir <path>
+         --from-env-file <path>  (default: .env) source file for secret values
+         --no-wait · --yes
+         --no-provision  (deploy) update-only: error instead of registering a new
+                         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 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 + seqapi login are still needed to resolve the repo and deploy.
+`;
+export async function runFunctionsCommand(sub, args) {
+    try {
+        switch (sub) {
+            case 'init':
+                return await functionsInitCommand(args);
+            case 'build':
+                return await functionsBuildCommand(args);
+            case 'deploy':
+                return await functionsDeployCommand(args);
+            case 'list':
+                return await functionsListCommand(args);
+            case 'show':
+                return await functionsShowCommand(args);
+            case 'logs':
+                return await functionsLogsCommand(args);
+            case 'promote':
+                return await functionsPromoteCommand(args);
+            case 'rollback':
+                return await functionsRollbackCommand(args);
+            case 'delete':
+                return await functionsDeleteCommand(args);
+            case 'help':
+            case '--help':
+            case '-h':
+            case undefined:
+                console.log(FUNCTIONS_USAGE);
+                return sub ? 0 : 1;
+            default:
+                console.error(`unknown functions command: ${sub}`);
+                console.error(FUNCTIONS_USAGE);
+                return 1;
+        }
+    }
+    catch (error) {
+        printError(error);
+        return 1;
+    }
+}