@sequenceholdings/studio-cli 0.1.9

package/dist/cli-errors.js

@@ -0,0 +1,78 @@
+import { AtlasApiError } from './atlas-client.js';
+export const LOG = '[seq-studio]';
+/** Map common apply failure reasons to clearer copy (original reason is preserved). */
+export function clarifyApplyFailureReason(reason) {
+    const hints = [
+        [
+            /^Function not found$/,
+            'Function shell not registered — run secrets apply from a function directory or deploy first',
+        ],
+        [
+            /^acknowledgeSharedDefault required/,
+            'Secret already has a shared default — re-run and confirm at the prompt',
+        ],
+        [
+            /^Admin access required on function$/,
+            'You need admin access on the target function',
+        ],
+        [
+            /^Editor access required on secret$/,
+            'You need editor access on the secret (or create permission for new secrets)',
+        ],
+        [
+            /secret_creator required/,
+            'Ask your org admin for secret_creator on the managed scope, or use secrets create first',
+        ],
+        [
+            /function_creator required/,
+            'Ask your org admin for function_creator on the managed scope before creating a function',
+        ],
+    ];
+    for (const [pattern, hint] of hints) {
+        if (pattern.test(reason))
+            return `${reason} — ${hint}`;
+    }
+    return reason;
+}
+function nextStepForAtlasError(error) {
+    const msg = error.message.toLowerCase();
+    if (error.status === 401) {
+        return 'Next step: run `seqapi login` and retry.';
+    }
+    if (error.status === 403) {
+        return 'Next step: confirm `-e` targets the right environment and you have the required access grant.';
+    }
+    if (error.status === 404 && msg.includes('function')) {
+        return 'Next step: run `seq-studio functions list -e <env>` and confirm `managed-function.yml` `function.id` matches a remote slug.';
+    }
+    if (error.status === 409 && msg.includes('version')) {
+        return 'Next step: rerun deploy — another upload may have taken the version slot.';
+    }
+    if (error.status === 413 || msg.includes('too large')) {
+        return 'Next step: run `seq-studio functions build` and reduce bundle size or dependencies.';
+    }
+    if (error.status === 503) {
+        return 'Next step: wait a few seconds and retry (backend may still be warming up).';
+    }
+    if (error.status === 524 || msg.includes('timeout') || msg.includes('timed out')) {
+        return 'Next step: retry; if it persists check VPN/network, then `seq-studio functions list` or logs to see whether the operation completed.';
+    }
+    return null;
+}
+export function formatCliError(error) {
+    if (error instanceof AtlasApiError) {
+        const lines = [`${LOG} ${error.status}${error.statusText ? ` ${error.statusText}` : ''}: ${error.message}`];
+        if (error.path)
+            lines.push(`${LOG} request: ${error.path}`);
+        const next = nextStepForAtlasError(error);
+        if (next)
+            lines.push(`${LOG} ${next}`);
+        return lines;
+    }
+    return [`${LOG} ${error instanceof Error ? error.message : String(error)}`];
+}
+export function printCliError(error) {
+    for (const line of formatCliError(error)) {
+        console.error(line);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `--env preview:<branch-or-slug>` targets a per-PR Vercel preview deployment
+ * without a config.toml entry. The slug after the prefix is run through the
+ * canonical branch→slug transform (see `preview.ts`). PR-number resolution and
+ * the Cloudflare WAF bypass header live in `artifact/delegate.ts`.
+ */
+export declare const PREVIEW_ENV_PREFIX = "preview:";
+export declare const ENV_NAMES: string[];
+export interface LatticeConfig {
+    envs: Record<string, {
+        url: string;
+    }>;
+    defaultEnv: string;
+}
+export declare function globalConfigDir(): string;
+export declare function configPath(): string;
+export declare function defaultConfig(): LatticeConfig;
+/**
+ * Read the config from disk. If the file does not exist, return defaults
+ * — no auto-write, since seq-studio should work out of the box without
+ * any state on disk. The user can run `seq-studio config init` (future)
+ * if they want a customizable file.
+ *
+ * User-supplied envs are merged on top of the built-ins, so an override
+ * for `local` (say, pointing at a different port) takes effect, and net
+ * new envs (e.g. `staging-2`) are picked up.
+ */
+export declare function readConfig(): Promise<LatticeConfig>;
+/** Write the config to disk, creating the dir if missing. */
+export declare function writeConfig(config: LatticeConfig): Promise<void>;
+export interface ResolvedEnv {
+    name: string;
+    url: string;
+}
+/**
+ * Resolve `--env <name>` against the user's config. Falls back to the
+ * config's `defaultEnv` when no name is passed. Throws a clear error
+ * when the name does not match any known env so users see a list of
+ * what's available rather than a confusing 404 later.
+ */
+export declare function resolveEnv({ config, requested, }: {
+    config: LatticeConfig;
+    requested?: string;
+}): ResolvedEnv;

package/dist/config.js

@@ -0,0 +1,103 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { resolvePreviewFromSlug } from './preview.js';
+/**
+ * `--env preview:<branch-or-slug>` targets a per-PR Vercel preview deployment
+ * without a config.toml entry. The slug after the prefix is run through the
+ * canonical branch→slug transform (see `preview.ts`). PR-number resolution and
+ * the Cloudflare WAF bypass header live in `artifact/delegate.ts`.
+ */
+export const PREVIEW_ENV_PREFIX = 'preview:';
+/**
+ * Environment URLs match the existing seqapi + artifact-studio mapping so
+ * an engineer's mental model is the same across all three tools. `local`
+ * is the dev / `make dev-all` URL — kept named `local` (not `dev`) so it
+ * lines up with `seqapi -e local` and `artifact-studio --env local`.
+ */
+const BUILT_IN_ENV_URLS = {
+    local: 'http://localhost:5001',
+    staging: 'https://staging.atlas.seqholdings.com',
+    production: 'https://atlas.seqholdings.com',
+    banksouth: 'https://banksouth.seqholdings.com',
+};
+export const ENV_NAMES = Object.keys(BUILT_IN_ENV_URLS);
+export function globalConfigDir() {
+    return join(homedir(), '.config', 'lattice');
+}
+export function configPath() {
+    return join(globalConfigDir(), 'config.toml');
+}
+export function defaultConfig() {
+    const envs = {};
+    for (const [name, url] of Object.entries(BUILT_IN_ENV_URLS)) {
+        envs[name] = { url };
+    }
+    return { envs, defaultEnv: 'local' };
+}
+/**
+ * Read the config from disk. If the file does not exist, return defaults
+ * — no auto-write, since seq-studio should work out of the box without
+ * any state on disk. The user can run `seq-studio config init` (future)
+ * if they want a customizable file.
+ *
+ * User-supplied envs are merged on top of the built-ins, so an override
+ * for `local` (say, pointing at a different port) takes effect, and net
+ * new envs (e.g. `staging-2`) are picked up.
+ */
+export async function readConfig() {
+    const path = configPath();
+    if (!existsSync(path))
+        return defaultConfig();
+    const raw = parseToml(await readFile(path, 'utf8'));
+    const merged = defaultConfig();
+    if (raw.env) {
+        for (const [name, value] of Object.entries(raw.env)) {
+            if (typeof value?.url === 'string') {
+                merged.envs[name] = { url: value.url };
+            }
+        }
+    }
+    if (typeof raw.default_env === 'string') {
+        merged.defaultEnv = raw.default_env;
+    }
+    return merged;
+}
+/** Write the config to disk, creating the dir if missing. */
+export async function writeConfig(config) {
+    const path = configPath();
+    await mkdir(dirname(path), { recursive: true });
+    // smol-toml's stringify can't accept arbitrary nested keys via the
+    // `env.<name>` syntax directly; we build it manually for stable
+    // ordering and clean output.
+    const lines = [];
+    for (const [name, value] of Object.entries(config.envs)) {
+        lines.push(`[env.${name}]`);
+        lines.push(`url = ${stringifyToml({ url: value.url }).trim().replace(/^url = /, '')}`);
+        lines.push('');
+    }
+    lines.push(`default_env = "${config.defaultEnv}"`);
+    await writeFile(path, lines.join('\n') + '\n', { encoding: 'utf8', mode: 0o600 });
+}
+/**
+ * Resolve `--env <name>` against the user's config. Falls back to the
+ * config's `defaultEnv` when no name is passed. Throws a clear error
+ * when the name does not match any known env so users see a list of
+ * what's available rather than a confusing 404 later.
+ */
+export function resolveEnv({ config, requested, }) {
+    const name = requested ?? config.defaultEnv;
+    if (name.startsWith(PREVIEW_ENV_PREFIX)) {
+        const { slug, url } = resolvePreviewFromSlug(name.slice(PREVIEW_ENV_PREFIX.length));
+        return { name: `${PREVIEW_ENV_PREFIX}${slug}`, url };
+    }
+    const env = config.envs[name];
+    if (!env) {
+        const known = Object.keys(config.envs).join(', ');
+        throw new Error(`Unknown env "${name}". Known envs: ${known}. ` +
+            `Pass --env <name> or set default_env in ${configPath()}.`);
+    }
+    return { name, url: env.url };
+}

package/dist/env-flags.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Shared argv env-flag handling for delegate namespaces. Delegated package
+ * CLIs only recognize the two-token `--env <value>` form, so every `-e value`
+ * / `-e=value` / `--env=value` spelling is rewritten before forwarding.
+ */
+export declare function normalizeShortEnvFlag(argv: readonly string[]): string[];
+/** Only valid AFTER normalizeShortEnvFlag — recognizes the two-token form. */
+export declare function readEnvFromArgv(rest: readonly string[]): string | undefined;

package/dist/env-flags.js

@@ -0,0 +1,47 @@
+/**
+ * Shared argv env-flag handling for delegate namespaces. Delegated package
+ * CLIs only recognize the two-token `--env <value>` form, so every `-e value`
+ * / `-e=value` / `--env=value` spelling is rewritten before forwarding.
+ */
+export function normalizeShortEnvFlag(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '-e' || arg === '--env') {
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                out.push('--env', next);
+                i += 1;
+            }
+            else {
+                out.push('--env');
+            }
+        }
+        else if (arg.startsWith('-e=')) {
+            out.push('--env', arg.slice('-e='.length));
+        }
+        else if (arg.startsWith('--env=')) {
+            out.push('--env', arg.slice('--env='.length));
+        }
+        else {
+            out.push(arg);
+        }
+    }
+    return out;
+}
+/** Only valid AFTER normalizeShortEnvFlag — recognizes the two-token form. */
+export function readEnvFromArgv(rest) {
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (!arg)
+            continue;
+        if (arg === '--env') {
+            const next = rest[i + 1];
+            if (next && !next.startsWith('-'))
+                return next;
+        }
+    }
+    return undefined;
+}

package/dist/functions/bundle.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Local bundle collection for `seq-studio functions deploy`. The CLI
+ * ALWAYS excludes dotenv files (the server rejects them as a backstop),
+ * plus node_modules (vendored server-side), VCS metadata, and .npmrc
+ * (the registry is pinned server-side). Pnpm hook files are kept in the
+ * collected file list so local validation can hard-fail before upload.
+ */
+export interface LocalBundleFile {
+    path: string;
+    content: string;
+    encoding: 'utf8' | 'base64';
+}
+export interface CollectResult {
+    files: LocalBundleFile[];
+    excludedEnvFiles: string[];
+}
+export declare function collectBundleFiles(rootDir: string): Promise<CollectResult>;
+export interface LocalValidationIssue {
+    level: 'error' | 'warning' | 'info';
+    message: string;
+}
+/**
+ * Pre-flight checks mirroring the server's bundle validation so engineers
+ * get fast local feedback instead of a 400 after uploading.
+ */
+export declare function validateLocalBundle({ rootDir, files, }: {
+    rootDir: string;
+    files: LocalBundleFile[];
+}): Promise<LocalValidationIssue[]>;
+export declare function isDirectory(path: string): Promise<boolean>;

package/dist/functions/bundle.js

@@ -0,0 +1,137 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { classifyLockfileOrigin } from './lockfile-origin.js';
+const ENV_FILE_RE = /^\.env(\..*)?$/;
+const PNPM_HOOK_FILE_RE = /^\.?pnpmfile\.cjs$/;
+// Mirrors the server: a pnpm-workspace.yaml defines catalog/workspace
+// indirection that can resolve deps outside Chainguard on the no-lockfile path.
+const PNPM_WORKSPACE_FILE_RE = /^pnpm-workspace\.ya?ml$/;
+const EXCLUDED_DIRS = new Set(['node_modules', '.git', '.idea', '.vscode', 'dist', 'build']);
+const EXCLUDED_FILES = new Set(['.npmrc', '.DS_Store']);
+function isProbablyBinary(buffer) {
+    const probe = buffer.subarray(0, 8192);
+    return probe.includes(0);
+}
+export async function collectBundleFiles(rootDir) {
+    const files = [];
+    const excludedEnvFiles = [];
+    const walk = async (dir) => {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            const rel = relative(rootDir, full).replace(/\\/g, '/');
+            if (entry.isDirectory()) {
+                if (EXCLUDED_DIRS.has(entry.name))
+                    continue;
+                await walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue; // symlinks etc. are skipped
+            if (ENV_FILE_RE.test(entry.name)) {
+                excludedEnvFiles.push(rel);
+                continue;
+            }
+            if (EXCLUDED_FILES.has(entry.name) || entry.name.endsWith('.log'))
+                continue;
+            const buffer = await readFile(full);
+            if (isProbablyBinary(buffer)) {
+                files.push({ path: rel, content: buffer.toString('base64'), encoding: 'base64' });
+            }
+            else {
+                files.push({ path: rel, content: buffer.toString('utf8'), encoding: 'utf8' });
+            }
+        }
+    };
+    await walk(rootDir);
+    return { files, excludedEnvFiles };
+}
+/**
+ * Pre-flight checks mirroring the server's bundle validation so engineers
+ * get fast local feedback instead of a 400 after uploading.
+ */
+export async function validateLocalBundle({ rootDir, files, }) {
+    const issues = [];
+    const paths = new Set(files.map((f) => f.path));
+    const lockfile = files.find((f) => f.path === 'pnpm-lock.yaml');
+    if (!lockfile) {
+        if (existsSync(join(rootDir, 'package-lock.json')) || existsSync(join(rootDir, 'yarn.lock'))) {
+            issues.push({
+                level: 'warning',
+                message: 'Found a non-pnpm lockfile (package-lock.json / yarn.lock). It is ignored — the deploy worker resolves dependencies against Chainguard, Sequence\'s internal registry. With Chainguard credentials, `pnpm install` produces a pinned lockfile for a faster deploy; without them this is fine as-is.',
+            });
+        }
+        else {
+            issues.push({
+                level: 'info',
+                message: 'No pnpm-lock.yaml — the deploy worker will resolve dependencies against Chainguard, Sequence\'s internal registry. With Chainguard credentials, `pnpm install` produces a pinned lockfile for a faster deploy; without them this is fine as-is.',
+            });
+        }
+    }
+    else {
+        const lockfileText = lockfile.encoding === 'base64'
+            ? Buffer.from(lockfile.content, 'base64').toString('utf8')
+            : lockfile.content;
+        if (classifyLockfileOrigin(lockfileText) !== 'chainguard') {
+            issues.push({
+                level: 'warning',
+                message: 'pnpm-lock.yaml was not resolved against Chainguard — the deploy worker will discard it and re-resolve (slower, and versions may differ). This is expected without Chainguard credentials; with them, regenerate against Chainguard (registry=https://libraries.cgr.dev/javascript/) for a fast, pinned deploy.',
+            });
+        }
+    }
+    if (!paths.has('package.json')) {
+        issues.push({ level: 'error', message: 'Missing package.json.' });
+    }
+    else {
+        try {
+            const raw = await readFile(join(rootDir, 'package.json'), 'utf8');
+            const pkg = JSON.parse(raw);
+            if (!pkg.dependencies?.['@google-cloud/functions-framework']) {
+                issues.push({
+                    level: 'error',
+                    message: 'package.json must declare @google-cloud/functions-framework as a dependency (pnpm add @google-cloud/functions-framework).',
+                });
+            }
+        }
+        catch {
+            issues.push({ level: 'error', message: 'package.json is not valid JSON.' });
+        }
+    }
+    const hookFiles = files.filter((file) => {
+        const segments = file.path.split('/');
+        return PNPM_HOOK_FILE_RE.test(segments[segments.length - 1] ?? '');
+    });
+    for (const file of hookFiles) {
+        issues.push({
+            level: 'error',
+            message: `${file.path} is not allowed — pnpm hook files execute during install in the deploy worker.`,
+        });
+    }
+    const workspaceFiles = files.filter((file) => {
+        const segments = file.path.split('/');
+        return PNPM_WORKSPACE_FILE_RE.test(segments[segments.length - 1] ?? '');
+    });
+    for (const file of workspaceFiles) {
+        issues.push({
+            level: 'error',
+            message: `${file.path} is not allowed — pnpm-workspace.yaml defines catalog/workspace indirection that can resolve dependencies outside Chainguard.`,
+        });
+    }
+    const totalBytes = files.reduce((sum, f) => sum + Buffer.byteLength(f.content, f.encoding === 'base64' ? 'base64' : 'utf8'), 0);
+    if (totalBytes > 25 * 1024 * 1024) {
+        issues.push({
+            level: 'error',
+            message: `Bundle is ${(totalBytes / 1024 / 1024).toFixed(1)} MiB unpacked — the limit is 25 MiB.`,
+        });
+    }
+    return issues;
+}
+export async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/functions/commands.d.ts

@@ -0,0 +1,86 @@
+import { type ResolvedEnv } from '../config.js';
+import type { ParsedArgs } from '../process/commands.js';
+import { type ManagedFunctionManifest } from './manifest.js';
+import { type SourceSpec } from '@sequenceholdings/artifact-studio/source-resolver';
+export declare const LOG = "[seq-studio]";
+export interface FunctionSummary {
+    id: string;
+    slug: string;
+    title: string;
+    description: string | null;
+    runtime: string;
+    activeVersionId?: string | null;
+    deployed: boolean;
+    secretsNeedDeploy?: boolean;
+    currentUserAccess: string | null;
+    canInvoke: boolean;
+    updatedAt?: string;
+    egressHosts?: string[];
+    egressIpRanges?: string[];
+    egressEnforced?: boolean;
+}
+export interface VersionSummary {
+    id: string;
+    functionId: string;
+    version: string;
+    status: string;
+    statusDetail: string | null;
+    deployMessage: string | null;
+    createdAt: string;
+    deployedAt: string | null;
+    isActive: boolean;
+}
+export declare function flagBool(flags: ParsedArgs['flags'], ...keys: string[]): boolean;
+export interface CommandContext {
+    env: ResolvedEnv;
+    token: string;
+}
+export declare function buildContext(args: ParsedArgs): Promise<CommandContext>;
+export declare function clientOptions(ctx: CommandContext): {
+    baseUrl: string;
+    token: string;
+};
+export declare function readManifestOptional(dir: string): Promise<ManagedFunctionManifest | null>;
+export declare function workDir(args: ParsedArgs): string;
+/**
+ * Source selection for build/deploy: --dir (local, default '.'), a platform
+ * git-service repo (--repo <ns>/<name>), or any git URL (--git-url <url>);
+ * --ref picks a branch/tag/commit. Reuses the artifact-studio resolver —
+ * functions name their local dir with --dir rather than a positional, so map
+ * it onto the spec parser's positional slot.
+ */
+export declare function parseFunctionsSourceSpec(args: ParsedArgs): SourceSpec;
+export declare function resolveOrRegisterFunction({ ctx, slug, title, description, }: {
+    ctx: CommandContext;
+    slug: string;
+    title: string;
+    description?: string | null;
+}): Promise<{
+    fn: FunctionSummary;
+    created: boolean;
+}>;
+export declare function predictNextVersion(latest: string | undefined): string;
+/** Prompt on the TTY with echo suppressed — secret values are never displayed. */
+export declare function promptHidden(question: string): Promise<string>;
+export declare function printError(error: unknown): void;
+export declare function functionsInitCommand(args: ParsedArgs): Promise<number>;
+export declare function functionsBuildCommand(args: ParsedArgs): Promise<number>;
+export declare function functionsDeployCommand(args: ParsedArgs): Promise<number>;
+export declare function pollVersion({ ctx, functionId, versionId, egressNote, }: {
+    ctx: CommandContext;
+    functionId: string;
+    versionId: string;
+    /** Print the egress-propagation hint once the version is live. */
+    egressNote?: boolean;
+}): Promise<number>;
+export declare function functionsListCommand(args: ParsedArgs): Promise<number>;
+export declare function functionsShowCommand(args: ParsedArgs): Promise<number>;
+export declare function functionsLogsCommand(args: ParsedArgs): Promise<number>;
+export declare function resolveLiveActiveVersionId(ctx: CommandContext, functionId: string): Promise<string | null>;
+export declare function functionsPromoteCommand(args: ParsedArgs): Promise<number>;
+export declare function functionsRollbackCommand(args: ParsedArgs): Promise<number>;
+/** Minimal dotenv parser — KEY=VALUE lines, quotes stripped, comments skipped. */
+export declare function parseDotenv(content: string): Record<string, string>;
+export declare function functionsDeleteCommand(args: ParsedArgs): Promise<number>;
+export declare const FUNCTIONS_USAGE = "usage:\n  seq-studio functions init <dir>                     scaffold manifest + TypeScript hello-world handler\n  seq-studio functions build [--dir d]                local pre-flight (manifest, lockfile, size)\n  seq-studio functions deploy [-e env] [-m msg]       preview + confirm secrets + upload and deploy\n  seq-studio functions list [-e env] [--match-local]  functions visible on the environment\n  seq-studio functions show [-e env] [--fn slug]      detail for one function (versions, secrets)\n  seq-studio functions logs [-e env] [--limit N] [--since t]  Cloud Logging snapshot (reader-gated)\n  seq-studio functions promote <version> [-e env]     make a version live\n  seq-studio functions rollback [<version>] [-e env]  redeploy a prior version\n  seq-studio functions delete [--yes]                 archive function + tear down GCP resources\n                                                      (version history is retained)\n\n  Flags: -e/--env <local|staging|production|banksouth|preview:<slug>> \u00B7 --fn <slug> \u00B7 --dir <path>\n         --from-env-file <path>  (default: .env) source file for secret values\n         --no-wait \u00B7 --yes\n         --no-provision  (deploy) update-only: error instead of registering a new\n                         shell, writing secret values, or attaching secrets (CI sweep)\n\n  Source for build/deploy: a local --dir (default .), a platform git-service\n  repo (--repo <ns>/<name>), or any git URL (--git-url <url>). --ref selects a\n  branch/tag/commit (default: the repo's default branch). Remote sources record\n  the pinned commit as provenance (never dirty) and NEVER read a repo-committed\n  .env for secret values \u2014 provision secrets server-side or pass a local\n  --from-env-file (resolved against your cwd).\n\n  --repo clones over smart-HTTP and REQUIRES a git PAT in ATLAS_GIT_PAT\n  (repo:read scope \u2014 `seq-studio auth pat create --scopes repo:read`, or\n  Atlas \u2192 Settings \u2192 Tokens). It's the same token you clone the repo with;\n  --env + seqapi login are still needed to resolve the repo and deploy.\n";
+export declare function runFunctionsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;