@pithy-sh/cli 0.1.0

package/src/feature/devConfig.ts

@@ -0,0 +1,201 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fromZodError, InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { writeFileAtomic } from "../project/atomic";
+import type { WorkerTarget } from "../project/workers";
+import type { PortBlock } from "./ports";
+
+/**
+ * The per-feature dev config — a git-ignored `.dev.config.json` at the worktree root, written once by
+ * `pithy feature create` and fixed for the life of the feature.
+ *
+ * It exists because `.dev.vars` is a single file shared repo-wide across every worktree (each worktree's
+ * copy is a symlink to the main checkout's), so it cannot carry per-feature values without one feature
+ * clobbering another. This file is that per-feature surface.
+ *
+ * Ports are **assigned here at creation time, not discovered at startup** — that is the whole point.
+ * Probing for a free port when a worker boots is a time-of-check/time-of-use race: two `pithy dev`
+ * processes in two worktrees can both see the same port free and both try to bind it. Pre-assigning every
+ * worker its own port from the feature's reserved block makes N features run simultaneously with no
+ * probing, no race, and stable addresses each worker can use to auto-wire to its siblings.
+ *
+ * It is named for what it is — the feature's dev config — not for ports alone, so later per-feature dev
+ * settings land here too without a rename.
+ */
+
+/** One worker's fixed local endpoint for the life of the feature. */
+export const DevWorkerConfig = z
+  .object({
+    port: z.number().int().positive().describe("The port this worker binds locally, reserved at feature creation."),
+    origin: z.string().describe("The origin sibling workers reach this one at, e.g. http://localhost:8787."),
+  })
+  .describe("One worker's fixed local endpoint within its feature's reserved port block.");
+export type DevWorkerConfig = z.output<typeof DevWorkerConfig>;
+
+/** The feature's reserved slice of the central port registry. */
+export const DevPortBlock = z
+  .object({
+    index: z
+      .number()
+      .int()
+      .nonnegative()
+      .describe("The block's index in the machine's <config>/dev-ports.json registry."),
+    base: z.number().int().positive().describe("The first port in the block."),
+    size: z.number().int().positive().describe("How many ports the block spans — its worker capacity."),
+  })
+  .describe("The contiguous port block this feature owns, allocated from the central registry.");
+export type DevPortBlock = z.output<typeof DevPortBlock>;
+
+/** The `.dev.config.json` document. */
+export const DevConfig = z
+  .object({
+    version: z.literal(1).describe("Dev-config schema version."),
+    branch: z.string().describe("The feature branch this config belongs to, e.g. feature/69-media-cli."),
+    ports: DevPortBlock.describe("The feature's reserved port block."),
+    workers: z
+      .record(z.string(), DevWorkerConfig)
+      .describe("Each worker's fixed endpoint, keyed by worker name — the map pithy dev starts from."),
+  })
+  .describe("A feature's per-worktree dev configuration (git-ignored): its reserved ports and per-worker endpoints.");
+export type DevConfig = z.output<typeof DevConfig>;
+
+/** The dev-config path for a worktree: `<worktreeDir>/.dev.config.json`. */
+export function devConfigPath(worktreeDir: string): string {
+  return join(worktreeDir, ".dev.config.json");
+}
+
+/**
+ * Build the feature's dev config: one port per worker, drawn from the reserved block.
+ *
+ * **Assignment is sticky.** A worker that already has a port in `previous` keeps it, whatever the current
+ * discovery order — worker discovery is alphabetical, so a purely positional assignment would renumber every
+ * later worker the moment someone adds one that sorts earlier, moving addresses out from under a running dev
+ * session. Only genuinely new workers are assigned, each taking the lowest port in the block that nothing
+ * else holds; a worker that goes away releases its port back to the block for reuse.
+ *
+ * Fails when the feature has more workers than its block holds rather than spilling into the next feature's
+ * ports — a silent overlap is exactly the collision the block allocation exists to prevent.
+ */
+export function buildDevConfig(args: {
+  branch: string;
+  block: PortBlock;
+  workers: WorkerTarget[];
+  /** The feature's current dev config, whose worker→port pairs are preserved. Omit on first creation. */
+  previous?: DevConfig | null;
+}): DevConfig {
+  if (args.workers.length > args.block.size) {
+    throw new InternalError({
+      message: `This feature has ${args.workers.length} workers but its port block holds only ${args.block.size}.`,
+      // The count includes each composed capability's host Worker, which `pithy dev` starts beside the
+      // `apps/*` set — so removing a capability is as much a fix here as removing a Worker.
+      action: "Remove a worker or a capability, or widen the feature port-block size.",
+    });
+  }
+
+  const inBlock = (port: number): boolean => port >= args.block.base && port < args.block.base + args.block.size;
+  const kept = new Map<string, number>();
+  for (const worker of args.workers) {
+    // Carry a port over only when it still falls inside the block (a resized or reallocated block invalidates it).
+    const port = args.previous?.workers[worker.name]?.port;
+    if (port !== undefined && inBlock(port)) kept.set(worker.name, port);
+  }
+
+  const taken = new Set(kept.values());
+  const nextFree = (): number => {
+    for (let port = args.block.base; port < args.block.base + args.block.size; port += 1) {
+      if (!taken.has(port)) return port;
+    }
+    // Unreachable: the worker-count guard above already bounds demand to the block's size.
+    throw new InternalError({ detail: `No free port left in block ${args.block.block}.` });
+  };
+
+  const workers: Record<string, DevWorkerConfig> = {};
+  for (const worker of args.workers) {
+    let port = kept.get(worker.name);
+    if (port === undefined) {
+      port = nextFree();
+      taken.add(port);
+    }
+    workers[worker.name] = { port, origin: `http://localhost:${port}` };
+  }
+
+  return {
+    version: 1,
+    branch: args.branch,
+    ports: { index: args.block.block, base: args.block.base, size: args.block.size },
+    workers,
+  };
+}
+
+/** Zod-validate then write the dev config atomically (pretty JSON, trailing newline). */
+export async function writeDevConfig(path: string, config: DevConfig): Promise<void> {
+  const parsed = DevConfig.safeParse(config);
+  if (!parsed.success) {
+    throw fromZodError(parsed.error, {
+      message: "The feature dev config is invalid.",
+      action: "Re-run pithy feature create to rebuild .dev.config.json.",
+    });
+  }
+  await writeFileAtomic(path, `${JSON.stringify(parsed.data, null, 2)}\n`);
+}
+
+/**
+ * Every port block currently pinned on disk, read from each worktree's own `.dev.config.json` under
+ * `<mainRoot>/.worktrees`. This is what lets a lost port registry be rebuilt from the worktrees that
+ * outlived it (see `reclaimPortBlocks`).
+ * Unreadable or malformed configs are skipped rather than failing the scan — one bad worktree must not block
+ * creating a new feature.
+ */
+export async function scanPinnedBlocks(mainRoot: string): Promise<{ branch: string; block: PortBlock }[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(join(mainRoot, ".worktrees"));
+  } catch {
+    return []; // no .worktrees yet — nothing to reclaim.
+  }
+
+  const found: { branch: string; block: PortBlock }[] = [];
+  for (const entry of entries) {
+    const config = await readDevConfig(devConfigPath(join(mainRoot, ".worktrees", entry))).catch(() => null);
+    if (!config) continue;
+    found.push({
+      branch: config.branch,
+      block: { block: config.ports.index, base: config.ports.base, size: config.ports.size },
+    });
+  }
+  return found;
+}
+
+/** Read and validate the dev config, or `null` when the file does not exist. */
+export async function readDevConfig(path: string): Promise<DevConfig | null> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (cause) {
+    throw new InternalError({
+      message: "The feature dev config is corrupt.",
+      action: "Delete .dev.config.json and re-run pithy feature create.",
+      detail: cause instanceof Error ? cause.message : String(cause),
+    });
+  }
+
+  const parsed = DevConfig.safeParse(value);
+  if (!parsed.success) {
+    throw fromZodError(parsed.error, {
+      message: "The feature dev config is invalid.",
+      action: "Delete .dev.config.json and re-run pithy feature create.",
+    });
+  }
+  return parsed.data;
+}

package/src/feature/identity.ts

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { FeatureIdentity } from "@pithy-sh/core/src/naming/feature";
+import { loadProject, requireProjectName } from "../project/config";
+import { projectCapabilities, resolveWorkers } from "../project/workerScope";
+import { defaultGit, type GitRunner } from "./worktree";
+
+/** A feature's identity as read from its branch: the issue number, the slug, and the full branch name. */
+export interface FeatureBranchIdentity {
+  /** The issue number as a string, e.g. "69". */
+  issue: string;
+  /** The kebab-case slug, e.g. "media-cli". */
+  slug: string;
+  /** The full branch, `feature/<issue>-<slug>`. */
+  branch: string;
+}
+
+/** `feature/<digits>-<kebab-slug>` — the branch shape `pithy feature` owns. */
+const FEATURE_BRANCH = /^feature\/(\d+)-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
+/** Parse a branch name into a feature identity, or null when it is not a `feature/<issue>-<slug>` branch. */
+export function parseFeatureBranch(branch: string): FeatureBranchIdentity | null {
+  const match = FEATURE_BRANCH.exec(branch);
+  if (!match) return null;
+  const [, issue, slug] = match;
+  if (!issue || !slug) return null;
+  return { issue, slug, branch };
+}
+
+/**
+ * Derive the feature identity from the current git branch — the source of truth for `provision` and
+ * `destroy`, which take no positional args and run from within the worktree. Fails with an actionable
+ * error when the checkout is not on a `feature/<issue>-<slug>` branch.
+ */
+export async function deriveIdentityFromBranch(
+  cwd: string,
+  git: GitRunner = defaultGit,
+): Promise<FeatureBranchIdentity> {
+  const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+  const identity = parseFeatureBranch(branch);
+  if (!identity) {
+    throw new ValidationError({
+      message: `Not on a feature branch (${branch}).`,
+      action: "Run this from inside a feature worktree, or create one with pithy feature create.",
+    });
+  }
+  return identity;
+}
+
+/**
+ * Resolve the feature identity (project + issue + slug) from the current branch and the root config, plus
+ * the capabilities the feature spans.
+ *
+ * The two come from different places, deliberately. **Identity** is project-wide policy and lives in the
+ * root `pithy.config.ts`. **Capabilities** are per Worker (`apps/<name>/pithy.config.ts`), so they are
+ * unioned: a feature provisions one resource per binding name for the whole feature — two Workers that both
+ * declare `DB` deliberately share one database — and the migrate/seed it runs must cover every table any
+ * Worker owns.
+ *
+ * **Reached only once an operator has said `--feature` or run `pithy feature`.** The branch names a
+ * feature; it never decides that this run is one.
+ */
+export async function branchIdentity(
+  projectDir: string,
+): Promise<{ identity: FeatureIdentity; capabilities: Capability[] }> {
+  const { issue, slug } = await deriveIdentityFromBranch(projectDir);
+  const config = await loadProject(projectDir);
+  // Never guessed: this name is the first segment of every resource name, and the only key teardown has
+  // to find them again. A fallback that differs between a worktree and a clone would make destroy
+  // recompute names that match nothing, delete nothing, and exit 0 — a silent leak.
+  const project = requireProjectName(config);
+  const capabilities = projectCapabilities(await resolveWorkers({ projectDir }));
+  return { identity: { project, issue, slug }, capabilities };
+}
+
+/**
+ * The feature's identity without loading a single Worker config — `#454`.
+ *
+ * {@link branchIdentity} answers identity *and* capabilities, and the capabilities come from every
+ * `apps/<name>/pithy.config.ts`. That is right for `provision`, which cannot act without knowing what it
+ * is acting on. It is wrong for `destroy`, whose local half — free the port block, prune the worktree —
+ * needs none of it, and which is most needed in exactly the state where a Worker config will not load.
+ *
+ * A `feature create` that failed partway used to leave a worktree whose config threw, and `destroy` threw
+ * on the same config before it reached the teardown. The one command that removes the worktree and frees
+ * the port block was unavailable in the state it exists for, and the block leaked: the registry kept a
+ * branch that no longer existed, and the way out was editing `<config>/dev-ports.json` by hand.
+ *
+ * The project name still comes from the **root** config, which is project identity and holds no
+ * capabilities — so it loads when a Worker's does not, and teardown keeps deriving resource names the same
+ * way it always did rather than guessing them.
+ */
+export async function branchIdentityWithoutWorkers(projectDir: string): Promise<FeatureIdentity> {
+  const { issue, slug } = await deriveIdentityFromBranch(projectDir);
+  const project = requireProjectName(await loadProject(projectDir));
+  return { project, issue, slug };
+}

package/src/feature/manifest.ts

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { join } from "node:path";
+import { fromZodError, InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { writeFileAtomic } from "../project/atomic";
+import { readOptionalFile } from "../project/readOptionalFile";
+
+/**
+ * The remedy for a file that is there and would not open, chosen from the errno (#217).
+ *
+ * `readOptionalFile`'s `unreadable` is **every errno but `ENOENT`**. *Check permissions on X* answers
+ * one of them. An adopter whose `.pithy-feature.json` is a directory, a symlink loop, or a bad sector
+ * reads a sentence about permissions, runs `chmod`, and learns nothing — which is the shape #217 is
+ * about: a `catch` reachable more than one way may not name a single remedy. Unrecognised errnos get no
+ * remedy at all, only the errno, because a wrong action is worse than no action.
+ *
+ * `ports.ts` carries its own copy for its own file. Two is under this repository's threshold for hoisting
+ * a rule out of its call sites (see `readOptionalFile.ts`: *three is this repository's count*). The home
+ * for a third is beside `readOptionalFile`, which already owns the absent/unreadable decision itself.
+ */
+function unreadableAction(code: string | undefined, name: string): string {
+  switch (code) {
+    case "EACCES":
+    case "EPERM":
+      return `Check permissions on ${name}.`;
+    case "EISDIR":
+      return `${name} is a directory, not a file. Remove it, then re-run.`;
+    case "ELOOP":
+      return `${name} is a symlink loop. Replace it with a regular file, then re-run.`;
+    default:
+      return `${name} is there and would not open (${code ?? "unknown error"}). Check that file, then re-run.`;
+  }
+}
+
+/** One provisioned Cloudflare resource recorded for teardown. */
+export const FeatureResource = z
+  .object({
+    kind: z.enum(["d1", "kv", "r2"]).describe("The Cloudflare resource type."),
+    binding: z.string().describe("The Worker binding name this resource backs, e.g. DB."),
+    name: z.string().describe("The full CF resource name, e.g. acme-f69-media-cli-db-d1."),
+    id: z.string().describe("The CF-assigned id (D1 uuid, KV namespace id) or the bucket name for r2."),
+  })
+  .describe("One provisioned Cloudflare resource recorded for teardown.");
+export type FeatureResource = z.output<typeof FeatureResource>;
+
+/** The per-feature record of provisioned Cloudflare resources (git-ignored, in the worktree). */
+export const FeatureManifest = z
+  .object({
+    version: z.literal(1).describe("Manifest schema version."),
+    project: z.string().describe('The project name, from pithy.config (e.g. "acme").'),
+    issue: z.string().describe('The issue number this feature was created for (e.g. "69").'),
+    slug: z.string().describe('The kebab-case feature slug (e.g. "media-cli").'),
+    env: z.string().describe("The environment these resources belong to."),
+    resources: z.array(FeatureResource).describe("Every provisioned resource, for exact-id teardown."),
+  })
+  .describe("The per-feature record of provisioned Cloudflare resources (git-ignored, in the worktree).");
+export type FeatureManifest = z.output<typeof FeatureManifest>;
+
+/** The manifest path for a worktree dir: `<worktreeDir>/.pithy-feature.json`. */
+export function manifestPath(worktreeDir: string): string {
+  return join(worktreeDir, ".pithy-feature.json");
+}
+
+/**
+ * Read + Zod-validate the manifest, or `null` if the file does not exist.
+ *
+ * "Does not exist" is {@link readOptionalFile}'s decision — a manifest that is there and will not open
+ * would otherwise read as "this worktree provisioned nothing", and `pithy feature destroy` tears down by
+ * exact id from this record. The words stay here; the errno does not.
+ */
+export async function readManifest(path: string): Promise<FeatureManifest | null> {
+  const raw = await readOptionalFile(path, {
+    unreadable: ({ code, cause }) =>
+      new InternalError({
+        message: "Could not read the feature manifest.",
+        action: unreadableAction(code, ".pithy-feature.json"),
+        detail: `${code ?? "unknown error"}: ${cause instanceof Error ? cause.message : String(cause)}`,
+      }),
+  });
+  if (raw === null) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new InternalError({
+      message: "The feature manifest is corrupt.",
+      action: "Delete .pithy-feature.json and re-run pithy provision --feature.",
+      detail: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  const result = FeatureManifest.safeParse(parsed);
+  if (!result.success) {
+    throw fromZodError(result.error, {
+      message: "The feature manifest is corrupt.",
+      action: "Delete .pithy-feature.json and re-run pithy provision --feature.",
+    });
+  }
+  return result.data;
+}
+
+/** Zod-validate then write the manifest atomically (pretty JSON, 2-space indent, trailing newline). */
+export async function writeManifest(path: string, manifest: FeatureManifest): Promise<void> {
+  const parsed = FeatureManifest.parse(manifest);
+  await writeFileAtomic(path, `${JSON.stringify(parsed, null, 2)}\n`);
+}
+
+/**
+ * Return a NEW manifest with `resource` upserted — deduped by (kind, binding, name); a match is
+ * replaced in place, otherwise the resource is appended. Pure: never mutates `manifest`.
+ */
+export function upsertResource(manifest: FeatureManifest, resource: FeatureResource): FeatureManifest {
+  const index = manifest.resources.findIndex(
+    (existing) =>
+      existing.kind === resource.kind && existing.binding === resource.binding && existing.name === resource.name,
+  );
+
+  const resources =
+    index === -1
+      ? [...manifest.resources, resource]
+      : manifest.resources.map((existing, i) => (i === index ? resource : existing));
+
+  return { ...manifest, resources };
+}
+
+/** Build an empty manifest for an identity + environment. */
+export function emptyManifest(args: { project: string; issue: string; slug: string; env: string }): FeatureManifest {
+  return { version: 1, ...args, resources: [] };
+}