@sequenceholdings/studio-cli 0.1.9

package/dist/preview.js

@@ -0,0 +1,291 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+/**
+ * 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 const PREVIEW_DOMAIN = 'preview.seqholdings.com';
+/** Vercel project name → the `<project>-git-<slug>` alias label prefix. */
+export const PREVIEW_PROJECT = 'studio-atlas';
+const LABEL_PREFIX = `${PREVIEW_PROJECT}-git-`;
+/**
+ * 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 const PREVIEW_PROTECTED_SLUGS = [
+    '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 const MAX_LABEL_LENGTH = 63;
+/** Apply the canonical branch → slug transform. */
+export function previewSlug(branchOrSlug) {
+    return branchOrSlug.replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase();
+}
+/** The `studio-atlas-git-<slug>` DNS label Vercel assigns the preview. */
+export function previewLabel(slug) {
+    return `${LABEL_PREFIX}${slug}`;
+}
+/** True for protected slugs that never get a preview (mirror of the workflow). */
+export function isProtectedPreviewSlug(slug) {
+    return (PREVIEW_PROTECTED_SLUGS.includes(slug) ||
+        slug.startsWith('dev-'));
+}
+/**
+ * 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 function isComputablePreviewSlug(slug) {
+    return previewLabel(slug).length <= MAX_LABEL_LENGTH;
+}
+/** The computed preview host for a (short) slug. */
+export function previewHost(slug) {
+    return `${previewLabel(slug)}.${PREVIEW_DOMAIN}`;
+}
+const PROTECTED_HINT = PREVIEW_PROTECTED_SLUGS.join(', ');
+/**
+ * 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 function resolvePreviewFromSlug(branchOrSlug) {
+    const slug = previewSlug(branchOrSlug);
+    if (!slug) {
+        throw new Error('Preview env requires a branch or slug, e.g. --env preview:my-branch');
+    }
+    if (isProtectedPreviewSlug(slug)) {
+        throw new Error(`Refusing to target a protected branch slug "${slug}". ` +
+            `Protected slugs never get a preview (${PROTECTED_HINT}, or anything starting with "dev-").`);
+    }
+    if (!isComputablePreviewSlug(slug)) {
+        throw new Error(`Branch slug "${slug}" is too long (label "${previewLabel(slug)}" is ` +
+            `${previewLabel(slug).length} > ${MAX_LABEL_LENGTH} chars): Vercel ` +
+            `hash-truncates the alias, so the preview host can't be computed. ` +
+            `Resolve it with --pr <number> (reads the real alias from the PR) or ` +
+            `pass --env-url <https://…preview.seqholdings.com>.`);
+    }
+    return { slug, url: `https://${previewHost(slug)}` };
+}
+const execFileAsync = promisify(execFile);
+const defaultGhRunner = async (args) => {
+    try {
+        const { stdout } = await execFileAsync('gh', args, { encoding: 'utf8' });
+        return stdout;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to run \`gh ${args.join(' ')}\`. Install the GitHub CLI and run ` +
+            `\`gh auth login\`, or pass --env-url <url> directly. (${message})`);
+    }
+};
+const TRUSTED_PREVIEW_COMMENT_AUTHORS = new Set([
+    'vercel',
+    'vercel[bot]',
+    'github-actions',
+    'github-actions[bot]',
+]);
+function compareIsoDesc(a, b) {
+    if (a === b)
+        return 0;
+    return a > b ? -1 : 1;
+}
+function commentsNewestFirst(comments) {
+    const withDates = comments
+        .map((c) => ({ c, d: typeof c.createdAt === 'string' ? c.createdAt : null }))
+        .filter((x) => x.d !== null);
+    if (withDates.length === 0)
+        return comments;
+    return [...comments].sort((a, b) => {
+        const da = typeof a.createdAt === 'string' ? a.createdAt : '';
+        const db = typeof b.createdAt === 'string' ? b.createdAt : '';
+        return compareIsoDesc(da, db);
+    });
+}
+/**
+ * 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 function findPreviewUrlInComments(comments, { expectedHost, requireTrustedAuthor = true, } = {}) {
+    if (!comments)
+        return null;
+    const ordered = commentsNewestFirst(comments);
+    const expected = expectedHost?.toLowerCase();
+    const re = /https:\/\/[a-z0-9-]+\.preview\.seqholdings\.com/gi;
+    const labelPrefix = LABEL_PREFIX.toLowerCase();
+    const isTrusted = (comment) => TRUSTED_PREVIEW_COMMENT_AUTHORS.has(comment.author?.login ?? '');
+    const search = (predicate) => {
+        for (const comment of ordered) {
+            if (!comment?.body)
+                continue;
+            if (!predicate(comment))
+                continue;
+            for (const match of comment.body.matchAll(re)) {
+                const url = match[0];
+                if (!url)
+                    continue;
+                let host;
+                try {
+                    host = new URL(url).host.toLowerCase();
+                }
+                catch {
+                    continue;
+                }
+                if (!host.endsWith(`.${PREVIEW_DOMAIN}`))
+                    continue;
+                if (!host.startsWith(labelPrefix))
+                    continue;
+                if (expected && host !== expected)
+                    continue;
+                return url;
+            }
+        }
+        return null;
+    };
+    if (requireTrustedAuthor) {
+        return search(isTrusted);
+    }
+    return search(() => true);
+}
+async function tryResolvePreviewUrlFromDeployments({ runGh, headSha, }) {
+    if (!headSha)
+        return null;
+    const repoStdout = await runGh(['repo', 'view', '--json', 'nameWithOwner']);
+    let repo;
+    try {
+        repo = JSON.parse(repoStdout);
+    }
+    catch {
+        return null;
+    }
+    const nameWithOwner = repo.nameWithOwner;
+    if (!nameWithOwner)
+        return null;
+    const deploymentsStdout = await runGh([
+        'api',
+        `repos/${nameWithOwner}/deployments?sha=${encodeURIComponent(headSha)}&per_page=100`,
+    ]);
+    let deployments;
+    try {
+        deployments = JSON.parse(deploymentsStdout);
+    }
+    catch {
+        return null;
+    }
+    const previewDeployments = deployments
+        .filter((d) => typeof d.id === 'number' && /preview/i.test(d.environment ?? ''))
+        .sort((a, b) => compareIsoDesc(a.created_at ?? '', b.created_at ?? ''));
+    const chosen = previewDeployments[0];
+    if (!chosen?.id)
+        return null;
+    const statusesStdout = await runGh([
+        'api',
+        `repos/${nameWithOwner}/deployments/${chosen.id}/statuses?per_page=100`,
+    ]);
+    let statuses;
+    try {
+        statuses = JSON.parse(statusesStdout);
+    }
+    catch {
+        return null;
+    }
+    const candidates = statuses
+        .filter((s) => typeof s.environment_url === 'string' && s.environment_url.length > 0)
+        .sort((a, b) => compareIsoDesc(a.created_at ?? '', b.created_at ?? ''));
+    const isPreviewHost = (url) => {
+        try {
+            const host = new URL(url).hostname.toLowerCase();
+            return host.endsWith(`.${PREVIEW_DOMAIN}`) && host.startsWith(LABEL_PREFIX.toLowerCase());
+        }
+        catch {
+            return false;
+        }
+    };
+    const success = candidates.find((s) => s.state === 'success' && isPreviewHost(s.environment_url));
+    if (success?.environment_url)
+        return success.environment_url;
+    const any = candidates.find((s) => isPreviewHost(s.environment_url));
+    return any?.environment_url ?? 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 async function resolvePreviewByPr({ pr, runGh = defaultGhRunner, }) {
+    if (!Number.isInteger(pr) || pr <= 0) {
+        throw new Error(`--pr must be a positive integer (got "${pr}").`);
+    }
+    const stdout = await runGh([
+        'pr',
+        'view',
+        String(pr),
+        '--json',
+        'headRefName,headRefOid,comments',
+    ]);
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error(`Could not parse \`gh pr view ${pr}\` output as JSON.`);
+    }
+    const branch = parsed.headRefName;
+    if (!branch) {
+        throw new Error(`Could not read the head branch for PR #${pr} from gh.`);
+    }
+    const slug = previewSlug(branch);
+    if (isProtectedPreviewSlug(slug)) {
+        throw new Error(`PR #${pr} targets a protected branch slug "${slug}", which never gets a preview.`);
+    }
+    // If the slug is short, the alias is deterministic; prefer the computed host.
+    // This avoids accidentally targeting a stale or user-pasted preview URL.
+    if (isComputablePreviewSlug(slug)) {
+        return { slug, url: `https://${previewHost(slug)}` };
+    }
+    // Long, hash-truncated slugs require reading the real alias back from Vercel.
+    // Prefer deployment metadata over comment text (comments can be stale or
+    // user-authored).
+    const fromDeployment = await tryResolvePreviewUrlFromDeployments({
+        runGh,
+        headSha: parsed.headRefOid ?? '',
+    }).catch(() => null);
+    if (fromDeployment)
+        return { slug, url: fromDeployment };
+    // Fall back to the Vercel comment if deployments aren't available.
+    const fromComment = findPreviewUrlInComments(parsed.comments);
+    if (fromComment)
+        return { slug, url: fromComment };
+    // No trusted Vercel comment yet — error loudly and ask for an explicit URL.
+    throw new Error(`PR #${pr} (branch "${branch}", slug "${slug}") has a long, ` +
+        `hash-truncated alias and no preview URL was found in the PR comments ` +
+        `yet. Wait for the Vercel "Visit Preview" comment, or pass ` +
+        `--env-url <https://…preview.seqholdings.com> directly.`);
+}

package/dist/process/agent-loader.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Online agent loader for lint's "agent output schema matches
+ * outgoing_edges" check. Hits `GET /api/agents/agents/:id` on the
+ * resolved env (instead of the previous Mongo `findAgentById` path, which
+ * required an Atlas tsx runtime).
+ *
+ * Outcomes are distinguished so lint can react proportionally: a
+ * definitive 404 returns 'not-found' (hard error — a misspelled or
+ * unsynced agent id must not pass apply), an existing agent without an
+ * edge_id enum returns null (accepted — the generic-agent contract,
+ * validated at runtime), and transport failures throw (lint degrades to
+ * a warning so seq-studio keeps working without network access).
+ */
+export type AgentSchemaLookup = string[] | null | 'not-found';
+export declare function buildAgentSchemaLoader({ baseUrl, token, }: {
+    baseUrl: string;
+    token: string;
+}): (agentId: string) => Promise<AgentSchemaLookup>;
+/**
+ * Walk a JSON Schema looking for an `edge_id` property whose constraint
+ * is an enum of strings. Recurses through `anyOf` / `oneOf` / `allOf`.
+ * Returns null if the schema has no such enum (or it isn't strings).
+ */
+export declare function findEdgeIdEnumInSchema(schema: unknown): string[] | null;

package/dist/process/agent-loader.js

@@ -0,0 +1,57 @@
+/**
+ * Online agent loader for lint's "agent output schema matches
+ * outgoing_edges" check. Hits `GET /api/agents/agents/:id` on the
+ * resolved env (instead of the previous Mongo `findAgentById` path, which
+ * required an Atlas tsx runtime).
+ *
+ * Outcomes are distinguished so lint can react proportionally: a
+ * definitive 404 returns 'not-found' (hard error — a misspelled or
+ * unsynced agent id must not pass apply), an existing agent without an
+ * edge_id enum returns null (accepted — the generic-agent contract,
+ * validated at runtime), and transport failures throw (lint degrades to
+ * a warning so seq-studio keeps working without network access).
+ */
+import { getJsonOr404 } from '../atlas-client.js';
+export function buildAgentSchemaLoader({ baseUrl, token, }) {
+    return async (agentId) => {
+        const agent = await getJsonOr404({
+            baseUrl,
+            token,
+            path: `/api/agents/agents/${encodeURIComponent(agentId)}`,
+        });
+        if (!agent)
+            return 'not-found';
+        const schema = agent.structuredOutput?.schema;
+        if (!schema)
+            return null;
+        return findEdgeIdEnumInSchema(schema);
+    };
+}
+/**
+ * Walk a JSON Schema looking for an `edge_id` property whose constraint
+ * is an enum of strings. Recurses through `anyOf` / `oneOf` / `allOf`.
+ * Returns null if the schema has no such enum (or it isn't strings).
+ */
+export function findEdgeIdEnumInSchema(schema) {
+    if (!schema || typeof schema !== 'object')
+        return null;
+    const s = schema;
+    const props = s['properties'];
+    if (props && typeof props === 'object') {
+        const edgeIdSchema = props['edge_id'];
+        if (edgeIdSchema && Array.isArray(edgeIdSchema['enum'])) {
+            return edgeIdSchema['enum'].filter((v) => typeof v === 'string');
+        }
+    }
+    for (const key of ['anyOf', 'oneOf', 'allOf']) {
+        const arr = s[key];
+        if (Array.isArray(arr)) {
+            for (const sub of arr) {
+                const found = findEdgeIdEnumInSchema(sub);
+                if (found)
+                    return found;
+            }
+        }
+    }
+    return null;
+}

package/dist/process/build.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bundle builder. Produces the canonical `bundle_hash` for a process
+ * source tree.
+ */
+import { type LatticeBundle, type LatticeBundleSummary } from '@sequenceholdings/lattice/bundle';
+import type { LoadedProcess } from './discover.js';
+export type ResolveProcessPin = (processId: string, version?: string) => Promise<{
+    version: string;
+    bundleHash: string;
+} | null>;
+export declare function buildBundleFromProcesses(defs: readonly LoadedProcess[], options?: {
+    resolveProcessPin?: ResolveProcessPin;
+}): Promise<LatticeBundle>;
+export declare function summarizeBundle(bundle: LatticeBundle): LatticeBundleSummary;