@pithy-sh/core 0.1.2 → 0.1.3

package/dist/workflow/host.d.ts

@@ -0,0 +1,176 @@
+import { type WorkflowHostNameParts } from "./naming";
+import type { WorkflowRegistry } from "./spec";
+/**
+ * The prebuilt-worker host contract.
+ *
+ * A capability that owns Workflows ships a committed `wrangler.jsonc` **template** beside its
+ * worker entry — not an env-stanza file, because staging and production are genuinely separate
+ * Workers. `pithy <capability> provision` resolves that template into one complete config per
+ * environment and deploys each with `wrangler deploy --config <resolved>`. The adopter authors
+ * none of it.
+ *
+ * Email, secrets, and media each grew their own copy of that resolver. This module is the one they
+ * converge on: a template shape wide enough for all three, and a pure resolver that fills it.
+ *
+ * Pure by construction — no filesystem, no Cloudflare, no `cloudflare:workers`. The caller parses
+ * the template and writes the result. That keeps core node-safe (its `.describe()` meta-test
+ * imports every module eagerly under node) and keeps the ordering and idempotency logic unit-
+ * testable without an account.
+ *
+ * **Workflows cannot use remote bindings**, so a host always runs locally in `wrangler dev`. Any
+ * binding it needs that has no local emulation — Vectorize and Workers AI both lack one — must
+ * carry `remote: true`, which is why {@link WorkflowHostParams.remoteBindings} exists rather than
+ * the flag being inferred per binding kind.
+ */
+/** A D1 binding in a host template. `database_name` is rewritten only when the caller supplies one. */
+export interface HostD1Binding {
+    binding: string;
+    database_name: string;
+    database_id: string;
+}
+/** A KV namespace binding in a host template. */
+export interface HostKvBinding {
+    binding: string;
+    id: string;
+}
+/** An R2 bucket binding in a host template. */
+export interface HostR2Binding {
+    binding: string;
+    bucket_name: string;
+    remote?: boolean;
+}
+/** A Vectorize index binding in a host template. Always `remote: true` — Vectorize has no local emulation. */
+export interface HostVectorizeBinding {
+    binding: string;
+    index_name: string;
+    remote?: boolean;
+}
+/** The Workers AI binding in a host template. Always `remote: true` — Workers AI has no local emulation. */
+export interface HostAiBinding {
+    binding: string;
+    remote?: boolean;
+}
+/** A Cloudflare Email Service send binding in a host template. */
+export interface HostSendEmailBinding {
+    name: string;
+    remote?: boolean;
+}
+/** A Secrets Store entry in a host template — the master key a host reads its secrets through. */
+export interface HostSecretsStoreBinding {
+    binding: string;
+    store_id: string;
+    secret_name: string;
+}
+/** One Workflow the host worker hosts: the binding, the deployed name, and the class that runs it. */
+export interface HostWorkflowBinding {
+    binding: string;
+    name: string;
+    class_name: string;
+}
+/**
+ * A capability's committed `wrangler.jsonc` template, typed. Every field is optional but `name` and
+ * `main` — a host that binds no D1 is legal, and email binds no R2. Unknown keys survive
+ * `structuredClone` untouched, so a template may carry fields this contract does not model.
+ */
+export interface WorkflowHostTemplate {
+    name: string;
+    main: string;
+    compatibility_date?: string;
+    compatibility_flags?: string[];
+    workers_dev?: boolean;
+    d1_databases?: HostD1Binding[];
+    kv_namespaces?: HostKvBinding[];
+    r2_buckets?: HostR2Binding[];
+    vectorize?: HostVectorizeBinding[];
+    ai?: HostAiBinding;
+    send_email?: HostSendEmailBinding[];
+    secrets_store_secrets?: HostSecretsStoreBinding[];
+    workflows?: HostWorkflowBinding[];
+    triggers?: {
+        crons: string[];
+    };
+    vars?: Record<string, string>;
+}
+/** What one environment's resolution needs. Everything absent is left exactly as the template had it. */
+export interface WorkflowHostParams {
+    /**
+     * The project name — the `<project>` segment every derived name leads with. The root
+     * `pithy.config.ts` `name`, resolved by `requireProjectName` and **never guessed**: Worker script
+     * and Workflow names are account-scoped, so a wrong value here overwrites another project's
+     * running Worker rather than colliding with it.
+     */
+    project: string;
+    /** The capability that owns the host — the `<capability>` segment of every derived name. */
+    capability: string;
+    /** The target environment (`dev` | `staging` | `production`). */
+    env: string;
+    /** D1 binding name → database id. An unlisted binding keeps the template's id. */
+    databaseIds?: Record<string, string>;
+    /**
+     * D1 binding name → database name. Rewritten **only** for the bindings listed here. Email
+     * deliberately lets `pithy-app`/`pithy-secrets` pass through while secrets rewrites its own, so
+     * the choice cannot be a blanket rule.
+     */
+    databaseNames?: Record<string, string>;
+    /** KV binding name → namespace id. */
+    kvNamespaceIds?: Record<string, string>;
+    /** R2 binding name → bucket name. */
+    r2BucketNames?: Record<string, string>;
+    /** Vectorize binding name → index name. */
+    vectorizeIndexNames?: Record<string, string>;
+    /** The Secrets Store id, set on every `secrets_store_secrets` entry. */
+    secretsStoreId?: string;
+    /**
+     * The environment-scoped name of the master-key secret. Passed in rather than derived: core must
+     * not depend on `@pithy-sh/secrets`, which owns that naming.
+     */
+    masterKeySecretName?: string;
+    /** Vars merged over the template's, e.g. the capability's config serialized as one JSON blob. */
+    vars?: Record<string, string>;
+    /**
+     * Binding names that must carry `remote: true`. A Workflow host runs locally in dev, so any
+     * binding without local emulation has to reach the real service.
+     */
+    remoteBindings?: readonly string[];
+    /**
+     * KV binding names to drop. A template declares every binding a capability *might* need; a mode
+     * that does not use one must not ship a binding pointing at a namespace that was never created.
+     */
+    omitKvBindings?: readonly string[];
+    /**
+     * The host's `workflows` array, already derived from the capability's registry by
+     * {@link hostWorkflowsFor}. **Required whenever the template declares any `workflows`.**
+     *
+     * The resolver used to build these by appending `-<env>` to the template's own name, which cannot
+     * produce a project-scoped name: the template says `pithy-email-send`, and the resolver has no way
+     * to recover the job from it. Deriving them from the registry is the only path that knows both the
+     * project and the job, so the textual suffix is gone and its absence is an error rather than a
+     * silent fallback to an unscoped, account-colliding Workflow name.
+     */
+    workflows?: readonly HostWorkflowBinding[];
+}
+/**
+ * Resolve a host template into one environment's complete, standalone config.
+ *
+ * Structural, never textual: the template is `structuredClone`d and fields are overwritten by
+ * binding-name lookup. The `<filled-at-provision>` markers in the committed templates are
+ * documentation for whoever reads the file — nothing matches or replaces them, so a template that
+ * spells a placeholder differently still resolves correctly.
+ *
+ * The worker name becomes `<project>-<env>-<capability>` through {@link workflowHostName}, and the
+ * `workflows` array is replaced wholesale by `params.workflows` (derived from the registry by
+ * {@link hostWorkflowsFor}), so the deployed names cannot drift from what the dispatcher and the
+ * CLI compute. `binding` and
+ * `class_name` are never rewritten — they are code references, not deployment identities.
+ */
+export declare function resolveWorkflowHost(template: WorkflowHostTemplate, params: WorkflowHostParams): WorkflowHostTemplate;
+/**
+ * Derive a host's `workflows` array and `triggers.crons` from the registry, so a capability's specs
+ * — not a hand-maintained block in its template — are the source of both. A spec without a
+ * `className` cannot be hosted: there would be no class for wrangler to instantiate.
+ */
+export declare function hostWorkflowsFor(registry: WorkflowRegistry, parts: WorkflowHostNameParts): {
+    workflows: HostWorkflowBinding[];
+    crons: string[];
+};
+//# sourceMappingURL=host.d.ts.map

package/dist/workflow/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/workflow/host.ts"],"names":[],"mappings":"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"}

package/dist/workflow/host.js

@@ -0,0 +1,116 @@
+import { InternalError } from "../error/pithyError.js";
+import { ENVIRONMENT_VAR, PROJECT_VAR } from "../worker/identity.js";
+import { workflowHostName, workflowScriptName } from "./naming.js";
+//#region src/workflow/host.ts
+/** Apply `remote: true` to an entry whose binding the caller listed. */
+function withRemote(entry, name, remote) {
+	return remote.has(name) ? {
+		...entry,
+		remote: true
+	} : entry;
+}
+/**
+* Resolve a host template into one environment's complete, standalone config.
+*
+* Structural, never textual: the template is `structuredClone`d and fields are overwritten by
+* binding-name lookup. The `<filled-at-provision>` markers in the committed templates are
+* documentation for whoever reads the file — nothing matches or replaces them, so a template that
+* spells a placeholder differently still resolves correctly.
+*
+* The worker name becomes `<project>-<env>-<capability>` through {@link workflowHostName}, and the
+* `workflows` array is replaced wholesale by `params.workflows` (derived from the registry by
+* {@link hostWorkflowsFor}), so the deployed names cannot drift from what the dispatcher and the
+* CLI compute. `binding` and
+* `class_name` are never rewritten — they are code references, not deployment identities.
+*/
+function resolveWorkflowHost(template, params) {
+	const resolved = structuredClone(template);
+	const remote = new Set(params.remoteBindings ?? []);
+	resolved.name = workflowHostName({
+		project: params.project,
+		capability: params.capability,
+		env: params.env
+	});
+	if (resolved.d1_databases) resolved.d1_databases = resolved.d1_databases.map((entry) => ({
+		...entry,
+		database_name: params.databaseNames?.[entry.binding] ?? entry.database_name,
+		database_id: params.databaseIds?.[entry.binding] ?? entry.database_id
+	}));
+	if (resolved.kv_namespaces) {
+		const omit = new Set(params.omitKvBindings ?? []);
+		const kept = resolved.kv_namespaces.filter((entry) => !omit.has(entry.binding));
+		if (kept.length > 0) resolved.kv_namespaces = kept.map((entry) => ({
+			...entry,
+			id: params.kvNamespaceIds?.[entry.binding] ?? entry.id
+		}));
+		else resolved.kv_namespaces = void 0;
+	}
+	if (resolved.r2_buckets) resolved.r2_buckets = resolved.r2_buckets.map((entry) => withRemote({
+		...entry,
+		bucket_name: params.r2BucketNames?.[entry.binding] ?? entry.bucket_name
+	}, entry.binding, remote));
+	if (resolved.vectorize) resolved.vectorize = resolved.vectorize.map((entry) => withRemote({
+		...entry,
+		index_name: params.vectorizeIndexNames?.[entry.binding] ?? entry.index_name
+	}, entry.binding, remote));
+	if (resolved.ai) resolved.ai = withRemote(resolved.ai, resolved.ai.binding, remote);
+	if (resolved.send_email) resolved.send_email = resolved.send_email.map((entry) => withRemote(entry, entry.name, remote));
+	if (resolved.secrets_store_secrets && params.secretsStoreId !== void 0) {
+		const storeId = params.secretsStoreId;
+		const masterKey = params.masterKeySecretName;
+		resolved.secrets_store_secrets = resolved.secrets_store_secrets.map((entry) => ({
+			...entry,
+			store_id: storeId,
+			secret_name: masterKey !== void 0 && entry.binding === "SECRETS_ENCRYPTION_KEYS" ? masterKey : entry.secret_name
+		}));
+	}
+	if (resolved.workflows) {
+		if (!params.workflows) throw new InternalError({
+			message: `The ${params.capability} host template declares workflows but none were derived.`,
+			action: "Pass `workflows` from hostWorkflowsFor(registry, { project, capability, env }).",
+			detail: "A Workflow name is account-scoped and must carry the project; the template name alone cannot produce one."
+		});
+		resolved.workflows = params.workflows.map((entry) => ({ ...entry }));
+	}
+	resolved.vars = {
+		...resolved.vars,
+		...params.vars,
+		[ENVIRONMENT_VAR]: params.env,
+		[PROJECT_VAR]: params.project
+	};
+	return resolved;
+}
+/**
+* Derive a host's `workflows` array and `triggers.crons` from the registry, so a capability's specs
+* — not a hand-maintained block in its template — are the source of both. A spec without a
+* `className` cannot be hosted: there would be no class for wrangler to instantiate.
+*/
+function hostWorkflowsFor(registry, parts) {
+	const { project, capability, env } = parts;
+	const owned = Object.values(registry).filter((entry) => entry.capability === capability);
+	const workflows = [];
+	const crons = [];
+	for (const entry of owned) {
+		if (!entry.spec.className) throw new InternalError({
+			message: `Workflow "${entry.key}" cannot be hosted without a className.`,
+			action: "Add className to the spec, naming the exported WorkflowEntrypoint class."
+		});
+		workflows.push({
+			binding: entry.spec.binding,
+			name: workflowScriptName({
+				project,
+				capability,
+				job: entry.job,
+				env
+			}),
+			class_name: entry.spec.className
+		});
+		if (entry.spec.schedule) crons.push(entry.spec.schedule);
+	}
+	return {
+		workflows,
+		crons
+	};
+}
+//#endregion
+export { hostWorkflowsFor, resolveWorkflowHost };

package/dist/workflow/hostEntry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The default export of a Workflow host that serves nothing over HTTP (#426).
+ *
+ * ## Why a host needs a default export at all
+ *
+ * wrangler infers a worker's **module format** from one thing: whether the entry has a default export. A
+ * module that exports only classes is read as a service worker, and a service worker may not import
+ * `cloudflare:workers` — so the build does not warn and continue, it fails:
+ *
+ *     ▲ [WARNING] The entrypoint … has exports like an ES Module, but hasn't defined a default export
+ *               like a module worker normally would. Building the worker using "service-worker" format...
+ *     ✘ [ERROR] Unexpected external import of "cloudflare:workers" and "cloudflare:workflows".
+ *
+ * `pithy dev` builds each worker separately and carries on past one that fails, so the whole of what an
+ * adopter sees is a host that is not there. `support`, `media` and `vector` each shipped that way, and every
+ * host that did not was a host with a cron — `export default { async scheduled(…) }`, written for the cron,
+ * making the module an ES module by accident. The four authors who satisfied the rule had a reason unrelated
+ * to it, and the three who did not had no reason at all. `cli/src/ci/workflowModuleFormat.test.ts` is what
+ * now asks the question of the class rather than of the author.
+ *
+ * ## Why it refuses rather than being empty
+ *
+ * `export default {}` would build. It would also say nothing: an operator who reaches this Worker in a
+ * browser or with a stray `curl` gets an empty 200-shaped nothing from a Worker they were told hosts a job.
+ * A Workflow host has no request surface — an app Worker starts its jobs through a cross-script Workflow
+ * binding, and a host with a cron fires its own `scheduled` — so an HTTP request arriving at one is a
+ * misconfiguration, and the refusal is the sentence that ends the operator's search. `core/not_found`,
+ * because that is the truth: this Worker has no HTTP resources. The `action` names the path that does work
+ * and is stripped before the body goes out, like every other action.
+ *
+ * ## The one host this is not for
+ *
+ * A host that *does* serve HTTP mounts `registerWorkflowDispatchRoute` (./dispatchRoute) and exports its own
+ * handler. `@pithy-sh/email` is the case, and its door is the loopback dispatch `pithy dev` knocks on
+ * (#410). The other hosts have not been given that door yet; when one is, its `export default` becomes the
+ * Hono app and this refusal becomes that app's fallthrough. Nothing here has to change for that.
+ */
+/** What a refusing host exports: a `fetch`, and nothing else. Every other entry a Worker has is absent. */
+export interface WorkflowHostEntry {
+    /** Refuse the request. The platform passes a request, an env and a context; none is read, so none is declared. */
+    fetch(): Promise<Response>;
+}
+/**
+ * Build the default export for a Workflow host with no HTTP surface.
+ *
+ * Takes the capability so the refusal says which Worker answered — an operator holding a port number and a
+ * 404 needs that before anything else.
+ */
+export declare function workflowHostEntry(capability: string): WorkflowHostEntry;
+//# sourceMappingURL=hostEntry.d.ts.map

package/dist/workflow/hostEntry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostEntry.d.ts","sourceRoot":"","sources":["../../src/workflow/hostEntry.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,2GAA2G;AAC3G,MAAM,WAAW,iBAAiB;IAChC,kHAAkH;IAClH,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAcvE"}

package/dist/workflow/hostEntry.js

@@ -0,0 +1,24 @@
+import { NotFoundError } from "../error/pithyError.js";
+import { HttpError } from "../error/http.js";
+//#region src/workflow/hostEntry.ts
+/**
+* Build the default export for a Workflow host with no HTTP surface.
+*
+* Takes the capability so the refusal says which Worker answered — an operator holding a port number and a
+* 404 needs that before anything else.
+*/
+function workflowHostEntry(capability) {
+	return { async fetch() {
+		const refusal = new NotFoundError({
+			message: `The ${capability} workflow host serves no HTTP requests.`,
+			action: `Start its Workflows through the ${capability} Workflow binding, not over HTTP.`,
+			detail: "This Worker hosts Workflow classes and registers no routes."
+		});
+		return new Response(JSON.stringify({ error: HttpError.encode(refusal.payload) }), {
+			status: refusal.payload.status,
+			headers: { "content-type": "application/json" }
+		});
+	} };
+}
+//#endregion
+export { workflowHostEntry };

package/dist/workflow/hostEnv.d.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import type { Logger } from "../logger/logger";
+/**
+ * What a capability host worker reads out of its env, and what fills each of it.
+ *
+ * A host is a Worker nobody authored: `pithy <capability> provision` resolves a committed template
+ * (see {@link ./host.ts}) and deploys it. Everything it needs therefore arrives as a binding, a var,
+ * a Secrets Store entry or a serialized config blob — and until this module, **none of it was
+ * validated anywhere.** `@pithy-sh/email`'s host read fourteen fields raw: a missing `BASE_URL`
+ * became a magic link to `undefined/…`, an unparseable `EMAIL_THEME` threw inside a render step
+ * three retries deep, and a `SCHEDULER_BATCH_SIZE` somebody typed as `"fifty"` became `NaN`, so the
+ * scheduler claimed nothing, quietly, forever. Every one of those is discovered as a mail that did
+ * not arrive.
+ *
+ * So a host declares its env once, as a Zod object with a `.describe()` per field, and pairs each
+ * field with the thing that provides it. Two consumers read that one declaration:
+ *
+ * - the host itself, at boot, through {@link requireHostEnv} — one legible block naming every
+ *   unusable value and what fills it, then a refusal. A host that cannot work does not wait to be
+ *   asked.
+ * - `pithy doctor`, statically, through {@link hostEnvFields} and {@link checkHostEnv} — the same
+ *   schema, so the check an operator runs and the check the host runs cannot disagree.
+ *
+ * ## Kept importable from the CLI
+ *
+ * No `cloudflare:` import, no Node builtin, no filesystem — the same constraint {@link ./host.ts}
+ * carries, and for the same reason: `pithy doctor` runs under node and imports this to read a
+ * capability's declaration without executing its Worker.
+ */
+/** The kinds of thing that can fill a host env field. One of these names is what an operator acts on. */
+export declare const HostEnvProviderKind: z.ZodEnum<{
+    binding: "binding";
+    config: "config";
+    secret: "secret";
+    var: "var";
+}>;
+export type HostEnvProviderKind = z.infer<typeof HostEnvProviderKind>;
+/**
+ * What provides one field. The whole point of the declaration: a report that says `BASE_URL is
+ * missing` sends a developer looking, and a report that says `Var BASE_URL in the host's
+ * wrangler.jsonc. Run pithy email provision --env dev.` ends the search.
+ */
+export declare const HostEnvProvider: z.ZodObject<{
+    kind: z.ZodEnum<{
+        binding: "binding";
+        config: "config";
+        secret: "secret";
+        var: "var";
+    }>;
+    name: z.ZodString;
+    command: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HostEnvProvider = z.infer<typeof HostEnvProvider>;
+/**
+ * A host's env declaration: the capability that owns it, the schema, and a provider per field.
+ *
+ * **This type is the contract `pithy doctor` reads** (pithy-sh/pithy#411). A capability exports one
+ * of these as an ordinary value, so the CLI can import it, walk the schema, and validate a resolved
+ * configuration against the very object the deployed Worker validates itself against.
+ */
+export interface HostEnvDeclaration<Env extends z.ZodObject = z.ZodObject> {
+    /** The capability that owns the host — the `<capability>` segment of its worker name. */
+    readonly capability: string;
+    /** The env schema. `z.output` is what the host runs on; coercions and JSON parses belong in here. */
+    readonly env: Env;
+    /** Field name → what fills it. Every field of {@link env} has an entry; nothing else may. */
+    readonly provided: Readonly<Record<string, HostEnvProvider>>;
+}
+/**
+ * Declare a host's env. The mapped `provided` type makes an unaccounted field a compile error; the
+ * runtime check below makes it an error for a declaration the CLI reads back off a package it never
+ * compiled, which is the case `pithy doctor` is entirely made of.
+ */
+export declare function defineHostEnv<Env extends z.ZodObject>(declaration: {
+    capability: string;
+    env: Env;
+    provided: {
+        readonly [Field in keyof Env["shape"] & string]: HostEnvProvider;
+    };
+}): HostEnvDeclaration<Env>;
+/** One field of a host env that is missing or unparseable, with what would fix it. */
+export interface HostEnvProblem {
+    /** The field name, as declared. */
+    field: string;
+    /** Why it is unusable — the Zod issue's own message, unedited. */
+    reason: string;
+    /** What provides it. */
+    provider: HostEnvProvider;
+}
+/** The outcome of checking one env against one declaration. `value` is present exactly when `ok`. */
+export interface HostEnvReport<Value> {
+    /** Whether every declared field parsed. */
+    ok: boolean;
+    /** The parsed env — the shape the host runs on — or `undefined` when anything failed. */
+    value: Value | undefined;
+    /** Every unusable field, one entry each, in declaration order. */
+    problems: HostEnvProblem[];
+}
+/**
+ * Check an env against a declaration. Pure: it parses, it reports, and it neither logs nor throws —
+ * which is what lets `pithy doctor` run the host's own check without a Worker.
+ *
+ * One problem per field, even where Zod raises several issues for it: an operator fixes a field, not
+ * an issue, and three lines about `EMAIL_THEME` push the field they have not read yet off the block.
+ */
+export declare function checkHostEnv<Env extends z.ZodObject>(declaration: HostEnvDeclaration<Env>, env: unknown): HostEnvReport<z.output<Env>>;
+/** One sentence naming the thing an operator changes, plus the command that writes it where there is one. */
+export declare function hostEnvProviderSentence(provider: HostEnvProvider): string;
+/**
+ * The block a host logs before it refuses. One headline, then one line per field: the field, why it
+ * is unusable, and what fills it. Brand voice — short sentences, deliberate periods, no decoration
+ * that a log aggregator would have to strip.
+ */
+export declare function renderHostEnvProblems(capability: string, problems: readonly HostEnvProblem[]): string;
+/**
+ * Validate a host's env, or say exactly what is wrong and refuse.
+ *
+ * Called at boot, before the host serves anything. The block goes to the log (the operator's
+ * audience, so it carries the provider lines) and the refusal is `core/internal`: a host that cannot
+ * parse config *we* generated is our failure, and our logs are where the answer is (CLAUDE.md
+ * §Errors). Nothing about the values themselves is logged — a provider name is a location, never a
+ * secret.
+ */
+export declare function requireHostEnv<Env extends z.ZodObject>(declaration: HostEnvDeclaration<Env>, env: unknown, log?: Logger): z.output<Env>;
+/** One declared field, flattened for a reader that never runs the host — `pithy doctor`'s row. */
+export interface HostEnvField {
+    /** The field name, as the env carries it. */
+    field: string;
+    /** The field's own `.describe()`, or `undefined` where the schema carries none. */
+    description: string | undefined;
+    /** What provides it. */
+    provider: HostEnvProvider;
+    /** Whether the host works without it — i.e. whether the field's schema accepts `undefined`. */
+    optional: boolean;
+}
+/**
+ * Read a declaration statically: what the host needs, what documents each field, and what fills it.
+ *
+ * The static half of this module, and the one `pithy doctor` builds its report from (#411). Field
+ * order is the schema's, so a report reads in the order the capability chose to explain itself.
+ */
+export declare function hostEnvFields(declaration: HostEnvDeclaration): HostEnvField[];
+//# sourceMappingURL=hostEnv.d.ts.map

package/dist/workflow/hostEnv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostEnv.d.ts","sourceRoot":"","sources":["../../src/workflow/hostEnv.ts"],"names":[],"mappings":"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"}