@sequenceholdings/studio-cli 0.1.22 → 0.1.24

package/dist/functions/manifest.d.ts

@@ -5,6 +5,20 @@ import { z } from 'zod';
  * as artifact-studio's duplicated manifest. Keep the two in sync.
  */
 export declare const MF_MANIFEST_FILENAME = "managed-function.yml";
+export declare const managedFunctionAuthorizationAdapterSchema: z.ZodEnum<{
+    "encompass.loan-read-by-guid": "encompass.loan-read-by-guid";
+    "encompass.loan-read-by-number": "encompass.loan-read-by-number";
+    "encompass.loan-search": "encompass.loan-search";
+}>;
+export type ManagedFunctionAuthorizationAdapter = z.infer<typeof managedFunctionAuthorizationAdapterSchema>;
+export declare const managedFunctionAuthorizationSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    adapter: z.ZodEnum<{
+        "encompass.loan-read-by-guid": "encompass.loan-read-by-guid";
+        "encompass.loan-read-by-number": "encompass.loan-read-by-number";
+        "encompass.loan-search": "encompass.loan-search";
+    }>;
+}, z.core.$strict>;
 /**
  * CLI-side copy of the server's egress entry validation (see
  * atlas/src/server/services/managed-functions/egress.ts). Returns the
@@ -59,6 +73,14 @@ export declare const managedFunctionManifestSchema: z.ZodObject<{
     secrets: z.ZodDefault<z.ZodArray<z.ZodString>>;
     egress: z.ZodDefault<z.ZodArray<z.ZodString>>;
     service_account: z.ZodOptional<z.ZodString>;
+    authorization: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        adapter: z.ZodEnum<{
+            "encompass.loan-read-by-guid": "encompass.loan-read-by-guid";
+            "encompass.loan-read-by-number": "encompass.loan-read-by-number";
+            "encompass.loan-search": "encompass.loan-search";
+        }>;
+    }, z.core.$strict>>;
     input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     output_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     capabilities: z.ZodDefault<z.ZodObject<{

package/dist/functions/manifest.js

@@ -6,6 +6,22 @@ import { z } from 'zod';
  */
 export const MF_MANIFEST_FILENAME = 'managed-function.yml';
 const SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+export const managedFunctionAuthorizationAdapterSchema = z.enum([
+    'encompass.loan-read-by-guid',
+    'encompass.loan-read-by-number',
+    'encompass.loan-search',
+]);
+export const managedFunctionAuthorizationSchema = z
+    .object({
+    version: z.literal(1),
+    adapter: managedFunctionAuthorizationAdapterSchema,
+})
+    .strict();
+const AUTHORIZATION_ADAPTER_BY_FUNCTION_ID = {
+    'encompass-get-common-loan-fields': 'encompass.loan-read-by-guid',
+    'encompass-get-loan-by-number': 'encompass.loan-read-by-number',
+    'encompass-search-pipeline': 'encompass.loan-search',
+};
 /** 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])?$/;
 /**
@@ -571,6 +587,11 @@ export const managedFunctionManifestSchema = z.object({
         .string()
         .regex(SERVICE_ACCOUNT_REF_RE, 'service_account must be a platform service-account slug (lowercase alphanumeric with hyphens) or uuid')
         .optional(),
+    /**
+     * Server-owned resource authorization. Authors select a reviewed adapter;
+     * they cannot provide input/output paths or executable policy.
+     */
+    authorization: managedFunctionAuthorizationSchema.optional(),
     input_schema: z.record(z.string(), z.unknown()).optional(),
     output_schema: z.record(z.string(), z.unknown()).optional(),
     /**
@@ -616,6 +637,30 @@ export const managedFunctionManifestSchema = z.object({
             .default({}),
     }).default({ uses: [], gates: [], data: {} }),
 }).superRefine((manifest, ctx) => {
+    const expectedAdapter = AUTHORIZATION_ADAPTER_BY_FUNCTION_ID[manifest.function.id];
+    if (expectedAdapter !== undefined && manifest.authorization === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `function "${manifest.function.id}" requires authorization adapter "${expectedAdapter}"`,
+            path: ['authorization'],
+        });
+    }
+    else if (expectedAdapter !== undefined &&
+        manifest.authorization?.adapter !== expectedAdapter) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `function "${manifest.function.id}" must use authorization adapter "${expectedAdapter}"`,
+            path: ['authorization', 'adapter'],
+        });
+    }
+    else if (expectedAdapter === undefined &&
+        manifest.authorization !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `function "${manifest.function.id}" is not registered for a server-owned authorization adapter`,
+            path: ['authorization'],
+        });
+    }
     for (const message of validateCapabilityPins({
         uses: manifest.capabilities.uses,
         roles: manifest.capabilities.roles,

package/dist/main.d.ts

@@ -2,6 +2,9 @@
  * seq-studio argv router.
  *
  * Top-level commands:
+ *   seq-studio init               scaffold an app monorepo (sequence.app.yml)
+ *   seq-studio add                 add a primitive to an app monorepo
+ *   seq-studio deploy             deploy all primitives from sequence.app.yml
  *   seq-studio process <sub>      manage Lattice processes
  *   seq-studio artifact <sub>     manage Artifact Studio apps
  *   seq-studio functions <sub>    manage Managed Functions

package/dist/main.js

@@ -2,6 +2,9 @@
  * seq-studio argv router.
  *
  * Top-level commands:
+ *   seq-studio init               scaffold an app monorepo (sequence.app.yml)
+ *   seq-studio add                 add a primitive to an app monorepo
+ *   seq-studio deploy             deploy all primitives from sequence.app.yml
  *   seq-studio process <sub>      manage Lattice processes
  *   seq-studio artifact <sub>     manage Artifact Studio apps
  *   seq-studio functions <sub>    manage Managed Functions
@@ -21,6 +24,9 @@ import { applyCommand, bundleCommand, doctorCommand, initCommand, lintCommand, p
 // 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 init <dir> --with <kinds>   scaffold an app monorepo (sequence.app.yml)
+  seq-studio add <kind> <name>           add a primitive to the current app monorepo
+  seq-studio deploy -e <env>             deploy primitives from sequence.app.yml
   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
@@ -65,6 +71,21 @@ export async function run(argv = process.argv.slice(2)) {
         return namespace ? 0 : 1;
     }
     switch (namespace) {
+        case 'init': {
+            const { runAppInitCommand } = await import('./app/commands.js');
+            return runAppInitCommand(parseArgs([sub, ...rest].filter((a) => Boolean(a))));
+        }
+        case 'add': {
+            const { runAppAddCommand } = await import('./app/commands.js');
+            return runAppAddCommand({
+                kindArg: sub,
+                args: parseArgs(rest),
+            });
+        }
+        case 'deploy': {
+            const { runAppDeployCommand } = await import('./app/commands.js');
+            return runAppDeployCommand(parseArgs([sub, ...rest].filter((a) => Boolean(a))));
+        }
         case 'process':
             return runProcessNamespace(sub, rest);
         case 'artifact': {

package/dist/pipeline/codegen.d.ts

@@ -0,0 +1,2 @@
+import type { ParsedArgs } from '../process/commands.js';
+export declare function pipelineCodegenTablesCommand(args: ParsedArgs): Promise<number>;

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,52 +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)
 
+  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>
-                            --native-id <id> [--resource-key <key>] [--kind job|dlt_pipeline]
+                            [--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>
+  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> [--repo pipelines/<slug>] [--json]
+  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
@@ -225,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';
@@ -296,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,
@@ -310,6 +375,15 @@ 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);

package/dist/pipeline/lifecycle.d.ts

@@ -37,19 +37,8 @@ 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>;