@sequenceholdings/studio-cli 0.1.22 → 0.1.24

package/README.md

@@ -2,8 +2,10 @@
 
 Standalone CLI for the Sequence platform: typed agents, Lattice processes, Artifact Studio
 apps, Managed Functions, Managed Secrets, ORM namespaces, Data Pipelines stage
-specs, and platform git repos. Runs from any repo against the platform over
-HTTP — no monorepo checkout required.
+specs, and platform git repos. Its published workflows run from any repo
+against the platform over HTTP — no monorepo checkout required. The v0
+app-monorepo commands below are currently internal; see their availability
+notice.
 
 ```
 seq-studio process lint
@@ -43,7 +45,7 @@ equivalent and would happily install a freshly-published malicious
 version of any transitive dep. **External process repos scaffolded by
 `seq-studio process init` ship a `pnpm-workspace.yaml` with the same
 guard.** Stick with pnpm so the policy actually applies.
-(The seq-studio publish chain — `atlas-ui`, `lattice-form-renderer`,
+(The seq-studio publish chain — `agent-spec`, `atlas-ui`, `lattice-form-renderer`,
 `artifact-studio`, `lattice`, `studio-cli` — is excluded from the quarantine;
 those come from the Studio repo's own publish pipeline, so new `seq-studio`
 releases install immediately.)
@@ -134,6 +136,54 @@ Pass `--env <name>` (or `-e <name>`) on commands that talk to the platform.
 the artifact folder's `.artifact-studio/config.json` `defaultEnv` (set by
 `artifact link` / `artifact env use`).
 
+## App monorepo commands
+
+One app repo can contain ORM, managed functions, and an Artifact Studio UI.
+The root `sequence.app.yml` manifest declares the structure — required for
+scaffolding and for the eventual Applications UI. Do not hand-author apps
+without it.
+
+> **Availability:** This is currently an internal orchestration workflow.
+> Generated ORM apps depend on unpublished `@sequenceholdings/orm`, so
+> standalone external installs and the function-to-ORM runtime path are not
+> supported yet.
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio init <dir> --with <kinds>` | Scaffold an app monorepo + `sequence.app.yml` + selected primitive subfolders |
+| `seq-studio add function&#124;artifact <name>` | Add a function or Artifact Studio UI to the current app (updates the manifest) |
+| `seq-studio deploy -e <env> [--yes] [--only id1,id2] [--dry-run]` | Deploy every primitive in `deploy.order` (orm → functions → artifact) |
+
+`init` supports v0 kinds `orm`, `function`, and `artifact`; pass them as a
+comma-list (`--with orm,function,artifact`) or boolean flags (`--orm`). `add`
+currently supports functions and one Artifact Studio UI; ORM is created only by
+`init`.
+
+```bash
+# Full-stack toy (ORM + function + artifact) — workspace / internal CLI only
+seq-studio init pokedex --with orm,function,artifact --function-name get-pokemon
+cd pokedex
+(cd orm/pokedex && pnpm install)
+(cd functions/get-pokemon && pnpm install)
+(cd artifact && pnpm install)
+
+seq-studio login
+seq-studio deploy -e local --yes
+
+# Day-2: add a second function without re-init
+seq-studio add function list-types
+(cd functions/list-types && pnpm install)
+seq-studio deploy -e local --only list-types --yes
+```
+
+Each primitive keeps its own `package.json` / lockfile. `deploy` fans out to
+the existing per-primitive commands (`orm apply`, `functions deploy`,
+`artifact deploy`). Pass `--yes` for non-interactive function deploys.
+
+`deploy.on_error` defaults to `stop`. Set it to `continue` to deploy independent
+primitives after a failure; any primitive whose `depends_on` prerequisite failed
+or was skipped is skipped as well.
+
 ## Agent commands
 
 Typed agent repositories export one or more `defineAgent(...)` values from files
@@ -355,6 +405,25 @@ limits:
 `min_instances` defaults to `0`, cannot exceed `max_instances`, and incurs
 Cloud Run idle-instance charges while warm.
 
+### Server-owned resource authorization
+
+Some functions expose regulated external resources whose authorization must be
+enforced by Atlas rather than by author code. Those functions select a reviewed
+adapter in `managed-function.yml`:
+
+```yaml
+authorization:
+  version: 1
+  adapter: encompass.loan-read-by-number
+```
+
+The adapter name is a closed platform registry. Authors cannot provide JSON
+pointers or custom filtering logic. `seq-studio functions build` rejects an
+unknown adapter, an adapter on an unregistered function, or a protected
+function whose required adapter is missing. The manifest declares only the
+server-owned adapter; authors cannot configure its runtime resource selection
+or policy.
+
 ### ORM data access
 
 A function declares its ORM Data API reach in `capabilities.data`, grouped by
@@ -375,6 +444,22 @@ capabilities:
       operations: [RollLuckyNumber]
 ```
 
+## Managed Secret commands
+
+| Command | What it does |
+|---------|--------------|
+| `seq-studio secrets create <NAME> -e <env> [--org <slug>]` | Register an org-owned secret (no value) |
+| `seq-studio secrets set <NAME> -e <env> [--org <slug>] [--from-file <path>]` | Set the shared default (write-only; file is not echoed) |
+| `seq-studio secrets list -e <env>` | Secrets you can see (never values) |
+
+`--org` targets a managed-scope org other than the login tenant and selects
+the intended same-named secret for `set`, `attach`, `detach`, `versions`,
+`set-default`, and `pin`; it is required when the name exists in multiple
+orgs. Tenant pipeline credentials must be created on that tenant's deployment:
+`seq-studio secrets create NAME -e <tenant> --org <tenant>`. Sequence-owned
+environments (`local`, `staging`, `production`) only accept `--org sequence`.
+The API requires Managed Functions Admin on that org.
+
 ## Artifact commands
 
 `seq-studio artifact <sub>` is the entry point for Artifact Studio. It runs
@@ -545,15 +630,33 @@ install it alongside the CLI to use this family.
 
 | Command | What it does |
 |---------|--------------|
-| `seq-studio pipeline init --type ingestion\|transformation\|serving <name> [--dir <dir>]` | Scaffold `<name>.stage.yml` (commented per-kind template) plus a `src/` entrypoint stub (serving stages are declarative — no stub). Refuses to overwrite an existing spec |
-| `seq-studio pipeline validate [dir] [--assets <file\|url>] [--json]` | Run the full offline spec gate: envelope + body validation, `schema_ref` resolution, and repo-level graph validation (reference resolution, single-writer, cycles, column subsets, serving projection checks). Exit 0/1 |
-| `seq-studio pipeline plan --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--json]` | Plan a Pipeline deploy (materialize → SDK/`validateSpecGraph` → compile → live-diff → provision findings). Does **not** run Databricks `bundle validate` (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). `--json` emits the stable plan envelope |
-| `seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha> -e <env> [--approved-by <sub>] [--no-wait]` | Plan then enqueue deploy; Trigger runs `bundle validate` then `bundle deploy` against reviewed bytes. Polls to terminal unless `--no-wait`. Production/banksouth require a pinned 40-hex SHA (client + server) |
-| `seq-studio pipeline adopt --stage <slug> --ref <sha\|branch> -e <env> --native-id <id> --approved-by <you> [--resource-key <key>] [--kind job\|dlt_pipeline] [--old-source-removal-pr <url>] [--repo pipelines/<slug>]` | Bind a live Databricks job/pipeline into the stage without recreation (`bundle deployment bind` on Trigger). Always requires `--approved-by` naming the caller. When the key is still in the monorepo DAB, pass `--old-source-removal-pr` and follow the returned cutover checklist: unbind the old bundle state without deleting the remote, then remove its DAB declaration and add the target-specific adopted-resource entry in the same PR before redeploying. |
-| `seq-studio pipeline unbind --stage <slug> --ref <sha\|branch> -e <env> --approved-by <you> [--resource-key <key>] [--repo pipelines/<slug>]` | Release an adopted binding on Trigger; the remote object stays live (never deleted) |
-| `seq-studio pipeline run-now --stage <slug> -e <env> [--repo pipelines/<slug>] [--json]` | Run the stage's active job or DLT pipeline immediately and print its Databricks run URL |
-| `seq-studio pipeline promote --stage <slug> --version <v> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]` | Promote a validated version to another environment. Prod/banksouth require `--approved-by` naming the authenticated caller (approvals are self-recorded); `--repo` disambiguates a slug that exists in multiple Pipelines |
-| `seq-studio pipeline rollback --stage <slug> -e <env> [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]` | Redeploy the previously retired deployment's version. Prod/banksouth require `--approved-by` — approvals are explicit even for rollbacks |
+| `seq-studio pipeline init --type ingestion\|transformation\|serving <name> [--dir <dir>]` | Scaffold `<name>.stage.yml` (commented per-kind template) plus a `src/` Databricks-notebook entrypoint stub (begins with `# Databricks notebook source`; serving stages are declarative — no stub). Refuses to overwrite an existing spec |
+| `seq-studio pipeline validate [dir] [--assets <file\|url>] [--orm-contracts <file\|url>] [--json]` | Run the full offline spec gate: envelope + body validation, `schema_ref` resolution, and repo-level graph validation (reference resolution, single-writer, cycles, column subsets, serving projection checks). Auto-loads `orm-contracts.json` from the pipeline dir when present. Exit 0/1 |
+| `seq-studio pipeline plan --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--json]` | Plan a Pipeline deploy (materialize → SDK/`validateSpecGraph` → compile → live-diff → provision findings). Fails closed listing **every** missing target binding (alert channels, workspace, Databricks `source.credential`) plus Data Sync edge-worker machine/operation/`credEnvFamilies` mismatches before registry writes. Does **not** run Databricks `bundle validate` (that is a Trigger deploy-path hard gate). Exit 1 on destructive findings (CI-safe). `--json` emits the stable plan envelope |
+| `seq-studio pipeline deploy --repo pipelines/<slug> --ref <sha\|branch> -e <env> [--target <id>] [--approved-by <sub>] [--no-wait]` | Plan then enqueue deploy; Trigger runs `bundle validate` then `bundle deploy` against reviewed bytes. Polls to terminal unless `--no-wait`. Targets that require approval need `--approved-by` naming the authenticated caller. |
+| `seq-studio pipeline adopt --stage <slug> --ref <sha\|branch> -e <env> [--target <id>] --native-id <id> --approved-by <you> [--resource-key <key>] [--kind job\|dlt_pipeline] [--old-source-removal-pr <url>] [--repo pipelines/<slug>]` | Bind a live Databricks job/pipeline into the stage without recreation (`bundle deployment bind` on Trigger). Always requires `--approved-by` naming the caller. When the key is still in the monorepo DAB, pass `--old-source-removal-pr` and follow the returned cutover checklist: unbind the old bundle state without deleting the remote, then remove its DAB declaration and add the target-specific adopted-resource entry in the same PR before redeploying. |
+| `seq-studio pipeline unbind --stage <slug> --ref <sha\|branch> -e <env> [--target <id>] --approved-by <you> [--resource-key <key>] [--repo pipelines/<slug>]` | Release an adopted binding on Trigger; the remote object stays live (never deleted) |
+| `seq-studio pipeline run-now --stage <slug> -e <env> [--target <id>] [--repo pipelines/<slug>] [--json]` | Run the stage's active job or DLT pipeline immediately and print its Databricks run URL |
+| `seq-studio pipeline promote --stage <slug> --version <v> -e <env> [--target <id>] [--repo pipelines/<slug>] [--approved-by <you>] [--no-wait]` | Promote a validated version to another target. Targets that require approval need `--approved-by`; `--repo` disambiguates a slug that exists in multiple Pipelines |
+| `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. Targets that require approval need `--approved-by`. |
+
+`-e/--env` selects the Atlas connection. `--target` selects the logical
+pipeline target advertised by that endpoint. It is optional when the alias
+matches a target id or when the endpoint has exactly one target.
+
+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; failures include
+the status detail, and any available Trigger run ID is shown. `--json` output
+is unchanged.
+
+### Managed Pipelines asset identity
+
+Compiled Databricks assets use stable, environment-qualified identities: display names are `{env}-MP-{type}-{stage}` (with `-trigger` for a scheduled DLT runner), DAB resource keys are `mp_{type}_{stage_snake_case}` (with `_trigger` for that runner), task keys are `{type}_{task}`, and bundles are `{env}-MP-pipelines-{domain}`. Compiled jobs and pipelines also carry `mp: "true"` and `mp_type: <type>` tags.
+
+Changing a DAB resource key is a delete-and-create operation. Treat these identities as the existing-resource contract when planning, adopting, unbinding, or inspecting a Managed Pipeline; Unity Catalog catalogs, volumes, tables, and synced tables are not renamed by this convention.
+
+The `{env}-MP-…` scheme itself is a one-shot break from the unprefixed names (`silverlake-core`, `pipelines-<domain>-<env>`). We do not migrate DAB bundle state or DLT resource identity: the first deploy after this change creates a new bundle and new jobs/pipelines, and can cascade-drop DLT-managed tables on the deleted resource. Operators should pause or delete leftover unprefixed jobs once the new ones are healthy. Each enabled OpCo deployment advertises and owns its own target profile.
 
 `validate` is offline — no network or database. `--assets` supplies a
 registry **asset export** (JSON) so inputs referencing other Pipelines'

package/dist/app/commands.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Top-level app monorepo commands:
+ *   seq-studio init <dir> --with orm,function,artifact
+ *   seq-studio add <kind> <name>
+ *   seq-studio deploy -e <env>
+ */
+import type { ParsedArgs } from '../process/commands.js';
+export declare const APP_INIT_USAGE: string;
+export declare const APP_ADD_USAGE = "usage:\n  seq-studio add <kind> <name>\n\n  Scaffold another primitive into the current app monorepo (must contain\n  sequence.app.yml) and append it to the manifest.\n\n  Kinds: function | artifact\n  (orm is only created at init today)\n\n  Examples:\n    seq-studio add function list-types\n    seq-studio add artifact ui\n\n  Run from the app root (directory with sequence.app.yml).\n";
+export declare const APP_DEPLOY_USAGE = "usage:\n  seq-studio deploy -e <env> [options]\n\n  Deploy every primitive in sequence.app.yml in manifest deploy.order\n  (default: orm \u2192 functions \u2192 artifact). Runs each kind's existing command:\n    orm       \u2192 seq-studio orm apply <path> -e <env>\n    function  \u2192 seq-studio functions deploy --dir <path> -e <env> [--yes]\n    artifact  \u2192 seq-studio artifact deploy <path> -e <env>\n\n  Options:\n    -e, --env <name>     target environment (required)\n    --dir <path>         app root (default: cwd; must contain sequence.app.yml)\n    --only <id1,id2>     deploy only these primitive ids (order preserved)\n    --yes                non-interactive (forwarded to functions deploy)\n    --dry-run            print the plan without deploying\n\n  Examples:\n    seq-studio deploy -e staging --yes\n    seq-studio deploy -e local --only get-pokemon --yes\n    seq-studio deploy --dir ./pokedex -e staging --dry-run\n\n  Run from the app root (directory with sequence.app.yml), or pass --dir.\n";
+export declare function runAppInitCommand(args: ParsedArgs): Promise<number>;
+export declare function runAppAddCommand({ kindArg, args, }: {
+    kindArg: string | undefined;
+    args: ParsedArgs;
+}): Promise<number>;
+export declare function runAppDeployCommand(args: ParsedArgs): Promise<number>;

package/dist/app/commands.js

@@ -0,0 +1,227 @@
+/**
+ * Top-level app monorepo commands:
+ *   seq-studio init <dir> --with orm,function,artifact
+ *   seq-studio add <kind> <name>
+ *   seq-studio deploy -e <env>
+ */
+import { basename, resolve } from 'node:path';
+import { REQUIRE_EXPLICIT_ENV_MESSAGE } from '../env-flags.js';
+import { deployApp } from './deploy.js';
+import { resolveRequestedKinds } from './kinds.js';
+import { APP_MANIFEST_FILENAME, isPrimitiveKind, PRIMITIVE_KINDS, slugifyAppId, } from './manifest.js';
+import { addPrimitiveToApp, defaultScaffoldNames, initAppMonorepo, printInitNextSteps, } from './scaffold.js';
+const LOG = '[seq-studio]';
+export const APP_INIT_USAGE = `usage:
+  seq-studio init <dir> --with <kinds> [options]
+  seq-studio init <dir> --orm --function --artifact [options]
+
+  Scaffold an app monorepo with ${APP_MANIFEST_FILENAME} and one subfolder per
+  selected primitive. At least one kind is required.
+
+  Kinds: ${PRIMITIVE_KINDS.join(', ')}
+
+  Options:
+    --with <k1,k2,…>       comma-separated kinds to scaffold
+    --orm --function …     boolean aliases for --with
+    --function-name <n>    name/slug for the first function (default: hello)
+    --description <text>   optional app.description in the manifest
+
+  Examples:
+    seq-studio init pokedex --with orm,function,artifact
+    seq-studio init pokedex --with orm,function,artifact --function-name get-pokemon
+    seq-studio init loan-tools --with function --function-name get-loan
+`;
+export const APP_ADD_USAGE = `usage:
+  seq-studio add <kind> <name>
+
+  Scaffold another primitive into the current app monorepo (must contain
+  ${APP_MANIFEST_FILENAME}) and append it to the manifest.
+
+  Kinds: function | artifact
+  (orm is only created at init today)
+
+  Examples:
+    seq-studio add function list-types
+    seq-studio add artifact ui
+
+  Run from the app root (directory with ${APP_MANIFEST_FILENAME}).
+`;
+export const APP_DEPLOY_USAGE = `usage:
+  seq-studio deploy -e <env> [options]
+
+  Deploy every primitive in ${APP_MANIFEST_FILENAME} in manifest deploy.order
+  (default: orm → functions → artifact). Runs each kind's existing command:
+    orm       → seq-studio orm apply <path> -e <env>
+    function  → seq-studio functions deploy --dir <path> -e <env> [--yes]
+    artifact  → seq-studio artifact deploy <path> -e <env>
+
+  Options:
+    -e, --env <name>     target environment (required)
+    --dir <path>         app root (default: cwd; must contain ${APP_MANIFEST_FILENAME})
+    --only <id1,id2>     deploy only these primitive ids (order preserved)
+    --yes                non-interactive (forwarded to functions deploy)
+    --dry-run            print the plan without deploying
+
+  Examples:
+    seq-studio deploy -e staging --yes
+    seq-studio deploy -e local --only get-pokemon --yes
+    seq-studio deploy --dir ./pokedex -e staging --dry-run
+
+  Run from the app root (directory with ${APP_MANIFEST_FILENAME}), or pass --dir.
+`;
+function printError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${LOG} ${message}`);
+}
+export async function runAppInitCommand(args) {
+    if (args.flags.help === true || args.flags.h === true) {
+        console.log(APP_INIT_USAGE);
+        return 0;
+    }
+    const target = args.positional[0];
+    if (!target) {
+        console.error(APP_INIT_USAGE);
+        return 1;
+    }
+    let kinds;
+    try {
+        kinds = resolveRequestedKinds(args.flags);
+    }
+    catch (error) {
+        printError(error);
+        console.error(APP_INIT_USAGE);
+        return 1;
+    }
+    if (kinds.length === 0) {
+        console.error(`${LOG} select at least one primitive via --with orm,function,artifact`);
+        console.error(APP_INIT_USAGE);
+        return 1;
+    }
+    const appRoot = resolve(target);
+    const appId = slugifyAppId(basename(appRoot));
+    if (!appId) {
+        console.error(`${LOG} could not derive an app id from "${target}" — use a directory name with letters/numbers`);
+        return 1;
+    }
+    const names = defaultScaffoldNames(appId);
+    if (typeof args.flags['function-name'] === 'string') {
+        names.functionName = slugifyAppId(args.flags['function-name']) || names.functionName;
+    }
+    else if (args.flags['function-name'] === true) {
+        console.error(`${LOG} --function-name requires a value`);
+        return 1;
+    }
+    const description = typeof args.flags.description === 'string' ? args.flags.description : undefined;
+    if (args.flags.description === true) {
+        console.error(`${LOG} --description requires a value`);
+        return 1;
+    }
+    try {
+        const manifest = await initAppMonorepo({
+            rootDir: appRoot,
+            appId,
+            kinds,
+            names,
+            description,
+        });
+        printInitNextSteps({ appRoot, manifest });
+        return 0;
+    }
+    catch (error) {
+        printError(error);
+        return 1;
+    }
+}
+export async function runAppAddCommand({ kindArg, args, }) {
+    if (!kindArg || kindArg === 'help' || kindArg === '--help' || kindArg === '-h') {
+        console.log(APP_ADD_USAGE);
+        return kindArg ? 0 : 1;
+    }
+    if (!isPrimitiveKind(kindArg)) {
+        console.error(`${LOG} unknown kind '${kindArg}' — expected one of: ${PRIMITIVE_KINDS.join(', ')}`);
+        console.error(APP_ADD_USAGE);
+        return 1;
+    }
+    if (kindArg === 'orm') {
+        console.error(`${LOG} \`seq-studio add orm\` is not supported — orm is created at init`);
+        return 1;
+    }
+    const nameRaw = args.positional[0];
+    if (!nameRaw) {
+        console.error(`${LOG} usage: seq-studio add ${kindArg} <name>`);
+        return 1;
+    }
+    const name = slugifyAppId(nameRaw);
+    if (!name) {
+        console.error(`${LOG} invalid name "${nameRaw}" — use kebab-case`);
+        return 1;
+    }
+    try {
+        const { entry } = await addPrimitiveToApp({
+            rootDir: process.cwd(),
+            kind: kindArg,
+            name,
+        });
+        console.log(`${LOG} added ${entry.kind} "${entry.id}" at ${entry.path}`);
+        console.log(`${LOG} updated ${APP_MANIFEST_FILENAME}`);
+        if (entry.kind === 'function') {
+            console.log(`${LOG} next: cd ${entry.path} && pnpm install && seq-studio functions deploy --dir ${entry.path} -e local`);
+        }
+        return 0;
+    }
+    catch (error) {
+        printError(error);
+        return 1;
+    }
+}
+function flagString(flags, key) {
+    const value = flags[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function flagBool(flags, key) {
+    return flags[key] === true;
+}
+export async function runAppDeployCommand(args) {
+    if (args.flags.help === true || args.flags.h === true) {
+        console.log(APP_DEPLOY_USAGE);
+        return 0;
+    }
+    const env = flagString(args.flags, 'env') ?? flagString(args.flags, 'e');
+    if (!env) {
+        console.error(`${LOG} ${REQUIRE_EXPLICIT_ENV_MESSAGE}`);
+        console.error(APP_DEPLOY_USAGE);
+        return 1;
+    }
+    const dirFlag = flagString(args.flags, 'dir');
+    const rootDir = resolve(dirFlag ?? process.cwd());
+    let only;
+    const onlyRaw = flagString(args.flags, 'only');
+    if (args.flags.only === true) {
+        console.error(`${LOG} --only requires a comma-separated list of primitive ids`);
+        return 1;
+    }
+    if (onlyRaw) {
+        only = onlyRaw
+            .split(',')
+            .map((part) => part.trim())
+            .filter(Boolean);
+        if (only.length === 0) {
+            console.error(`${LOG} --only requires at least one primitive id`);
+            return 1;
+        }
+    }
+    try {
+        const result = await deployApp({
+            rootDir,
+            env,
+            only,
+            yes: flagBool(args.flags, 'yes'),
+            dryRun: flagBool(args.flags, 'dry-run'),
+        });
+        return result.exitCode;
+    }
+    catch (error) {
+        printError(error);
+        return 1;
+    }
+}

package/dist/app/deploy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Top-level `seq-studio deploy` — fan out from sequence.app.yml in deploy order.
+ *
+ * Child primitives keep their own deploy/apply verbs; this command only
+ * orchestrates them. Injectable runners keep unit tests offline.
+ */
+import { type AppManifest, type PrimitiveEntry, type PrimitiveKind } from './manifest.js';
+/**
+ * Resolve a manifest primitive path under the app root. Rejects absolute paths,
+ * lexical traversal, and symlink escapes (via realpath) before a deployer runs.
+ * Missing targets keep the lexical candidate after a lexical containment check.
+ */
+export declare function resolveContainedPrimitivePath({ rootDir, entryPath, }: {
+    rootDir: string;
+    entryPath: string;
+}): Promise<string>;
+export type DeployPrimitiveArgs = {
+    entry: PrimitiveEntry;
+    /** Absolute path to the primitive directory. */
+    path: string;
+    env: string;
+    yes: boolean;
+};
+export type PrimitiveDeployers = {
+    [K in PrimitiveKind]: (args: DeployPrimitiveArgs) => Promise<number>;
+};
+export type DeployAppOptions = {
+    rootDir: string;
+    env: string;
+    /** Restrict to these primitive ids (manifest order still applies). */
+    only?: readonly string[];
+    yes?: boolean;
+    dryRun?: boolean;
+    deployers?: PrimitiveDeployers;
+};
+export type DeployAppResult = {
+    attempted: string[];
+    succeeded: string[];
+    failed: string[];
+    skipped: string[];
+    exitCode: number;
+};
+/** Resolve ordered primitive entries for deploy, validating order / --only ids. */
+export declare function resolveDeployEntries({ manifest, only, }: {
+    manifest: AppManifest;
+    only?: readonly string[];
+}): PrimitiveEntry[];
+export declare function createDefaultDeployers(): Promise<PrimitiveDeployers>;
+export declare function deployApp(options: DeployAppOptions): Promise<DeployAppResult>;

package/dist/app/deploy.js

@@ -0,0 +1,197 @@
+/**
+ * Top-level `seq-studio deploy` — fan out from sequence.app.yml in deploy order.
+ *
+ * Child primitives keep their own deploy/apply verbs; this command only
+ * orchestrates them. Injectable runners keep unit tests offline.
+ */
+import { realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { defaultDeployOrder, loadAppManifest, } from './manifest.js';
+const LOG = '[seq-studio]';
+const APP_MANIFEST_HINT = 'sequence.app.yml';
+function assertRelativePrimitivePath(entryPath) {
+    const segments = entryPath.split('/');
+    if (entryPath.length === 0 ||
+        entryPath.trim() !== entryPath ||
+        isAbsolute(entryPath) ||
+        entryPath.includes('\\') ||
+        [...entryPath].some((character) => character.charCodeAt(0) < 0x20) ||
+        segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw new Error(`${APP_MANIFEST_HINT}: primitive path must be a relative directory within the app root (got ${JSON.stringify(entryPath)})`);
+    }
+}
+function assertPathInsideRoot({ rootDir, candidate, entryPath, }) {
+    const relativePath = relative(rootDir, candidate);
+    if (relativePath === '..' ||
+        relativePath.startsWith(`..${sep}`) ||
+        isAbsolute(relativePath)) {
+        throw new Error(`${APP_MANIFEST_HINT}: primitive path escapes the app root (got ${JSON.stringify(entryPath)})`);
+    }
+}
+/**
+ * Resolve a manifest primitive path under the app root. Rejects absolute paths,
+ * lexical traversal, and symlink escapes (via realpath) before a deployer runs.
+ * Missing targets keep the lexical candidate after a lexical containment check.
+ */
+export async function resolveContainedPrimitivePath({ rootDir, entryPath, }) {
+    assertRelativePrimitivePath(entryPath);
+    const root = resolve(rootDir);
+    let canonicalRoot = root;
+    try {
+        canonicalRoot = await realpath(root);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    // Resolve against the canonical root so macOS /var → /private/var does not
+    // look like an escape when comparing realpath(root) to a lexical candidate.
+    const candidate = resolve(canonicalRoot, entryPath);
+    assertPathInsideRoot({ rootDir: canonicalRoot, candidate, entryPath });
+    try {
+        const canonicalCandidate = await realpath(candidate);
+        assertPathInsideRoot({
+            rootDir: canonicalRoot,
+            candidate: canonicalCandidate,
+            entryPath,
+        });
+        return canonicalCandidate;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        // Target does not exist yet (dry-run / pre-scaffold) — lexical check stands.
+        return candidate;
+    }
+}
+/** Resolve ordered primitive entries for deploy, validating order / --only ids. */
+export function resolveDeployEntries({ manifest, only, }) {
+    const byId = new Map(manifest.primitives.map((entry) => [entry.id, entry]));
+    const order = manifest.deploy.order && manifest.deploy.order.length > 0
+        ? manifest.deploy.order
+        : defaultDeployOrder(manifest.primitives);
+    for (const id of order) {
+        if (!byId.has(id)) {
+            throw new Error(`${APP_MANIFEST_HINT}: deploy.order references unknown primitive id "${id}"`);
+        }
+    }
+    // Include primitives missing from an incomplete explicit order (append by default).
+    const orderedIds = [...order];
+    for (const entry of manifest.primitives) {
+        if (!orderedIds.includes(entry.id))
+            orderedIds.push(entry.id);
+    }
+    if (only && only.length > 0) {
+        const unknown = only.filter((id) => !byId.has(id));
+        if (unknown.length > 0) {
+            throw new Error(`Unknown primitive id(s) in --only: ${unknown.join(', ')}. Known: ${[...byId.keys()].join(', ')}`);
+        }
+        const onlySet = new Set(only);
+        return orderedIds
+            .filter((id) => onlySet.has(id))
+            .map((id) => byId.get(id));
+    }
+    return orderedIds.map((id) => byId.get(id));
+}
+export async function createDefaultDeployers() {
+    const { runOrmCommand } = await import('../orm/delegate.js');
+    const { functionsDeployCommand } = await import('../functions/commands.js');
+    const { runArtifactCommand } = await import('../artifact/delegate.js');
+    return {
+        async orm({ path, env }) {
+            return runOrmCommand('apply', [path, '--env', env]);
+        },
+        async function({ path, env, yes }) {
+            return functionsDeployCommand({
+                positional: [],
+                flags: {
+                    dir: path,
+                    env,
+                    ...(yes ? { yes: true } : {}),
+                },
+            });
+        },
+        async artifact({ path, env }) {
+            return runArtifactCommand('deploy', [path, '--env', env]);
+        },
+    };
+}
+export async function deployApp(options) {
+    const rootDir = resolve(options.rootDir);
+    const manifest = await loadAppManifest(rootDir);
+    const entries = resolveDeployEntries({ manifest, only: options.only });
+    const onError = manifest.deploy.on_error;
+    const deployers = options.deployers ?? (await createDefaultDeployers());
+    // Validate every selected path before any deployer runs (including dry-run).
+    const resolvedPaths = new Map();
+    for (const entry of entries) {
+        resolvedPaths.set(entry.id, await resolveContainedPrimitivePath({ rootDir, entryPath: entry.path }));
+    }
+    console.log(`${LOG} deploying app "${manifest.app.id}" (${entries.length} primitive(s)) → ${options.env}`);
+    for (const entry of entries) {
+        console.log(`${LOG}   - ${entry.kind.padEnd(9)} ${entry.id}  (${entry.path})`);
+    }
+    if (options.dryRun) {
+        console.log(`${LOG} dry-run: no primitives deployed`);
+        return {
+            attempted: [],
+            succeeded: [],
+            failed: [],
+            skipped: entries.map((entry) => entry.id),
+            exitCode: 0,
+        };
+    }
+    const attempted = [];
+    const succeeded = [];
+    const failed = [];
+    const skipped = [];
+    /** Failed or dependency-skipped ids — blocks transitive `depends_on` edges. */
+    const unavailable = new Set();
+    let stop = false;
+    for (const entry of entries) {
+        if (stop) {
+            skipped.push(entry.id);
+            unavailable.add(entry.id);
+            console.log(`${LOG} skip ${entry.id} (stopped after earlier failure)`);
+            continue;
+        }
+        const blockedBy = entry.depends_on.filter((id) => unavailable.has(id));
+        if (blockedBy.length > 0) {
+            skipped.push(entry.id);
+            unavailable.add(entry.id);
+            console.log(`${LOG} skip ${entry.id} (depends on failed/skipped: ${blockedBy.join(', ')})`);
+            continue;
+        }
+        const path = resolvedPaths.get(entry.id);
+        attempted.push(entry.id);
+        console.log(`${LOG} → ${entry.kind} ${entry.id}`);
+        let code;
+        try {
+            code = await deployers[entry.kind]({
+                entry,
+                path,
+                env: options.env,
+                yes: options.yes === true,
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`${LOG} ${entry.id} threw: ${message}`);
+            code = 1;
+        }
+        if (code === 0) {
+            succeeded.push(entry.id);
+            console.log(`${LOG} ✓ ${entry.id}`);
+        }
+        else {
+            failed.push(entry.id);
+            unavailable.add(entry.id);
+            console.error(`${LOG} ✗ ${entry.id} exited ${code}`);
+            if (onError === 'stop')
+                stop = true;
+        }
+    }
+    const exitCode = failed.length > 0 ? 1 : 0;
+    console.log(`${LOG} deploy finished: ${succeeded.length} ok, ${failed.length} failed, ${skipped.length} skipped`);
+    return { attempted, succeeded, failed, skipped, exitCode };
+}

package/dist/app/kinds.d.ts

@@ -0,0 +1,10 @@
+import { type PrimitiveKind } from './manifest.js';
+/**
+ * Resolve which primitive kinds to scaffold from CLI flags.
+ *
+ * Supports:
+ *   --with orm,function,artifact
+ *   --with=orm,function
+ *   --orm --function --artifact   (boolean aliases)
+ */
+export declare function resolveRequestedKinds(flags: Record<string, string | true>): PrimitiveKind[];