@usenaive-sdk/blueprints 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,408 @@
+import { z } from 'zod';
+import { VettaClient } from '@usenaive-sdk/vetta';
+
+/**
+ * Blueprints and their templates.
+ *
+ * A **blueprint** is the machine: screens, `/api/*`, the store, build and deploy, the approval
+ * flow. It is one repository, and it is shared across its templates. A **template** is DATA — the
+ * crew and its prompts, the tool allow-lists, the kinds of work it files, its schedules, the demo
+ * seed and the words its screens print. One repo carries every template its blueprint has, so
+ * switching is an edit plus `naive up`: never a re-clone, never a new app.
+ *
+ * The pair is checked here and refused at define time (`define.ts`), in the author's own
+ * vocabulary, for the same reason every other refusal is: a wrong pair discovered at apply time is
+ * discovered against a half-provisioned organization.
+ */
+
+/** One kind of work a template files — a deliverable kind, a post kind. `id` is what rows carry. */
+interface TemplateKind {
+    id: string;
+    label: string;
+    description?: string;
+}
+/**
+ * The data module a blueprint repo exports, one per template it carries. Everything here is data:
+ * nothing in it is a function, a component or a route, because those are the blueprint's and are
+ * shared. `agents` is the config's own `agents` shape, so a template declares a crew exactly as a
+ * hand-written config would — prompts, tool allow-lists and schedules included.
+ */
+interface Template {
+    /** Spelled exactly as `defineProject({ template })` and `naive template --template` name it. */
+    name: string;
+    /** One line for the operator: what this crew does. */
+    description: string;
+    agents: AgentDecl[];
+    /** The kinds this template's queue holds; the screens list them in this order. */
+    kinds: TemplateKind[];
+    /** The demo rows the store seeds on first run, keyed by collection (`clients`, `posts`, …). */
+    seed: Record<string, unknown>;
+    /** Every word a screen prints that changes with the template — headings, labels, onboarding copy. */
+    words: Record<string, string>;
+}
+/**
+ * Every blueprint and the templates it carries. `agency` defaults to `blank` — a working agency
+ * with no specialism is a safe thing to get by accident. `media` has NO default on purpose: its
+ * two crews spend money in different ways, so defaulting one of them is a bill the operator did
+ * not choose.
+ */
+declare const BLUEPRINTS: Record<string, {
+    templates: readonly string[];
+    default?: string;
+}>;
+/** Resolved (a default may have filled it in), or the refusal's own words for the caller to raise. */
+type TemplateChoice = {
+    ok: true;
+    template: string | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+/** The one place a `blueprint` / `template` pair is judged — `defineProject` and the CLI share it. */
+declare function chooseTemplate(blueprint: string | undefined, template: string | undefined): TemplateChoice;
+
+/**
+ * A config that loaded but refuses itself. A distinct class so the loader can tell "the author's
+ * declaration is wrong" apart from "the module could not be evaluated" — the two failure modes the
+ * old `naive up` collapsed into one, silently.
+ */
+declare class BlueprintRefusal extends Error {
+    readonly name = "BlueprintRefusal";
+}
+declare const AppDeclSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        frontend_only: "frontend_only";
+        fullstack: "fullstack";
+    }>;
+    description: z.ZodOptional<z.ZodString>;
+    deploy_dir: z.ZodOptional<z.ZodString>;
+    mcp: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        from_env: z.ZodString;
+    }, z.core.$strip>]>>>;
+}, z.core.$strip>;
+/**
+ * A cron on the agent — a platform deployment (§12) minus what `up` fills in: `agent_id`, and the
+ * `identity`, a declared persona *name* like the agent's own. `cron` is the key the reconciler
+ * matches live rows by (deployments have no name), so it must be unique within one agent.
+ * `budget_micro_usd` has no default on `POST /v1/deployments`, so it is required here for the
+ * same reason the agent's `budget` is.
+ */
+declare const ScheduleDeclSchema: z.ZodObject<{
+    cron: z.ZodString;
+    timezone: z.ZodOptional<z.ZodString>;
+    input: z.ZodString;
+    budget_micro_usd: z.ZodNumber;
+    identity: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Exactly the `POST /v1/agents` fields a blueprint declares — `model` and `budget` are required by that route, so requiring them here turns a guaranteed apply-time refusal into a define-time one. */
+declare const AgentDeclSchema: z.ZodObject<{
+    name: z.ZodString;
+    model: z.ZodString;
+    budget: z.ZodObject<{
+        cap_micro_usd: z.ZodNumber;
+        max_task_micro_usd: z.ZodNumber;
+        period: z.ZodEnum<{
+            day: "day";
+            week: "week";
+            month: "month";
+        }>;
+    }, z.core.$strip>;
+    description: z.ZodOptional<z.ZodString>;
+    system: z.ZodOptional<z.ZodString>;
+    tools: z.ZodOptional<z.ZodObject<{
+        default_config: z.ZodObject<{
+            permission: z.ZodEnum<{
+                allow: "allow";
+                ask: "ask";
+                deny: "deny";
+            }>;
+        }, z.core.$strip>;
+        configs: z.ZodRecord<z.ZodString, z.ZodObject<{
+            enabled: z.ZodBoolean;
+            permission: z.ZodEnum<{
+                allow: "allow";
+                ask: "ask";
+                deny: "deny";
+            }>;
+            config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    mcp_servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodURL;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>>;
+    allowed_apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    identity: z.ZodOptional<z.ZodString>;
+    schedules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        cron: z.ZodString;
+        timezone: z.ZodOptional<z.ZodString>;
+        input: z.ZodString;
+        budget_micro_usd: z.ZodNumber;
+        identity: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * A vault credential (§23) minus what `up` fills in. `value` is a real third-party secret, so it is
+ * `{ from_env }` only — never a literal — and travels once, on create. Values are write-only and
+ * rows immutable, so `kind`, `key` and `host` / `mcp_server_url` are all the reconciler can match a
+ * live row by.
+ */
+declare const CredentialDeclSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        env_var: "env_var";
+        static_bearer: "static_bearer";
+        mcp_oauth: "mcp_oauth";
+    }>;
+    key: z.ZodString;
+    host: z.ZodOptional<z.ZodString>;
+    mcp_server_url: z.ZodOptional<z.ZodURL>;
+    value: z.ZodObject<{
+        from_env: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/** `name` is the vault's `display_name`, the key it is found by; `identity` a declared persona *name*. */
+declare const VaultDeclSchema: z.ZodObject<{
+    name: z.ZodString;
+    identity: z.ZodOptional<z.ZodString>;
+    credentials: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            env_var: "env_var";
+            static_bearer: "static_bearer";
+            mcp_oauth: "mcp_oauth";
+        }>;
+        key: z.ZodString;
+        host: z.ZodOptional<z.ZodString>;
+        mcp_server_url: z.ZodOptional<z.ZodURL>;
+        value: z.ZodObject<{
+            from_env: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** `file` holds the skill body, resolved against the config's directory; the slug grammar is `POST /v1/skills`' (§13). */
+declare const SkillDeclSchema: z.ZodObject<{
+    slug: z.ZodString;
+    file: z.ZodString;
+}, z.core.$strip>;
+declare const IdentityDeclSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    name: z.ZodString;
+}, z.core.$strip>;
+declare const ProjectSchema: z.ZodObject<{
+    name: z.ZodString;
+    blueprint: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodString>;
+    skills: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        file: z.ZodString;
+    }, z.core.$strip>>>;
+    identities: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        name: z.ZodString;
+    }, z.core.$strip>>>;
+    vaults: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        identity: z.ZodOptional<z.ZodString>;
+        credentials: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                env_var: "env_var";
+                static_bearer: "static_bearer";
+                mcp_oauth: "mcp_oauth";
+            }>;
+            key: z.ZodString;
+            host: z.ZodOptional<z.ZodString>;
+            mcp_server_url: z.ZodOptional<z.ZodURL>;
+            value: z.ZodObject<{
+                from_env: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    apps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            frontend_only: "frontend_only";
+            fullstack: "fullstack";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        deploy_dir: z.ZodOptional<z.ZodString>;
+        mcp: z.ZodOptional<z.ZodString>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            from_env: z.ZodString;
+        }, z.core.$strip>]>>>;
+    }, z.core.$strip>>>;
+    agents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        model: z.ZodString;
+        budget: z.ZodObject<{
+            cap_micro_usd: z.ZodNumber;
+            max_task_micro_usd: z.ZodNumber;
+            period: z.ZodEnum<{
+                day: "day";
+                week: "week";
+                month: "month";
+            }>;
+        }, z.core.$strip>;
+        description: z.ZodOptional<z.ZodString>;
+        system: z.ZodOptional<z.ZodString>;
+        tools: z.ZodOptional<z.ZodObject<{
+            default_config: z.ZodObject<{
+                permission: z.ZodEnum<{
+                    allow: "allow";
+                    ask: "ask";
+                    deny: "deny";
+                }>;
+            }, z.core.$strip>;
+            configs: z.ZodRecord<z.ZodString, z.ZodObject<{
+                enabled: z.ZodBoolean;
+                permission: z.ZodEnum<{
+                    allow: "allow";
+                    ask: "ask";
+                    deny: "deny";
+                }>;
+                config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mcp_servers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodURL;
+            headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>>>;
+        allowed_apps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        identity: z.ZodOptional<z.ZodString>;
+        schedules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            cron: z.ZodString;
+            timezone: z.ZodOptional<z.ZodString>;
+            input: z.ZodString;
+            budget_micro_usd: z.ZodNumber;
+            identity: z.ZodOptional<z.ZodString>;
+            enabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    removed: z.ZodDefault<z.ZodObject<{
+        apps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        skills: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        identities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        vaults: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    kept: z.ZodDefault<z.ZodObject<{
+        agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type AppDecl = z.infer<typeof AppDeclSchema>;
+type AgentDecl = z.infer<typeof AgentDeclSchema>;
+type ScheduleDecl = z.infer<typeof ScheduleDeclSchema>;
+type SkillDecl = z.infer<typeof SkillDeclSchema>;
+type IdentityDecl = z.infer<typeof IdentityDeclSchema>;
+type VaultDecl = z.infer<typeof VaultDeclSchema>;
+type CredentialDecl = z.infer<typeof CredentialDeclSchema>;
+type ProjectConfig = z.infer<typeof ProjectSchema>;
+/** Validate an untyped value (a loaded `.json`, an evaluated module) into a frozen project. */
+declare function parseProject(input: unknown): Readonly<ProjectConfig>;
+/** A config, plus the template data modules its blueprint repo carries (`template.ts`). */
+interface DefineInput extends z.input<typeof ProjectSchema> {
+    /**
+     * Every template this blueprint has — all of them, not just the chosen one. The chosen one's
+     * agents become the project's crew; the others are what the switch rule keeps, which is why a
+     * repo that carries only some of them is refused: switching would silently narrow.
+     */
+    templates?: readonly Template[];
+}
+/** The one export a `naive.config.ts` calls. Identity plus validation; the object comes back frozen. */
+declare function defineProject({ templates, ...input }: DefineInput): Readonly<ProjectConfig>;
+
+declare const CONFIG_CANDIDATES: readonly ["naive.config.ts", "naive.config.js", "naive.config.mjs", "naive.config.json"];
+type ConfigLoad = {
+    ok: true;
+    path: string;
+    config: Readonly<ProjectConfig>;
+}
+/** No candidate file exists in the directory. */
+ | {
+    ok: false;
+    reason: "not_found";
+    message: string;
+}
+/** The module system could not evaluate the file: the toolchain/deps are missing. */
+ | {
+    ok: false;
+    reason: "unloadable";
+    message: string;
+}
+/** The file loaded and its config is wrong — a refusal or a bad shape. Fix the config. */
+ | {
+    ok: false;
+    reason: "invalid";
+    message: string;
+};
+declare function loadConfig(dir: string): Promise<ConfigLoad>;
+
+/**
+ * The report vocabulary `up` speaks (`workstreams/10-blueprints.md §2` item 4) and the handful of
+ * client-side moves every resource kind shares: one line per attempt with refusals caught into
+ * the report, drift as "a declared field whose live value differs", 404 as "not yet", full
+ * cursor pagination, and the by-name tombstone behind `removed`.
+ */
+
+type ResourceAction = "created" | "updated" | "unchanged" | "deleted" | "refused";
+interface ResourceReport {
+    name: string;
+    action: ResourceAction;
+    id?: string;
+    url?: string | null;
+    /** Why, for `refused`; what would happen, for a dry-run line that needs explaining. */
+    reason?: string;
+}
+
+/**
+ * The reconciler behind `naive up` (`workstreams/10-blueprints.md §2`): a pure client of the
+ * public REST API through the SDK — upsert-by-name over routes that are already idempotent. No
+ * server-side diff engine, no manifest store; re-running is always safe because every resource is
+ * keyed by its config name.
+ *
+ * Nothing is deleted by omission (ADR-0352): `removed` names are the only tombstones, with one
+ * bounded exception — a declared agent's `schedules` are owned as a complete set (`agents.ts`).
+ * Skills and identities live here; apps, agents and vaults each have their own module, sharing the
+ * report vocabulary in `report.ts`.
+ */
+
+interface UpReport {
+    dry_run: boolean;
+    /** The machine, and the template within it whose crew this apply provisioned (`template.ts`). */
+    blueprint?: string;
+    template?: string;
+    skills: ResourceReport[];
+    identities: ResourceReport[];
+    /** One line per vault, then one per declared credential named `<vault> / <key>`. */
+    vaults: ResourceReport[];
+    apps: ResourceReport[];
+    agents: ResourceReport[];
+    /** One line per declared cron and per pruned live row, named `<agent> @ <cron>`. */
+    schedules: ResourceReport[];
+    /**
+     * Live rows this client could not parse, named and stepped over (`report.ts`). One legacy row
+     * used to abort the whole apply before any write; it is now a line here and nothing else.
+     */
+    skipped: string[];
+}
+interface UpOptions {
+    /** Plan only: reads happen, writes do not, and the report says what apply would do. */
+    dry_run?: boolean;
+    /** Base directory `deploy_dir` is resolved against — the config file's directory. */
+    dir?: string;
+    /**
+     * `naive up --adopt`: take every app this run touches whose row names another project, or none
+     * (ADR-0375). Off by default — adopting by default is what overwrote a live deployment.
+     */
+    adopt?: boolean;
+}
+/** Plan → apply → report. Every refusal is one line in the report, never a thrown escape. */
+declare function up(config: Readonly<ProjectConfig>, client: VettaClient, opts?: UpOptions): Promise<UpReport>;
+
+export { type AgentDecl, type AppDecl, BLUEPRINTS, BlueprintRefusal, CONFIG_CANDIDATES, type ConfigLoad, type CredentialDecl, type DefineInput, type IdentityDecl, type ProjectConfig, type ResourceAction, type ResourceReport, type ScheduleDecl, type SkillDecl, type Template, type TemplateChoice, type TemplateKind, type UpOptions, type UpReport, type VaultDecl, chooseTemplate, defineProject, loadConfig, parseProject, up };