@sequenceholdings/studio-cli 0.1.9

package/dist/functions/manifest.js

@@ -0,0 +1,586 @@
+import { z } from 'zod';
+/**
+ * CLI-side mirror of the server manifest schema at
+ * atlas/src/server/services/managed-functions/manifest.ts — same pattern
+ * as artifact-studio's duplicated manifest. Keep the two in sync.
+ */
+export const MF_MANIFEST_FILENAME = 'managed-function.yml';
+const SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+/** RFC 1035 label: alnum, optional inner dashes, max 63 chars. */
+const DNS_LABEL_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+/**
+ * CLI-side copy of the server's egress entry validation (see
+ * atlas/src/server/services/managed-functions/egress.ts). Returns the
+ * failure reason, or null when the entry is valid.
+ */
+export function egressEntryError(input) {
+    const raw = input.trim();
+    if (!raw)
+        return 'egress entry is empty';
+    if (looksLikeIpv4EntryCli(raw)) {
+        return egressIpError(raw);
+    }
+    return egressHostError(input);
+}
+const IPV4_OCTET_RE = /^(25[0-5]|2[0-4]\d|1?\d?\d)$/;
+function parseIpv4Cli(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return null;
+    const octets = [];
+    for (const part of parts) {
+        if (!IPV4_OCTET_RE.test(part))
+            return null;
+        octets.push(Number(part));
+    }
+    return octets;
+}
+function looksLikeIpv4EntryCli(raw) {
+    if (raw.includes('://')) {
+        try {
+            return parseIpv4Cli(new URL(raw).hostname) !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    const head = raw.split('/')[0].split(':')[0];
+    return parseIpv4Cli(head) !== null || /^(\d{1,3}\.){3}\d{1,3}\/\d{1,2}$/.test(raw.split(':')[0]);
+}
+function ipv4ToIntCli(octets) {
+    return ((octets[0] << 24) | (octets[1] << 16) | (octets[2] << 8) | octets[3]) >>> 0;
+}
+function intToIpv4Cli(value) {
+    return [
+        (value >>> 24) & 0xff,
+        (value >>> 16) & 0xff,
+        (value >>> 8) & 0xff,
+        value & 0xff,
+    ].join('.');
+}
+function parseCidrCli(cidr) {
+    const slash = cidr.lastIndexOf('/');
+    const ipPart = slash === -1 ? cidr : cidr.slice(0, slash);
+    const prefixPart = slash === -1 ? '32' : cidr.slice(slash + 1);
+    const octets = parseIpv4Cli(ipPart);
+    if (!octets)
+        return null;
+    const prefix = Number(prefixPart);
+    if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32)
+        return null;
+    const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+    const ip = ipv4ToIntCli(octets);
+    if ((ip & ~mask) !== 0)
+        return null;
+    return { network: ip & mask, mask, prefix };
+}
+function cidrContainsCli(outerCidr, innerCidr) {
+    const outer = parseCidrCli(outerCidr);
+    const inner = parseCidrCli(innerCidr);
+    if (!outer || !inner)
+        return false;
+    return inner.prefix >= outer.prefix && (inner.network & outer.mask) === outer.network;
+}
+const RESERVED_CIDRS_CLI = [
+    { cidr: '10.0.0.0/8', reason: 'private (RFC1918)' },
+    { cidr: '172.16.0.0/12', reason: 'private (RFC1918)' },
+    { cidr: '192.168.0.0/16', reason: 'private (RFC1918)' },
+    { cidr: '127.0.0.0/8', reason: 'loopback' },
+    { cidr: '169.254.0.0/16', reason: 'link-local / metadata' },
+    { cidr: '100.64.0.0/10', reason: 'carrier-grade NAT' },
+    { cidr: '0.0.0.0/8', reason: 'reserved' },
+    { cidr: '224.0.0.0/4', reason: 'multicast' },
+    { cidr: '240.0.0.0/4', reason: 'reserved' },
+];
+function normalizeEgressIpCli(input) {
+    const error = egressIpErrorImpl(input);
+    if (error !== null)
+        return { error };
+    const raw = input.trim().toLowerCase();
+    let candidate;
+    if (raw.includes('://')) {
+        candidate = new URL(raw).hostname;
+    }
+    else {
+        const beforePath = raw.split('/');
+        const head = beforePath[0];
+        const bareHost = head.split(':')[0];
+        candidate =
+            beforePath.length > 1 && /^\d{1,2}$/.test(beforePath[1])
+                ? `${bareHost}/${beforePath[1]}`
+                : bareHost;
+    }
+    const slash = candidate.indexOf('/');
+    const ipPart = slash === -1 ? candidate : candidate.slice(0, slash);
+    const prefix = slash === -1 ? 32 : Number(candidate.slice(slash + 1));
+    const normalized = parseCidrCli(`${ipPart}/${prefix}`);
+    if (!normalized)
+        return { error: `egress IP/CIDR is not a valid IPv4 network: ${input}` };
+    return { cidr: `${intToIpv4Cli(normalized.network)}/${prefix}` };
+}
+function egressIpErrorImpl(input) {
+    const raw = input.trim().toLowerCase();
+    let candidate;
+    if (raw.includes('://')) {
+        let url;
+        try {
+            url = new URL(raw);
+        }
+        catch {
+            return `egress entry is not a valid URL: ${input}`;
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return `egress URLs must be http(s): ${input}`;
+        }
+        if (url.port !== '' && url.port !== '80' && url.port !== '443') {
+            return `egress ports other than 80/443 are not supported (the proxy only carries web ports): ${input}`;
+        }
+        candidate = url.hostname;
+    }
+    else {
+        const beforePath = raw.split('/');
+        const head = beforePath[0];
+        const [bareHost, port, ...rest] = head.split(':');
+        if (rest.length > 0)
+            return `egress IP contains unsupported characters: ${input}`;
+        if (port !== undefined && port !== '80' && port !== '443') {
+            return `egress ports other than 80/443 are not supported (the proxy only carries web ports): ${input}`;
+        }
+        if (beforePath.length > 1) {
+            // Anything after the slash must be a bare 1-2 digit prefix — reject
+            // `1.2.3.4/24:8443`, `1.2.3.4/24/x`, etc. rather than silently
+            // dropping the suffix and treating the entry as a /32 (which would
+            // also skip the port 80/443 rejection above). Mirrors the server.
+            if (beforePath.length > 2 || !/^\d{1,2}$/.test(beforePath[1])) {
+                return `egress IP/CIDR is not a valid IPv4 network: ${input}`;
+            }
+            candidate = `${bareHost}/${beforePath[1]}`;
+        }
+        else {
+            candidate = bareHost;
+        }
+    }
+    const slash = candidate.indexOf('/');
+    const ipPart = slash === -1 ? candidate : candidate.slice(0, slash);
+    const prefix = slash === -1 ? 32 : Number(candidate.slice(slash + 1));
+    if (!Number.isInteger(prefix)) {
+        return `egress IP/CIDR is not a valid IPv4 network: ${input}`;
+    }
+    if (prefix < 24) {
+        return `egress CIDR prefix must be /24 or narrower (got /${prefix}): ${input}`;
+    }
+    const normalized = parseCidrCli(`${ipPart}/${prefix}`);
+    if (!normalized) {
+        return `egress IP/CIDR is not a valid IPv4 network: ${input}`;
+    }
+    const canonical = `${intToIpv4Cli(normalized.network)}/${prefix}`;
+    for (const reserved of RESERVED_CIDRS_CLI) {
+        if (cidrContainsCli(reserved.cidr, canonical)) {
+            return `egress IP/CIDR falls in ${reserved.reason} range: ${input}`;
+        }
+    }
+    return null;
+}
+export function egressIpError(input) {
+    const result = normalizeEgressIpCli(input);
+    return 'error' in result ? result.error : null;
+}
+/**
+ * CLI-side copy of the server's normalizeEgressHost validation (see
+ * atlas/src/server/services/managed-functions/egress.ts) so authors get the
+ * same rejection locally at `functions deploy` time instead of a server 400.
+ * Returns the failure reason, or null when the entry is a valid egress host.
+ */
+export function egressHostError(input) {
+    const raw = input.trim().toLowerCase();
+    if (!raw)
+        return 'egress entry is empty';
+    let host;
+    if (raw.includes('://')) {
+        let url;
+        try {
+            url = new URL(raw);
+        }
+        catch {
+            return `egress entry is not a valid URL: ${input}`;
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            return `egress URLs must be http(s): ${input}`;
+        }
+        // The SWP gateway carries ports 80/443 only — any other port would
+        // validate here and then be unreachable at runtime. Fail loudly.
+        if (url.port !== '' && url.port !== '80' && url.port !== '443') {
+            return `egress ports other than 80/443 are not supported (the proxy only carries web ports): ${input}`;
+        }
+        host = url.hostname;
+    }
+    else {
+        const beforePath = raw.split('/')[0];
+        const [bareHost, port, ...rest] = beforePath.split(':');
+        if (rest.length > 0) {
+            return `egress host contains unsupported characters: ${input}`;
+        }
+        if (port !== undefined && port !== '80' && port !== '443') {
+            return `egress ports other than 80/443 are not supported (the proxy only carries web ports): ${input}`;
+        }
+        host = bareHost;
+    }
+    host = host.replace(/\.$/, '');
+    if (host.includes('*')) {
+        return `wildcard hosts are not supported — list each hostname explicitly: ${input}`;
+    }
+    if (!/^[a-z0-9.-]+$/.test(host)) {
+        return `egress host contains unsupported characters: ${input}`;
+    }
+    if (host.length > 253) {
+        return `egress host exceeds 253 characters: ${input}`;
+    }
+    const labels = host.split('.');
+    if (labels.length < 2) {
+        return `egress host must be a fully-qualified domain name (single-label hosts are not allowed): ${input}`;
+    }
+    for (const label of labels) {
+        if (!DNS_LABEL_RE.test(label)) {
+            return `egress host is not a valid DNS name: ${input}`;
+        }
+    }
+    if (/^\d+$/.test(labels[labels.length - 1])) {
+        return `egress entry looks like an IPv4 address — use the IP/CIDR form directly: ${input}`;
+    }
+    return null;
+}
+export const MAX_EGRESS_IP_RANGES = 16;
+/**
+ * Partition a validated manifest egress list into normalized, deduped host
+ * and IP/CIDR sets — mirrors the server's `manifestEgressEntries` split so
+ * CLI output and budgets match what the deploy pipeline enforces.
+ */
+function partitionEgressEntries(entries) {
+    const hosts = new Set();
+    const ipCidrs = new Set();
+    for (const entry of entries) {
+        if (egressEntryError(entry) !== null)
+            continue;
+        if (looksLikeIpv4EntryCli(entry.trim())) {
+            const normalized = normalizeEgressIpCli(entry);
+            if (!('error' in normalized))
+                ipCidrs.add(normalized.cidr);
+            continue;
+        }
+        const raw = entry.trim().toLowerCase();
+        const host = raw.includes('://')
+            ? new URL(raw).hostname.replace(/\.$/, '')
+            : raw.split('/')[0].split(':')[0].replace(/\.$/, '');
+        hosts.add(host);
+    }
+    return { hosts, ipCidrs };
+}
+/**
+ * Normalized, deduped, sorted egress hosts from a validated manifest egress
+ * list — mirrors `manifestEgressHosts` on the server so CLI output matches
+ * what the deploy pipeline enforces.
+ */
+export function manifestEgressHosts(entries) {
+    return [...partitionEgressEntries(entries).hosts].sort();
+}
+/**
+ * Normalized, deduped, sorted egress IP/CIDR ranges from a validated manifest
+ * egress list — mirrors `manifestEgressIpRanges` on the server so CLI output
+ * matches the per-function routes the deploy pipeline creates.
+ */
+export function manifestEgressIpRanges(entries) {
+    return [...partitionEgressEntries(entries).ipCidrs].sort();
+}
+/**
+ * CLI-side copy of the server's SWP sessionMatcher budget check: the whole
+ * egress list compiles into ONE proxy rule matcher (2048-char GCP cap).
+ * Deduped after normalization — the rule builder compiles the deduped host
+ * set, so aliases of one host cost one matcher clause. IP/CIDR entries
+ * bypass the matcher and are capped separately (per-function route count).
+ */
+export function egressBudgetError(entries) {
+    const { hosts, ipCidrs } = partitionEgressEntries(entries);
+    let hostChars = 0;
+    for (const host of hosts) {
+        hostChars += host.length + 16;
+    }
+    if (ipCidrs.size > MAX_EGRESS_IP_RANGES) {
+        return `egress list may include at most ${MAX_EGRESS_IP_RANGES} IP/CIDR entries`;
+    }
+    if (140 + hostChars > 2048) {
+        return (`egress list is too large to compile into a single proxy rule ` +
+            `(combined host length exceeds the 2048-character matcher limit) — ` +
+            `remove entries or shorten hostnames`);
+    }
+    return null;
+}
+// --- Custom Roles & Capabilities (PER-75) --------------------------------
+// CLI-side mirror of the host-agnostic vocabulary at
+// atlas/src/server/services/custom-roles/manifest-block.ts and the
+// function-specific gates at
+// atlas/src/server/services/managed-functions/custom-roles.ts — same
+// keep-in-sync pattern as the rest of this file, so `functions push`
+// reports the exact errors the server would.
+/** Key grammar excludes `_` so the FGA id `custom_role:function_<id>__<key>` can use `__` as delimiter. */
+const CUSTOM_ROLE_KEY_RE = /^[a-z0-9-]+$/;
+const customRoleKeySchema = z.string().min(1).max(64).regex(CUSTOM_ROLE_KEY_RE, 'Role and capability keys must match [a-z0-9-]+');
+const MAX_CUSTOM_ROLE_DEFINITIONS = 50;
+const MAX_CUSTOM_ROLE_CAPABILITIES = 100;
+const customRoleDefinitionSchema = z.object({
+    description: z.string().max(500).optional(),
+    default: z.boolean().default(false),
+    inherits: z.array(customRoleKeySchema).default([]),
+    grants: z.array(customRoleKeySchema).default([]),
+});
+const customRolesBlockSchema = z.object({
+    definitions: z.record(customRoleKeySchema, customRoleDefinitionSchema).default({}),
+    capabilities: z
+        .record(customRoleKeySchema, z.object({ description: z.string().max(500).optional() }))
+        .default({}),
+}).superRefine((block, ctx) => {
+    const roleKeys = Object.keys(block.definitions);
+    const capabilityKeys = new Set(Object.keys(block.capabilities));
+    if (roleKeys.length > MAX_CUSTOM_ROLE_DEFINITIONS) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `At most ${MAX_CUSTOM_ROLE_DEFINITIONS} role definitions are allowed`,
+            path: ['definitions'],
+        });
+    }
+    if (capabilityKeys.size > MAX_CUSTOM_ROLE_CAPABILITIES) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `At most ${MAX_CUSTOM_ROLE_CAPABILITIES} capabilities are allowed`,
+            path: ['capabilities'],
+        });
+    }
+    for (const key of roleKeys) {
+        if (capabilityKeys.has(key)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Key "${key}" is declared as both a role and a capability`,
+                path: ['definitions', key],
+            });
+        }
+    }
+    const roleKeySet = new Set(roleKeys);
+    for (const [roleKey, definition] of Object.entries(block.definitions)) {
+        const seenInherits = new Set();
+        for (const inherited of definition.inherits) {
+            if (seenInherits.has(inherited)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Role "${roleKey}" lists "${inherited}" in inherits more than once`,
+                    path: ['definitions', roleKey, 'inherits'],
+                });
+            }
+            seenInherits.add(inherited);
+            if (!roleKeySet.has(inherited)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Role "${roleKey}" inherits unknown role "${inherited}"`,
+                    path: ['definitions', roleKey, 'inherits'],
+                });
+            }
+        }
+        const seenGrants = new Set();
+        for (const granted of definition.grants) {
+            if (seenGrants.has(granted)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Role "${roleKey}" lists "${granted}" in grants more than once`,
+                    path: ['definitions', roleKey, 'grants'],
+                });
+            }
+            seenGrants.add(granted);
+            if (!capabilityKeys.has(granted)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Role "${roleKey}" grants unknown capability "${granted}"`,
+                    path: ['definitions', roleKey, 'grants'],
+                });
+            }
+        }
+    }
+    // The inherits graph must be a DAG (tri-color DFS, first cycle reported).
+    const state = new Map();
+    const visit = (key, path) => {
+        if (state.get(key) === 'done')
+            return null;
+        if (state.get(key) === 'visiting')
+            return [...path, key];
+        state.set(key, 'visiting');
+        const definition = block.definitions[key];
+        for (const inherited of definition?.inherits ?? []) {
+            if (!roleKeySet.has(inherited))
+                continue;
+            const cycle = visit(inherited, [...path, key]);
+            if (cycle)
+                return cycle;
+        }
+        state.set(key, 'done');
+        return null;
+    };
+    for (const roleKey of roleKeys) {
+        const cycle = visit(roleKey, []);
+        if (cycle) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Role inheritance cycle: ${cycle.join(' -> ')}`,
+                path: ['definitions'],
+            });
+            break;
+        }
+    }
+});
+const CUSTOM_CAPABILITY_PIN_RE = /^(?:org\/)?[a-z0-9-]+$/;
+const MAX_CAPABILITY_PINS = 100;
+const capabilityPinsSchema = z
+    .array(z.string().min(1).max(68).regex(CUSTOM_CAPABILITY_PIN_RE, 'Pins must be "org/<key>" or a bare "<key>" matching [a-z0-9-]+'))
+    .max(MAX_CAPABILITY_PINS)
+    .default([]);
+function parseCapabilityPin(pin) {
+    return pin.startsWith('org/')
+        ? { scope: 'org', key: pin.slice('org/'.length) }
+        : { scope: 'host', key: pin };
+}
+function validateCapabilityPins({ uses, roles, }) {
+    const errors = [];
+    const seen = new Set();
+    const roleKeys = new Set(Object.keys(roles?.definitions ?? {}));
+    for (const pin of uses) {
+        if (seen.has(pin))
+            errors.push(`Pin "${pin}" is listed more than once`);
+        seen.add(pin);
+        const parsed = parseCapabilityPin(pin);
+        if (parsed.scope === 'host' && roleKeys.has(parsed.key)) {
+            errors.push(`Pin "${pin}" references a role — roles are never pinned`);
+        }
+    }
+    return errors;
+}
+const MAX_CAPABILITY_GATES = 20;
+const capabilityGateSchema = z.object({
+    requires: z.string().min(1).max(68).regex(CUSTOM_CAPABILITY_PIN_RE, 'Gate requirements must be "org/<key>" or a bare "<key>" matching [a-z0-9-]+'),
+    when: z.object({
+        field: z.string().min(1).max(128),
+        equals: z.union([z.string().max(256), z.number(), z.boolean()]),
+    }).optional(),
+});
+const capabilityGatesSchema = z
+    .array(capabilityGateSchema)
+    .max(MAX_CAPABILITY_GATES)
+    .default([]);
+function validateCapabilityGates({ gates, uses, roles, }) {
+    const errors = [];
+    const pinSet = new Set(uses);
+    const declaredCapabilities = new Set(Object.keys(roles?.capabilities ?? {}));
+    for (const gate of gates) {
+        const parsed = parseCapabilityPin(gate.requires);
+        const claimable = parsed.scope === 'org'
+            ? pinSet.has(gate.requires)
+            : declaredCapabilities.has(parsed.key) || pinSet.has(parsed.key);
+        if (!claimable) {
+            errors.push(parsed.scope === 'org'
+                ? `Gate requires "${gate.requires}" which is not pinned in capabilities.uses`
+                : `Gate requires "${gate.requires}" which is neither declared in capabilities.roles.capabilities nor pinned in capabilities.uses`);
+        }
+    }
+    return errors;
+}
+export const managedFunctionManifestSchema = z.object({
+    schema_version: z.literal(1).default(1),
+    function: z.object({
+        id: z
+            .string()
+            .min(1)
+            .max(200)
+            .regex(/^[a-z][a-z0-9-]*$/, 'function id must be lowercase letters, digits, and dashes'),
+        title: z.string().min(1).max(255),
+        description: z.string().max(2000).optional(),
+    }),
+    runtime: z.literal('nodejs20').default('nodejs20'),
+    entrypoint: z.string().min(1).max(255).default('handler'),
+    limits: z
+        .object({
+        memory_mb: z.number().int().min(128).max(2048).default(256),
+        timeout_seconds: z.number().int().min(1).max(540).default(60),
+        max_instances: z.number().int().min(1).max(10).default(3),
+        invoke_rate_per_minute: z.number().int().min(1).max(600).default(60),
+    })
+        .default({
+        memory_mb: 256,
+        timeout_seconds: 60,
+        max_instances: 3,
+        invoke_rate_per_minute: 60,
+    }),
+    secrets: z
+        .array(z.string().regex(SECRET_NAME_RE, 'secret names must be UPPER_SNAKE_CASE'))
+        .max(32)
+        .default([]),
+    /**
+     * External hosts the function is allowed to reach (bare hostnames or
+     * http(s) URLs) — the single source of truth for the egress allowlist,
+     * enforced at the network layer. Empty/omitted = no egress at all.
+     */
+    egress: z
+        .array(z.string().min(1).max(255).superRefine((value, ctx) => {
+        const error = egressEntryError(value);
+        if (error !== null) {
+            ctx.addIssue({ code: 'custom', message: error });
+        }
+    }))
+        .max(64)
+        .superRefine((entries, ctx) => {
+        const error = egressBudgetError(entries);
+        if (error !== null) {
+            ctx.addIssue({ code: 'custom', message: error });
+        }
+    })
+        .default([]),
+    input_schema: z.record(z.string(), z.unknown()).optional(),
+    output_schema: z.record(z.string(), z.unknown()).optional(),
+    /**
+     * Custom Roles & Capabilities (PER-75) — declared roles/capabilities,
+     * registry capability pins, and invoke gates. Enforced server-side at
+     * activation and invoke time; validated here so push fails fast.
+     */
+    capabilities: z.object({
+        roles: customRolesBlockSchema.optional(),
+        uses: capabilityPinsSchema,
+        gates: capabilityGatesSchema,
+        /**
+         * ORM Data API consumer reach, grouped by namespace: the `tables` this
+         * function may read, the `actions` it may invoke, and whether raw `query`
+         * (arbitrary read SQL over the namespace) is allowed — all ON BEHALF OF the
+         * invoking user. The invoke proxy mints a short-lived token scoped to
+         * exactly these refs; the Data API re-resolves the user's claims per call,
+         * so declaring a table never widens what the user could see. Writes go
+         * through declared actions only — raw table writes don't exist.
+         *
+         * Mirrors atlas/src/server/services/managed-functions/manifest.ts — must
+         * stay in sync so `seq-studio` doesn't strip the block before deploy.
+         */
+        data: z
+            .record(z.string().regex(/^[a-z][a-z0-9_]{0,40}$/, 'capabilities.data keys are ORM namespace names'), z.object({
+            tables: z.array(z.string().regex(/^[a-z_][a-z0-9_]*$/, 'table names')).max(64).default([]),
+            actions: z.array(z.string().regex(/^[a-z_][a-z0-9_]*$/, 'action names')).max(64).default([]),
+            query: z.boolean().default(false),
+        }))
+            .default({}),
+    }).default({ uses: [], gates: [], data: {} }),
+}).superRefine((manifest, ctx) => {
+    for (const message of validateCapabilityPins({
+        uses: manifest.capabilities.uses,
+        roles: manifest.capabilities.roles,
+    })) {
+        ctx.addIssue({ code: 'custom', message, path: ['capabilities', 'uses'] });
+    }
+    for (const message of validateCapabilityGates({
+        gates: manifest.capabilities.gates,
+        uses: manifest.capabilities.uses,
+        roles: manifest.capabilities.roles,
+    })) {
+        ctx.addIssue({ code: 'custom', message, path: ['capabilities', 'gates'] });
+    }
+});

package/dist/functions/secret-reconcile.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Pure secret classifier for deploy-time reconciliation.
+ *
+ * This module performs no IO. The caller fetches the inputs (manifest,
+ * parsed .env, server secret list, current function attachments) and
+ * passes them here to get a categorised view that drives the deploy
+ * preview and the reconcile step.
+ */
+export interface ServerSecretInfo {
+    /** Server-side managed-secret id. */
+    id: string;
+    /** Whether a default value has been stored in GCP Secret Manager. */
+    hasDefaultValue: boolean;
+    /** Total number of function attachments for this secret across the org. */
+    attachmentCount: number;
+}
+export type SecretCategory = 'UPLOAD_NEW' | 'OVERWRITE' | 'USE_EXISTING' | 'BLOCKED';
+export interface ClassifiedSecret {
+    name: string;
+    category: SecretCategory;
+    /** Whether this secret is already attached to the target function. */
+    attachedToFn: boolean;
+    /**
+     * The server-side secret id — null when the secret does not yet exist
+     * on the server (UPLOAD_NEW). Required for USE_EXISTING attach-only path.
+     */
+    secretId: string | null;
+    /** Total function attachments on the server (0 when secret doesn't exist). */
+    attachmentCount: number;
+}
+export interface SecretClassification {
+    /** All satisfiable secrets in manifest declaration order. */
+    secrets: ClassifiedSecret[];
+    /** Secrets that cannot be satisfied — deploy must abort if non-empty. */
+    blocked: ClassifiedSecret[];
+}
+/** Partial shape of POST /api/managed-secrets/apply response. */
+export interface ApplySecretsResult {
+    summary: {
+        attempted: number;
+        succeeded: number;
+        failed: number;
+    };
+    succeeded: Array<{
+        secret: string;
+        function: string;
+    }>;
+    failed: Array<{
+        secret: string;
+        function: string;
+        reason: string;
+    }>;
+}
+/**
+ * Categorise each manifest-declared secret into one of four states:
+ *
+ * UPLOAD_NEW   — in .env, no server default → create + set + attach via /apply
+ * OVERWRITE    — in .env, server default exists → overwrite + attach if missing via /apply
+ * USE_EXISTING — not in .env, server default exists → attach only (no value change)
+ * BLOCKED      — not in .env, no server default → unsatisfiable; deploy must abort
+ */
+export declare function classifySecrets({ manifestSecrets, envValues, serverInfoByName, attachedByEnvVar, }: {
+    manifestSecrets: string[];
+    envValues: Record<string, string>;
+    serverInfoByName: Map<string, ServerSecretInfo>;
+    /**
+     * Map from env var name to the secretId of the secret currently attached to
+     * this function. Using the id (not just the name) prevents mistaking a
+     * different secret that occupies the same env var as the correct attachment.
+     */
+    attachedByEnvVar: Map<string, string>;
+}): SecretClassification;
+/**
+ * Build the preview lines for the secrets section of the deploy preview.
+ *
+ * @param log  The LOG prefix string (e.g. '[seq-studio]').
+ * @param secrets  Non-BLOCKED classified secrets.
+ */
+export declare function buildSecretPreviewLines(log: string, secrets: ClassifiedSecret[]): string[];