@c9up/goldstone 0.0.0-stage → 0.1.0

package/dist/vendor/nativeBinary.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Every `platform-arch` a binary is built for.
+ *
+ * For the message a package raises when it refuses: "no binary for
+ * linux-riscv64" is only actionable next to the list of what there IS.
+ */
+export declare function supportedTargets(): readonly string[];
+/** The suffix a given `platform-arch` builds under, or `undefined`. */
+export declare function nativeTargetSuffix(target: string): string | undefined;
+/** The suffix for THIS platform, or `undefined` where no binary is built. */
+export declare function nativeBinarySuffix(): string | undefined;
+/**
+ * Why the binary is not there, phrased for whoever has to fix it.
+ *
+ * "not found" and "not built for your platform" call for different actions,
+ * and a single "unavailable" leaves the reader to guess which one they are
+ * looking at.
+ */
+export declare function unavailableReason(cause?: unknown): string;
+/**
+ * `musl` builds under a different suffix, and the failure is otherwise
+ * baffling: the file is there, and `require` still refuses it. Worth saying so
+ * in a message rather than leaving a reader to discover glibc.
+ */
+export declare function muslHint(): string;
+/** What a load attempt did, so the caller can apply its own policy. */
+export type NativeBinaryResult<T> = {
+    loaded: true;
+    binary: T;
+} | {
+    loaded: false;
+    suffix: string | undefined;
+    cause?: unknown;
+};
+/**
+ * The names among `names` that `value` does not carry as functions.
+ *
+ * Classes count, being functions, and so does a class's static member: `value`
+ * may itself be a function. What a guard rejects is only useful named, so the
+ * loader reports this list rather than a bare "no".
+ */
+export declare function missingFunctions(value: unknown, names: readonly string[]): string[];
+/**
+ * Whether `value` carries every one of `names` as a function.
+ *
+ * The building block of the guard a package hands to `loadNativeBinary`, over
+ * the list of what it actually calls on its binary — the same list it passes
+ * as `expects`, so the message can name what is missing.
+ */
+export declare function hasFunctions(value: unknown, names: readonly string[]): value is object;
+/**
+ * Load `<package root>/index.<suffix>.node`, and check it is the binary the
+ * package calls.
+ *
+ * The path is fixed rather than passed: this file is generated into
+ * `<package>/src/vendor/`, so the package root is always two levels up, from
+ * `src` and from `dist` alike.
+ *
+ * `isBinary` is the package's own check of what it calls. A declaration only
+ * says what the Rust promises: a stale build, or one from another version,
+ * loads just as well and then fails on the first missing call, far from here.
+ * A rejected module is reported as a failed load, so the package's policy
+ * (degrade or refuse) applies to it unchanged. `expects`, the list the guard is
+ * built from, lets that report name the missing calls.
+ */
+export declare function loadNativeBinary<T>(isBinary: (value: unknown) => value is T, expects?: readonly string[]): NativeBinaryResult<T>;
+//# sourceMappingURL=nativeBinary.d.ts.map

package/dist/vendor/nativeBinary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeBinary.d.ts","sourceRoot":"","sources":["../../src/vendor/nativeBinary.ts"],"names":[],"mappings":"AAoCA;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAEpD;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAErE;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAQzD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAIjC;AAED,uEAAuE;AACvE,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAC7B;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GAC3B;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAQlE;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,SAAS,MAAM,EAAE,GACtB,MAAM,EAAE,CAQV;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC3B,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,SAAS,MAAM,EAAE,GACtB,KAAK,IAAI,MAAM,CAQjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EACjC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,EACxC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GACzB,kBAAkB,CAAC,CAAC,CAAC,CAoBvB"}

package/dist/vendor/nativeBinary.js

@@ -0,0 +1,156 @@
+// Generated from scripts/vendor/nativeBinary.ts — do not edit.
+//
+// This package is published and built from its own repository, so the file
+// has to exist here rather than be imported. `pnpm vendor:sync` rewrites it,
+// and `pnpm vendor:check` fails if this copy has drifted from the original.
+/**
+ * Finding the NAPI binary a package ships beside itself.
+ *
+ * Every package with a Rust engine repeats the same table: napi-rs names its
+ * artefacts `index.<platform>-<arch>-<abi>.node`, and the mapping from Node's
+ * `platform`/`arch` to that suffix is the part that must never differ between
+ * packages. Adding a target means adding it everywhere, and a package that
+ * missed the edit fails only on that platform — which is exactly the failure
+ * nobody reproduces.
+ *
+ * What is NOT here is the policy. Some packages degrade when the binary is
+ * absent and answer `undefined`; others refuse loudly with build instructions.
+ * Both are right for their package, so the loader reports what happened and
+ * the caller decides.
+ */
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { arch, platform } from "node:process";
+import { fileURLToPath } from "node:url";
+/** Node's `platform-arch` → the suffix napi-rs builds under. */
+const TARGETS = {
+    "linux-x64": "linux-x64-gnu",
+    "linux-arm64": "linux-arm64-gnu",
+    "darwin-x64": "darwin-x64",
+    "darwin-arm64": "darwin-arm64",
+    "win32-x64": "win32-x64-msvc",
+};
+/**
+ * Every `platform-arch` a binary is built for.
+ *
+ * For the message a package raises when it refuses: "no binary for
+ * linux-riscv64" is only actionable next to the list of what there IS.
+ */
+export function supportedTargets() {
+    return Object.keys(TARGETS);
+}
+/** The suffix a given `platform-arch` builds under, or `undefined`. */
+export function nativeTargetSuffix(target) {
+    return TARGETS[target];
+}
+/** The suffix for THIS platform, or `undefined` where no binary is built. */
+export function nativeBinarySuffix() {
+    return nativeTargetSuffix(`${platform}-${arch}`);
+}
+/**
+ * Why the binary is not there, phrased for whoever has to fix it.
+ *
+ * "not found" and "not built for your platform" call for different actions,
+ * and a single "unavailable" leaves the reader to guess which one they are
+ * looking at.
+ */
+export function unavailableReason(cause) {
+    if (cause !== undefined) {
+        return `failed to load (${cause instanceof Error ? cause.message : String(cause)})`;
+    }
+    const target = `${platform}-${arch}`;
+    return nativeTargetSuffix(target) !== undefined
+        ? "binary not found"
+        : `no prebuilt binary for ${target}`;
+}
+/**
+ * `musl` builds under a different suffix, and the failure is otherwise
+ * baffling: the file is there, and `require` still refuses it. Worth saying so
+ * in a message rather than leaving a reader to discover glibc.
+ */
+export function muslHint() {
+    return platform === "linux"
+        ? " On Alpine/musl, the gnu binary will not load — build the musl target."
+        : "";
+}
+/** Whether `value` carries a function under `name` (a napi class is one too). */
+function hasFunction(value, name) {
+    const member = Reflect.get(value, name);
+    return typeof member === "function";
+}
+/**
+ * The names among `names` that `value` does not carry as functions.
+ *
+ * Classes count, being functions, and so does a class's static member: `value`
+ * may itself be a function. What a guard rejects is only useful named, so the
+ * loader reports this list rather than a bare "no".
+ */
+export function missingFunctions(value, names) {
+    if (value === null ||
+        (typeof value !== "object" && typeof value !== "function")) {
+        return [...names];
+    }
+    return names.filter((name) => !hasFunction(value, name));
+}
+/**
+ * Whether `value` carries every one of `names` as a function.
+ *
+ * The building block of the guard a package hands to `loadNativeBinary`, over
+ * the list of what it actually calls on its binary — the same list it passes
+ * as `expects`, so the message can name what is missing.
+ */
+export function hasFunctions(value, names) {
+    if (value === null ||
+        (typeof value !== "object" && typeof value !== "function")) {
+        return false;
+    }
+    return missingFunctions(value, names).length === 0;
+}
+/**
+ * Load `<package root>/index.<suffix>.node`, and check it is the binary the
+ * package calls.
+ *
+ * The path is fixed rather than passed: this file is generated into
+ * `<package>/src/vendor/`, so the package root is always two levels up, from
+ * `src` and from `dist` alike.
+ *
+ * `isBinary` is the package's own check of what it calls. A declaration only
+ * says what the Rust promises: a stale build, or one from another version,
+ * loads just as well and then fails on the first missing call, far from here.
+ * A rejected module is reported as a failed load, so the package's policy
+ * (degrade or refuse) applies to it unchanged. `expects`, the list the guard is
+ * built from, lets that report name the missing calls.
+ */
+export function loadNativeBinary(isBinary, expects) {
+    const suffix = nativeBinarySuffix();
+    if (suffix === undefined)
+        return { loaded: false, suffix };
+    const here = dirname(fileURLToPath(import.meta.url));
+    let loaded;
+    try {
+        const nodeRequire = createRequire(import.meta.url);
+        loaded = nodeRequire(join(here, `../../index.${suffix}.node`));
+    }
+    catch (cause) {
+        return { loaded: false, suffix, cause };
+    }
+    if (isBinary(loaded))
+        return { loaded: true, binary: loaded };
+    return {
+        loaded: false,
+        suffix,
+        cause: new Error(`index.${suffix}.node loaded, but ${rejection(loaded, expects)}. ` +
+            "The binary is stale or from another version: rebuild it."),
+    };
+}
+/** What a rejected binary lacks, or, without a list to check, what it has. */
+function rejection(loaded, expects) {
+    const missing = expects === undefined ? [] : missingFunctions(loaded, expects);
+    if (missing.length > 0)
+        return `it lacks ${missing.join(", ")}`;
+    const exported = typeof loaded === "object" && loaded !== null
+        ? Object.keys(loaded).filter((name) => hasFunction(loaded, name))
+        : [];
+    return `it is not the binary this package calls (it exports: ${exported.length > 0 ? exported.join(", ") : "none"})`;
+}
+//# sourceMappingURL=nativeBinary.js.map

package/dist/vendor/nativeBinary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeBinary.js","sourceRoot":"","sources":["../../src/vendor/nativeBinary.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@c9up/goldstone",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Goldstone — reading mail for the Ream framework: IMAP mailboxes and inbound mail, received as hostile input",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./provider": {
+      "types": "./dist/GoldstoneProvider.d.ts",
+      "import": "./dist/GoldstoneProvider.js"
+    },
+    "./services/main": {
+      "types": "./dist/services/main.d.ts",
+      "import": "./dist/services/main.js"
+    }
+  },
+  "dependencies": {
+    "imapflow": "^2.4.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.12",
+    "@c9up/ream": "^0.2.26",
+    "@types/node": "^22.20.1",
+    "@vitest/coverage-v8": "4.1.11",
+    "typescript": "^6.0.3",
+    "vitest": "4.1.11"
+  },
+  "//engines": "Node 24, not 22, because AsyncLocalStorage sits on the request hot path — the container resolves through it, HttpContext is it, and the emitter reads it on every event. Node 24 backs it with AsyncContextFrame by default, and measured on that exact pattern (one context per request, six async boundaries, several reads) it costs 0.61 us per request instead of 1.55 us: 2.5x, on every request, for free. Before 24 the same mechanism existed only behind an experimental flag, and a framework cannot base its performance on a flag the application has to remember to pass. This is NOT 'track the current LTS' — security fixes still land in 22 until 2027, npm 11 is irrelevant under pnpm, and node:sqlite is not what atlas uses.",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "dist",
+    "index.*.node",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/goldstone.git"
+  },
+  "peerDependencies": {
+    "@c9up/ream": "^0.2.26"
+  },
+  "peerDependenciesMeta": {
+    "@c9up/ream": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:napi": "cargo build --locked --release -p goldstone-engine-napi && pnpm build:napi-types && node scripts/copy-napi.mjs",
+    "build:napi-types": "node scripts/build-napi-types.mjs",
+    "test": "vitest run",
+    "test:rust": "cargo test --locked",
+    "lint": "biome check src/ tests/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit -p ."
+  }
 }

package/src/GoldstoneProvider.ts

@@ -0,0 +1,75 @@
+/**
+ * Wires `config/inbox.ts` into the container as `'inbox'`, and seats the
+ * manager on `@c9up/goldstone/services/main`.
+ *
+ *   // reamrc.ts
+ *   providers: [() => import('@c9up/goldstone/provider')]
+ *
+ * The host is duck-typed — this package stays publishable without importing
+ * `@c9up/ream`. `register` opens no connection: mailboxes open on first use.
+ */
+
+import "./augmentations.js";
+import type { InboxConfig, MailboxConfig } from "./config.js";
+import { InboxManager } from "./InboxManager.js";
+import { clearInbox, setInbox } from "./services/main.js";
+
+interface GoldstoneContainer {
+	singleton(token: unknown, factory: () => unknown): void;
+}
+interface GoldstoneConfigStore {
+	get(key: string): unknown;
+}
+export interface GoldstoneAppContext {
+	container: GoldstoneContainer;
+	config: GoldstoneConfigStore;
+}
+
+function isInboxConfig(
+	value: unknown,
+): value is InboxConfig<Record<string, MailboxConfig>> {
+	if (typeof value !== "object" || value === null) return false;
+	const mailboxes = Reflect.get(value, "mailboxes");
+	return (
+		typeof Reflect.get(value, "mailbox") === "string" &&
+		typeof mailboxes === "object" &&
+		mailboxes !== null
+	);
+}
+
+export default class GoldstoneProvider {
+	readonly #app: GoldstoneAppContext;
+	#manager: InboxManager | undefined;
+
+	constructor(app: GoldstoneAppContext) {
+		this.#app = app;
+	}
+
+	register(): void {
+		const raw = this.#app.config.get("inbox");
+		if (raw === undefined) throw new Error("[inbox] missing config/inbox.ts");
+		if (!isInboxConfig(raw)) {
+			throw new Error(
+				"[inbox] config/inbox.ts must export defineConfig({ mailbox, mailboxes }).",
+			);
+		}
+		const manager = new InboxManager(raw);
+		this.#manager = manager;
+		setInbox(manager);
+		this.#app.container.singleton(InboxManager, () => manager);
+		this.#app.container.singleton("goldstone.inbox", () => manager);
+		this.#app.container.singleton("inbox", () => manager);
+	}
+
+	/**
+	 * Log out of every mailbox and stop every watch. Without it, an IDLE
+	 * connection keeps the process alive and the server looks hung on stop.
+	 */
+	async shutdown(): Promise<void> {
+		const manager = this.#manager;
+		if (!manager) return;
+		await manager.closeAll();
+		clearInbox(manager);
+		this.#manager = undefined;
+	}
+}

package/src/InboxManager.ts

@@ -0,0 +1,51 @@
+/**
+ * The configured mailboxes, each opened on first use.
+ *
+ *   inbox.mailbox()            // the default one
+ *   inbox.mailbox('billing')
+ */
+
+import type { InboxConfig, MailboxConfig } from "./config.js";
+import { GoldstoneError } from "./errors.js";
+import { Mailbox } from "./Mailbox.js";
+
+export class InboxManager<
+	Mailboxes extends Record<string, MailboxConfig> = Record<
+		string,
+		MailboxConfig
+	>,
+> {
+	readonly #config: InboxConfig<Mailboxes>;
+	readonly #open = new Map<string, Mailbox>();
+
+	constructor(config: InboxConfig<Mailboxes>) {
+		this.#config = config;
+	}
+
+	/** A mailbox by name; the default one without. Opens nothing yet. */
+	mailbox(name: keyof Mailboxes & string = this.#config.mailbox): Mailbox {
+		const existing = this.#open.get(name);
+		if (existing) return existing;
+		const config = this.#config.mailboxes[name];
+		if (config === undefined) {
+			throw new GoldstoneError(
+				"E_GOLDSTONE_UNKNOWN_MAILBOX",
+				`[inbox] no mailbox "${name}" — got ${Object.keys(this.#config.mailboxes).join(", ")}`,
+			);
+		}
+		const mailbox = new Mailbox(name, config, {
+			limits: this.#config.limits,
+			authenticate: this.#config.authenticate,
+			remoteContent: this.#config.remoteContent,
+		});
+		this.#open.set(name, mailbox);
+		return mailbox;
+	}
+
+	/** Stop every watch and log out of every mailbox. */
+	async closeAll(): Promise<void> {
+		const mailboxes = [...this.#open.values()];
+		this.#open.clear();
+		await Promise.all(mailboxes.map((mailbox) => mailbox.close()));
+	}
+}