@pithy-sh/cli 0.1.0

package/src/capabilities/prerequisites.ts

@@ -0,0 +1,168 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CapabilityManifest } from "@pithy-sh/core/src/capability/manifest";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+
+/**
+ * **A capability's prerequisites are declared in its manifest, and every command reads them from there.**
+ *
+ * `peerCapabilities` has been in `pithy.manifest.json` since the contract landed, and `createBackend`
+ * has always refused to assemble without them — `Capability "auth" requires the "secrets" capability,
+ * which is not composed.` What was missing was anything between the two: `pithy add auth` wrote the
+ * registration, said `Done.`, and left a Worker that could not start (#273). `pithy doctor` said the
+ * project was healthy, because it checked bindings, config keys and migrations, and nobody had asked it
+ * this question.
+ *
+ * So this module is the one place that answers it, for both commands. `pithy add` resolves the closure
+ * before it wires anything; `pithy doctor` reports a composed capability whose peer is absent and fails
+ * its exit. Neither hand-lists a capability's prerequisites, because hand-listing them is how the next
+ * capability's get missed — `payments`, `support`, `storage`, `media` and `turnstile` all declare
+ * `secrets`, and `testers` declares `email`.
+ *
+ * The manifest, and not the composed instance's `dependsOn`: the two mirror each other by test in each
+ * capability's package, and the manifest is the half that is readable before a capability is composed —
+ * which is exactly when `pithy add` has to decide.
+ */
+
+/** A composed capability whose declared prerequisite is not composed beside it. */
+export const MissingPrerequisite = z
+  .object({
+    capability: z.string().describe("The composed capability that declares the prerequisite, by manifest name."),
+    requires: z
+      .string()
+      .describe(
+        "The capability it declares as a peer and this Worker does not compose. Boot refuses on exactly this pair.",
+      ),
+  })
+  .describe("A composed capability whose manifest declares a peer the Worker's config does not register.");
+export type MissingPrerequisite = z.infer<typeof MissingPrerequisite>;
+
+/**
+ * Whether a Worker's `pithy.config.ts` **registers** a capability — the call, not the import.
+ *
+ * The call is what composes, so the call is what is asked about. A config that imports `email` and never
+ * writes `email()` composes nothing, and `createBackend` agrees. Anchored to the start of a line and to
+ * the whole name, so `myauth(` is not `auth(` — the same rule `pithy add`'s idempotency check uses, and
+ * it reads the source rather than importing it: the config this is asked about is frequently one that
+ * cannot boot.
+ */
+export function isRegistered(source: string, name: string): boolean {
+  return new RegExp(`^[ \\t]*${escapeRegExp(name)}[ \\t]*\\(`, "m").test(source);
+}
+
+/** Escape a capability name for use inside a `RegExp` (names are bare identifiers, but be safe). */
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** What {@link prerequisiteClosure} needs: the capability being added, what is already composed, and the manifests. */
+export interface PrerequisiteClosureOptions {
+  /** The manifest of the capability being added — the root of the walk. */
+  manifest: CapabilityManifest;
+  /** The capability names this Worker already composes. A peer in here is satisfied and never proposed. */
+  composed: ReadonlySet<string>;
+  /**
+   * A peer's manifest, or `undefined` when its package is not installed yet.
+   *
+   * Undefined is a real answer and not a failure: a peer nobody has installed is still missing, and
+   * naming it beats silence. It is walked no deeper, because there is nothing there to read — the add
+   * that composes it resolves its own peers once its package is on disk.
+   */
+  manifestFor: (name: string) => CapabilityManifest | undefined;
+}
+
+/**
+ * The prerequisites one capability needs and this Worker lacks, **deepest first**.
+ *
+ * Order is the point, which is why this is a graph walk and not a filter over `peerCapabilities`.
+ * `auth` declares `secrets` and `email`; `email` declares `secrets`; and `pithy add email` into a
+ * Worker with no secrets composed is the same defect one capability along. Post-order DFS puts a
+ * capability after everything it reads, whatever order its manifest happens to list them in.
+ *
+ * Cycles terminate. Nothing in the kit declares one, and a manifest is somebody else's file.
+ */
+export function prerequisiteClosure(options: PrerequisiteClosureOptions): string[] {
+  const { composed, manifestFor } = options;
+  const order: string[] = [];
+  const resolved = new Set<string>();
+  // Everything currently on the walk, root included — a peer already being resolved above is what a
+  // cycle looks like from in here, and re-entering it is what would not terminate.
+  const walking = new Set<string>([options.manifest.name]);
+
+  const visit = (manifest: CapabilityManifest): void => {
+    for (const peer of manifest.peerCapabilities) {
+      if (composed.has(peer) || resolved.has(peer) || walking.has(peer)) continue;
+      walking.add(peer);
+      const peerManifest = manifestFor(peer);
+      if (peerManifest) visit(peerManifest);
+      walking.delete(peer);
+      resolved.add(peer);
+      order.push(peer);
+    }
+  };
+  visit(options.manifest);
+  return order;
+}
+
+/**
+ * Every prerequisite a Worker's composed set declares and does not satisfy — `pithy doctor`'s check.
+ *
+ * Scoped to the composed set on purpose. Manifests resolve once from the project root, so they describe
+ * every capability installed *anywhere* in the project; only this Worker's `pithy.config.ts` says what
+ * this Worker is made of. An `audit` another Worker composes must not make this one unhealthy.
+ *
+ * Reported in the order a manifest declares its peers, so the sentence matches the file.
+ */
+export function missingPrerequisites(
+  manifests: readonly CapabilityManifest[],
+  composed: ReadonlySet<string>,
+): MissingPrerequisite[] {
+  const missing: MissingPrerequisite[] = [];
+  for (const manifest of manifests) {
+    if (!composed.has(manifest.name)) continue;
+    for (const peer of manifest.peerCapabilities) {
+      if (!composed.has(peer)) missing.push({ capability: manifest.name, requires: peer });
+    }
+  }
+  return missing;
+}
+
+/** `a`, `a and b`, `a, b and c` — for a sentence, never for a command line. */
+function andList(names: readonly string[]): string {
+  if (names.length <= 1) return names.join("");
+  return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+
+/** What {@link prerequisiteRefusal} names: the capability asked for, the Worker, and what it lacks. */
+export interface PrerequisiteRefusalOptions {
+  /** The capability the adopter asked for. */
+  capability: string;
+  /** The Worker it was to be wired into — the one whose config lacks the peers. */
+  worker: string;
+  /** The missing prerequisites, deepest first, as {@link prerequisiteClosure} ordered them. */
+  missing: readonly string[];
+}
+
+/**
+ * The refusal a run that cannot ask takes.
+ *
+ * **It names the commands, in dependency order.** A refusal that says only "auth requires secrets" makes
+ * the adopter guess the order, and guessing wrong reproduces the defect one capability along. The flag
+ * comes first because it is the one-command answer; the manual sequence is there for whoever wants to
+ * decide each one, which is the honest half of composing something nobody asked for.
+ */
+export function prerequisiteRefusal(options: PrerequisiteRefusalOptions): ValidationError {
+  const { capability, worker, missing } = options;
+  const commands = missing.map((name) => `pithy add ${name}`);
+  const sequence =
+    commands.length > 1
+      ? `${commands.slice(0, -1).join(", ")}, then ${commands[commands.length - 1]}`
+      : commands.join("");
+  return new ValidationError({
+    message: `${capability} requires ${andList(missing)}, which ${worker} does not compose.`,
+    action: `Run pithy add ${capability} --with-prerequisites, or compose ${missing.length === 1 ? "it" : "them"} first: ${sequence}.`,
+    detail: `${capability}'s manifest declares peerCapabilities ${JSON.stringify(missing)}; createBackend refuses to assemble without them.`,
+  });
+}

package/src/capabilities/r2Bucket.ts

@@ -0,0 +1,113 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import { R2Credentials } from "@pithy-sh/cloudflare/src/r2/r2Credentials";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+
+/**
+ * The R2 bucket steps `pithy storage` and `pithy media` share: resolving the S3 key pair, and taking a
+ * bucket down with everything in it.
+ *
+ * Both capabilities provision a per-environment bucket and both tear one down, so the sequence lives
+ * here rather than twice. It sits in the CLI provisioner layer, not in either package: the packages own
+ * the *orchestration* (which environments, in what order) behind a seam they unit-test with a fake, and
+ * the live Cloudflare calls are deliberately on this side of that seam.
+ */
+
+/**
+ * Resolve the R2 S3 key pair: the explicit flags first, then `R2_CREDENTIALS` in `.dev.vars`. Both legs
+ * validate through the canonical {@link R2Credentials} schema, so a half-supplied or malformed pair fails
+ * here rather than at the Worker's first presign — or, on teardown, half way through deleting buckets.
+ */
+export function resolveR2Credentials(
+  accessKeyId: string | undefined,
+  secretAccessKey: string | undefined,
+  raw: string | undefined,
+): R2Credentials {
+  if (accessKeyId || secretAccessKey) {
+    const parsed = R2Credentials.safeParse({ accessKeyId, secretAccessKey });
+    if (!parsed.success) {
+      throw new ValidationError({
+        message: "The R2 access-key pair is incomplete.",
+        action: "Pass both --r2-access-key-id and --r2-secret-access-key.",
+      });
+    }
+    return parsed.data;
+  }
+  if (!raw) {
+    throw new ValidationError({
+      message: "No R2 S3 credentials were supplied.",
+      action:
+        "Pass --r2-access-key-id and --r2-secret-access-key, or set R2_CREDENTIALS in .dev.vars. Create the pair under R2 → Manage API tokens; Cloudflare has no API for minting one.",
+    });
+  }
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(raw);
+  } catch {
+    throw new ValidationError({
+      message: "R2_CREDENTIALS is not valid JSON.",
+      action: 'Set R2_CREDENTIALS to {"accessKeyId":"…","secretAccessKey":"…"}.',
+    });
+  }
+  const parsed = R2Credentials.safeParse(decoded);
+  if (!parsed.success) {
+    throw new ValidationError({
+      message: "R2_CREDENTIALS is not a valid access-key/secret-key pair.",
+      action: 'Set R2_CREDENTIALS to {"accessKeyId":"…","secretAccessKey":"…"}.',
+    });
+  }
+  return parsed.data;
+}
+
+/** What a bucket teardown did, so the caller can audit it and report it. */
+export interface R2BucketTeardown {
+  /** Whether a bucket was there to delete. `false` means teardown found nothing and did nothing. */
+  deleted: boolean;
+  /** How many stored objects the drain removed before the bucket came down. */
+  objectsDeleted: number;
+  /** How many abandoned multipart uploads the drain aborted. */
+  uploadsAborted: number;
+}
+
+/** What deleting one bucket needs: the clients, the S3 key pair the drain runs on, and the name. */
+export interface DeleteR2BucketOptions {
+  /** The configured Cloudflare clients — the control plane for the delete, the object plane for the drain. */
+  cf: CloudflareClients;
+  /**
+   * The R2 S3 key pair. Optional because a deprovision that does not touch storage never needs one; a
+   * teardown that reaches a real bucket without it fails with an actionable error instead of a SigV4 fault.
+   */
+  credentials?: R2Credentials;
+  /** The bucket to remove, by name — R2's only address for one. */
+  bucketName: string;
+}
+
+/**
+ * Delete a bucket **and everything in it**, or do nothing if it is not there.
+ *
+ * Drain first, then delete. R2 rejects the delete of a non-empty bucket, so a teardown that only called
+ * the control plane worked on an untouched bucket and failed on every bucket anyone had actually used —
+ * the one case it exists for. Emptying is an S3-protocol operation the CF API cannot express, which is
+ * why this needs the key pair and the plain `deleteBucket` above it does not.
+ *
+ * Idempotent end to end: a missing bucket, an empty one, and a retried run all land the same way.
+ */
+export async function deleteR2BucketWithContents(options: DeleteR2BucketOptions): Promise<R2BucketTeardown> {
+  const existing = await options.cf.r2Provisioner().findBucketByName(options.bucketName);
+  if (!existing) return { deleted: false, objectsDeleted: 0, uploadsAborted: 0 };
+
+  const credentials = options.credentials;
+  if (!credentials) {
+    throw new ValidationError({
+      message: `The R2 access-key pair is needed to delete the ${existing.name} bucket.`,
+      action: "Pass --r2-access-key-id and --r2-secret-access-key, or set R2_CREDENTIALS in .dev.vars.",
+      detail: "R2 refuses to delete a non-empty bucket, and emptying one is an S3-protocol operation.",
+    });
+  }
+
+  const drain = await options.cf.r2({ ...credentials, bucketName: existing.name }).emptyBucket();
+  await options.cf.r2Provisioner().deleteBucket(existing.name);
+  return { deleted: true, ...drain };
+}