@usenaive-sdk/blueprints 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -80,6 +80,8 @@ declare const AppDeclSchema: z.ZodObject<{
     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.ZodObject<{
+        generate: z.ZodLiteral<true>;
     }, z.core.$strip>]>>>;
 }, z.core.$strip>;
 /**
@@ -146,6 +148,10 @@ declare const AgentDeclSchema: z.ZodObject<{
         identity: z.ZodOptional<z.ZodString>;
         enabled: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
+    intake: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        budget_micro_usd: z.ZodOptional<z.ZodNumber>;
+    }, 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
@@ -197,6 +203,21 @@ declare const ProjectSchema: z.ZodObject<{
     name: z.ZodString;
     blueprint: z.ZodOptional<z.ZodString>;
     template: z.ZodOptional<z.ZodString>;
+    questions: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+        placeholder: z.ZodOptional<z.ZodString>;
+        key: z.ZodString;
+        label: z.ZodString;
+        help: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"choice">;
+        options: z.ZodArray<z.ZodString>;
+        multiple: z.ZodDefault<z.ZodBoolean>;
+        other: z.ZodDefault<z.ZodBoolean>;
+        key: z.ZodString;
+        label: z.ZodString;
+        help: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>>;
     skills: z.ZodDefault<z.ZodArray<z.ZodObject<{
         slug: z.ZodString;
         file: z.ZodString;
@@ -233,6 +254,8 @@ declare const ProjectSchema: z.ZodObject<{
         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.ZodObject<{
+            generate: z.ZodLiteral<true>;
         }, z.core.$strip>]>>>;
     }, z.core.$strip>>>;
     agents: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -283,6 +306,10 @@ declare const ProjectSchema: z.ZodObject<{
             identity: z.ZodOptional<z.ZodString>;
             enabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>>;
+        intake: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            budget_micro_usd: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>>;
     removed: z.ZodDefault<z.ZodObject<{
         apps: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -343,6 +370,75 @@ type ConfigLoad = {
 };
 declare function loadConfig(dir: string): Promise<ConfigLoad>;
 
+/**
+ * A built tree, from either place one can be. A **directory** is the apply a person runs: a
+ * checkout on their laptop or in CI. A **file map** is the apply the platform runs on their
+ * behalf — the tree comes out of a published artifact's object-store entry (`canonical-spec §31.1`)
+ * and there is no checkout anywhere, because a hosted run never clones a blueprint.
+ */
+type FileSource = string | Record<string, string>;
+/**
+ * ONE FILTER, ONE DIGEST, BOTH SOURCES — which is the whole of why the map arm exists rather than
+ * the caller handing its map straight to `contentHash`.
+ *
+ * A published artifact's `content_hash` is compared against the newest deployment's to decide
+ * whether to upload at all (§31.1), and the two sides of that comparison are collected in different
+ * places: the deployment's from a directory here, the artifact's from a map on the server. If the
+ * map arm skipped one exclusion or one size cap, the digests would differ for two trees that ship
+ * the same bytes and every hosted install would re-upload, forever, with nothing to point at.
+ */
+declare function collectFiles(source: FileSource): Record<string, string>;
+/**
+ * sha-256 over the files in path order, each as `path NUL byte-length NUL bytes`: the same tree
+ * hashes the same from any walk order, and the length prefix keeps two trees from sharing an
+ * encoding. Hex, so it travels as a plain string.
+ */
+declare function contentHash(files: Record<string, string>): string;
+
+/**
+ * The blueprint install (`canonical-spec §29.6`) — one applied declaration per
+ * (organization, project), and the drift a `revision_conflict` names.
+ *
+ * `naive up` needed no server-side state while the only writer was a person with a clone: its
+ * working tree was the manifest. The studio applying the same declaration makes two writers on one
+ * organization, and neither can see the other. This row is what they share.
+ *
+ * It is not a second source of truth for what is provisioned — apps, agents, skills, identities and
+ * vaults stay keyed by name on their own routes. It records *that* an apply happened, with what, by
+ * whom, and against which revision.
+ */
+
+/**
+ * What one apply did to one resource. This is the vocabulary `naive up` has printed since it
+ * existed; it is written HERE, and imported by `@usenaive-sdk/blueprints`, for the reason
+ * `CLAUDE.md §2` gives: the hosted apply publishes the engine's report on the install (below), so
+ * it is a wire shape, and a wire shape has exactly one definition. The engine re-exports these two
+ * names unchanged, so nothing downstream of it learns a second word for the same thing.
+ */
+declare const ResourceActionSchema: z.ZodEnum<{
+    created: "created";
+    updated: "updated";
+    unchanged: "unchanged";
+    deleted: "deleted";
+    refused: "refused";
+}>;
+type ResourceAction = z.infer<typeof ResourceActionSchema>;
+/** One line of an apply: what was named, what happened to it, and — for a refusal — why. */
+declare const ResourceReportSchema: z.ZodObject<{
+    name: z.ZodString;
+    action: z.ZodEnum<{
+        created: "created";
+        updated: "updated";
+        unchanged: "unchanged";
+        deleted: "deleted";
+        refused: "refused";
+    }>;
+    id: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type ResourceReportLine = z.infer<typeof ResourceReportSchema>;
+
 /**
  * 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
@@ -350,14 +446,62 @@ declare function loadConfig(dir: string): Promise<ConfigLoad>;
  * 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;
+type ResourceReport = ResourceReportLine;
+
+/**
+ * Apps in `naive up`: upsert by `GET /v1/apps?name=` (§29.2), `env` written as write-only secrets
+ * only when the live `value_hash` differs from the local one (ADR-0354, ADR-0357), and the
+ * `deploy_dir` shipped only when its content hash differs from the newest live deployment's
+ * (ADR-0357). Live secret names the config does not declare are reported, never deleted
+ * (ADR-0352). `mcp` is patched on drift, absent meaning `null` (§29.5); the platform mints the
+ * app's `VETTA_MCP_TOKEN` itself, so nothing here ever holds that token.
+ *
+ * A hosted apply also arrives with a PLATFORM ENVIRONMENT (`PlatformEnv`, §29.7) — the base URL, the
+ * identity the install runs as, and a scoped key it will mint for an app that asks. That layer is
+ * read before `{ from_env }`'s own environment, and a declaration may ask for a value nobody has
+ * with `{ generate: true }`. Both are provisioned ONCE per app, because a value the platform invents
+ * has no stable digest and rewriting it every apply would rotate a live credential.
+ *
+ * An app also records the project that made it (ADR-0375), and that stamp is compared before any
+ * write: a name this project does not own is refused rather than adopted, which is what standing
+ * up a second blueprint did to the first one's live deployment.
+ */
+
+/** The platform environment's variable names (`canonical-spec §29.7`) — fixed, never inferred. */
+declare const PLATFORM_ENV: {
+    /** The base URL of the API this apply ran through. */
+    readonly api_url: "NAIVE_API_URL";
+    /** The identity the install runs as, when the declaration declares exactly one. */
+    readonly identity_id: "NAIVE_IDENTITY_ID";
+    /** A scoped organization API key minted for the app that asks for it. */
+    readonly api_key: "NAIVE_API_KEY";
+};
+/**
+ * WHAT THE PLATFORM PROVIDES A HOSTED APPLY, AND THE ONE DISTINCTION THAT MATTERS
+ * (`canonical-spec §29.7`).
+ *
+ * Absent on a laptop apply, which reads the author's shell and nothing else — the hosted path gains
+ * a layer, the local path does not lose one.
+ *
+ * **What the platform KNOWS it always tells the app; what the platform must INVENT it invents only
+ * on request, and only once.** That is not a stylistic split. A known value has a stable digest, so
+ * the `value_hash` compare that makes `naive up` idempotent (§29.2) can say `unchanged` about it and
+ * re-asserting it every apply costs nothing. An invented one never matches its own previous digest,
+ * so re-inventing it every apply would rotate a live credential under a build that still holds the
+ * old one — and, for a minted key, leave one dead `api_key` row behind per apply.
+ */
+interface PlatformEnv {
+    /**
+     * Values the platform knows. Written to every app this apply deploys that declares an `env` —
+     * whether or not the declaration names them, which is the `VETTA_MCP_TOKEN` precedent (§29.2) —
+     * and read FIRST by a `{ from_env }` that does name them.
+     */
+    known: Record<string, string>;
+    /**
+     * Values the platform must invent, by variable name, given the app that asked. Called at most
+     * once per app, and only when that app holds no secret of that name.
+     */
+    minted?: Record<string, (app: string) => Promise<string>>;
 }
 
 /**
@@ -370,6 +514,11 @@ interface ResourceReport {
  * 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`.
+ *
+ * One thing here is not a reconcile: an agent this apply **created** that declares an `intake` is
+ * sent its briefing as a started session (`agents.ts`, `canonical-spec §31.4`). It is what turns a
+ * provisioned crew into a crew that has started working, and it is idempotent for the same reason
+ * everything else here is — the agent is created exactly once.
  */
 
 interface UpReport {
@@ -385,6 +534,12 @@ interface UpReport {
     agents: ResourceReport[];
     /** One line per declared cron and per pruned live row, named `<agent> @ <cron>`. */
     schedules: ResourceReport[];
+    /**
+     * One line per agent this apply **created** that declares an `intake` — the session that was
+     * started, named by the agent, `id` the `ses_`. Empty on every later apply of the same crew: an
+     * agent is created once, so it is briefed once (`agents.ts`).
+     */
+    intake: 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.
@@ -401,8 +556,43 @@ interface UpOptions {
      * (ADR-0375). Off by default — adopting by default is what overwrote a live deployment.
      */
     adopt?: boolean;
+    /**
+     * The built trees, by app name, for an apply that runs where there is no checkout: the platform
+     * applying a published artifact on an operator's behalf (`canonical-spec §31.1`). The bytes come
+     * out of the artifact's object-store entry, in the same file map `deploy_dir` would have been
+     * collected into — which is why `collectFiles` takes both and there is one digest (`files.ts`).
+     *
+     * Present ⇒ the disk is never read for an app, and an app whose tree is not in the map is refused
+     * by name rather than deployed empty. Absent ⇒ `dir` + `deploy_dir`, exactly as before.
+     */
+    trees?: Record<string, Record<string, string>>;
+    /**
+     * Why a declared app is absent from `trees`, by app name — an object-store read that failed
+     * rather than an object that was never uploaded. Both come out of `builtTree` as one refusal;
+     * only the caller that did the reading can tell them apart, so only it can say (`apps.ts`).
+     */
+    tree_errors?: Record<string, string>;
+    /**
+     * What an app's `{ from_env }` reads (`apps.ts`). The process's own environment by default —
+     * the author's shell, which is the whole point of `from_env` on a laptop. A hosted apply has no
+     * shell and passes the operator's **answers** instead (`canonical-spec §31.2`): the same
+     * declaration, resolved against the only environment that apply has.
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * THE PLATFORM ENVIRONMENT (`canonical-spec §29.7`) — what the platform itself provides an app,
+     * read BEFORE `env` and written whether or not the declaration names it.
+     *
+     * Present only on a hosted apply, and that is the whole of the local/hosted difference: `naive up`
+     * from a checkout passes none, reads the author's shell, and behaves exactly as it always has.
+     *
+     * `NAIVE_IDENTITY_ID` is filled in here rather than by the caller, because the id does not exist
+     * until this run has created the identity — identities are upserted before apps for the same
+     * reason agents reference them by name.
+     */
+    platform?: PlatformEnv;
 }
 /** 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 };
+export { type AgentDecl, type AppDecl, BLUEPRINTS, BlueprintRefusal, CONFIG_CANDIDATES, type ConfigLoad, type CredentialDecl, type DefineInput, type FileSource, type IdentityDecl, PLATFORM_ENV, type PlatformEnv, type ProjectConfig, type ResourceAction, type ResourceReport, type ScheduleDecl, type SkillDecl, type Template, type TemplateChoice, type TemplateKind, type UpOptions, type UpReport, type VaultDecl, chooseTemplate, collectFiles, contentHash, defineProject, loadConfig, parseProject, up };