@sequenceholdings/studio-cli 0.1.9

package/dist/secrets/commands.js

@@ -0,0 +1,704 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { buildContext, clientOptions, flagBool, parseDotenv, pollVersion, printError, promptHidden, readManifestOptional, resolveLiveActiveVersionId, resolveOrRegisterFunction, workDir, } from '../functions/commands.js';
+import { clarifyApplyFailureReason } from '../cli-errors.js';
+import { confirmChoice, confirmYes } from '../prompt.js';
+import { AtlasApiError, deleteJson, getJson, patchJson, postJson, putJson } from '../atlas-client.js';
+export const LOG = '[seq-studio]';
+const VERSION_ROW_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Match a version arg by stable row id, or by gcpVersion when unambiguous. */
+function resolveVersionTarget(versions, versionArg) {
+    if (VERSION_ROW_ID_RE.test(versionArg)) {
+        const byId = versions.find((v) => v.id === versionArg);
+        if (!byId)
+            return { error: `version id "${versionArg}" not found` };
+        return { target: byId };
+    }
+    const wanted = versionArg.replace(/^v/, '');
+    const matches = versions.filter((v) => v.gcpVersion === wanted);
+    if (matches.length === 0) {
+        return {
+            error: `version "${versionArg}" not found. Known: ${versions.map((v) => `v${v.gcpVersion}`).join(', ')}`,
+        };
+    }
+    if (matches.length > 1) {
+        return {
+            error: `version "${versionArg}" is ambiguous (${matches.length} rows share v${wanted}). ` +
+                `Pass the version row id from "seq-studio secrets versions": ${matches.map((v) => v.id).join(', ')}`,
+        };
+    }
+    return { target: matches[0] };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function parseCommaList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
+async function listSecrets(ctx) {
+    const { secrets } = await getJson({
+        ...clientOptions(ctx),
+        path: '/api/managed-secrets',
+    });
+    return secrets;
+}
+async function resolveSecretByName({ ctx, name, }) {
+    const secrets = await listSecrets(ctx);
+    const secret = secrets.find((row) => row.name === name);
+    if (!secret) {
+        throw new Error(`Managed secret "${name}" not found on ${ctx.env.name} (or you don't have access).`);
+    }
+    return secret;
+}
+function canAdminFunction(fn) {
+    return fn.currentUserAccess === 'admin' || fn.currentUserAccess === 'owner';
+}
+async function resolvePinRedeployChoice({ args, fnSlug, preview, canRedeploy, }) {
+    if (flagBool(args.flags, 'yes')) {
+        const redeploy = !flagBool(args.flags, 'no-redeploy');
+        if (redeploy && !canRedeploy) {
+            console.error(`${LOG} redeploy requires admin access on ${fnSlug} — use --yes --no-redeploy to pin only`);
+            return { ok: false };
+        }
+        for (const line of preview)
+            console.log(line);
+        console.log(redeploy
+            ? `${LOG} pinning and redeploying ${fnSlug} (--yes)`
+            : `${LOG} pinning WITHOUT redeploy (--yes --no-redeploy)`);
+        return { ok: true, redeploy };
+    }
+    const choices = canRedeploy
+        ? [
+            { key: 'y', label: `yes — pin and redeploy ${fnSlug} now`, value: 'redeploy' },
+            { key: 'p', label: 'pin only (mounts on the next redeploy)', value: 'pin-only' },
+            { key: 'n', label: 'no / back', value: 'cancel' },
+        ]
+        : [
+            { key: 'p', label: 'pin only (mounts on the next redeploy)', value: 'pin-only' },
+            { key: 'n', label: 'no / back', value: 'cancel' },
+        ];
+    const choice = await confirmChoice({
+        preview,
+        prompt: canRedeploy ? 'Choose [y/p/n]: ' : 'Choose [p/n]: ',
+        choices,
+    });
+    if (choice === null || choice === 'cancel') {
+        console.error(`${LOG} aborted`);
+        return { ok: false };
+    }
+    return { ok: true, redeploy: choice === 'redeploy' };
+}
+async function resolveFunctionBySlug({ ctx, slug, }) {
+    const { functions } = await getJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions?slug=${encodeURIComponent(slug)}`,
+    });
+    const fn = functions.find((row) => row.slug === slug);
+    if (!fn) {
+        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;
+}
+async function functionExistsBySlug({ ctx, slug, }) {
+    const { functions } = await getJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions?slug=${encodeURIComponent(slug)}`,
+    });
+    return functions.some((row) => row.slug === slug);
+}
+async function functionExistsBySlugEventually({ ctx, slug, attempts = 3, retryDelayMs = 250, }) {
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (await functionExistsBySlug({ ctx, slug }))
+            return true;
+        if (attempt < attempts - 1) {
+            await new Promise((resolveSleep) => setTimeout(resolveSleep, retryDelayMs));
+        }
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+export async function secretsCreateCommand(args) {
+    const name = args.positional[0];
+    if (!name) {
+        console.error('usage: seq-studio secrets create <NAME> [-e env] [--description text]');
+        return 1;
+    }
+    const ctx = await buildContext(args);
+    const description = typeof args.flags.description === 'string' ? args.flags.description : undefined;
+    const secret = await postJson({
+        ...clientOptions(ctx),
+        path: '/api/managed-secrets',
+        body: {
+            name,
+            description: description ?? null,
+        },
+    });
+    console.log(`${LOG} created managed secret "${secret.name}" (${secret.id}) on ${ctx.env.name}`);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// set (default value)
+// ---------------------------------------------------------------------------
+export async function secretsSetCommand(args) {
+    const name = args.positional[0];
+    if (!name) {
+        console.error('usage: seq-studio secrets set <NAME> [-e env]');
+        return 1;
+    }
+    const ctx = await buildContext(args);
+    const secret = await resolveSecretByName({ ctx, name });
+    const value = await promptHidden(`Default value for ${name} (input hidden): `);
+    if (!value) {
+        console.error(`${LOG} empty value — aborted`);
+        return 1;
+    }
+    await putJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-secrets/${secret.id}/value`,
+        body: { value },
+    });
+    console.log(`${LOG} set default value for "${name}"`);
+    console.log(`${LOG} functions with this secret attached need redeploy to mount the new version`);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+export async function secretsListCommand(args) {
+    const ctx = await buildContext(args);
+    const secrets = await listSecrets(ctx);
+    if (secrets.length === 0) {
+        console.log(`${LOG} no managed secrets visible on ${ctx.env.name}`);
+        return 0;
+    }
+    console.log(`${LOG} ${secrets.length} secret${secrets.length === 1 ? '' : 's'} on ${ctx.env.name}:`);
+    for (const secret of secrets) {
+        const defaultState = secret.hasDefaultValue ? 'default set' : 'no default';
+        const access = secret.currentUserAccess ?? 'none';
+        console.log(`  ${secret.name}  [${defaultState}]  access=${access}  attachments=${secret.attachmentCount}`);
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// attach / detach
+// ---------------------------------------------------------------------------
+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]');
+        return 1;
+    }
+    const ctx = await buildContext(args);
+    const secret = await resolveSecretByName({ ctx, name });
+    const fn = await resolveFunctionBySlug({ ctx, slug: fnSlug });
+    const envVarName = (typeof args.flags['env-var'] === 'string' ? args.flags['env-var'] : undefined) ?? name;
+    if (secret.hasDefaultValue) {
+        const preview = [
+            `${LOG} attach preview:`,
+            `${LOG}   secret:    ${name}`,
+            `${LOG}   function:  ${fnSlug}`,
+            `${LOG}   env var:   ${envVarName}`,
+            `${LOG}   note:      shared default — anyone who can invoke "${fnSlug}" receives it at runtime`,
+        ];
+        const ok = await confirmYes({ preview, confirmed: flagBool(args.flags, 'yes') });
+        if (!ok)
+            return 1;
+    }
+    await postJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-secrets/${secret.id}/attachments`,
+        body: {
+            functionId: fn.id,
+            envVarName,
+        },
+    });
+    console.log(`${LOG} attached "${name}" to ${fnSlug} as env var ${envVarName}`);
+    console.log(`${LOG} redeploy ${fnSlug} to mount the secret`);
+    return 0;
+}
+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>');
+        return 1;
+    }
+    const ctx = await buildContext(args);
+    const secret = await resolveSecretByName({ ctx, name });
+    const fn = await resolveFunctionBySlug({ ctx, slug: fnSlug });
+    await deleteJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-secrets/${secret.id}/attachments`,
+        body: { functionId: fn.id },
+    });
+    console.log(`${LOG} detached "${name}" from ${fnSlug}. Redeploy to unmount.`);
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// apply
+// ---------------------------------------------------------------------------
+function printApplyResult(result) {
+    const { summary, succeeded, failed } = result;
+    console.log(`${LOG} apply: ${summary.succeeded}/${summary.attempted} succeeded, ${summary.failed} failed`);
+    if (succeeded.length > 0) {
+        console.log(`${LOG} succeeded:`);
+        for (const row of succeeded) {
+            console.log(`  ${row.secret} → ${row.function}`);
+        }
+    }
+    if (failed.length > 0) {
+        console.error(`${LOG} failed:`);
+        for (const row of failed) {
+            console.error(`  ${row.secret} → ${row.function}: ${clarifyApplyFailureReason(row.reason)}`);
+        }
+    }
+}
+function resolveApplyKeys({ parsed, manifest, explicitKeys, applyAll, }) {
+    if (explicitKeys.length > 0) {
+        return { keys: explicitKeys, mode: 'explicit --keys' };
+    }
+    if (applyAll) {
+        return {
+            keys: Object.keys(parsed).filter((key) => (parsed[key]?.length ?? 0) > 0),
+            mode: '--all',
+        };
+    }
+    if (manifest) {
+        const keys = manifest.secrets.filter((key) => parsed[key] && parsed[key].length > 0);
+        return {
+            keys,
+            mode: manifest.secrets.length > 0 ? 'manifest secrets ∩ .env' : 'manifest secrets (none declared)',
+        };
+    }
+    return { keys: [], mode: 'none (no manifest)' };
+}
+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]');
+        return 1;
+    }
+    const dir = workDir(args);
+    const envPath = isAbsolute(fromEnvFile) ? fromEnvFile : resolve(dir, fromEnvFile);
+    if (!existsSync(envPath)) {
+        console.error(`${LOG} file not found: ${envPath}`);
+        return 1;
+    }
+    const explicitKeys = parseCommaList(typeof args.flags.keys === 'string' ? args.flags.keys : undefined);
+    const applyAll = flagBool(args.flags, 'all');
+    let functionSlugs = parseCommaList(typeof args.flags.functions === 'string' ? args.flags.functions : undefined);
+    let manifest = null;
+    let manifestReadError = null;
+    try {
+        manifest = await readManifestOptional(dir);
+    }
+    catch (error) {
+        manifestReadError = error;
+    }
+    const fullyExplicitTarget = functionSlugs.length > 0 && (explicitKeys.length > 0 || applyAll);
+    if (manifestReadError && !fullyExplicitTarget) {
+        throw manifestReadError;
+    }
+    if (manifestReadError && fullyExplicitTarget) {
+        console.warn(`${LOG} ignoring invalid ${'managed-function.yml'} in ${dir} because --functions and --keys/--all were provided`);
+    }
+    if (functionSlugs.length === 0) {
+        if (manifest) {
+            functionSlugs = [manifest.function.id];
+        }
+        else {
+            console.error(`${LOG} --functions is required when no ${'managed-function.yml'} is present in ${dir}`);
+            return 1;
+        }
+    }
+    if (!manifest && explicitKeys.length === 0 && !applyAll) {
+        console.error(`${LOG} refusing to apply every key in ${envPath} without managed-function.yml — pass --keys K1,K2 to select secrets, or --all to apply the whole file`);
+        return 1;
+    }
+    const parsed = parseDotenv(await readFile(envPath, 'utf8'));
+    const { keys: selectedKeys, mode: keyMode } = resolveApplyKeys({
+        parsed,
+        manifest,
+        explicitKeys,
+        applyAll,
+    });
+    const entries = selectedKeys
+        .filter((name) => parsed[name] && parsed[name].length > 0)
+        .map((name) => ({ name, value: parsed[name] }));
+    if (explicitKeys.length > 0) {
+        const missing = explicitKeys.filter((key) => !(parsed[key] && parsed[key].length > 0));
+        if (missing.length > 0) {
+            console.warn(`${LOG} --keys not found (or empty) in ${envPath}: ${missing.join(', ')}`);
+        }
+    }
+    if (entries.length === 0) {
+        console.error(`${LOG} nothing to apply — no matching non-empty KEY=VALUE lines in ${envPath}`);
+        if (manifest && manifest.secrets.length > 0 && !applyAll && explicitKeys.length === 0) {
+            console.error(`${LOG} manifest declares [${manifest.secrets.join(', ')}] but none have values in ${envPath}`);
+        }
+        if (manifest && manifest.secrets.length === 0 && !applyAll && explicitKeys.length === 0) {
+            console.error(`${LOG} managed-function.yml declares no secrets — add secrets there, or pass --keys/--all explicitly`);
+        }
+        return 1;
+    }
+    const ctx = await buildContext(args);
+    const shellsToRegister = [];
+    for (const slug of functionSlugs) {
+        const exists = await functionExistsBySlug({ ctx, slug });
+        if (!exists)
+            shellsToRegister.push(slug);
+    }
+    const preview = [
+        `${LOG} secrets apply preview:`,
+        `${LOG}   environment:  ${ctx.env.name}`,
+        `${LOG}   env file:     ${envPath}`,
+        `${LOG}   key selection: ${keyMode}`,
+        `${LOG}   functions:    ${functionSlugs.join(', ')}`,
+        `${LOG}   secrets:      ${entries.map((e) => e.name).join(', ')}`,
+    ];
+    if (shellsToRegister.length > 0) {
+        preview.push(`${LOG}   shell:        will register missing function shell(s): ${shellsToRegister.join(', ')}`);
+    }
+    const confirmed = flagBool(args.flags, 'yes');
+    const ok = await confirmYes({ preview, confirmed });
+    if (!ok)
+        return 1;
+    const unavailableFunctionSlugs = new Set();
+    for (const slug of shellsToRegister) {
+        const title = manifest && manifest.function.id === slug ? manifest.function.title : slug;
+        const description = manifest && manifest.function.id === slug ? (manifest.function.description ?? null) : null;
+        console.log(`${LOG} registering function shell "${slug}" on ${ctx.env.name}`);
+        try {
+            await resolveOrRegisterFunction({ ctx, slug, title, description });
+        }
+        catch (error) {
+            if (error instanceof AtlasApiError && error.status === 409) {
+                const visibleNow = await functionExistsBySlugEventually({ ctx, slug });
+                if (visibleNow) {
+                    // Conflict can happen on a read-after-write race; continue once visible.
+                    console.warn(`${LOG} function shell "${slug}" already exists on ${ctx.env.name}; continuing`);
+                    continue;
+                }
+                // Slug exists but remains unavailable (for example archived or inaccessible).
+                unavailableFunctionSlugs.add(slug);
+                console.warn(`${LOG} function shell "${slug}" already exists but is not available on ${ctx.env.name}; skipping this function`);
+                continue;
+            }
+            throw error;
+        }
+    }
+    const applyFunctionSlugs = functionSlugs.filter((slug) => !unavailableFunctionSlugs.has(slug));
+    if (applyFunctionSlugs.length === 0) {
+        console.error(`${LOG} no available functions remain to apply secrets to on ${ctx.env.name}; check function slugs and access`);
+        return 1;
+    }
+    const result = await postJson({
+        ...clientOptions(ctx),
+        path: '/api/managed-secrets/apply',
+        body: {
+            entries,
+            functionSlugs: applyFunctionSlugs,
+        },
+    });
+    printApplyResult(result);
+    if (result.summary.succeeded === 0)
+        return 1;
+    if (result.summary.failed > 0) {
+        console.log(`${LOG} partial success — redeploy affected functions to mount new values`);
+    }
+    else {
+        console.log(`${LOG} redeploy affected functions to mount new values`);
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// versions / set-default
+// ---------------------------------------------------------------------------
+async function listSecretVersions(ctx, secretId) {
+    const all = [];
+    let cursor;
+    do {
+        const params = new URLSearchParams({ limit: '100' });
+        if (cursor)
+            params.set('cursor', cursor);
+        const { versions, nextCursor } = await getJson({
+            ...clientOptions(ctx),
+            path: `/api/managed-secrets/${secretId}/versions?${params}`,
+        });
+        all.push(...versions);
+        cursor = nextCursor ?? undefined;
+    } while (cursor);
+    return all;
+}
+/** Unpinned attachment slugs, for the set-default confirmation preview. */
+async function attachedFunctionSlugs(ctx, secretId) {
+    const detail = await getJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-secrets/${secretId}`,
+    });
+    const unpinned = detail.attachments.filter((a) => !a.pinnedVersionId);
+    if (unpinned.length === 0)
+        return [];
+    try {
+        const { functions } = await getJson({
+            ...clientOptions(ctx),
+            path: '/api/managed-functions',
+        });
+        const slugById = new Map(functions.map((fn) => [fn.id, fn.slug]));
+        return unpinned.map((a) => slugById.get(a.functionId) ?? a.functionId.slice(0, 8));
+    }
+    catch {
+        // Slug lookup needs managed-functions viewer; set-default only needs secret editor.
+        return unpinned.map((a) => a.functionId.slice(0, 8));
+    }
+}
+export async function secretsVersionsCommand(args) {
+    const name = args.positional[0];
+    if (!name) {
+        console.error('usage: seq-studio secrets versions <NAME> [-e env]');
+        return 1;
+    }
+    const ctx = await buildContext(args);
+    const secret = await resolveSecretByName({ ctx, name });
+    const versions = await listSecretVersions(ctx, secret.id);
+    if (versions.length === 0) {
+        console.log(`${LOG} no versions recorded for "${name}" on ${ctx.env.name}`);
+        return 0;
+    }
+    console.log(`${LOG} ${versions.length} version${versions.length === 1 ? '' : 's'} for "${name}" on ${ctx.env.name}:`);
+    const ambiguousVersions = new Set(versions
+        .filter((v, i, arr) => arr.some((o, j) => j !== i && o.gcpVersion === v.gcpVersion))
+        .map((v) => v.gcpVersion));
+    for (const v of versions) {
+        const idHint = ambiguousVersions.has(v.gcpVersion) ? `  ${v.id}` : '';
+        console.log(`  v${v.gcpVersion}${idHint}  ${v.createdBy}  ${v.createdAt}${v.isActive ? '  (active)' : ''}`);
+    }
+    return 0;
+}
+/**
+ * Point the shared default at a prior version. Editor-tier, same as `set` —
+ * and with the same propagation model: nothing is redeployed, attached
+ * functions are flagged and pick the version up on their own next redeploy.
+ */
+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]');
+        return 1;
+    }
+    const ctx = await buildContext(args);
+    const secret = await resolveSecretByName({ ctx, name });
+    const versions = await listSecretVersions(ctx, secret.id);
+    if (versions.length === 0) {
+        console.error(`${LOG} "${name}" has no recorded versions`);
+        return 1;
+    }
+    const active = versions.find((v) => v.isActive);
+    let target;
+    const versionArg = args.positional[1];
+    if (versionArg) {
+        const resolved = resolveVersionTarget(versions, versionArg);
+        if (resolved.error) {
+            console.error(`${LOG} ${resolved.error}`);
+            return 1;
+        }
+        target = resolved.target;
+        if (!target)
+            return 1;
+        if (target.isActive) {
+            console.error(`${LOG} v${target.gcpVersion} is already the default`);
+            return 1;
+        }
+    }
+    else {
+        target = versions.find((v) => !v.isActive);
+        if (!target) {
+            console.error(`${LOG} no prior version to point the default at`);
+            return 1;
+        }
+    }
+    const slugs = await attachedFunctionSlugs(ctx, secret.id);
+    const activeLabel = active ? `v${active.gcpVersion}` : 'current';
+    const preview = [
+        `${LOG} set-default ${name} ${activeLabel} -> v${target.gcpVersion}`,
+        slugs.length > 0
+            ? `${LOG} nothing redeploys — ${slugs.join(', ')} pick it up on their next redeploy`
+            : `${LOG} no default-tracking functions attached`,
+    ];
+    const ok = await confirmYes({ preview, confirmed: flagBool(args.flags, 'yes') });
+    if (!ok)
+        return 1;
+    const result = await postJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-secrets/${secret.id}/versions/${target.id}/set-default`,
+    });
+    console.log(`${LOG} ${name} default set to v${result.gcpVersion}`);
+    if (result.flagged.length > 0) {
+        console.log(`${LOG} flagged for redeploy: ${result.flagged.map((f) => f.slug).join(', ')} — ` +
+            `redeploy to mount v${result.gcpVersion}`);
+    }
+    return 0;
+}
+/**
+ * Pin one attached function to a specific secret version (sticky — survives
+ * rotations until `--unpin`). Requires editor+ on the secret AND the
+ * function (server-enforced dual-editor gate). Three-way flow mirroring the
+ * UI: pin + redeploy the function's active version / pin only / cancel.
+ */
+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]');
+        return 1;
+    }
+    const ctx = await buildContext(args);
+    const secret = await resolveSecretByName({ ctx, name });
+    const fn = await resolveFunctionBySlug({ ctx, slug: fnSlug });
+    if (flagBool(args.flags, 'unpin')) {
+        const preview = [
+            `${LOG} unpin ${fnSlug} from ${name} — back to the shared default`,
+            `${LOG} redeploy ${fnSlug} afterwards to apply`,
+        ];
+        const ok = await confirmYes({ preview, confirmed: flagBool(args.flags, 'yes') });
+        if (!ok)
+            return 1;
+        const result = await patchJson({
+            ...clientOptions(ctx),
+            path: `/api/managed-secrets/${secret.id}/attachments`,
+            body: { functionId: fn.id, versionId: null },
+        });
+        console.log(`${LOG} ${result.detail}`);
+        return 0;
+    }
+    const versions = await listSecretVersions(ctx, secret.id);
+    if (versions.length === 0) {
+        console.error(`${LOG} "${name}" has no recorded versions to pin`);
+        return 1;
+    }
+    let target;
+    const versionArg = args.positional[1];
+    if (versionArg) {
+        const resolved = resolveVersionTarget(versions, versionArg);
+        if (resolved.error) {
+            console.error(`${LOG} ${resolved.error}`);
+            return 1;
+        }
+        target = resolved.target;
+        if (!target)
+            return 1;
+    }
+    else {
+        target = versions.find((v) => v.isActive);
+        if (!target) {
+            console.error(`${LOG} "${name}" has no default version — pass an explicit version to pin`);
+            return 1;
+        }
+    }
+    const preview = [
+        `${LOG} pin ${fnSlug} to ${name} v${target.gcpVersion} (sticky — survives rotations until --unpin)`,
+    ];
+    const canRedeploy = canAdminFunction(fn);
+    const redeployChoice = await resolvePinRedeployChoice({
+        args,
+        fnSlug,
+        preview,
+        canRedeploy,
+    });
+    if (!redeployChoice.ok)
+        return 1;
+    const { redeploy } = redeployChoice;
+    const result = await patchJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-secrets/${secret.id}/attachments`,
+        body: { functionId: fn.id, versionId: target.id },
+    });
+    console.log(`${LOG} pinned ${fnSlug} to ${name} v${result.gcpVersion}`);
+    if (!redeploy) {
+        console.log(`${LOG} redeploy ${fnSlug} to mount v${result.gcpVersion}`);
+        return 0;
+    }
+    const activeVersionId = await resolveLiveActiveVersionId(ctx, fn.id);
+    if (!activeVersionId) {
+        console.warn(`${LOG} ${fnSlug} has no deployed version — nothing to redeploy`);
+        return 0;
+    }
+    console.log(`${LOG} redeploying ${fnSlug}…`);
+    await postJson({
+        ...clientOptions(ctx),
+        path: `/api/managed-functions/${fn.id}/versions/${activeVersionId}/promote`,
+    });
+    return pollVersion({ ctx, functionId: fn.id, versionId: activeVersionId });
+}
+// ---------------------------------------------------------------------------
+// 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)
+
+  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 <local|staging|production|banksouth>
+         --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
+         pin: [version|version-row-id] (defaults to the current default) · --unpin · --yes (redeploy) · --yes --no-redeploy
+`;
+export async function runSecretsCommand(sub, args) {
+    try {
+        switch (sub) {
+            case 'create':
+                return await secretsCreateCommand(args);
+            case 'set':
+                return await secretsSetCommand(args);
+            case 'list':
+                return await secretsListCommand(args);
+            case 'attach':
+                return await secretsAttachCommand(args);
+            case 'detach':
+                return await secretsDetachCommand(args);
+            case 'apply':
+                return await secretsApplyCommand(args);
+            case 'versions':
+                return await secretsVersionsCommand(args);
+            case 'set-default':
+                return await secretsSetDefaultCommand(args);
+            case 'pin':
+                return await secretsPinCommand(args);
+            case 'help':
+            case '--help':
+            case '-h':
+            case undefined:
+                console.log(SECRETS_USAGE);
+                return sub ? 0 : 1;
+            default:
+                console.error(`unknown secrets command: ${sub}`);
+                console.error(SECRETS_USAGE);
+                return 1;
+        }
+    }
+    catch (error) {
+        printError(error);
+        return 1;
+    }
+}