@pithy-sh/core 0.9.0 → 0.10.0

package/src/error/cause.ts

@@ -11,8 +11,12 @@
  * This module holds only what does not — the facts about the shapes a runtime hands over, and the filter
  * that decides whether one of its strings is safe to put in front of an adopter.
  *
+ * The one exception is an import that would not resolve, and it has its own module: `unresolved.ts`
+ * decides the kind and the remedy for all three surfaces, because three surfaces deciding it kept
+ * disagreeing (#709).
+ *
  * **The filter is here for the same reason the facts are, and the argument took two issues to finish.**
- * #223 moved `rootCause`, `prop` and `isBuildFailureWrapper` in and deliberately left `safeReason` beside
+ * #223 moved `rootCause` and `prop` in and deliberately left `safeReason` beside
  * the three refusals, on the reading that what a surface may say is that surface's business. That is true
  * of the sentences and false of the filter: whether a string carries a path, a stack frame or half a
  * parser's ANSI box is a property of the string, and the answer cannot differ between the CLI, a
@@ -26,11 +30,12 @@
 /**
  * Read a property off an unknown throwable without widening anything to `any`.
  *
- * Deliberately duck-typed. Bun's `ResolveMessage` and `BuildMessage` — the two shapes the CLI's `bin` and
- * the vite plugin actually catch, since both run on Bun — are their own classes and are **not**
- * `instanceof Error`. An `instanceof` gate here passes a whole suite under vitest, which runs on Node,
- * and silently drops the parser's own sentence on the runtime that ships. That is #207, and it is why
- * every reader of a cause in this kit goes through this function.
+ * Deliberately duck-typed. A cause is `unknown`, and an `instanceof Error` gate is a claim about a
+ * runtime's classes that the runtime can break. Bun did: on 1.3 its `ResolveMessage` and `BuildMessage`
+ * were **not** `instanceof Error`, so a gate passed a whole suite under vitest, which runs on Node, and
+ * silently dropped the parser's own sentence on the runtime that ships. That is #207. Bun 1.4 made both
+ * real `Error`s (measured on 1.4.2), and nothing here had to change, which is the point: every reader of
+ * a cause in this kit goes through this function and reads fields, never a class.
  *
  * Non-enumerable properties are read too — `AggregateError.errors` is one, and {@link rootCause}
  * depends on it.
@@ -49,7 +54,7 @@ export function prop(cause: unknown, key: string): unknown {
  * and only by running on Bun with a failure of the *realistic* shape.
  *
  * **And the realistic shape is the wrapped one.** A stray brace cascades — one missing `}` in a
- * `pithy.config.ts` produced four diagnostics on Bun 1.3.14 — so a syntax error arrives wrapped far more
+ * `pithy.config.ts` produces four diagnostics on Bun 1.4.2 — so a syntax error arrives wrapped far more
  * often than bare. Classified as-is, the wrapper matches nothing: not a resolution failure, not a parse
  * error, just something with a message. The refusal then says *the config threw while loading, run the
  * file directly* while holding the line and column in its hand. #207 fixed the bare case and left this
@@ -73,33 +78,6 @@ export function rootCause(cause: unknown): unknown {
   return current;
 }
 
-/** Bun's wrapper announces itself: `4 errors building "<absolute path>"`, and nothing else says that. */
-const BUILD_FAILURE = /^\d+ errors? building "/;
-
-/**
- * The wrapper **after the diagnostics are gone** — a build that failed, and that is all that is left.
- *
- * {@link rootCause} handles the first `import()`. It cannot handle the second: Bun caches a failed module
- * and re-throws an `AggregateError` with **no `errors` at all**, just the count and the path. There is
- * nothing to unwrap, so a classifier that only unwraps reads a syntax error as "it threw" from the second
- * caller onward — which is what `pithy doctor` shows an adopter, because resolving the project's account
- * loads the root config before the report does (#206, #223).
- *
- * Nothing else Bun throws degrades this way: a `ResolveMessage`, a bare `BuildMessage` and a module's own
- * `Error` are byte-identical on every import. Only the wrapper forgets.
- *
- * So the wrapper is recognized by its own message. **What it proves is narrow and worth stating:** the
- * module reached the builder and the builder produced diagnostics. It did not fail to resolve — Bun
- * throws the first `ResolveMessage` bare, wrapping nothing, even for a file with several bad imports —
- * and it did not run, so it cannot have thrown. It failed to parse or to build. A caller may say that
- * much and no more: the message itself carries an absolute path and a count, neither of which is the
- * adopter's business, so it is a *predicate* here rather than a string anyone is tempted to print.
- */
-export function isBuildFailureWrapper(cause: unknown): boolean {
-  const message = prop(cause, "message");
-  return typeof message === "string" && BUILD_FAILURE.test(message);
-}
-
 /** Escape sequences a runtime colors its diagnostics with. They are formatting, and they never travel. */
 // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping the control characters is the point.
 const ANSI = /\u001b\[[0-9;]*m/g;
@@ -139,19 +117,9 @@ export function causeMessage(cause: unknown): string | undefined {
  * developer one frame of digging, and a mistake puts a path, a source line or a stack frame in a field
  * that is rendered.
  *
- * **Provenance first, then content.** Bun's build-failure wrapper is refused outright, before a single
- * content test runs. The content tests exist for a diagnostic that *might* be safe; the wrapper never is,
- * because its whole message is a count nobody asked for and a path that must not travel. Leaving it to
- * the content tests is what leaked: `2 errors building "app/config:12:5.ts"` has no leading slash, sailed
- * through the absolute-path check, and produced *The config does not parse: 2 errors building
- * "app/config:12:5.ts". Line 12, column 5.* — a path the adopter never wrote, and a position fabricated
- * out of a file name (#223). That suppression was written three times because the filter was. It is
- * written once here, and {@link failurePosition} refuses the same shape for the same reason.
- *
  * A trailing period comes off: every caller puts this inside a sentence of its own.
  */
 export function safeReason(cause: unknown): string | undefined {
-  if (isBuildFailureWrapper(cause)) return undefined;
   const text = (causeMessage(cause) ?? "").trim();
   if (text.length === 0 || text.length > REASON_LIMIT) return undefined;
   if (text.includes("\n")) return undefined;
@@ -176,13 +144,14 @@ export interface FailurePosition {
  * path they are appended to. Whether a surface prints them is that surface's policy: two of the three
  * classifiers do, and the capability loader deliberately does not.
  *
- * Refuses Bun's build-failure wrapper on provenance, exactly as {@link safeReason} does. That message
- * holds a file name and a count and nothing about where anything failed, so a `:12:5` found in it is a
- * coincidence of the path's own characters — and a fabricated position reads as authoritative.
+ * `isOwn`, when given, is asked about the file a structured position names, and a position in a file it
+ * disowns is no position at all: Bun's line and column in a file the config imports, quoted as the config's,
+ * send the adopter to a place in their config that is fine (#709).
  */
-export function failurePosition(cause: unknown): FailurePosition | undefined {
-  if (isBuildFailureWrapper(cause)) return undefined;
+export function failurePosition(cause: unknown, isOwn?: (file: string) => boolean): FailurePosition | undefined {
   const position = prop(cause, "position");
+  const file = prop(position, "file");
+  if (isOwn !== undefined && typeof file === "string" && !isOwn(file)) return undefined;
   const line = prop(position, "line");
   const column = prop(position, "column");
   if (typeof line === "number" && line > 0 && typeof column === "number") return { line, column };
@@ -190,135 +159,3 @@ export function failurePosition(cause: unknown): FailurePosition | undefined {
   if (!match?.[1] || !match[2]) return 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.
- *
- * A recorded fact about two runtimes: Bun's `ResolveMessage` carries it as a **field**, and Node states it
- * in prose. The field is preferred wherever there is one, because the prose around it names the referrer's
- * absolute path — the specifier is the adopter's own import, the referrer is our frame.
- *
- * Whether a surface names it, and what it advises when it does, is that surface's policy and stays there.
- */
-export function unresolvedSpecifier(cause: unknown): string | undefined {
-  const field = prop(cause, "specifier");
-  if (typeof field === "string" && field.length > 0) return field;
-  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/error/payload.ts

@@ -85,6 +85,54 @@ const InvalidInputPublic = z
   })
   .describe("Input failed validation at a boundary (400).");
 
+const InputRequiredPublic = z
+  .object({
+    code: z
+      .literal("input/required")
+      .describe(
+        "A run that may not prompt reached a question with no answer. `PITHY_NONINTERACTIVE=1`, `--no-input` and `--json` each forbid a prompt; this is what one turns into, so an agent is told what to pass rather than left waiting on a question nobody will answer.",
+      ),
+    status: z.literal(400).describe("Bad Request — the call left out something it has to say."),
+    flag: z
+      .string()
+      .nullable()
+      .describe(
+        "The flag that answers the question, as it is typed (`--worker`). `null` when no flag can: only a person, or a document piped to stdin, answers it.",
+      ),
+    choices: z
+      .array(z.string().describe("One value the flag takes."))
+      .optional()
+      .describe("Every value the flag takes, when the set is known. Absent when it is open, such as a name."),
+    ...publicFields,
+  })
+  .describe("A run that may not prompt needed an answer it was not given (400).");
+
+const PreconditionFailedPublic = z
+  .object({
+    code: z
+      .literal("core/precondition_failed")
+      .describe(
+        "The call is well formed, and the state it needs is not there yet: no credentials, an environment that is not provisioned, a resource nothing has created. Distinct from `validation/invalid_input` because the remedy is a different step run first, not a different call.",
+      ),
+    status: z.literal(412).describe("Precondition Failed — the request is valid, and what it depends on is missing."),
+    ...publicFields,
+  })
+  .describe("The state this request depends on is not there yet (412).");
+
+const PersonRequiredPublic = z
+  .object({
+    code: z
+      .literal("core/person_required")
+      .describe(
+        "The step is one only a person may take: a typed confirmation phrase, or a command that is manual by design. Distinct from `input/required` because no flag value an automated caller could choose is the right answer — the right move is to stop and ask.",
+      ),
+    status: z
+      .literal(403)
+      .describe("Forbidden — the caller may not take this step for a person, however the call is phrased."),
+    ...publicFields,
+  })
+  .describe("A step only a person may take (403).");
+
 const InvalidTokenPublic = z
   .object({
     code: z.literal("auth/invalid_token").describe("The bearer/session credential is missing, expired, or invalid."),
@@ -1555,6 +1603,9 @@ const TestersNotConfiguredPublic = z
 export const KitPublicErrorPayload = z
   .discriminatedUnion("code", [
     InvalidInputPublic,
+    InputRequiredPublic,
+    PreconditionFailedPublic,
+    PersonRequiredPublic,
     InvalidTokenPublic,
     ForbiddenPublic,
     AuthProviderUnavailablePublic,
@@ -1690,6 +1741,11 @@ export const KitPublicErrorPayload = z
 // The full members: each public member plus the operator-only `action` and `detail`. Built as explicit consts
 // (not mapped) so the `code`-literal discriminated-union types survive for `Extract` narrowing.
 const InvalidInput = InvalidInputPublic.extend(internalFields).describe(InvalidInputPublic.description ?? "");
+const InputRequired = InputRequiredPublic.extend(internalFields).describe(InputRequiredPublic.description ?? "");
+const PreconditionFailed = PreconditionFailedPublic.extend(internalFields).describe(
+  PreconditionFailedPublic.description ?? "",
+);
+const PersonRequired = PersonRequiredPublic.extend(internalFields).describe(PersonRequiredPublic.description ?? "");
 const InvalidToken = InvalidTokenPublic.extend(internalFields).describe(InvalidTokenPublic.description ?? "");
 const Forbidden = ForbiddenPublic.extend(internalFields).describe(ForbiddenPublic.description ?? "");
 const AuthProviderUnavailable = AuthProviderUnavailablePublic.extend(internalFields).describe(
@@ -2053,6 +2109,9 @@ const SupportReplyFailed = SupportReplyFailedPublic.extend(internalFields).descr
 export const KitErrorPayload = z
   .discriminatedUnion("code", [
     InvalidInput,
+    InputRequired,
+    PreconditionFailed,
+    PersonRequired,
     InvalidToken,
     Forbidden,
     AuthProviderUnavailable,

package/src/error/pithyError.ts

@@ -61,6 +61,82 @@ export class ValidationError extends PithyError {
   }
 }
 
+/**
+ * A run that may not prompt reached a question nobody gave it the answer to (#697).
+ *
+ * `flag` is the flag that answers it, or `null` when no flag can — a person, or a document on stdin, is
+ * the only answer. `choices` is every value the flag takes when that set is known, and is left off the
+ * payload rather than written empty when it is not: an empty list would claim the flag takes nothing.
+ */
+export class InputRequiredError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "input/required" }>;
+
+  constructor(
+    args: ErrorArgs & { flag?: string | null; choices?: readonly string[] } = {},
+    options?: { cause?: unknown },
+  ) {
+    super(
+      {
+        code: "input/required",
+        status: 400,
+        message: args.message ?? "An answer is required, and this run may not ask for it.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+        flag: args.flag ?? null,
+        ...(args.choices === undefined ? {} : { choices: [...args.choices] }),
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * The call is well formed, and what it depends on is not there yet (#697): no credentials, an environment
+ * nothing has provisioned. A separate class from {@link ValidationError} because the remedy is a step to
+ * run first, not a different call — the CLI exits 3 for it and 2 for a validation failure.
+ */
+export class PreconditionFailedError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/precondition_failed" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/precondition_failed",
+        status: 412,
+        message: args.message ?? "Something this needs is not set up yet.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+/**
+ * A step only a person may take (#697): a typed confirmation phrase, or a command that is manual by
+ * design. Not {@link InputRequiredError}, which names a flag an automated caller can pass — here no value
+ * a caller could choose is the right answer, and the CLI exits 5 so an agent stops and asks.
+ */
+export class PersonRequiredError extends PithyError {
+  declare readonly payload: Extract<ErrorPayload, { code: "core/person_required" }>;
+
+  constructor(args: ErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "core/person_required",
+        status: 403,
+        message: args.message ?? "Only a person may take this step.",
+        action: args.action,
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
 export class UnauthorizedError extends PithyError {
   declare readonly payload: Extract<ErrorPayload, { code: "auth/invalid_token" }>;