@sequenceholdings/studio-cli 0.1.21 → 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
@@ -145,13 +195,17 @@ bundle; it never implicitly deletes agents.
 | Command | What it does |
 |---------|--------------|
 | `seq-studio agents init <dir>` | Scaffold a standalone typed agent repository |
-| `seq-studio agents validate [--dir <dir>] [--target <APP_ENV>]` | Compile and validate locally, without API access |
-| `seq-studio agents plan [--dir <dir>]` | Offline compile/hash plan |
-| `seq-studio agents plan [--dir <dir>] -e <env> [--target <APP_ENV>]` | Diff creates, updates, and unchanged definitions against an environment |
-| `seq-studio agents apply [--dir <dir>] -e <env> [--target <APP_ENV>] [--yes]` | Apply creates and updates after showing the plan |
+| `seq-studio agents validate [--dir <dir>] [--target <APP_ENV>] [--only <id1,id2>]` | Compile and validate locally, without API access |
+| `seq-studio agents plan [--dir <dir>] [--only <id1,id2>]` | Offline compile/hash plan |
+| `seq-studio agents plan [--dir <dir>] -e <env> [--target <APP_ENV>] [--only <id1,id2>]` | Diff creates, updates, and unchanged definitions against an environment |
+| `seq-studio agents apply [--dir <dir>] -e <env> [--target <APP_ENV>] [--only <id1,id2>] [--yes]` | Apply creates and updates after showing the plan |
 | `seq-studio agents list -e <env>` | List visible runtime agents |
 | `seq-studio agents show <id> -e <env>` | Show one runtime agent |
 
+For `validate`, `plan`, and `apply`, `--only` accepts a comma-separated list of
+agent IDs after deployment-environment selection; every requested ID must be
+selected.
+
 An optional `deploy-manifest.json` targets definitions by deployment identity:
 
 ```json
@@ -187,8 +241,10 @@ Use `--repo agents/<name> [--ref <ref>]` or `--git-url <url>` instead of
 ## ORM commands
 
 `seq-studio orm` authors and deploys governed ORM v2 namespaces: TypeScript
-table definitions and policies plus named GraphQL documents compiled into
-persisted operations.
+table definitions, Drizzle-authored read-only views, and policies plus named
+GraphQL documents compiled into persisted operations. Import Drizzle query
+helpers from `@sequenceholdings/orm/drizzle`; managed view builders are
+compiled to canonical SQL before registration.
 
 | Command | What it does |
 |---------|--------------|
@@ -335,6 +391,75 @@ same repo share Git review and commit provenance, but keep separate manifests,
 versions, runtime resources, secrets, and permissions. `--path` accepts only a
 canonical relative directory inside a remote repo; use `--dir` for local source.
 
+### Scaling
+
+Managed functions scale to zero by default. Set a bounded warm pool in
+`managed-function.yml` when first-request latency matters:
+
+```yaml
+limits:
+  min_instances: 1
+  max_instances: 3
+```
+
+`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
+namespace: `tables` it may read, v1 `actions` and ORM v2 persisted `operations`
+it may invoke, and whether raw read `query` is allowed. At invoke time the
+platform mints a short-lived data token scoped to exactly these refs — an
+operation is scoped as `<namespace>/ops/<OperationName>` (the GraphQL operation
+name from the namespace's `graphql/` documents, case-sensitive), and anything
+undeclared is denied by the Data API. A function that reaches any namespace
+must also attach a top-level `service_account`:
+
+```yaml
+service_account: lucky-svc
+capabilities:
+  data:
+    lucky:
+      tables: [lucky_draws]
+      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
@@ -467,11 +592,34 @@ JSON API — the same repos `--repo <ns>/<name>` sources build from.
 | `seq-studio repos clone <ns>/<name> \| --url <clone-url> \| --id <uuid> -e <env> [--ref <r>] [--out <dir>] [--force]` | smart-HTTP `git clone` when `ATLAS_GIT_PAT` is set (`--url`/`--id` need no seqapi); otherwise JSON materialize + PAT hint |
 | `seq-studio repos pull <ns>/<name> -e <env> [--ref <r>] [--out <dir>] [--force]` | always materialize via JSON API (no `.git` dir); refuses a non-empty destination unless `--force` |
 | `seq-studio repos delete <ns>/<name> -e <env> [--yes]` | delete a repo — interactive confirm unless `--yes` |
+| `seq-studio repos ci show <ns>/<name> -e <env> [--ref <r>]` | preview CI checks discovered from the ref |
+| `seq-studio repos ci require <ns>/<name> --check <name> -e <env>` | reserved for requiring a named CI check; currently refuses to write until the sandboxed runner is live |
+| `seq-studio repos ci import <ns>/<name> -e <env> [--ref <r>]` | reserved for requiring every discovered check; currently refuses to write until the sandboxed runner is live |
 
 `show` prints the smart-HTTP clone URL (`…/repos/<id>/git`). Basic auth:
 any username, PAT as password. Prefer `repos clone` over hand-rolling the
 tree API.
 
+PR CI discovers `ci/check` from the first available `lint`, `typecheck`, or
+`check` script and `ci/test` from `test`. A `.seq/ci.json` takes precedence;
+its `checks` array can declare script/argv checks or be empty to opt out.
+
+For example:
+
+    { "checks": [
+      { "phase": "check", "script": "lint" },
+      { "phase": "test", "command": ["pnpm", "test"] }
+    ] }
+
+Each check needs `phase` (`check` or `test`) and exactly one of `script` or
+`command`; `name` is optional and otherwise defaults to `ci/<phase>`
+(`-2`, etc. for additional checks in that phase).
+Discovery alone never blocks a merge. Until the sandboxed executor is live,
+`repos ci show` is preview-only, Settings controls are disabled, and
+`require`/`import` refuse to write (discovery currently posts `neutral`
+check-runs). Once the executor is live, repo owners can opt in by requiring
+check names in Settings or with `repos ci require`/`repos ci import`.
+
 ## Pipeline commands
 
 `seq-studio pipeline <sub>` authors and validates Data Pipelines **stage
@@ -482,13 +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 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/agents/commands.d.ts

@@ -6,5 +6,5 @@ export declare function agentsPlanCommand(args: ParsedArgs): Promise<number>;
 export declare function agentsApplyCommand(args: ParsedArgs): Promise<number>;
 export declare function agentsListCommand(args: ParsedArgs): Promise<number>;
 export declare function agentsShowCommand(args: ParsedArgs): Promise<number>;
-export declare const AGENTS_USAGE = "usage:\n  seq-studio agents init <dir>                         scaffold a typed agent\n  seq-studio agents validate [--dir d] [--target app] offline compile + validation\n  seq-studio agents plan [--dir d] [-e <env>]          offline bundle plan or live diff\n  seq-studio agents apply [--dir d] -e <env> [--yes]  apply creates/updates; never deletes\n  seq-studio agents list -e <env>                      list visible agents\n  seq-studio agents show <id> -e <env>                 show one agent\n\n  Source: local --dir (default .), --repo agents/<name>, or --git-url <url>.\n  Use --ref for remote sources. --target selects the deployment APP_ENV when it\n  differs from the CLI environment alias (notably OpCo registrations).\n";
+export declare const AGENTS_USAGE = "usage:\n  seq-studio agents init <dir>                         scaffold a typed agent\n  seq-studio agents validate [--dir d] [--target app] [--only ids] offline compile + validation\n  seq-studio agents plan [--dir d] [-e <env>] [--only ids]          offline bundle plan or live diff\n  seq-studio agents apply [--dir d] -e <env> [--only ids] [--yes]  apply creates/updates; never deletes\n  seq-studio agents list -e <env>                      list visible agents\n  seq-studio agents show <id> -e <env>                 show one agent\n\n  Source: local --dir (default .), --repo agents/<name>, or --git-url <url>.\n  Use --ref for remote sources. --target selects the deployment APP_ENV when it\n  differs from the CLI environment alias (notably OpCo registrations). --only\n  accepts a comma-separated list of agent IDs after environment selection.\n";
 export declare function runAgentsCommand(sub: string | undefined, args: ParsedArgs): Promise<number>;

package/dist/agents/commands.js

@@ -7,6 +7,22 @@ import { compileAgentSource as compileSource, materializeAgentSource as material
 import { agentsInitCommand } from './scaffold.js';
 export { agentsInitCommand };
 const LOG = '[seq-studio]';
+function requestedAgentIds(args) {
+    const only = args.flags.only;
+    if (only === undefined)
+        return undefined;
+    if (typeof only !== 'string') {
+        throw new Error('--only must be a comma-separated list of agent IDs');
+    }
+    const ids = only
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+    if (ids.length === 0) {
+        throw new Error('--only must include at least one agent ID');
+    }
+    return [...new Set(ids)];
+}
 export async function agentsValidateCommand(args) {
     const { source } = await materialize({ args, requireEnvironment: false });
     try {
@@ -15,6 +31,7 @@ export async function agentsValidateCommand(args) {
             directory: source.dir,
             targetEnvironment: target,
             deployEnvironments: await deployEnvironmentNames(),
+            onlyIds: requestedAgentIds(args),
         });
         if (bundle.definitions.length === 0) {
             console.error(`${LOG} no named agent.ts definitions found`);
@@ -34,6 +51,7 @@ async function deploymentBundle({ args, source, context, }) {
         directory: source.dir,
         targetEnvironment: target,
         deployEnvironments: await deployEnvironmentNames(),
+        onlyIds: requestedAgentIds(args),
     });
 }
 /**
@@ -75,6 +93,7 @@ export async function agentsPlanCommand(args) {
                 directory: source.dir,
                 targetEnvironment: target,
                 deployEnvironments: await deployEnvironmentNames(),
+                onlyIds: requestedAgentIds(args),
             });
             console.log(`${LOG} offline plan: ${bundle.definitions.length} valid definition${bundle.definitions.length === 1 ? '' : 's'}, bundle ${bundle.hash}`);
             console.log(`${LOG} pass -e <env> for create/update/unchanged live diff`);
@@ -174,15 +193,16 @@ export async function agentsShowCommand(args) {
 }
 export const AGENTS_USAGE = `usage:
   seq-studio agents init <dir>                         scaffold a typed agent
-  seq-studio agents validate [--dir d] [--target app] offline compile + validation
-  seq-studio agents plan [--dir d] [-e <env>]          offline bundle plan or live diff
-  seq-studio agents apply [--dir d] -e <env> [--yes]  apply creates/updates; never deletes
+  seq-studio agents validate [--dir d] [--target app] [--only ids] offline compile + validation
+  seq-studio agents plan [--dir d] [-e <env>] [--only ids]          offline bundle plan or live diff
+  seq-studio agents apply [--dir d] -e <env> [--only ids] [--yes]  apply creates/updates; never deletes
   seq-studio agents list -e <env>                      list visible agents
   seq-studio agents show <id> -e <env>                 show one agent
 
   Source: local --dir (default .), --repo agents/<name>, or --git-url <url>.
   Use --ref for remote sources. --target selects the deployment APP_ENV when it
-  differs from the CLI environment alias (notably OpCo registrations).
+  differs from the CLI environment alias (notably OpCo registrations). --only
+  accepts a comma-separated list of agent IDs after environment selection.
 `;
 export async function runAgentsCommand(sub, args) {
     try {

package/dist/agents/source.d.ts

@@ -10,9 +10,11 @@ export declare function materializeAgentSource({ args, requireEnvironment, }: {
     source: ResolvedSource;
     context: CommandContext | null;
 }>;
-export declare function compileAgentSource({ directory, targetEnvironment, deployEnvironments, }: {
+export declare function compileAgentSource({ directory, targetEnvironment, deployEnvironments, onlyIds, }: {
     directory: string;
     targetEnvironment?: string;
     /** Registered deployment environments, so a real env absent from the manifest is not read as a typo. */
     deployEnvironments?: readonly string[];
+    /** Restrict a plan or apply to explicit agent IDs after environment selection. */
+    onlyIds?: readonly string[];
 }): Promise<CompiledAgentBundle>;

package/dist/agents/source.js

@@ -87,10 +87,25 @@ async function compileManifestEntries({ directory, entries, allowDuplicateIds =
         sources: compiled.sources,
     };
 }
-export async function compileAgentSource({ directory, targetEnvironment, deployEnvironments = [], }) {
+export async function compileAgentSource({ directory, targetEnvironment, deployEnvironments = [], onlyIds, }) {
     const manifest = await readManifest(directory);
-    if (!manifest)
-        return compileAgentDirectory({ rootDir: directory });
+    if (!manifest) {
+        const compiled = await compileAgentDirectory({ rootDir: directory });
+        if (!onlyIds || onlyIds.length === 0)
+            return compiled;
+        const requested = new Set(onlyIds);
+        const definitions = compiled.definitions.filter((definition) => requested.has(definition.id));
+        const missing = [...requested].filter((id) => !definitions.some((definition) => definition.id === id));
+        if (missing.length > 0) {
+            throw new Error(`Requested agent IDs were not selected: ${missing.join(', ')}`);
+        }
+        return {
+            ...compiled,
+            definitions,
+            hash: hashAgentBundle({ definitions }),
+            sources: compiled.sources.filter((source) => requested.has(source.definition.id)),
+        };
+    }
     if (targetEnvironment !== undefined) {
         assertKnownTargetEnvironment({
             manifest,
@@ -109,10 +124,18 @@ export async function compileAgentSource({ directory, targetEnvironment, deployE
     }
     // With a target: last-wins by id (tenant overrides). Without: every distinct
     // path, so validate still compiles override sources that lose a collapse.
-    const entries = selectAgentEntries({
+    const selectedEntries = selectAgentEntries({
         manifest,
         environment: targetEnvironment,
     });
+    const requested = new Set(onlyIds);
+    const entries = requested.size === 0
+        ? selectedEntries
+        : selectedEntries.filter((entry) => requested.has(entry.id));
+    const missing = [...requested].filter((id) => !entries.some((entry) => entry.id === id));
+    if (missing.length > 0) {
+        throw new Error(`Requested agent IDs were not selected: ${missing.join(', ')}`);
+    }
     return compileManifestEntries({
         directory,
         entries,

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;
+    }
+}