@pithy-sh/core 0.1.4 → 0.2.0

package/src/capability/manifest.ts

@@ -281,6 +281,25 @@ export function renderConfigOptionComment(describe: string, indent: string): str
   return `${indent}// ${describe}`;
 }
 
+/**
+ * The line a writer puts in `pithy.config.ts` for a **seam** — the option a capability takes that is a
+ * function, so no renderer can ever state its value.
+ *
+ * Shorthand (`resolveSubject,`) rather than `key: value`, because the two are the same identifier: the
+ * scaffolded module exports the name the factory takes, and a config that spelled it twice would invite
+ * an adopter to rename one half of it.
+ *
+ * **It takes the seam's key and nothing else.** That is the same closed-set argument
+ * {@link CONFIG_CONSTANTS} makes one function up, and it has to be made again here for a stronger
+ * reason: a constant is one identifier in an expression position, and a seam is an identifier *plus* an
+ * import statement plus a file written into the adopter's repository. A manifest states which seam, by a
+ * key this package enumerates; every character that reaches the adopter's TypeScript comes from
+ * {@link CONFIG_SEAMS}.
+ */
+export function renderConfigSeamLine(seam: ConfigSeam, indent: string): string {
+  return `${indent}${CONFIG_SEAMS[seam].binding},`;
+}
+
 /**
  * A capability's own name, as generated source carries it.
  *
@@ -439,6 +458,53 @@ export const ConfigConstant = z
   .describe("A constant the scaffolded pithy.config.ts defines, named from a closed set rather than spelled out.");
 export type ConfigConstant = z.infer<typeof ConfigConstant>;
 
+/** One seam a capability takes: what `pithy add` writes for it, and what the config then references. */
+export interface ConfigSeamSpec {
+  /** The identifier the scaffolded module exports, and the key the capability's factory takes for it. */
+  readonly binding: string;
+  /** The module `pithy add` writes, relative to the Worker's own directory. */
+  readonly module: string;
+  /** How that module is imported from the Worker's `pithy.config.ts`. */
+  readonly specifier: string;
+  /** The comment written above the seam's line, saying what the adopter still owes it. */
+  readonly describe: string;
+}
+
+/**
+ * The seams `pithy add` knows how to scaffold — a capability option whose value is **behavior**, named
+ * from a closed set exactly as {@link CONFIG_CONSTANTS} names an identifier.
+ *
+ * A missing *value* has always been scaffoldable: `pithy add secrets` writes an empty registry and the
+ * project still loads, because an empty registry is a valid empty state. A missing *behavior* was not,
+ * so `payments`' `billingSubject: "organization"` was refused outright — and its remedy routed through
+ * `--set billingSubject=user`, a value that is untrue for every project that wanted the other one (#500).
+ *
+ * What makes the behavior scaffoldable is that the scaffold is **not a stub that answers**. A resolver
+ * returning nothing composes cleanly and then denies every gate, which is indistinguishable from a
+ * customer who has not paid. The module written here is branded as unimplemented by the capability that
+ * owns it, and that capability refuses the Worker's entrypoint while the brand is still on it — so the
+ * adopter says what they mean, gets the file and the signature, and the project still refuses to boot
+ * until they have written the one thing only they can write.
+ *
+ * One entry today. Every string in it is this package's, because all four of them reach the adopter's
+ * repository unquoted: an identifier, a path, an import specifier, a comment.
+ */
+export const CONFIG_SEAMS = {
+  paymentsSubject: {
+    binding: "resolveSubject",
+    module: "src/billing/subject.ts",
+    specifier: "./src/billing/subject",
+    describe:
+      "Which organization this caller is acting for. Scaffolded unimplemented — this Worker refuses to boot until src/billing/subject.ts answers it.",
+  },
+} as const satisfies Record<string, ConfigSeamSpec>;
+
+/** Which scaffolded seam a choice needs, by key. */
+export const ConfigSeam = z
+  .enum(Object.keys(CONFIG_SEAMS) as [keyof typeof CONFIG_SEAMS])
+  .describe("A seam pithy add knows how to scaffold, named from a closed set rather than described.");
+export type ConfigSeam = z.infer<typeof ConfigSeam>;
+
 export const ConfigOption = z
   .object({
     key: z
@@ -467,6 +533,11 @@ export const ConfigOption = z
       .describe(
         "Choices `pithy add` must refuse, each mapped to the sentence telling the adopter what to do instead — a value whose composition needs a seam only they can write. `pithy add` renders JSON into `pithy.config.ts`; it cannot render a function, so a choice whose validity depends on one is a choice it can write and the kit will then refuse to load. `payments`' `billingSubject: \"organization\"` is the one: it requires a `resolveSubject` saying which organization a caller acts for, deliberately has no default because a capability that guessed would key a company's plan to whoever signed in first, and so a config carrying the choice without the seam is refused at assembly — bricking every later command in the project, since they all begin by loading the config (#483). Refusing the choice up front costs the adopter one hand-edit; writing it costs them the project.",
       ),
+    choicesNeedingSeam: manifestRecord(z.record(PrintableString, ConfigSeam))
+      .optional()
+      .describe(
+        "Choices `pithy add` writes **together with the code they need** — the other half of `choicesNeedingCode`, for a choice whose missing half the kit can scaffold. Each names a seam from `CONFIG_SEAMS`; `pithy add` writes that module into the Worker, imports it, and passes it to the capability's factory beside the choice. `payments`' `billingSubject: \"organization\"` is the one: reaching it used to mean passing `--set billingSubject=user`, a value that is wrong for the project, and then hand-editing both halves (#500). The scaffolded module is deliberately **not** a working stub — it is branded unimplemented, and the capability refuses the Worker's entrypoint while the brand is on it, because a resolver that answers nothing denies every gate and reads exactly like a customer who has not paid. A choice states this or `choicesNeedingCode`, never both: one is a refusal and the other is a scaffold.",
+      ),
     constant: ConfigConstant.optional().describe(
       "A constant the scaffolded pithy.config.ts defines, rendered *unquoted* in place of `default` when the target config declares it. The one that exists is `publicOrigin` — `PUBLIC_ORIGIN`, this Worker's address for the environment it composes in. An option whose value is an origin must name it rather than state a URL, because a URL written down is production's URL written into staging: it is what mailed staging's testers magic links into production and unsubscribed them there (#256). `default` is still required *for such an option* and is what a config with no such constant gets, so an older project is never handed an identifier it does not define — the one place the absent-default rule does not reach, and it is checked rather than trusted.",
     ),
@@ -506,6 +577,29 @@ export const ConfigOption = z
         });
       }
     }
+    // The same rule the line above holds `choicesNeedingCode` to, for the same reason: a seam keyed on a
+    // value this option does not offer never fires, and the choice is written with no seam beside it.
+    for (const choice of Object.keys(option.choicesNeedingSeam ?? {})) {
+      if (!option.choices?.includes(choice)) {
+        ctx.issues.push({
+          code: "custom",
+          input: choice,
+          path: ["choicesNeedingSeam", choice],
+          message: `A choice needing a seam must be one this option offers, and ${JSON.stringify(choice)} is not — ${option.key} offers ${JSON.stringify(option.choices ?? [])}.`,
+        });
+      }
+      // Refused *and* scaffolded is not a state with an answer. `pithy add` reads one map to decide
+      // whether to stop and the other to decide what to write, so a choice in both would be refused by
+      // the first reader and the second would never run — a scaffold declared and silently never written.
+      if (option.choicesNeedingCode?.[choice] !== undefined) {
+        ctx.issues.push({
+          code: "custom",
+          input: choice,
+          path: ["choicesNeedingSeam", choice],
+          message: `A choice is refused or scaffolded, never both, and ${option.key} states ${JSON.stringify(choice)} in choicesNeedingCode and choicesNeedingSeam alike.`,
+        });
+      }
+    }
     if (option.constant !== undefined && option.default === undefined) {
       ctx.issues.push({
         code: "custom",

package/src/createEntrypoint.ts

@@ -80,6 +80,11 @@ export function createEntrypoint<
   const all: Capability[] = options.app ? [...options.capabilities, options.app] : [...options.capabilities];
   const handlers: CapabilityEmailHandler[] = all.flatMap((cap) => (cap.email ? [cap.email] : []));
 
+  // The last gate before this Worker can take a request, and the first one the CLI never reaches: only a
+  // Worker's own entry calls `createEntrypoint`, while `createBackend` is assembled by tooling too. A
+  // capability that must load for the adopter's toolchain and must not serve refuses here (#500).
+  for (const cap of all) cap.boot?.({ capabilities: all });
+
   const registry = composeWorkflows(all);
   const scheduled = scheduledWorkflows(registry);
 

package/src/error/cause.ts

@@ -191,6 +191,63 @@ export function failurePosition(cause: unknown): FailurePosition | undefined {
   return { line: Number(match[1]), column: Number(match[2]) };
 }
 
+/** What kind of thing failed to resolve. Three causes that wore one sentence until #489. */
+export type UnresolvedKind =
+  /** A bare specifier for a package that is not installed. Installing dependencies is the remedy. */
+  | "package"
+  /** An installed package asked for a subpath it does not provide. Installing again changes nothing. */
+  | "package-subpath"
+  /** A relative import of a file in the project's own tree. Installing again changes nothing. */
+  | "local-file";
+
+/** Whether a path sits inside an installed package. */
+function insideNodeModules(path: string): boolean {
+  return path.split(/[\\/]/).includes("node_modules");
+}
+
+/**
+ * Which of the three unresolved-import causes this was, or `undefined` when it cannot be told.
+ *
+ * **The discriminator was already in the message and was being thrown away.** `unresolvedSpecifier`
+ * matches `Cannot find (?:package|module)` — and `package` versus `module` is exactly the fact that
+ * separates a missing dependency from the other two. It sat in a non-capturing group, so every cause
+ * arrived wearing one sentence, and for two of the three that sentence advised an install which is
+ * *guaranteed* to change nothing. That is #489's class exactly: guidance a caller cannot follow, worst
+ * for the caller it is written for, which has no human to shrug and try something else.
+ *
+ * Measured across Node 24.13.0 and Bun 1.3.14, because the two runtimes hand back different halves and
+ * each hands back exactly one usable one:
+ *
+ * | cause | Node says | Bun's `specifier` |
+ * |---|---|---|
+ * | package absent | `Cannot find package 'pkg'`, no `url` | `pkg` |
+ * | subpath missing | `Cannot find module '/abs/node_modules/pkg/src/nope.js'`, `url` under node_modules | `pkg/src/nope` |
+ * | adopter's file | `Cannot find module '/abs/apps/board/src/x'`, `url` outside node_modules | `./src/x` |
+ *
+ * Bun gives the **specifier as written**, so a leading `.` settles it. Node gives the **already-resolved
+ * path**, where being under `node_modules` settles it. Neither read works on both runtimes; the pair
+ * does, and it is the same predicate — *is this inside node_modules* — applied to whichever fact the
+ * runtime supplied.
+ */
+export function unresolvedKind(cause: unknown): UnresolvedKind | undefined {
+  if (/Cannot find package /.test(causeMessage(cause) ?? "")) return "package";
+
+  const specifier = unresolvedSpecifier(cause);
+  if (specifier === undefined) return undefined;
+
+  // Bun's field is the specifier as written: relative means the adopter's own file.
+  if (/^(?:\.|\/|[A-Za-z]:[\\/])/.test(specifier)) {
+    return insideNodeModules(specifier) ? "package-subpath" : "local-file";
+  }
+
+  // Node states an already-resolved absolute path; a bare specifier reaching here is a package subpath.
+  const url = prop(cause, "url");
+  if (typeof url === "string" && url.length > 0) {
+    return insideNodeModules(url) ? "package-subpath" : "local-file";
+  }
+  return "package-subpath";
+}
+
 /**
  * The specifier that did not resolve.
  *
@@ -206,3 +263,62 @@ export function unresolvedSpecifier(cause: unknown): string | undefined {
   const match = /Cannot find (?:package|module) ['"]([^'"]+)['"]/.exec(causeMessage(cause) ?? "");
   return match?.[1];
 }
+
+/** A package name as npm allows one: an optional `@scope/`, and never a store's dot-directory. */
+const PACKAGE_NAME = /^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*$/i;
+
+/**
+ * The file the failing import was written in, as the runtime named it. **Module-private on purpose**: it
+ * is an absolute path, and {@link importingPackage} exists to make sure only its package half leaves here.
+ */
+function importerPath(cause: unknown): string | undefined {
+  const field = prop(cause, "referrer");
+  if (typeof field === "string" && field.length > 0) return field;
+  const message = causeMessage(cause) ?? "";
+  // Node ends its sentence with the path, so it is taken to the end of the line — a directory may
+  // contain a space. Bun quotes it when it states one in prose, and always carries the field as well.
+  return (/ imported from (.+)$/.exec(message) ?? /\bfrom ['"]([^'"]+)['"]/.exec(message))?.[1];
+}
+
+/**
+ * The package whose own source contained the import that did not resolve — **never a path**.
+ *
+ * {@link unresolvedSpecifier} answers *what* did not resolve. This answers *where the import lives*, and
+ * the two are different facts whenever the failing import is not the adopter's own. #480 is that case
+ * verbatim: `pithy add email` on a fresh project refused with
+ *
+ * > Nothing resolves "@pithy-sh/core/src/capability/capability".
+ *
+ * while `@pithy-sh/core` resolved from the Worker at every step of the run, before and after. The
+ * specifier was honest — the runtime really could not resolve it — but the import belonged to
+ * `@pithy-sh/email`, which had just been installed and was the package genuinely not linked. So the
+ * refusal named the one dependency that was definitely fine, and an adopter following it ran `bun
+ * install` against a tree that already had core in it. The importer is the half that would have pointed
+ * at `email`, and both runtimes hand it over: **Bun's `ResolveMessage` carries `referrer` as a field**
+ * (measured on 1.3.14) and Node states it in prose as `imported from <path>`.
+ *
+ * **A package name, or nothing.** The referrer is an absolute path — our frame, and the reason
+ * {@link unresolvedSpecifier} drops the prose around the specifier — so what travels is the one part of
+ * it that is not a path: the package directory it sits under. A referrer outside `node_modules` is the
+ * adopter's own file, and there is nothing to say about it that the refusal does not already say by
+ * naming the config, so it answers `undefined` rather than a path. The path itself is never returned
+ * from this module, which is what makes leaking it impossible rather than merely discouraged.
+ *
+ * The **last** `node_modules` in the path, because every store layout nests: pnpm's
+ * `node_modules/.pnpm/<id>/node_modules/<pkg>` and Bun's isolated linker's
+ * `node_modules/.bun/<pkg>@<version>/node_modules/<pkg>` (both measured) put the real owner last, and so
+ * does an ordinary nested install. The name is then checked against what npm allows, so a store's own
+ * bookkeeping directory (`.bun`, `.pnpm`, `hono@4.6.3`) can only ever answer nothing.
+ *
+ * Whether a surface names it, and what it advises when it does, is that surface's policy and stays there.
+ */
+export function importingPackage(cause: unknown): string | undefined {
+  const referrer = importerPath(cause);
+  if (referrer === undefined) return undefined;
+  const segments = referrer.split(/[\\/]/);
+  const at = segments.lastIndexOf("node_modules");
+  const head = at === -1 ? undefined : segments[at + 1];
+  if (head === undefined) return undefined;
+  const name = head.startsWith("@") ? `${head}/${segments[at + 2] ?? ""}` : head;
+  return PACKAGE_NAME.test(name) ? name : undefined;
+}

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 export const PACKAGE_NAME = "@pithy-sh/core";
 
 /** This package's version, stamped from its own package.json at generation time. */
-export const PACKAGE_VERSION = "0.1.4";
+export const PACKAGE_VERSION = "0.2.0";