@pithy-sh/core 0.1.4 → 0.1.5

package/dist/version.generated.js

@@ -1,7 +1,9 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 //#region src/version.generated.ts
 /** This package's npm name — the join key against a release feed. */
 const PACKAGE_NAME = "@pithy-sh/core";
 /** This package's version, stamped from its own package.json at generation time. */
-const PACKAGE_VERSION = "0.1.4";
+const PACKAGE_VERSION = "0.1.5";
 //#endregion
 export { PACKAGE_NAME, PACKAGE_VERSION };

package/dist/worker/health.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 /**
  * **Where every Pithy Worker answers liveness — written once, read by everyone who needs it.**
  *

package/dist/worker/health.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 //#region src/worker/health.ts
 /**
 * **Where every Pithy Worker answers liveness — written once, read by everyone who needs it.**

package/dist/worker/identity.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 /**
  * What a running Worker knows about itself — the three vars every Pithy Worker is scaffolded with, and
  * the one reader for them.

package/dist/worker/identity.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 //#region src/worker/identity.ts
 /**
 * What a running Worker knows about itself — the three vars every Pithy Worker is scaffolded with, and

package/dist/workflow/bindings.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import type { BindingSpecInput } from "../capability/bindings";
 import type { RegisteredWorkflow, WorkflowSpec, WorkflowSpecMap } from "./spec";
 /**

package/dist/workflow/bindings.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 //#region src/workflow/bindings.ts
 /**
 * The one derivation from a durable job to the `workflow` binding that job needs.

package/dist/workflow/dispatch.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import type { Logger } from "../logger/logger";
 import { type LoopbackFetch } from "./loopback";
 import type { WorkflowBinding, WorkflowRegistry } from "./spec";

package/dist/workflow/dispatch.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { PithyError, messageOf } from "../error/pithyError.js";
 import "../worker/identity.js";
 import { noopLogger } from "../logger/logger.js";

package/dist/workflow/dispatchRoute.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import type { Hono } from "hono";
 import type { PithyHonoEnv } from "../capability/capability";
 import { type AmbientEnv } from "../env/ambient";

package/dist/workflow/dispatchRoute.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { ForbiddenError, PithyError } from "../error/pithyError.js";
 import { validationHook } from "../http/validation.js";
 import { WORKFLOW_DISPATCH_ROUTE, WorkflowDispatchParams, WorkflowDispatchRequest } from "./schemas.js";

package/dist/workflow/faults.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 /**
  * **Every fault that reaches a durable step is classified — retryable or terminal — at a stated site.**
  *

package/dist/workflow/faults.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { PithyError } from "../error/pithyError.js";
 import { d1TransientFault } from "../data/withD1Retry.js";
 import { encodeWorkflowStepMessage } from "./stepMessage.js";

package/dist/workflow/host.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { type WorkflowHostNameParts } from "./naming";
 import type { WorkflowRegistry } from "./spec";
 /**

package/dist/workflow/host.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { InternalError } from "../error/pithyError.js";
 import { ENVIRONMENT_VAR, PROJECT_VAR } from "../worker/identity.js";
 import { workflowHostName, workflowScriptName } from "./naming.js";

package/dist/workflow/hostEntry.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 /**
  * The default export of a Workflow host that serves nothing over HTTP (#426).
  *

package/dist/workflow/hostEntry.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { NotFoundError } from "../error/pithyError.js";
 import { HttpError } from "../error/http.js";
 //#region src/workflow/hostEntry.ts

package/dist/workflow/hostEnv.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { z } from "zod";
 import type { Logger } from "../logger/logger";
 /**

package/dist/workflow/hostEnv.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { InternalError } from "../error/pithyError.js";
 import { createWorkerLogger } from "../logger/worker.js";
 import { z } from "zod";

package/dist/workflow/loopback.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import type { WorkflowBinding } from "./spec";
 /**
  * The loopback dispatcher: the one-method dispatch seam, carried over a sibling's origin instead of

package/dist/workflow/loopback.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { UpstreamError, UpstreamTimeoutError } from "../error/pithyError.js";
 import { workflowDispatchPath } from "./schemas.js";
 //#region src/workflow/loopback.ts

package/dist/workflow/naming.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 /**
  * Every name a durable job answers to, in one module. The CLI writes these into a host worker's
  * resolved `wrangler.jsonc`, the provisioner deploys under them, and the dispatcher resolves

package/dist/workflow/naming.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { NAME_SEGMENT } from "../naming/segment.js";
 import { InternalError } from "../error/pithyError.js";
 import { NAMESPACE_LIMITS } from "../naming/limits.js";

package/dist/workflow/register.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import type { Capability } from "../capability/capability";
 import type { RegisteredWorkflow, WorkflowRegistry } from "./spec";
 /**

package/dist/workflow/register.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { InternalError } from "../error/pithyError.js";
 import { workflowKey } from "./naming.js";
 //#region src/workflow/register.ts

package/dist/workflow/schemas.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { z } from "zod";
 /**
  * The request and response contract of the host's dispatch route ({@link ./dispatchRoute.ts}).

package/dist/workflow/schemas.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import { z } from "zod";
 //#region src/workflow/schemas.ts
 /**

package/dist/workflow/spec.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 import type { z } from "zod";
 /**
  * The durable-job seam. A capability declares the Cloudflare Workflows it owns as a map of

package/dist/workflow/spec.js

@@ -0,0 +1,2 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT

package/dist/workflow/stepMessage.d.ts

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 /**
  * **The one statement of what a terminal Workflow step writes into its error text, and the one reader of it.**
  *

package/dist/workflow/stepMessage.js

@@ -1,3 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
 //#region src/workflow/stepMessage.ts
 /**
 * **The one statement of what a terminal Workflow step writes into its error text, and the one reader of it.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pithy-sh/core",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
     }
   },
   "scripts": {
-    "build": "tsdown && tsc -p tsconfig.build.json",
+    "build": "tsdown && tsc -p tsconfig.build.json && bun ../../tooling/build/src/stampDeclarations.ts",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run",
     "test:node": "vitest run --project=node",

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.1.5";