@pithy-sh/cli 0.1.0

package/src/project/jsonc.ts

@@ -0,0 +1,289 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { stringify } from "comment-json";
+import { type AtomicWriteOptions, writeFileAtomic } from "./atomic";
+import { readFileOutcome } from "./readOptionalFile";
+
+/**
+ * The one place Pithy turns a parsed JSONC document back into bytes.
+ *
+ * **The invariant: a file Pithy writes is a file the formatter it scaffolds would print unchanged.**
+ * The kit scaffolds Biome *and* the pre-commit hook that runs it, so it already knows the rules its own
+ * output has to satisfy — and until #249 it did not follow them. `comment-json`'s `stringify` puts every
+ * array element on its own line, Biome collapses a short array onto one, and so `pithy ui sync` wrote a
+ * `wrangler.jsonc` that failed the commit hook the CLI itself installed. The workaround was to exempt
+ * `wrangler.jsonc` and `pithy.worker.jsonc` from the scaffolded formatter, which is not a fix: it says
+ * the two files Pithy touches most are the two nothing formats.
+ *
+ * Two rules, which together are Biome's `expand: "auto"` for JSON:
+ *
+ * - **An array is one line when it fits, and one element per line when it does not.** No source to
+ *   consult and no choice to preserve; the width decides it.
+ * - **An object keeps the shape it already had.** Biome preserves an object's expansion, so both forms
+ *   pass — but only one of them leaves the diff alone. A `pithy ui sync` that changed two lines was
+ *   producing 78 insertions, because re-printing expanded every object in the file, and a real edit
+ *   invisible inside a reformat is an edit nobody reviewed. The previous bytes are the oracle;
+ *   an object Pithy is adding has none, and collapses if it fits.
+ *
+ * A span holding a comment is never collapsed. Joining its lines would put everything after a `//`
+ * inside it, and comments are the reason this repo writes JSONC at all.
+ */
+
+/** The width Biome prints JSON at, and the width the starter's `biome.jsonc` declares. */
+export const JSONC_LINE_WIDTH = 120;
+
+/** One bracketed span in a source text, and everything the printer has to know about it. */
+interface Span {
+  /** `[` or `{`. */
+  readonly kind: "array" | "object";
+  /** Index of the opening bracket. */
+  readonly open: number;
+  /** Index of the closing bracket. */
+  readonly close: number;
+  /** Where the span sits in the document — `/assets/run_worker_first`. The oracle's key. */
+  readonly path: string;
+  /** True when a comment sits anywhere inside, at any depth. Such a span is never collapsed. */
+  readonly hasComment: boolean;
+  /** True when a newline separated the opening bracket from the first thing inside it. */
+  readonly expanded: boolean;
+  /** The spans directly inside this one, in source order. */
+  readonly children: Span[];
+}
+
+/** A span being scanned, before its closing bracket has been found. */
+interface Frame {
+  kind: "array" | "object";
+  open: number;
+  path: string;
+  /** The key the object is currently inside the value of, or `null` before the first `:`. */
+  key: string | null;
+  /** How many elements of an array have been passed. */
+  index: number;
+  hasComment: boolean;
+  expanded: boolean;
+  sawFirstToken: boolean;
+  sawNewline: boolean;
+  /** True while the next string literal in an object would be a key rather than a value. */
+  expectKey: boolean;
+  children: Span[];
+}
+
+/** The path of the value a frame is currently reading — its key, or its index inside an array. */
+function childPath(frame: Frame): string {
+  return `${frame.path}/${frame.kind === "object" ? (frame.key ?? "") : frame.index}`;
+}
+
+/** Where a string literal starting at `start` ends, escapes honored. Returns the index of its closing quote. */
+function endOfString(text: string, start: number): number {
+  for (let index = start + 1; index < text.length; index += 1) {
+    if (text[index] === "\\") {
+      index += 1;
+      continue;
+    }
+    if (text[index] === '"') return index;
+  }
+  return text.length - 1;
+}
+
+/**
+ * Every bracketed span in `text`, as a forest in source order.
+ *
+ * One pass, because the printer and the oracle both need the same three facts about a span — where it
+ * is, what its path is, and whether anything inside it forbids a collapse — and two scanners would be
+ * two chances to disagree about them.
+ */
+function scanSpans(text: string): Span[] {
+  const roots: Span[] = [];
+  const stack: Frame[] = [];
+  let pendingKey: string | null = null;
+
+  /** Everything up the stack refuses to collapse: a joined line would swallow what follows a `//`. */
+  const markComment = (): void => {
+    for (const frame of stack) frame.hasComment = true;
+  };
+
+  /** The first thing inside a span settles whether the source had it expanded. */
+  const markToken = (): void => {
+    const frame = stack.at(-1);
+    if (!frame || frame.sawFirstToken) return;
+    frame.sawFirstToken = true;
+    frame.expanded = frame.sawNewline;
+  };
+
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+
+    if (char === "\n") {
+      const frame = stack.at(-1);
+      if (frame && !frame.sawFirstToken) frame.sawNewline = true;
+      continue;
+    }
+    if (char === " " || char === "\t" || char === "\r") continue;
+
+    if (char === "/" && text[index + 1] === "/") {
+      markComment();
+      const end = text.indexOf("\n", index);
+      index = end === -1 ? text.length : end - 1;
+      continue;
+    }
+    if (char === "/" && text[index + 1] === "*") {
+      markComment();
+      const end = text.indexOf("*/", index + 2);
+      index = end === -1 ? text.length : end + 1;
+      continue;
+    }
+
+    if (char === '"') {
+      markToken();
+      const end = endOfString(text, index);
+      const frame = stack.at(-1);
+      if (frame?.kind === "object" && frame.expectKey) pendingKey = text.slice(index + 1, end);
+      index = end;
+      continue;
+    }
+
+    if (char === ":") {
+      const frame = stack.at(-1);
+      if (frame?.kind === "object") {
+        frame.key = pendingKey;
+        frame.expectKey = false;
+      }
+      continue;
+    }
+
+    if (char === ",") {
+      const frame = stack.at(-1);
+      if (frame?.kind === "object") frame.expectKey = true;
+      if (frame?.kind === "array") frame.index += 1;
+      continue;
+    }
+
+    if (char === "{" || char === "[") {
+      markToken();
+      const parent = stack.at(-1);
+      stack.push({
+        kind: char === "{" ? "object" : "array",
+        open: index,
+        path: parent ? childPath(parent) : "",
+        key: null,
+        index: 0,
+        hasComment: false,
+        expanded: false,
+        sawFirstToken: false,
+        sawNewline: false,
+        expectKey: char === "{",
+        children: [],
+      });
+      continue;
+    }
+
+    if (char === "}" || char === "]") {
+      const frame = stack.pop();
+      if (!frame) continue;
+      const span: Span = {
+        kind: frame.kind,
+        open: frame.open,
+        close: index,
+        path: frame.path,
+        hasComment: frame.hasComment,
+        expanded: frame.expanded,
+        children: frame.children,
+      };
+      const parent = stack.at(-1);
+      if (parent) parent.children.push(span);
+      else roots.push(span);
+      continue;
+    }
+
+    markToken();
+  }
+  return roots;
+}
+
+/**
+ * Which objects the previous bytes had expanded, by path.
+ *
+ * Objects only. An array's shape is decided by the width every time, so remembering one would only let a
+ * stale answer overrule the rule.
+ */
+function objectWrapping(previous: string): Map<string, boolean> {
+  const wrapping = new Map<string, boolean>();
+  const visit = (span: Span): void => {
+    if (span.kind === "object") wrapping.set(span.path, span.expanded);
+    for (const child of span.children) visit(child);
+  };
+  for (const root of scanSpans(previous)) visit(root);
+  return wrapping;
+}
+
+/** The span's text with every child already decided, then this span's own decision applied. */
+function printSpan(text: string, span: Span, wrapping: Map<string, boolean>): string {
+  let printed = "";
+  let cursor = span.open;
+  for (const child of span.children) {
+    printed += text.slice(cursor, child.open) + printSpan(text, child, wrapping);
+    cursor = child.close + 1;
+  }
+  printed += text.slice(cursor, span.close + 1);
+
+  if (span.hasComment) return printed;
+  const inner = printed.slice(1, -1).trim();
+  if (inner.length === 0) return span.kind === "array" ? "[]" : "{}";
+  // The document's top level stays expanded whatever its width: no config file is one line, and an
+  // absent oracle is the ordinary case for a file Pithy is creating.
+  if (span.kind === "object" && (wrapping.get(span.path) ?? span.path.length === 0)) return printed;
+
+  const joined = printed
+    .slice(1, -1)
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .join(" ");
+  const collapsed = span.kind === "array" ? `[${joined}]` : `{ ${joined} }`;
+
+  // What the line would measure once collapsed. Nothing but a comma and a comment ever follows a value
+  // on its own line, and neither moves, so the prefix and the suffix are read from the expanded text.
+  const lineStart = text.lastIndexOf("\n", span.open) + 1;
+  const lineEnd = text.indexOf("\n", span.close);
+  const prefix = text.slice(lineStart, span.open);
+  const suffix = text.slice(span.close + 1, lineEnd === -1 ? text.length : lineEnd);
+  if (prefix.length + collapsed.length + suffix.length > JSONC_LINE_WIDTH) return printed;
+  return collapsed;
+}
+
+/**
+ * `value` as the bytes of a JSONC file — comments preserved, formatted the way the project's Biome
+ * would print them, and shaped like `previous` wherever `previous` had an opinion.
+ *
+ * Pass the file's current contents as `previous` whenever there are any. Without them every object
+ * collapses that fits, which is right for a file being created and wrong for one being edited: it would
+ * rewrap an adopter's whole file around a two-line change.
+ */
+export function formatJsonc(value: unknown, previous?: string | null): string {
+  const expanded = stringify(value, null, 2) ?? "";
+  const wrapping = previous ? objectWrapping(previous) : new Map<string, boolean>();
+  const roots = scanSpans(expanded);
+  let printed = "";
+  let cursor = 0;
+  for (const root of roots) {
+    printed += expanded.slice(cursor, root.open) + printSpan(expanded, root, wrapping);
+    cursor = root.close + 1;
+  }
+  printed += expanded.slice(cursor);
+  return `${printed}\n`;
+}
+
+/**
+ * Write `value` to `path` as JSONC, atomically, shaped like whatever is already there.
+ *
+ * The previous bytes are read here rather than passed in, so no caller can forget them. Most callers
+ * have already read the file, so this is a second read of something small — the price of an argument
+ * nobody has to remember, whose absence would show up only as a reformatted diff. A file that will not
+ * open is not a refusal: this is about formatting, and the write itself is about to answer for the path.
+ */
+export async function writeJsonc(path: string, value: unknown, options?: AtomicWriteOptions): Promise<void> {
+  const previous = await readFileOutcome(path);
+  const bytes = formatJsonc(value, previous.state === "read" ? previous.text : null);
+  await writeFileAtomic(path, bytes, options);
+}

package/src/project/packageManager.ts

@@ -0,0 +1,238 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { execFile } from "node:child_process";
+import { access, readFile, realpath } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { promisify } from "node:util";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+
+const run = promisify(execFile);
+
+/** The package managers a Pithy adopter might use. Adoption is never gated behind Bun. */
+export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+/**
+ * Lockfile → package manager, most specific first. `bun.lock` precedes
+ * `package-lock.json` so a project carrying both (a Bun project npm once touched)
+ * resolves to Bun. The fallback is npm — present on every Node install.
+ */
+const LOCKFILES: readonly [string, PackageManager][] = [
+  ["bun.lock", "bun"],
+  ["bun.lockb", "bun"],
+  ["pnpm-lock.yaml", "pnpm"],
+  ["yarn.lock", "yarn"],
+  ["package-lock.json", "npm"],
+];
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Detect the project's package manager from its lockfile; npm when none is found. */
+export async function detectPackageManager(projectDir: string): Promise<PackageManager> {
+  for (const [lockfile, pm] of LOCKFILES) {
+    if (await exists(join(projectDir, lockfile))) return pm;
+  }
+  return "npm";
+}
+
+/** The install argv for a package manager: npm `install`, the rest `add`, for one or many packages. */
+export function installArgs(pm: PackageManager, pkgs: string | string[]): string[] {
+  const list = Array.isArray(pkgs) ? pkgs : [pkgs];
+  return [pm === "npm" ? "install" : "add", ...list];
+}
+
+/** The uninstall argv for a package manager: npm `uninstall`, the rest `remove`. */
+export function uninstallArgs(pm: PackageManager, pkg: string): string[] {
+  return [pm === "npm" ? "uninstall" : "remove", pkg];
+}
+
+/**
+ * Resolve a package binary through the project's package manager, so `pithy` never assumes a global
+ * install. Each manager has its own "run a workspace-local bin" invocation:
+ * `bun x <bin>`, `pnpm exec <bin>`, `yarn <bin>`, `npx <bin>`. The returned `{ command, args }` is
+ * ready to hand to `child_process.spawn`.
+ */
+export function execArgs(pm: PackageManager, bin: string, args: string[]): { command: string; args: string[] } {
+  switch (pm) {
+    case "bun":
+      return { command: "bun", args: ["x", bin, ...args] };
+    case "pnpm":
+      return { command: "pnpm", args: ["exec", bin, ...args] };
+    case "yarn":
+      return { command: "yarn", args: [bin, ...args] };
+    default:
+      return { command: "npx", args: [bin, ...args] };
+  }
+}
+
+/** The scope every package this kit ships lives under. */
+const PITHY_SCOPE = "@pithy-sh/";
+
+/**
+ * Whether `projectDir/node_modules/<pkg>` is a **checkout linked in** rather than something a registry
+ * install put there.
+ *
+ * Two conditions, and both are load-bearing.
+ *
+ * *At the project root, and only there.* Node's own lookup walks `node_modules` up every ancestor to
+ * `/`; this deliberately does not. The rest of the CLI never walks — `loadManifest` reads
+ * `projectDir/node_modules/@pithy-sh/<pkg>` and nothing above it — so an ancestor hit made `pithy add`
+ * skip the install and then report the capability as not installed, telling the adopter to run the
+ * command that had just declined to run. And walking is a way in: `/tmp` and `$HOME` are ancestors
+ * anyone can leave a `node_modules` in, `pithy add` wires the resolved package into `pithy.config.ts`,
+ * and `pithy migrate` imports that config. Bounded, a planted copy is shadowed by a real install again.
+ *
+ * *Resolving out of `node_modules`.* A registry install is a real directory under `node_modules` — bun
+ * hoists transitive dependencies there too, and the scope depends on itself (`auth` pulls `email`,
+ * `secrets`, `turnstile`). Treating a hoisted copy as provided meant `pithy add email` after
+ * `pithy add auth` declared nothing, and `pithy remove auth` then pruned it out from under a config that
+ * still imported it. A link that lands *outside* `node_modules` is the thing that has no version to
+ * write: a workspace member, a `bun link`, a `file:` dependency. pnpm's store is inside `node_modules`,
+ * so its symlinks read as the registry installs they are.
+ *
+ * The manifest is read rather than the directory stat'ed, because a stat answers the wrong question. The
+ * checkout a link points at can be gone, and an `@pithy-sh` folder can be left behind empty by a
+ * half-finished remove. Reading `package.json` and checking the name it declares is what "importable"
+ * actually means.
+ */
+async function linkedFromCheckout(projectDir: string, pkg: string): Promise<boolean> {
+  const modules = join(projectDir, "node_modules");
+  const at = join(modules, ...pkg.split("/"));
+  let resolved: string;
+  let root: string;
+  try {
+    const raw = await readFile(join(at, "package.json"), "utf8");
+    if ((JSON.parse(raw) as { name?: unknown }).name !== pkg) return false;
+    // Both sides through `realpath`, or a `node_modules` reached by a symlinked path — a macOS tmpdir,
+    // a symlinked home — would read as outside itself and call every install a checkout.
+    [resolved, root] = await Promise.all([realpath(at), realpath(modules)]);
+  } catch {
+    // Missing, dangling, unreadable, or unparsable. None of them is a resolution.
+    return false;
+  }
+  return relative(root, resolved).startsWith("..");
+}
+
+/**
+ * Whether a `@pithy-sh/*` package is already provided by the project, so nothing should reach for the
+ * registry on its behalf — neither an install nor a version range written into a `package.json`.
+ *
+ * Nothing under `@pithy-sh/*` is published yet, so a project working against a local checkout links the
+ * packages in and every registry reference 404s: `pithy add secrets` failed on `bun add`, and
+ * `pithy ui add react` succeeded while writing a `"@pithy-sh/vite": "^0.0.0"` that broke the *next*
+ * install. One predicate, both call sites, no flag to remember. Once the packages publish it goes quiet:
+ * an installed copy is a real directory with a real version, so the normal path runs and declares it.
+ *
+ * The scope is part of the rule, not incidental. `react` linked into the project says only that someone
+ * is developing against a fork — its range is still correct and must still be written.
+ */
+export async function alreadyProvided(projectDir: string, pkg: string): Promise<boolean> {
+  return pkg.startsWith(PITHY_SCOPE) && (await linkedFromCheckout(projectDir, pkg));
+}
+
+/** Spawn a package manager. Injectable so the flow is testable without a real install. */
+export type InstallRunner = (command: string, args: string[], cwd: string) => Promise<void>;
+
+const spawnInstall: InstallRunner = async (command, args, cwd) => {
+  try {
+    await run(command, args, { cwd });
+  } catch (cause) {
+    throw new InternalError({
+      message: `${command} ${args.join(" ")} failed.`,
+      action: `Install the package by hand: ${command} ${args.join(" ")}.`,
+      detail: cause instanceof Error ? cause.message : String(cause),
+    });
+  }
+};
+
+export interface InstallPackageOptions {
+  /** The project root — where the lockfile lives and the install runs. */
+  projectDir: string;
+  /** The package to install, e.g. `@pithy-sh/auth`. */
+  pkg: string;
+  /** Override the spawner (tests inject a stub); defaults to the real install. */
+  run?: InstallRunner;
+}
+
+/**
+ * Install a package with the project's detected package manager. Returns the project's manager, so
+ * `pithy add` can report it. The adopter's PM is always used — Bun stays a dev-only signal, never a
+ * requirement of adoption. The manager is detected whether or not an install runs: it is a fact about
+ * the project, not a record of a spawn, and the caller only ever renders it as "run `<pm> install`".
+ *
+ * A package a linked checkout already provides is skipped ({@link alreadyProvided}), and the trade is
+ * deliberate: nothing then declares it in a `package.json`. That is the point. The only range there is
+ * to write names a version no registry has, and writing it breaks the adopter's next install — the
+ * failure `pithy ui add` used to plant on a command days away. A checkout is already outside the
+ * lockfile's world; the moment the scope publishes, the copy is a real directory and this stops firing.
+ */
+export async function installPackage(options: InstallPackageOptions): Promise<{ packageManager: PackageManager }> {
+  const packageManager = await detectPackageManager(options.projectDir);
+  if (await alreadyProvided(options.projectDir, options.pkg)) return { packageManager };
+  await (options.run ?? spawnInstall)(packageManager, installArgs(packageManager, options.pkg), options.projectDir);
+  return { packageManager };
+}
+
+export interface UninstallPackageOptions {
+  /** The project root — where the lockfile lives and the uninstall runs. */
+  projectDir: string;
+  /** The package to uninstall, e.g. `@pithy-sh/auth`. */
+  pkg: string;
+  /** Override the spawner (tests inject a stub); defaults to the real uninstall. */
+  run?: InstallRunner;
+}
+
+/** What an uninstall did: the manager it would use, and whether it actually removed anything. */
+export interface UninstallOutcome {
+  /** The project's package manager — reported whether or not an uninstall ran, like {@link installPackage}. */
+  packageManager: PackageManager;
+  /** False when the package was left alone because a linked checkout provides it. */
+  uninstalled: boolean;
+}
+
+/**
+ * Uninstall a package with the project's detected package manager — the inverse of {@link installPackage},
+ * behind `pithy remove`. Returns which manager ran, and whether anything was removed. The adopter's PM is
+ * always used.
+ *
+ * A package a linked checkout provides is **not** uninstalled ({@link alreadyProvided}), exactly as the
+ * install skips it, and the asymmetry was the bug: nothing declared the package, so there is no
+ * declaration for a remove to take out — but every manager is asked anyway, and npm answers by pruning
+ * the *whole* linked scope as extraneous. One `pithy remove auth` unlinked `secrets` and `core` out from
+ * under the same worker's config, which still imports them. `detectPackageManager` returns npm for a
+ * project with no lockfile, so that is the default path here, not an edge.
+ *
+ * The alternative was to make the caller check first. It is the same predicate the install already owns,
+ * and a guard every call site must remember is a guard one of them forgets.
+ */
+export async function uninstallPackage(options: UninstallPackageOptions): Promise<UninstallOutcome> {
+  const packageManager = await detectPackageManager(options.projectDir);
+  if (await alreadyProvided(options.projectDir, options.pkg)) return { packageManager, uninstalled: false };
+  await (options.run ?? spawnInstall)(packageManager, uninstallArgs(packageManager, options.pkg), options.projectDir);
+  return { packageManager, uninstalled: true };
+}
+
+/**
+ * Add several packages at once with the project's detected package manager — one install invocation.
+ * Used by `--eject` to promote a forked capability's runtime dependencies (`better-auth`, `zod`, …)
+ * into the project so the local copy builds without the `@pithy-sh/*` package. A no-op when the list
+ * is empty. Returns which manager ran.
+ */
+export async function promoteDependencies(
+  projectDir: string,
+  packages: string[],
+  runner?: InstallRunner,
+): Promise<{ packageManager: PackageManager }> {
+  const packageManager = await detectPackageManager(projectDir);
+  if (packages.length > 0) {
+    await (runner ?? spawnInstall)(packageManager, installArgs(packageManager, packages), projectDir);
+  }
+  return { packageManager };
+}