@sequenceholdings/studio-cli 0.1.21 → 0.1.24

package/dist/pipeline/codegen.js

@@ -0,0 +1,118 @@
+/**
+ * `seq-studio pipeline codegen tables` — emit one `.stage.yml` per table from a
+ * typed TypeScript authoring module (SEQ-2485).
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { tsImport } from 'tsx/esm/api';
+const LOG = '[seq-studio]';
+function isAuthoring(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return (typeof record.stagePrefix === 'string' &&
+        typeof record.runtime === 'string' &&
+        typeof record.entrypoint === 'string' &&
+        Array.isArray(record.owners) &&
+        Array.isArray(record.tables));
+}
+function findAuthoringExport(value) {
+    if (isAuthoring(value))
+        return value;
+    if (!value || typeof value !== 'object')
+        return null;
+    const record = value;
+    for (const key of ['default', 'authoring', 'silverlakeAuthoring']) {
+        const nested = record[key];
+        if (isAuthoring(nested))
+            return nested;
+    }
+    return null;
+}
+async function loadAuthoringModule(fromPath) {
+    const absolute = resolve(fromPath);
+    if (!existsSync(absolute)) {
+        throw new Error(`authoring module not found: ${absolute}`);
+    }
+    const loaded = await tsImport(pathToFileURL(absolute).href, import.meta.url);
+    if (!loaded || typeof loaded !== 'object') {
+        throw new Error(`authoring module '${absolute}' did not export an object`);
+    }
+    const record = loaded;
+    const candidate = findAuthoringExport(record.default) ??
+        findAuthoringExport(record.authoring) ??
+        findAuthoringExport(record.silverlakeAuthoring);
+    if (!candidate) {
+        throw new Error(`authoring module '${absolute}' must export default, authoring, or silverlakeAuthoring ` +
+            `as a PerTableIngestionAuthoring object (exports: ${Object.keys(record).join(', ')})`);
+    }
+    return candidate;
+}
+export async function pipelineCodegenTablesCommand(args) {
+    const spec = await import('@sequenceholdings/pipeline-spec');
+    const from = typeof args.flags.from === 'string'
+        ? args.flags.from
+        : join(process.cwd(), 'authoring.tables.ts');
+    const dir = resolve(typeof args.flags.dir === 'string' ? args.flags.dir : '.');
+    const dryRun = args.flags['dry-run'] === true;
+    let authoring;
+    try {
+        authoring = await loadAuthoringModule(from);
+    }
+    catch (error) {
+        console.error(`${LOG} ${error instanceof Error ? error.message : String(error)}`);
+        console.error('usage: seq-studio pipeline codegen tables --from <authoring.ts> [--dir <dir>] [--dry-run]');
+        return 1;
+    }
+    const files = spec.generatePerTableStageFiles(authoring);
+    const parseErrors = [];
+    for (const file of files) {
+        const parsed = spec.stageSpecSchema.safeParse(file.spec);
+        if (!parsed.success) {
+            parseErrors.push(`${file.filename}: ${parsed.error.message}`);
+        }
+    }
+    if (parseErrors.length > 0) {
+        console.error(`${LOG} generated specs failed schema validation:`);
+        for (const line of parseErrors)
+            console.error(`  ${line}`);
+        return 1;
+    }
+    if (dryRun) {
+        console.log(`${LOG} dry-run: would write ${files.length} stage file(s) to ${dir}`);
+        for (const file of files)
+            console.log(`  ${file.filename}`);
+        return 0;
+    }
+    const targets = files.map((file) => ({
+        file,
+        target: join(dir, file.filename),
+    }));
+    const seenTargets = new Set();
+    const duplicateTarget = targets.find(({ target }) => {
+        if (seenTargets.has(target))
+            return true;
+        seenTargets.add(target);
+        return false;
+    });
+    if (duplicateTarget) {
+        console.error(`${LOG} duplicate output target ${duplicateTarget.target}`);
+        return 1;
+    }
+    if (args.flags.force !== true) {
+        const existingTarget = targets.find(({ target }) => existsSync(target));
+        if (existingTarget) {
+            console.error(`${LOG} ${existingTarget.target} already exists — pass --force to overwrite`);
+            return 1;
+        }
+    }
+    await mkdir(dir, { recursive: true });
+    for (const { file, target } of targets) {
+        await writeFile(target, file.yaml, 'utf8');
+        console.log(`${LOG} wrote ${target}`);
+    }
+    console.log(`${LOG} next: seq-studio pipeline validate ${dir === process.cwd() ? '.' : dir}`);
+    return 0;
+}

package/dist/pipeline/commands.d.ts

@@ -12,6 +12,8 @@
  * the CLI without the package get a clear install hint instead of a crash.
  */
 import type { ParsedArgs } from '../process/commands.js';
+/** Conventional ORM contract catalog filename beside stage specs (CI auto-loads this). */
+export declare const ORM_CONTRACTS_FILENAME = "orm-contracts.json";
 /**
  * Same classification as the orm delegate: is the pipeline-spec package
  * itself absent (installable) or did one of its dependencies fail to load?
@@ -53,6 +55,11 @@ export declare function buildExternalAssetsRequest({ source, knownOrigins, token
 export declare function configuredEnvOrigins(envs: Readonly<Record<string, {
     url: string;
 }>>): string[];
+/** Resolve ORM contracts from --orm-contracts or conventional orm-contracts.json. */
+export declare function resolveOrmContractsPath({ dir, flag, }: {
+    dir: string;
+    flag: unknown;
+}): string | undefined;
 export declare function pipelineValidateCommand(args: ParsedArgs): Promise<number>;
 export declare function runPipelineCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;
 export {};

package/dist/pipeline/commands.js

@@ -19,39 +19,68 @@ import { tryGetAccessToken } from '../auth.js';
 import { readConfig } from '../config.js';
 import { renderEntrypointStub, renderStageTemplate, STAGE_TYPES, } from './templates.js';
 const LOG = '[seq-studio]';
+/** Conventional ORM contract catalog filename beside stage specs (CI auto-loads this). */
+export const ORM_CONTRACTS_FILENAME = 'orm-contracts.json';
 const PIPELINE_USAGE = `usage:
   seq-studio pipeline init --type ingestion|transformation|serving <name> [--dir <dir>]
       scaffold <name>.stage.yml (commented template) + src/ entrypoint stub
 
-  seq-studio pipeline validate [dir] [--assets <file|url>] [--json]
+  seq-studio pipeline validate [dir] [--assets <file|url>] [--orm-contracts <file|url>] [--json]
       run the offline spec gate: envelope + body validation, schema_ref
       resolution, and repo-level graph validation (references, single-writer,
       cycles, column subsets). --assets supplies a registry asset export for
-      cross-Pipeline references. Exits 1 on any error-severity finding.
+      cross-Pipeline references; --orm-contracts (or orm-contracts.json in dir)
+      supplies ORM synced-table contracts for serving satisfies pins. Exits 1 on
+      any error-severity finding.
 
-  seq-studio pipeline plan --repo pipelines/<slug> --ref <sha|branch> -e <env> [--json]
+  seq-studio pipeline codegen tables [--from <authoring.ts>] [--dir <dir>] [--dry-run] [--force]
+      emit one <stage>.stage.yml per table from a typed PerTableIngestionAuthoring
+      module (default export, authoring, or silverlakeAuthoring export name)
+
+  seq-studio pipeline plan --repo pipelines/<slug> --ref <sha|branch> -e <env> [--target <id>] [--json]
       materialize + SDK/graph + compile + live-diff + provision findings
       (no Databricks CLI / DAB validate on Atlas); exit 1 on destructive findings
 
-  seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha> -e <env>
-                            [--approved-by <sub>] [--no-wait] [--json]
+  seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha|branch> -e <env>
+                            [--target <id>] [--approved-by <sub>] [--no-wait] [--json]
       plan then enqueue Trigger deploy (DAB bundle validate hard-gates before
-      bundle deploy); production/banksouth require a pinned 40-hex SHA
+      bundle deploy); use a full 40-hex SHA for explicit rollback deployments
 
   seq-studio pipeline promote --stage <slug> --version <v> -e <env>
-                              [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]
+                              [--target <id>] [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]
       promote a validated version to the next environment (approvals are
       self-recorded: --approved-by must name the authenticated caller)
 
-  seq-studio pipeline rollback --stage <slug> -e <env> [--repo pipelines/<slug>]
+  seq-studio pipeline rollback --stage <slug> -e <env> [--target <id>] [--repo pipelines/<slug>]
                                [--approved-by <you>] [--no-wait]
       redeploy the previously retired deployment's version (production/
       banksouth require --approved-by — approvals are explicit even for
       rollbacks)
 
-  seq-studio pipeline run-now --stage <slug> -e <env> [--repo pipelines/<slug>] [--json]
+  Unless --no-wait is set, deploy, promote, and rollback report status or
+  status-detail changes while waiting, then emit a 20-second progress heartbeat.
+  Terminal output includes the deployment id and elapsed time; it also includes
+  a Trigger run id when the deployment provides one.
+
+  seq-studio pipeline adopt --stage <slug> --ref <sha|branch> -e <env>
+                            [--target <id>] --native-id <id> [--resource-key <key>] [--kind job|dlt_pipeline]
+                            --approved-by <you> [--old-source-removal-pr <url>]
+                            [--repo pipelines/<slug>] [--json]
+      bind a live Databricks job/pipeline to the stage without recreation
+      (SEQ-2449). Always requires --approved-by. Monorepo-declared keys also
+      require --old-source-removal-pr.
+
+  seq-studio pipeline unbind --stage <slug> --ref <sha|branch> -e <env> [--target <id>]
+                             --approved-by <you> [--resource-key <key>]
+                             [--repo pipelines/<slug>] [--json]
+      release an adopted binding; the remote object stays live (never deleted)
+
+  seq-studio pipeline run-now --stage <slug> -e <env> [--target <id>] [--repo pipelines/<slug>] [--json]
       fire the stage's active deployment resource (job run-now / DLT
       start_update) and print the Databricks run URL
+
+  -e/--env selects the Atlas connection. --target selects the logical target
+      advertised by that deployment; it is inferred when the endpoint exposes one target.
 `;
 /**
  * Same classification as the orm delegate: is the pipeline-spec package
@@ -212,6 +241,34 @@ async function loadExternalAssets(spec, source) {
     }
     return spec.externalAssetsExportSchema.parse(JSON.parse(raw));
 }
+async function loadOrmContracts(spec, source) {
+    let raw;
+    if (/^https?:\/\//.test(source)) {
+        const config = await readConfig();
+        const token = await tryGetAccessToken();
+        const request = buildExternalAssetsRequest({
+            source,
+            knownOrigins: configuredEnvOrigins(config.envs),
+            token,
+        });
+        const response = await fetch(request.url, request.init);
+        if (!response.ok) {
+            throw new Error(`fetching ORM contracts catalog failed: ${response.status} ${response.statusText}`);
+        }
+        raw = await response.text();
+    }
+    else {
+        raw = await readFile(resolve(source), 'utf8');
+    }
+    return spec.ormContractCatalogSchema.parse(JSON.parse(raw));
+}
+/** Resolve ORM contracts from --orm-contracts or conventional orm-contracts.json. */
+export function resolveOrmContractsPath({ dir, flag, }) {
+    if (typeof flag === 'string')
+        return flag;
+    const conventional = join(dir, ORM_CONTRACTS_FILENAME);
+    return existsSync(conventional) ? conventional : undefined;
+}
 function printHumanReport(report) {
     for (const finding of report.findings) {
         const prefix = finding.severity === 'error' ? 'error' : 'warning';
@@ -283,7 +340,28 @@ export async function pipelineValidateCommand(args) {
             });
         }
     }
-    const result = spec.validateSpecGraph(pipeline.stages, externalAssets);
+    let ormContracts;
+    const ormContractsPath = resolveOrmContractsPath({ dir, flag: args.flags['orm-contracts'] });
+    if (ormContractsPath) {
+        try {
+            ormContracts = await loadOrmContracts(spec, ormContractsPath);
+        }
+        catch (error) {
+            return emit({
+                ok: false,
+                dir: dirArg,
+                stages: pipeline.stages.map((stage) => stage.stage),
+                findings: [
+                    {
+                        severity: 'error',
+                        code: 'orm_contracts_unreadable',
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                ],
+            });
+        }
+    }
+    const result = spec.validateSpecGraph(pipeline.stages, externalAssets, ormContracts !== undefined ? { ormContracts } : undefined);
     return emit({
         ok: result.ok,
         dir: dirArg,
@@ -297,6 +375,23 @@ export async function runPipelineCommand(sub, args) {
             return pipelineInitCommand(args);
         case 'validate':
             return pipelineValidateCommand(args);
+        case 'codegen': {
+            const codegenSub = args.positional[0];
+            if (codegenSub === 'tables') {
+                const { pipelineCodegenTablesCommand } = await import('./codegen.js');
+                return pipelineCodegenTablesCommand({ ...args, positional: args.positional.slice(1) });
+            }
+            console.error(`${LOG} unknown pipeline codegen target '${codegenSub ?? ''}' — expected: tables`);
+            return 1;
+        }
+        case 'adopt': {
+            const { pipelineAdoptCommand } = await import('./lifecycle.js');
+            return pipelineAdoptCommand(args);
+        }
+        case 'unbind': {
+            const { pipelineUnbindCommand } = await import('./lifecycle.js');
+            return pipelineUnbindCommand(args);
+        }
         case 'plan': {
             const { pipelinePlanCommand } = await import('./lifecycle.js');
             return pipelinePlanCommand(args);

package/dist/pipeline/lifecycle.d.ts

@@ -37,22 +37,13 @@ export interface DeploymentDetail {
     id: string;
     status: string;
     statusDetail: string | null;
+    triggerRunId?: string | null;
 }
-/**
- * The CLI's local dev-loop env is named `local` — chosen so `-e local` lines
- * up with `seqapi -e local` / `artifact-studio --env local` (see `config.ts`
- * `BUILT_IN_ENV_URLS`). There is no `local` in the server's deploy-lifecycle
- * enum (`DEPLOY_ENVIRONMENTS` in `atlas/src/server/services/data-pipelines/schema.ts`
- * is `dev | staging | production | banksouth`); the server's name for that
- * same developer-loop target is `dev` (`targetFactsForEnvironment` treats
- * `dev` as the one target exempt from a `lakebase_branch` binding). Map at
- * this one boundary — every lifecycle request body funnels through here —
- * so the CLI never sends the wire-invalid `local` and every other env name
- * passes through unchanged.
- */
 export declare function deployEnvironmentForEnv(env: ResolvedEnv): string;
 export declare function pipelinePlanCommand(args: ParsedArgs): Promise<number>;
 export declare function pipelineDeployCommand(args: ParsedArgs): Promise<number>;
 export declare function pipelinePromoteCommand(args: ParsedArgs): Promise<number>;
 export declare function pipelineRunNowCommand(args: ParsedArgs): Promise<number>;
 export declare function pipelineRollbackCommand(args: ParsedArgs): Promise<number>;
+export declare function pipelineAdoptCommand(args: ParsedArgs): Promise<number>;
+export declare function pipelineUnbindCommand(args: ParsedArgs): Promise<number>;