@sequenceholdings/studio-cli 0.1.9

package/dist/functions/secret-reconcile.js

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function classifySecrets({ manifestSecrets, envValues, serverInfoByName, attachedByEnvVar, }) {
+    const secrets = [];
+    const blocked = [];
+    const seen = new Set();
+    for (const name of manifestSecrets) {
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        const inEnv = Boolean(envValues[name]?.length);
+        const serverInfo = serverInfoByName.get(name);
+        const serverHasDefault = Boolean(serverInfo?.hasDefaultValue);
+        // Only count as attached when the env var is mapped to this exact secret.
+        const attachedToFn = serverInfo !== undefined && attachedByEnvVar.get(name) === serverInfo.id;
+        const secretId = serverInfo?.id ?? null;
+        const attachmentCount = serverInfo?.attachmentCount ?? 0;
+        let category;
+        if (inEnv && !serverHasDefault) {
+            category = 'UPLOAD_NEW';
+        }
+        else if (inEnv && serverHasDefault) {
+            category = 'OVERWRITE';
+        }
+        else if (!inEnv && serverHasDefault) {
+            category = 'USE_EXISTING';
+        }
+        else {
+            category = 'BLOCKED';
+        }
+        const entry = { name, category, attachedToFn, secretId, attachmentCount };
+        if (category === 'BLOCKED') {
+            blocked.push(entry);
+        }
+        else {
+            secrets.push(entry);
+        }
+    }
+    return { secrets, blocked };
+}
+/**
+ * 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 function buildSecretPreviewLines(log, secrets) {
+    if (secrets.length === 0) {
+        return [`${log}   secrets: (none declared)`];
+    }
+    const lines = [`${log}   secrets:`];
+    for (const c of secrets) {
+        let desc;
+        if (c.category === 'UPLOAD_NEW') {
+            desc = 'new — will upload from .env and attach';
+        }
+        else if (c.category === 'OVERWRITE') {
+            // Compute how many OTHER functions the existing default serves.
+            const otherCount = c.attachmentCount - (c.attachedToFn ? 1 : 0);
+            const sharedNote = otherCount > 0 ? ` — also used by ${otherCount} other function(s)` : '';
+            desc = `will overwrite existing default${sharedNote}`;
+        }
+        else {
+            // USE_EXISTING
+            desc = c.attachedToFn
+                ? 'uses existing default, no change'
+                : 'uses existing default, linking to function (value unchanged)';
+        }
+        lines.push(`${log}     - ${c.name}: ${desc}`);
+    }
+    return lines;
+}

package/dist/main.d.ts

@@ -0,0 +1,14 @@
+/**
+ * seq-studio argv router.
+ *
+ * Top-level commands:
+ *   seq-studio process <sub>      manage Lattice processes
+ *   seq-studio artifact <sub>     manage Artifact Studio apps
+ *   seq-studio functions <sub>    manage Managed Functions
+ *   seq-studio secrets <sub>      manage org-owned Managed Secrets
+ *   seq-studio repos <sub>        manage platform git-service repos
+ *   seq-studio auth <sub>         manage git-service PATs
+ *   seq-studio doctor             check token + env + writer gate
+ *   seq-studio help               show usage
+ */
+export declare function run(argv?: string[]): Promise<number>;

package/dist/main.js

@@ -0,0 +1,129 @@
+/**
+ * seq-studio argv router.
+ *
+ * Top-level commands:
+ *   seq-studio process <sub>      manage Lattice processes
+ *   seq-studio artifact <sub>     manage Artifact Studio apps
+ *   seq-studio functions <sub>    manage Managed Functions
+ *   seq-studio secrets <sub>      manage org-owned Managed Secrets
+ *   seq-studio repos <sub>        manage platform git-service repos
+ *   seq-studio auth <sub>         manage git-service PATs
+ *   seq-studio doctor             check token + env + writer gate
+ *   seq-studio help               show usage
+ */
+import { parseArgs } from './process/commands.js';
+import { applyCommand, bundleCommand, doctorCommand, initCommand, lintCommand, planCommand, promoteCommand, pullCommand, simulateCommand, testCommand, } from './process/commands.js';
+// Lazy-load artifact delegate: published @sequenceholdings/artifact-studio/cli
+// still auto-runs runCli() at module load; importing it here breaks doctor/process.
+const TOP_LEVEL_USAGE = `usage:
+  seq-studio process <sub> [args]    lint | plan | apply | test | simulate | bundle | init
+  seq-studio artifact <sub> [args]   init | build | plan | deploy | dev | list | show | pull | promote | rollback
+  seq-studio functions <sub> [args]  init | build | deploy | list | show | logs | promote | rollback | delete
+  seq-studio secrets <sub> [args]    create | set | list | attach | detach | apply
+  seq-studio repos <sub> [args]      list | namespaces | show | create | clone | pull | delete
+  seq-studio auth <sub> [args]       pat create | pat list | pat revoke
+  seq-studio orm <sub> [args]        init | validate | plan | apply
+  seq-studio doctor [-e <env>]       diagnose config, auth, and writer gate
+  seq-studio help                    show this message
+
+  Authenticate with: seqapi login
+  Env URLs come from ~/.config/lattice/config.toml (built-ins: local, staging, production, banksouth).
+`;
+const PROCESS_USAGE = `usage:
+  seq-studio process init <dir>
+  seq-studio process lint
+  seq-studio process plan [-e <env>]
+  seq-studio process apply [-e <env>] [--only <id1,id2,...>]
+  seq-studio process promote <processId> --version <v> [-e <env>]
+  seq-studio process pull <processId> [--version <v>] [-e <env>] [--out <dir>] [--no-children]
+  seq-studio process test [-e <env>] [--offline]
+  seq-studio process simulate <process-id>
+  seq-studio process bundle build [-o file.json]
+  seq-studio process bundle pull <hash> [-o file.json] [-e <env>]
+  seq-studio process bundle archive <hash> [-e <env>]
+  seq-studio process bundle inspect <bundle.json>
+  seq-studio process bundle list [-e <env>] [--limit N] [--cursor <hash>]
+  seq-studio process bundle publish <hash|bundle.json> [-e <env>]
+`;
+export async function run(argv = process.argv.slice(2)) {
+    const [namespace, sub, ...rest] = argv;
+    if (!namespace || namespace === 'help' || namespace === '--help' || namespace === '-h') {
+        console.log(TOP_LEVEL_USAGE);
+        return namespace ? 0 : 1;
+    }
+    switch (namespace) {
+        case 'process':
+            return runProcessNamespace(sub, rest);
+        case 'artifact': {
+            const { runArtifactCommand } = await import('./artifact/delegate.js');
+            return runArtifactCommand(sub, rest);
+        }
+        case 'functions': {
+            const { runFunctionsCommand } = await import('./functions/commands.js');
+            return runFunctionsCommand(sub, parseArgs(rest));
+        }
+        case 'secrets': {
+            const { runSecretsCommand } = await import('./secrets/commands.js');
+            return runSecretsCommand(sub, parseArgs(rest));
+        }
+        case 'repos': {
+            const { runReposCommand } = await import('./repos/commands.js');
+            return runReposCommand(sub, parseArgs(rest));
+        }
+        case 'auth': {
+            const { runAuthCommand } = await import('./auth-cmds/commands.js');
+            return runAuthCommand(sub, parseArgs(rest));
+        }
+        case 'orm': {
+            const { runOrmCommand } = await import('./orm/delegate.js');
+            return runOrmCommand(sub, rest);
+        }
+        case 'doctor':
+            return doctorCommand(parseArgs([sub, ...rest].filter(Boolean)));
+        default:
+            console.error(`unknown command: ${namespace}`);
+            console.error(TOP_LEVEL_USAGE);
+            return 1;
+    }
+}
+async function runProcessNamespace(sub, rest) {
+    if (!sub) {
+        console.error(PROCESS_USAGE);
+        return 1;
+    }
+    const args = parseArgs(sub === 'bundle' ? [sub, ...rest] : rest);
+    switch (sub) {
+        case 'init':
+            return initCommand(args);
+        case 'lint':
+            return lintCommand(args);
+        case 'plan':
+            return planCommand(args);
+        case 'apply':
+            return applyCommand(args);
+        case 'promote':
+            return promoteCommand(args);
+        case 'pull':
+            return pullCommand(args);
+        case 'test':
+            return testCommand(args);
+        case 'simulate':
+            return simulateCommand(args);
+        case 'bundle':
+            // bundle command needs the subcommand (build/pull/inspect) in positional[0].
+            // parseArgs already includes it because we threaded sub into args.
+            return bundleCommand({
+                positional: args.positional.slice(1),
+                flags: args.flags,
+            });
+        case 'help':
+        case '--help':
+        case '-h':
+            console.log(PROCESS_USAGE);
+            return 0;
+        default:
+            console.error(`unknown process command: ${sub}`);
+            console.error(PROCESS_USAGE);
+            return 1;
+    }
+}

package/dist/orm/delegate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `seq-studio orm <sub>` — the Sequence ORM (OpCo data layer).
+ *
+ * Delegates to `runCli` from `@sequenceholdings/orm/cli` (same pattern as
+ * `artifact`): resolve `--env` from `~/.config/lattice/config.toml`, set
+ * SEQUENCE_ORM_BASE_URL, share the seqapi token, forward argv.
+ */
+export declare function runOrmCommand(sub: string | undefined, rest: string[]): Promise<number>;

package/dist/orm/delegate.js

@@ -0,0 +1,61 @@
+/**
+ * `seq-studio orm <sub>` — the Sequence ORM (OpCo data layer).
+ *
+ * Delegates to `runCli` from `@sequenceholdings/orm/cli` (same pattern as
+ * `artifact`): resolve `--env` from `~/.config/lattice/config.toml`, set
+ * SEQUENCE_ORM_BASE_URL, share the seqapi token, forward argv.
+ */
+import { getAccessToken, tryGetAccessToken } from '../auth.js';
+import { readConfig, resolveEnv } from '../config.js';
+import { normalizeShortEnvFlag, readEnvFromArgv } from '../env-flags.js';
+const ORM_USAGE = `usage:
+  seq-studio orm init <dir>            scaffold a namespace directory
+  seq-studio orm validate [dir]        parse + validate definitions, print the content hash
+  seq-studio orm plan [dir] -e <env>   compile definitions and diff against the registry
+  seq-studio orm diff [dir]            write the next committed migration (--check verifies, --allow-destructive consents)
+  seq-studio orm apply [dir] -e <env>  register the definitions and apply them to the env
+
+  Built-in envs: local, staging, production, banksouth.
+  Authenticate with: seqapi login
+`;
+export async function runOrmCommand(sub, rest) {
+    if (!sub || sub === 'help' || sub === '--help' || sub === '-h') {
+        console.log(ORM_USAGE);
+        return sub ? 0 : 1;
+    }
+    const normalized = normalizeShortEnvFlag(rest);
+    const requested = readEnvFromArgv(normalized);
+    if (requested) {
+        const config = await readConfig();
+        const resolved = resolveEnv({ config, requested });
+        process.env['SEQUENCE_ORM_BASE_URL'] = resolved.url;
+    }
+    const token = await tryGetAccessToken({ failClosedForM2m: true });
+    if (token)
+        process.env['SEQUENCE_ORM_TOKEN'] = token;
+    // Lazy import keeps `process`/`doctor` from pulling in the orm package.
+    // @sequenceholdings/orm is a private, optional peer — absent in public
+    // installs of the CLI, present in the monorepo (dev dep) and internal setups.
+    let ormCli;
+    try {
+        ormCli = await import('@sequenceholdings/orm/cli');
+    }
+    catch (err) {
+        if (err.code === 'ERR_MODULE_NOT_FOUND') {
+            console.error('seq-studio orm requires @sequenceholdings/orm, which is not included ' +
+                'in this installation. It is available to Sequence-internal setups only.');
+            return 1;
+        }
+        throw err;
+    }
+    const { runCli, setTokenProvider } = ormCli;
+    setTokenProvider(async () => {
+        try {
+            return await getAccessToken();
+        }
+        catch {
+            return null;
+        }
+    });
+    return runCli([sub, ...normalized]);
+}

package/dist/pat-hints.d.ts

@@ -0,0 +1,17 @@
+/**
+ * User-facing hints for minting a git-service PAT.
+ *
+ * Third-party / OpCo developers typically do not have `seqapi`. Their path is
+ * the Atlas UI at `/settings/tokens`. Sequence staff can also use
+ * `seq-studio auth pat create` after `seqapi login`.
+ */
+export declare function settingsTokensUrl(envUrl: string): string;
+/**
+ * Multi-line setup instructions. Prefer the Atlas UI first (works for anyone
+ * with Atlas access); mention the CLI mint path as a staff convenience.
+ */
+export declare function formatPatSetupHint({ envUrl, envName, indent, }: {
+    envUrl: string;
+    envName: string;
+    indent?: string;
+}): string[];

package/dist/pat-hints.js

@@ -0,0 +1,28 @@
+/**
+ * User-facing hints for minting a git-service PAT.
+ *
+ * Third-party / OpCo developers typically do not have `seqapi`. Their path is
+ * the Atlas UI at `/settings/tokens`. Sequence staff can also use
+ * `seq-studio auth pat create` after `seqapi login`.
+ */
+export function settingsTokensUrl(envUrl) {
+    return `${envUrl.replace(/\/$/, '')}/settings/tokens`;
+}
+/**
+ * Multi-line setup instructions. Prefer the Atlas UI first (works for anyone
+ * with Atlas access); mention the CLI mint path as a staff convenience.
+ */
+export function formatPatSetupHint({ envUrl, envName, indent = '  ', }) {
+    const tokensUrl = settingsTokensUrl(envUrl);
+    return [
+        `${indent}Get a PAT (no seqapi required):`,
+        `${indent}  1. Open ${tokensUrl} and sign in to Atlas`,
+        `${indent}  2. New token → scopes repo:read (add repo:write for push) → copy once`,
+        `${indent}  3. export ATLAS_GIT_PAT=<token>`,
+        `${indent}  4. Copy the clone URL from Repositories → Clone, then:`,
+        `${indent}       ATLAS_GIT_PAT=<token> seq-studio repos clone --url <https://…/repos/<id>/git>`,
+        `${indent}     (or with seqapi: seq-studio repos clone <ns>/<name>)`,
+        `${indent}Sequence staff with seqapi can instead:`,
+        `${indent}  seqapi login && seq-studio auth pat create --name laptop --scopes repo:read,repo:write -e ${envName}`,
+    ];
+}

package/dist/preview.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Per-PR preview-environment resolution for `seq-studio artifact`.
+ *
+ * Lets an engineer target a specific PR's Vercel preview deployment
+ * (`https://studio-atlas-git-<slug>.preview.seqholdings.com`) WITHOUT
+ * hand-editing `~/.config/lattice/config.toml`. See
+ * `docs/preview-environments.md` for the full lifecycle.
+ *
+ * SLUG ALGORITHM — must stay byte-for-byte in sync with the three other
+ * places that compute the same slug from a branch name:
+ *   - `.github/workflows/preview-deploy.yml`  (`sed 's/[^a-zA-Z0-9-]/-/g' | tr '[:upper:]' '[:lower:]'`)
+ *   - `atlas/src/server/db.ts:sanitize`        (`replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase()`)
+ *   - `databricks/lakebase/atlas-db/pr-lifecycle.ts:sanitize`
+ * Changing it here without changing those produces a host that does NOT
+ * match what `preview-deploy.yml` actually deployed.
+ */
+/** Cloudflare zone the preview aliases live on. */
+export declare const PREVIEW_DOMAIN = "preview.seqholdings.com";
+/** Vercel project name → the `<project>-git-<slug>` alias label prefix. */
+export declare const PREVIEW_PROJECT = "studio-atlas";
+/**
+ * Mirror of `preview-deploy.yml`'s `PROTECTED` list. A branch whose slug
+ * matches one of these (or starts with `dev-`) never gets a preview — the
+ * workflow's guard refuses to deploy it — so the CLI refuses to target it.
+ */
+export declare const PREVIEW_PROTECTED_SLUGS: readonly ["banksouth", "staging", "dev", "production", "main", "development", "master"];
+/**
+ * Vercel deploys the preview under the DNS label `studio-atlas-git-<slug>`.
+ * A single DNS label can be at most 63 chars; Vercel hash-truncates labels
+ * past that, so the resulting host can NOT be computed from the slug and must
+ * be read back from the deployment. This is the SAME cutoff the workflow uses
+ * (`[ "${#LABEL}" -le 63 ]`).
+ */
+export declare const MAX_LABEL_LENGTH = 63;
+/** Apply the canonical branch → slug transform. */
+export declare function previewSlug(branchOrSlug: string): string;
+/** The `studio-atlas-git-<slug>` DNS label Vercel assigns the preview. */
+export declare function previewLabel(slug: string): string;
+/** True for protected slugs that never get a preview (mirror of the workflow). */
+export declare function isProtectedPreviewSlug(slug: string): boolean;
+/**
+ * True when the slug is short enough that its preview host can be computed
+ * without reading the real alias back from Vercel (label ≤ 63 chars).
+ */
+export declare function isComputablePreviewSlug(slug: string): boolean;
+/** The computed preview host for a (short) slug. */
+export declare function previewHost(slug: string): string;
+export interface ResolvedPreview {
+    /** The canonical branch slug. */
+    slug: string;
+    /** Fully-qualified `https://…preview.seqholdings.com` URL. */
+    url: string;
+}
+/**
+ * Resolve a `preview:<branch-or-slug>` target to its computed preview URL.
+ * Throws for protected slugs and for long slugs whose alias can't be computed
+ * (the caller should fall back to `--pr <number>` or `--env-url <url>`).
+ */
+export declare function resolvePreviewFromSlug(branchOrSlug: string): ResolvedPreview;
+/** Injectable `gh` runner so PR resolution is unit-testable. */
+export type GhRunner = (args: string[]) => Promise<string>;
+interface GhPrComment {
+    body?: string;
+    author?: {
+        login?: string;
+    } | null;
+    createdAt?: string;
+}
+/**
+ * Find the real `*.preview.seqholdings.com` alias the Vercel bot posts on the
+ * PR. This is the ONLY reliable way to get the host for a long (hash-truncated)
+ * slug — we can't compute it. Returns the newest trusted match or null.
+ */
+export declare function findPreviewUrlInComments(comments: ReadonlyArray<GhPrComment> | undefined, { expectedHost, requireTrustedAuthor, }?: {
+    expectedHost?: string;
+    requireTrustedAuthor?: boolean;
+}): string | null;
+/**
+ * Resolve a preview env from a PR number. Reads the PR's head branch (and the
+ * Vercel bot's preview-URL comment) via `gh`. Prefers the real alias from the
+ * comment — which works even for long, hash-truncated slugs — and falls back to
+ * computing the host from the branch slug for short slugs. Throws for protected
+ * slugs and for long slugs with no resolvable alias.
+ */
+export declare function resolvePreviewByPr({ pr, runGh, }: {
+    pr: number;
+    runGh?: GhRunner;
+}): Promise<ResolvedPreview>;
+export {};