@pithy-sh/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pithy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@pithy-sh/cli",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pithy-sh/pithy.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "pithy": "./src/bin.ts"
+  },
+  "exports": {
+    "./src/*": "./src/*.ts"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "templates",
+    "!src/**/*.test.*"
+  ],
+  "scripts": {
+    "prepack": "bun scripts/vendorTemplate.ts",
+    "postpack": "bun scripts/vendorTemplate.ts --clean",
+    "pack:verify": "bun scripts/verifyPack.ts",
+    "build": "tsc -p tsconfig.json --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.contract.json && tsc -p scripts/tsconfig.json && tsc -p tsconfig.ciScripts.json",
+    "test": "vitest run",
+    "test:node": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "clean": "rm -rf dist .turbo",
+    "reset": "bun run clean && rm -rf node_modules"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@cloudflare/workers-types": "^5.20260729.1",
+    "@pithy-sh/cloudflare": "workspace:*",
+    "@pithy-sh/core": "workspace:*",
+    "@pithy-sh/email": "workspace:*",
+    "@pithy-sh/secrets": "workspace:*",
+    "@pithy-sh/turnstile": "workspace:*",
+    "@pithy-sh/ui-react": "workspace:*",
+    "citty": "^0.2.2",
+    "comment-json": "^5.0.0",
+    "kysely": "^0.29.0",
+    "miniflare": "^4.20260722.1",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@pithy-sh/audit": "workspace:*",
+    "@pithy-sh/auth": "workspace:*",
+    "@pithy-sh/i18n": "workspace:*",
+    "@pithy-sh/media": "workspace:*",
+    "@pithy-sh/payments": "workspace:*",
+    "@pithy-sh/storage": "workspace:*",
+    "@pithy-sh/support": "workspace:*",
+    "@pithy-sh/testers": "workspace:*",
+    "@pithy-sh/tsconfig": "workspace:*",
+    "@pithy-sh/vector": "workspace:*",
+    "@types/node": "^22.15.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "rolldown": "^1.2.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.0",
+    "wrangler": "^4.115.0",
+    "zod": "^4.0.0"
+  }
+}

package/scripts/templateManifest.ts

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * What the published `@pithy-sh/cli` is allowed to carry from the starter template, and where it comes from.
+ *
+ * Side-effect free, because two scripts need the same answer: `vendorTemplate.ts` copies the allowlist in,
+ * `verifyPack.ts` checks the tarball against it. One definition, or the check agrees with the copy by
+ * coincidence.
+ */
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { committedFiles } from "../src/project/templateFiles";
+
+/** `packages/cli`. */
+export const CLI_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The repo root's starter — the single copy. Present in a checkout, absent in an installed package. */
+export const SOURCE = resolve(CLI_DIR, "../../templates/starter");
+
+/** Where `prepack` puts it, and the only path `files` carries. */
+export const TEMPLATES_DIR = resolve(CLI_DIR, "templates");
+
+/** The template's path inside the package, and inside the tarball under `package/`. */
+export const VENDORED = "templates/starter";
+
+/**
+ * The starter's committed files, relative to `source`, sorted. **The allowlist.**
+ *
+ * {@link committedFiles} is the allowlist itself, and it lives in `src/` because `pithy init` reads it
+ * too: the packer decides what a published tarball carries, and the scaffold decides what an adopter's
+ * new project carries, and both were reading the same directory by different rules. `.dev.vars` got past
+ * `files` into the tarball (#145) and past `cp` into an adopter's project (#152) — one defect, two
+ * readers, and fixing the packer alone left the worse half open.
+ *
+ * What is not shared is the answer to "no index". Here it is fatal: a tarball built from a working tree
+ * is exactly what the allowlist exists to prevent, so a pack outside a checkout must stop. `pithy init`
+ * carries on, because an installed CLI has a vendored copy and no `.git` to ask.
+ */
+export function templateFiles(source: string): string[] {
+  const files = committedFiles(source);
+  if (files === null) {
+    throw new Error(
+      `Could not read the git index at ${source}, or nothing under it is committed. Pack from a checkout, with git available.`,
+    );
+  }
+  return files;
+}

package/scripts/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  // A third program, for the same reason `tsconfig.contract.json` is a second one: these files are
+  // outside `src`, so the package's own tsconfig — `rootDir: "src"` — cannot include them without
+  // moving its emit root. They were therefore in no program at all, and the script that decides
+  // whether a published CLI can run its first command was never typechecked. `bun` ran it anyway.
+  //
+  // Node only. Nothing here executes in a Worker; it runs on the machine doing the packing.
+  //
+  // `rootDir` is the package, not this directory, so one module under `src` can be shared with the
+  // scaffold that reads the same starter directory the packer does — `src/project/templateFiles.ts`.
+  // The rule it holds is "what git has committed here", and duplicating it is how the packer and
+  // `pithy init` came to disagree about `.dev.vars`.
+  //
+  // Only that one file crosses, and only in this direction. `src` roots at `src`, so a module there
+  // importing a script is `TS6059`; a script importing `src` is fine as long as the module it reaches
+  // has no project imports of its own. That one has none — `node:child_process` and `node:path` — so
+  // nothing of the CLI's graph, and none of its Workers types, arrives in this program behind it.
+  // `include` still names only this directory: the shared module joins through the import, as a leaf.
+  "extends": "@pithy-sh/tsconfig/base.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "lib": ["ES2022"],
+    "types": ["node"]
+  },
+  "include": ["**/*.ts"]
+}

package/scripts/vendorTemplate.ts

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Vendor the starter template into the package for publication, and take it out again after.
+ *
+ * `templates/starter` lives at the repo root — one copy, read by the CLI and by the tests that hold
+ * the template to the kit's rules. That path is outside `packages/cli`, so `npm pack` never saw it and
+ * a published `@pithy-sh/cli` shipped no template at all. `prepack` copies it in, `postpack --clean`
+ * removes it, and `files` in the manifest carries it into the tarball. The copy is never committed:
+ * two copies of the starter is the failure mode this avoids, not the one it introduces.
+ *
+ * What gets copied is the allowlist in `templateManifest.ts`, file by file — never the directory. A
+ * recursive copy published the maintainer's working tree, `.dev.vars` included.
+ *
+ * Run by the packer, so it fails loudly. A silent no-op here publishes a CLI whose first command cannot
+ * run. `verifyPack.ts` is the post-condition on the artefact, for the packs this hook never sees.
+ */
+
+import { copyFile, lstat, mkdir, readdir, rm, stat } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { SOURCE, TEMPLATES_DIR, templateFiles } from "./templateManifest";
+
+const TARGET = join(TEMPLATES_DIR, "starter");
+
+/** Every file under `dir`, relative to it, sorted, with `/` separators. */
+async function walk(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { recursive: true, withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => relative(dir, join(entry.parentPath, entry.name)).split(sep).join("/"))
+    .sort();
+}
+
+async function vendor(): Promise<void> {
+  const files = templateFiles(SOURCE);
+  await rm(TEMPLATES_DIR, { recursive: true, force: true });
+  try {
+    for (const file of files) {
+      const from = join(SOURCE, file);
+      // Regular files only. A symlink in the tarball resolves inside the adopter's `node_modules`, and a
+      // committed one aimed out of the template would copy whatever it points at.
+      if (!(await lstat(from)).isFile()) throw new Error(`${from} is not a regular file. The template ships files.`);
+      const to = join(TARGET, file);
+      await mkdir(dirname(to), { recursive: true });
+      await copyFile(from, to);
+    }
+    // The post-condition, checked rather than assumed: what landed is the allowlist, exactly.
+    const copied = await walk(TARGET);
+    if (copied.join("\n") !== files.join("\n")) {
+      throw new Error(`Vendored ${TARGET} does not match the git index:\n  got ${copied.join(", ")}`);
+    }
+    // stderr, not stdout: `npm pack --json` splices a script's stdout into the JSON it prints.
+    process.stderr.write(`Vendored ${files.length} committed template files into ${TARGET}\n`);
+  } catch (error) {
+    // A half-copied `templates/` outlives the failed pack, is gitignored, and then shadows the repo root
+    // for every later run in this checkout. Leave nothing.
+    await rm(TEMPLATES_DIR, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+/**
+ * True in a checkout, false in an installed package.
+ *
+ * `files` ships `scripts/` now, because a published manifest naming `prepack` and `postpack` has to carry
+ * what they run. So both hooks can fire inside somebody's `node_modules` — where the repo-root template
+ * does not exist and `templates/starter` is already in place. There, both are no-ops. The clean hook
+ * especially: deleting the template out of an installed package is the defect this file exists to prevent.
+ */
+async function inCheckout(): Promise<boolean> {
+  return (await stat(SOURCE).catch(() => null))?.isDirectory() === true;
+}
+
+if (!(await inCheckout())) {
+  if (!(await stat(join(TARGET, "package.json")).catch(() => null))?.isFile()) {
+    throw new Error(`No starter template at ${SOURCE} and none vendored at ${TARGET}. This install is broken.`);
+  }
+  process.stderr.write(`Template already in place at ${TARGET}. Nothing to do.\n`);
+} else if (process.argv.includes("--clean")) {
+  await rm(TEMPLATES_DIR, { recursive: true, force: true });
+} else {
+  await vendor();
+}

package/scripts/verifyPack.ts

@@ -0,0 +1,88 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Hold a `@pithy-sh/cli` tarball to what it must contain, and fail the pack when it does not.
+ *
+ * `files` does not fail on a missing path. Pack with scripts disabled — `npm pack --ignore-scripts`, or
+ * any publish path that turns lifecycle hooks off — and `prepack` never vendors the starter, `templates`
+ * matches nothing, and the tarball ships with no template at all: silently, exit 0. That is a straight
+ * regression to the defect this whole mechanism was built to close, and the mechanism itself could not
+ * detect it, because the only check lived inside the hook that did not run.
+ *
+ * This is that missing post-condition, and it sits on the artefact rather than on the hook. Nothing our
+ * manifest declares can execute during a pack that refuses to execute scripts — so the check has to be a
+ * separate step, run by CI on every commit and by whatever publishes, on the exact file it is about to
+ * push. `bun run pack:verify` packs and checks; `bun run pack:verify <tarball>` checks one already built.
+ *
+ *   packages/cli $ bun run pack:verify
+ *   packages/cli $ bun run pack:verify ../../pithy-sh-cli-1.2.3.tgz
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CLI_DIR, SOURCE, templateFiles, VENDORED } from "./templateManifest";
+
+/** Everything the tarball holds, relative to the package root, `/`-separated and sorted. */
+function entries(tarball: string): string[] {
+  const listed = execFileSync("tar", ["-tzf", tarball], { encoding: "utf8" });
+  return listed
+    .split("\n")
+    .filter((line) => line.length > 0 && !line.endsWith("/"))
+    .map((line) => line.replace(/^package\//, ""))
+    .sort();
+}
+
+function verify(tarball: string): string[] {
+  const packed = entries(tarball);
+  const expected = templateFiles(SOURCE).map((file) => `${VENDORED}/${file}`);
+  const faults: string[] = [];
+
+  const shipped = packed.filter((file) => file.startsWith("templates/"));
+  const missing = expected.filter((file) => !shipped.includes(file));
+  const extra = shipped.filter((file) => !expected.includes(file));
+  if (missing.length > 0) {
+    faults.push(`${missing.length} template file(s) missing — pithy init cannot run:\n  ${missing.join("\n  ")}`);
+  }
+  // The security half. A tarball is published once and cannot be unpublished.
+  if (extra.length > 0) {
+    faults.push(`${extra.length} file(s) under templates/ that are not committed:\n  ${extra.join("\n  ")}`);
+  }
+
+  const tests = packed.filter((file) => file.startsWith("src/") && file.endsWith(".test.ts"));
+  if (tests.length > 0) faults.push(`${tests.length} of the CLI's own test file(s) shipped.`);
+
+  // `prepack` and `postpack` run wherever the package sits, an adopter's `node_modules` included.
+  const referenced = new Set<string>();
+  const manifest = JSON.parse(readFileSync(join(CLI_DIR, "package.json"), "utf8")) as {
+    scripts?: Record<string, string>;
+  };
+  for (const command of Object.values(manifest.scripts ?? {})) {
+    for (const match of command.matchAll(/(?:^|\s)(scripts\/[\w./-]+\.ts)/g)) referenced.add(match[1] as string);
+  }
+  const absent = [...referenced].filter((file) => !packed.includes(file)).sort();
+  if (absent.length > 0)
+    faults.push(`the manifest runs script(s) the tarball does not carry:\n  ${absent.join("\n  ")}`);
+
+  return faults;
+}
+
+const given = process.argv[2];
+const workDir = mkdtempSync(join(tmpdir(), "pithy-verify-pack-"));
+try {
+  let tarball = given;
+  if (tarball === undefined) {
+    tarball = join(workDir, "cli.tgz");
+    execFileSync("bun", ["pm", "pack", "--quiet", "--filename", tarball], { cwd: CLI_DIR, stdio: "inherit" });
+  }
+  const faults = verify(tarball);
+  if (faults.length > 0) {
+    process.stderr.write(`${tarball} is not publishable.\n\n${faults.join("\n\n")}\n`);
+    process.exit(1);
+  }
+  process.stderr.write(`${tarball} checks out.\n`);
+} finally {
+  rmSync(workDir, { recursive: true, force: true });
+}