@pithy-sh/core 0.1.2 → 0.1.3

package/dist/capability/manifest.d.ts

@@ -0,0 +1,298 @@
+import { z } from "zod";
+/**
+ * What a manifest states as an option's rendered value: a JSON value other than `null`, nested freely,
+ * and printable as source without Biome wanting it back a different way.
+ *
+ * A scalar is what an option normally is, and every `--set` override still coerces to one — the CLI
+ * takes strings from a flag or a prompt, and neither can carry an object.
+ *
+ * Objects and arrays are here for the options a scalar cannot express: one the capability's config type
+ * **requires** and whose contents only the adopter can write. `SecretsConfig` requires a `registry`; a
+ * manifest could not state one, so `pithy add secrets` rendered every option but that and left a
+ * `pithy.config.ts` failing `tsc` with TS2741 on a project nobody had touched yet (#161).
+ *
+ * #161 admitted only the **empty** literal, which is right for a registry — an empty registry is a legal
+ * registry. It is wrong everywhere the collection is required to be non-empty. `ledger.currencies`,
+ * `leaderboard.boards` and `multiplayer.games` each carry `.min(1)` with a message saying why, so an
+ * empty seed typechecks and then throws `too_small` on the first config load — and `pithy upgrade`
+ * reports that as "Could not load pithy.config.ts", naming the wrong cause (#168). So a default may now
+ * be a **complete, minimal, working example**: one currency, one board, one game. The option's
+ * `describe`, rendered as the comment directly above it, is what tells the adopter to replace it.
+ *
+ * `null` stays out. `typeof null === "object"`, and the CLI reads exactly that to decide an option is
+ * hand-written and therefore not settable from `--set` or a prompt; a null default would be mistaken for
+ * a collection nobody can fill.
+ *
+ * The recursion is this widening's cost, paid in the open. Every shape admitted here has to come back
+ * out as the TypeScript Biome prints — see {@link renderConfigValue}.
+ *
+ * **The schema is narrower than the type, deliberately.** TypeScript cannot say "a string with no double
+ * quote in it", so the two characters {@link renderConfigValue} cannot print as Biome would are refused
+ * here instead, at the one door a manifest comes through. The alternative was to teach the renderer
+ * Biome's quote-preference heuristic and its numeric-literal normalizer, and then keep both in step with
+ * a formatter that is free to change either — for inputs no worked example should carry. A manifest
+ * default is an *example*; one that needs a quote inside a string is already too clever (#171).
+ */
+export type ConfigOptionValue = string | number | boolean | ConfigOptionValue[] | {
+    [key: string]: ConfigOptionValue;
+};
+export declare const ConfigOptionValue: z.ZodType<ConfigOptionValue>;
+/**
+ * Render a manifest default as TypeScript source, on one line.
+ *
+ * `pithy add` writes this straight into the adopter's `pithy.config.ts`, which the scaffold's own
+ * `biome check` then reads — so *valid* TypeScript is not the bar. It has to be the TypeScript Biome
+ * would have printed. `JSON.stringify` is not: it quotes every key, and Biome's `quoteProperties`
+ * default rewrites `{"code":"chips"}` to `{ code: "chips" }`, failing the lint gate on a project the
+ * adopter has not touched. This prints Biome's shape directly — bare keys wherever they are legal,
+ * spaces inside braces, `, ` between entries, `{}` and `[]` for the empty literals #161 relies on.
+ *
+ * **Total over what {@link ConfigOptionValue} *parses*, which is narrower than what it types.** The two
+ * shapes the schema refuses — a string carrying `"` or `${`, a number no plain decimal spells — are
+ * refused here too, with a `ValidationError`. A manifest cannot reach that path, since every manifest is
+ * parsed before it is rendered; `pithy add --set` can, because a flag's string goes straight through. A
+ * refusal at the command beats a config file that fails the adopter's first `bun run lint`.
+ *
+ * One line, always. Biome breaks any literal past {@link CONFIG_LINE_WIDTH}, and a broken literal is a
+ * `biome check` failure on a project the adopter has not touched — #161 and #168 both. That rule used to
+ * be this sentence and nothing else, with multiplayer's seed sitting at 98 columns of 120; it is now a
+ * test over every shipped manifest default, rendered by {@link renderConfigOptionLine} at the indent the
+ * writers really use (#171).
+ */
+export declare function renderConfigValue(value: ConfigOptionValue): string;
+/**
+ * The column Biome wraps at — `formatter.lineWidth` in the `biome.jsonc` that `pithy init` scaffolds.
+ *
+ * A line of exactly this width survives untouched; one character more and Biome explodes the literal
+ * across a dozen lines, so `biome check` fails on a file the adopter never opened. Measured by running
+ * Biome over generated lines of 118 through 122 columns, not read off a docs page.
+ */
+export declare const CONFIG_LINE_WIDTH = 120;
+/**
+ * The indent both writers render an option line at in a scaffolded project: the managed-region marker
+ * sits four columns in, and an option sits two further.
+ *
+ * Each writer takes its real indent from the file it is editing, so an adopter who nested `capabilities`
+ * deeper gets a longer line than this. This is the scaffold's indent, and the scaffold is what the width
+ * rule is measured against — a default that does not fit here fits nowhere.
+ */
+export declare const CONFIG_OPTION_INDENT = "      ";
+/**
+ * The one line both writers put in `pithy.config.ts` for one option.
+ *
+ * `pithy add` renders a whole registration and `pithy upgrade` splices keys into an existing one, but the
+ * line itself is this — so neither command can drift from the other by rendering a default its own way.
+ * That drift was real and shipped: `upgrade` called `JSON.stringify` where `add` called
+ * {@link renderConfigValue}, so one manifest produced `{"code":"chips"}` from one command and
+ * `{ code: "chips" }` from the other, and only the second survived `biome check` (#171).
+ *
+ * The comment above the line is not measured against {@link CONFIG_LINE_WIDTH}: Biome never reflows a
+ * comment, so an option's `describe` may run as long as it needs to.
+ */
+/**
+ * What a writer has decided to put on the right of an option line: a value, or one of the scaffold's
+ * constants referenced by name.
+ *
+ * A marker object rather than a string, because a string would be indistinguishable from a value that
+ * happens to spell an identifier — and the difference is quotes, which is the difference between an
+ * origin that follows the environment and one written down. Constructed by the CLI from
+ * `ConfigOption.constant` after it has checked the target config declares it; never parsed from a
+ * manifest, which states only the key.
+ */
+export interface ConfigConstantRef {
+    /** The constant to render, by key into {@link CONFIG_CONSTANTS}. */
+    readonly constant: ConfigConstant;
+}
+export declare function renderConfigOptionLine(key: string, value: ConfigOptionValue | ConfigConstantRef, indent: string): string;
+/**
+ * The comment line both writers put above an option: its `describe`, verbatim, as a `//` comment.
+ *
+ * The rationale is the whole reason the generated config documents itself, and it comes out of a manifest
+ * read from `node_modules` — third-party text reaching generated source. Both writers used to build this
+ * line themselves, which is the arrangement that let `pithy add` and `pithy upgrade` disagree about the
+ * line *below* it (#171); they now share this, so a rule stated here holds for both.
+ *
+ * Total over what {@link ConfigOption} parses, exactly as {@link renderConfigOptionLine} is: a manifest
+ * cannot reach the throw, because every manifest is parsed before it is rendered.
+ */
+export declare function renderConfigOptionComment(describe: string, indent: string): string;
+/**
+ * The one import line a capability's wiring is written as.
+ *
+ * Both halves are interpolated raw, and both used to be `z.string().min(1)`: `pithy add` wrote
+ * `import { audit }) ; evil( } from "@pithy-sh/audit/src/index";` from a manifest that parsed, and
+ * reported `Done.` (#183). The line has one producer now, for the same reason
+ * {@link renderConfigOptionLine} does — a rule stated at one call site is a rule the next call site does
+ * not have.
+ *
+ * Total over what {@link CapabilityManifest} parses. A parsed manifest cannot reach either throw; the
+ * fork path `pithy add --eject` composes can, which is why the specifier is checked rather than assumed.
+ */
+export declare function renderCapabilityImport(name: string, specifier: string): string;
+/** What {@link renderCapabilityRegistration} writes one registration from. */
+export interface CapabilityRegistration {
+    /** The capability's name — written bare as the call, so a bare identifier and nothing else. */
+    name: string;
+    /** The indent the call sits at, taken by each writer from the file it is editing. */
+    indent: string;
+    /**
+     * The option lines already rendered by {@link renderConfigOptionComment} and
+     * {@link renderConfigOptionLine}, in order. Empty renders the one-liner form.
+     */
+    optionLines?: readonly string[];
+    /**
+     * Whether the registration ends with the array's separating comma. `pithy add` writes a whole entry and
+     * needs it; `pithy upgrade` splices a block over an existing `name()` whose comma is already in the file.
+     */
+    trailingComma?: boolean;
+}
+/**
+ * The registration both writers put in `pithy.config.ts` for one capability — `auth(),` with no options,
+ * the block form with them.
+ *
+ * The name is the only thing here that comes from a manifest, and it is the thing that reached generated
+ * source unchecked (#183). One producer, so the rule holds for `pithy add`'s whole-entry write and for
+ * `pithy upgrade`'s conversion of a one-liner into a block alike.
+ */
+export declare function renderCapabilityRegistration({ name, indent, optionLines, trailingComma, }: CapabilityRegistration): string;
+/**
+ * One configurable option a capability exposes. `pithy add` renders each as
+ * `cap({ key: default })` in `pithy.config.ts`, with `describe` as the comment
+ * above it — the self-documenting config surface (docs/CLI.md §Config). The
+ * mount-point model rides on options like this (e.g. `basePath`), so handlers
+ * stay in the package and the user owns the wiring.
+ *
+ * **Every option the capability's config type requires belongs here.** The manifest is the only thing
+ * `pithy add` reads, so an option it omits is an option the generated config omits — see
+ * {@link ConfigOptionValue} for the one that got away.
+ *
+ * **All three fields are narrowed to what the renderer can print, not just the value.** #171 held
+ * `default` to shapes Biome prints unchanged and left `key` and `describe` as `z.string().min(1)`, so a
+ * manifest could still state `content-type` — rendered `content-type: "x",`, which is not TypeScript at
+ * all — or a `describe` with a newline in it, whose second line landed in `pithy.config.ts` as bare code.
+ * A manifest is third-party data read from `node_modules`, and an option key is that data interpolated
+ * into generated source; `}) ; evil(` is the shape that makes the point. Narrowing here is what lets
+ * {@link renderConfigOptionLine} and {@link renderConfigOptionComment} guarantee the whole line rather
+ * than its right-hand side (#174).
+ */
+/**
+ * The constants a scaffolded `pithy.config.ts` defines, that a manifest option may name instead of
+ * stating a literal — identifier by key, so the manifest carries a **name from a closed set** and never
+ * an expression.
+ *
+ * That is the whole security argument, and it is the same one #183 settled for a capability's name: a
+ * manifest is third-party data read out of `node_modules` and written into the adopter's TypeScript, so
+ * anything it states unquoted must come from a list this package controls. An `expression` field would
+ * put arbitrary code in the adopter's config on the strength of a package they installed.
+ *
+ * One entry today. `PUBLIC_ORIGIN` is the Worker's address for the environment it composes in, derived
+ * by `originFor(compositionEnvironment(), DOMAINS)` in the scaffolded config — the line that exists so no
+ * capability ever asks an adopter to write an origin down again.
+ */
+export declare const CONFIG_CONSTANTS: {
+    readonly publicOrigin: "PUBLIC_ORIGIN";
+};
+/** Which scaffolded constant an option's value is, by key. */
+export declare const ConfigConstant: z.ZodEnum<{
+    publicOrigin: "publicOrigin";
+}>;
+export type ConfigConstant = z.infer<typeof ConfigConstant>;
+export declare const ConfigOption: z.ZodObject<{
+    key: z.ZodString;
+    default: z.ZodOptional<z.ZodType<ConfigOptionValue, unknown, z.core.$ZodTypeInternals<ConfigOptionValue, unknown>>>;
+    choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    choicesNeedingCode: z.ZodOptional<z.ZodPipe<z.ZodCustom<Record<string, string>, Record<string, string>>, z.ZodType<Record<string, string>, Record<string, string>, z.core.$ZodTypeInternals<Record<string, string>, Record<string, string>>>>>;
+    constant: z.ZodOptional<z.ZodEnum<{
+        publicOrigin: "publicOrigin";
+    }>>;
+    describe: z.ZodString;
+}, z.core.$strip>;
+export type ConfigOption = z.infer<typeof ConfigOption>;
+/**
+ * Declarative, CLI-facing description of a capability. Lives at `pithy.manifest.json` in
+ * each capability package; read by `pithy add`/`upgrade` to wire bindings into
+ * `wrangler.jsonc` and scaffold config — without executing the package. Plain data, so
+ * it's a validated Zod object. `requiredBindings` reuse the `BindingSpec` contract, so a
+ * manifest's bindings are normalized (and rejected) exactly like a capability's own.
+ *
+ * **The invariant, stated here rather than at the writers: every string a manifest states that reaches
+ * generated source is constrained to what the renderer can print.** Three rounds got there one field at a
+ * time — #171 narrowed an option's `default`, #174 its `key` and `describe`, #183 the capability's own
+ * `name` and `package` — because each time the rule lived at the call site that had just been fixed. It
+ * lives here now, and `manifest.test.ts` walks this schema and fails the build on a string field that is
+ * neither constrained nor declared prose the CLI only ever prints.
+ */
+export declare const CapabilityManifest: z.ZodObject<{
+    name: z.ZodString;
+    package: z.ZodString;
+    requiredBindings: z.ZodArray<z.ZodObject<{
+        type: z.ZodUnion<readonly [z.ZodLiteral<"d1">, z.ZodLiteral<"kv">, z.ZodLiteral<"r2">, z.ZodLiteral<"ai">, z.ZodLiteral<"vectorize">, z.ZodLiteral<"queue">, z.ZodLiteral<"ratelimit">, z.ZodLiteral<"email">, z.ZodLiteral<"secret">, z.ZodLiteral<"workflow">, z.ZodLiteral<"service">, z.ZodLiteral<"durable_object">]>;
+        name: z.ZodString;
+        optional: z.ZodDefault<z.ZodBoolean>;
+        className: z.ZodOptional<z.ZodString>;
+        classModule: z.ZodOptional<z.ZodString>;
+        job: z.ZodOptional<z.ZodString>;
+        service: z.ZodOptional<z.ZodString>;
+        remote: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    peerCapabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    optionalCapabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    migrationNamespace: z.ZodOptional<z.ZodString>;
+    devSecrets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        devValue: z.ZodEnum<{
+            random: "random";
+        }>;
+    }, z.core.$strip>>>;
+    secrets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        origin: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"minted">;
+            recipe: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"random">;
+                bytes: z.ZodInt;
+                encoding: z.ZodEnum<{
+                    base64: "base64";
+                    base64url: "base64url";
+                    hex: "hex";
+                }>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"encryptionConfig">;
+            }, z.core.$strip>], "kind">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"helped">;
+            issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+            needs: z.ZodPipe<z.ZodCustom<Partial<Record<string, string[]>>, Partial<Record<string, string[]>>>, z.ZodType<Partial<Record<string, string[]>>, Partial<Record<string, string[]>>, z.core.$ZodTypeInternals<Partial<Record<string, string[]>>, Partial<Record<string, string[]>>>>>;
+            documentation: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"obtained">;
+            issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+            documentation: z.ZodURL;
+        }, z.core.$strip>], "kind">;
+        rotation: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"local">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"provider">;
+            issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+            documentation: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"manual">;
+            issuer: z.ZodType<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown, z.core.$ZodTypeInternals<"apple" | "atlassian" | "cloudflare" | "facebook" | "github" | "gitlab" | "google" | "lemonSqueezy" | "microsoft" | "other" | "paddle" | "project" | "stripe", unknown>>;
+            documentation: z.ZodURL;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>>>;
+    scaffold: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    configOptions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        default: z.ZodOptional<z.ZodType<ConfigOptionValue, unknown, z.core.$ZodTypeInternals<ConfigOptionValue, unknown>>>;
+        choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        choicesNeedingCode: z.ZodOptional<z.ZodPipe<z.ZodCustom<Record<string, string>, Record<string, string>>, z.ZodType<Record<string, string>, Record<string, string>, z.core.$ZodTypeInternals<Record<string, string>, Record<string, string>>>>>;
+        constant: z.ZodOptional<z.ZodEnum<{
+            publicOrigin: "publicOrigin";
+        }>>;
+        describe: z.ZodString;
+    }, z.core.$strip>>>;
+    whenToEnable: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CapabilityManifest = z.infer<typeof CapabilityManifest>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/capability/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/capability/manifest.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgDxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,iBAAiB,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAEvH,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAUgD,CAAC;AA6D5G;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CASlE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,WAAW,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAOD,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,iBAAiB,GAAG,iBAAiB,EAC5C,MAAM,EAAE,MAAM,GACb,MAAM,CAaR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CASlF;AAwDD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAU9E;AAED,8EAA8E;AAC9E,MAAM,WAAW,sBAAsB;IACrC,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,IAAI,EACJ,MAAM,EACN,WAAgB,EAChB,aAAoB,GACrB,EAAE,sBAAsB,GAAG,MAAM,CAKjC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB;aAAK,YAAY,EAAE,eAAe;CAAW,CAAC;AAE3E,8DAA8D;AAC9D,eAAO,MAAM,cAAc;;EAEuF,CAAC;AACnH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,YAAY;;;;;;;;;iBA4EoE,CAAC;AAC9F,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiE0D,CAAC;AAC1F,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}