@jini-ai/platform 0.6.12 → 0.6.15-rc.2

package/dist/fetch-with-timeout.js

@@ -87,6 +87,126 @@ export const FETCH_TIMEOUT_MS = {
      * legitimately still-generating request early. */
     GENERATE: 10 * 60_000,
 };
+/**
+ * Creates one signal that aborts when the remaining wait budget expires or the caller cancels.
+ * Spent time is subtracted once; future start times cannot increase the original budget.
+ * @param input - Wait budget in milliseconds. Negative remaining budgets become zero.
+ * @param options - Optional caller signal, start time and clock port.
+ * @returns A native deadline signal preserving the first abort reason. Zero expires asynchronously,
+ * following AbortSignal.timeout(0); an already-aborted caller is reflected immediately.
+ * Creates a native timeout without mutating inputs or the caller's signal.
+ * @throws {RangeError} If the remaining delay is invalid for AbortSignal.timeout.
+ * @complexity O(1) time and space.
+ * @example createDeadlineSignal({ waitMs: 5_000 }, { signal, startedAt, now: Date.now })
+ */
+export function createDeadlineSignal({ waitMs }, { signal, startedAt, now = Date.now } = {}) {
+    const elapsedMs = startedAt === undefined ? 0 : Math.max(0, now() - startedAt);
+    const deadline = AbortSignal.timeout(Math.max(0, waitMs - elapsedMs));
+    if (signal === undefined)
+        return deadline;
+    return AbortSignal.any([deadline, signal]);
+}
+export async function readFetchResponseText(input, { maxResponseBytes, strictUtf8 = false } = {}) {
+    const details = "result" in input && input.result === "details";
+    const options = details ? input : { ...(maxResponseBytes === undefined ? {} : { maxResponseBytes }), strictUtf8 };
+    validateTextReadOptions({ maxResponseBytes: options.maxResponseBytes, requireCap: details });
+    if (!details && options.maxResponseBytes === undefined && !options.strictUtf8)
+        return input.response.text();
+    const result = await consumeResponseText({ response: input.response, awaitCancel: !details }, options);
+    return details ? result : result.text;
+}
+/** Owns reader cleanup for every caller; legacy failure cleanup keeps its awaited behavior.
+ * Signal-driven callers skip that wait: a body that ignores its signal may never settle cancel. */
+async function consumeResponseText({ response, awaitCancel }, options = {}) {
+    options.signal?.throwIfAborted();
+    if (response.body === null)
+        return { text: "", byteLength: 0, truncated: false };
+    const reader = response.body.getReader();
+    let failed = true;
+    try {
+        const result = await decodeResponseStream({ reader }, options);
+        if (result.truncated)
+            void cancelResponseReader({ reader });
+        failed = false;
+        return result;
+    }
+    catch (error) {
+        const cancellation = cancelResponseReader({ reader, reason: error });
+        if (awaitCancel)
+            await cancellation;
+        throw error;
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch (error) {
+            if (!failed)
+                throw error;
+        }
+    }
+}
+/** Observe synchronous/asynchronous cancellation failure without masking the consumption outcome. */
+function cancelResponseReader({ reader, reason }) {
+    try {
+        return reader.cancel(reason).catch(() => { });
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
+/** Reject invalid caps before consumption, including for empty responses. */
+function validateTextReadOptions({ maxResponseBytes, requireCap = false }) {
+    if (maxResponseBytes === undefined && !requireCap)
+        return;
+    if (typeof maxResponseBytes !== "number" || !Number.isSafeInteger(maxResponseBytes) || maxResponseBytes < 0) {
+        throw new RangeError("maxResponseBytes must be a nonnegative safe integer");
+    }
+}
+/** Byte counting precedes decoding; final flush detects truncated UTF-8 in strict mode.
+ * Retains only the allowed prefix, independently of upstream chunk size or headers. */
+async function decodeResponseStream({ reader }, { maxResponseBytes = Infinity, strictUtf8 = false, onLimit = "reject", signal } = {}) {
+    const decoder = new TextDecoder("utf-8", { fatal: strictUtf8 });
+    let total = 0;
+    let text = "";
+    for (;;) {
+        const { done, value } = await readResponseChunk({ reader, signal });
+        if (done)
+            break;
+        const remaining = maxResponseBytes - total;
+        if (value.byteLength > remaining) {
+            if (onLimit === "reject")
+                throw new RangeError(`response exceeds the ${maxResponseBytes}-byte limit`);
+            text += decoder.decode(value.subarray(0, remaining), { stream: true });
+            return { text: text + decoder.decode(), byteLength: maxResponseBytes, truncated: true };
+        }
+        total += value.byteLength;
+        text += decoder.decode(value, { stream: true });
+    }
+    return { text: text + decoder.decode(), byteLength: total, truncated: false };
+}
+/** Race one read against cancellation, removing the listener on every outcome.
+ * Per-read listeners avoid accumulating pending race handlers over a long response. */
+async function readResponseChunk({ reader, signal }) {
+    if (!signal)
+        return reader.read();
+    signal.throwIfAborted();
+    let abort = () => { };
+    try {
+        return await Promise.race([
+            new Promise((_resolve, reject) => {
+                abort = () => reject(signal.reason);
+                signal.addEventListener("abort", abort, { once: true });
+                if (signal.aborted)
+                    abort();
+            }),
+            Promise.resolve().then(() => { signal.throwIfAborted(); return reader.read(); }),
+        ]);
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+    }
+}
 /**
  * `fetch`, but aborted after `options.timeoutMs` if it hasn't settled by then. If `init.signal` is
  * already set, the call aborts on EITHER that signal or the timeout, via `AbortSignal.any` — a
@@ -103,11 +223,37 @@ export const FETCH_TIMEOUT_MS = {
  * genuine network error) propagates unchanged.
  */
 export async function fetchWithTimeout(url, init = {}, options) {
-    const { timeoutMs } = options;
+    return executeFetchWithTimeout({ url, init, timeoutMs: options.timeoutMs, consume: async ({ response }) => response }, options);
+}
+/**
+ * Fetches and consumes text inside one timeout scope. The returned response keeps its metadata
+ * and has a consumed body. No retries; other fetch/read errors propagate unchanged.
+ * @throws {FetchTimeoutError} The timeout ends fetch or body consumption before caller abort.
+ * @throws {RangeError | TypeError} See {@link readFetchResponseText} for opt-in guards.
+ * @complexity O(n) time and text storage for n response bytes, optionally capped.
+ */
+export async function fetchTextWithTimeout(required, optional = {}) {
+    return executeFetchWithTimeout({
+        url: required.url,
+        timeoutMs: required.timeoutMs,
+        init: required.init ?? {},
+        consume: async ({ response, signal }) => {
+            const { maxResponseBytes, strictUtf8 = false } = optional;
+            validateTextReadOptions({ maxResponseBytes });
+            // Always stream under the scope's signal: an injected fetch's body may ignore that signal,
+            // and only racing each read lets the timeout end consumption.
+            const read = await consumeResponseText({ response, awaitCancel: false }, { ...(maxResponseBytes === undefined ? {} : { maxResponseBytes }), strictUtf8, signal });
+            return { response, text: read.text };
+        },
+    }, optional);
+}
+/** Shared signal composition/error mapping; consumption decides the timeout scope's endpoint. */
+async function executeFetchWithTimeout({ url, init, timeoutMs, consume }, options = {}) {
     const timeoutSignal = AbortSignal.timeout(timeoutMs);
     const signal = init.signal ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
     try {
-        return await fetch(url, { ...init, signal });
+        const response = await (options.fetch ?? fetch)(url, { ...init, signal });
+        return await consume({ response, signal });
     }
     catch (error) {
         // `timeoutSignal` is the original object this function created, not the (possibly composed)

package/dist/fs/directory-user-config.js

@@ -68,7 +68,8 @@ export function createDirectoryUserConfig({ homeDir, defaultFolder, envName, pol
     }
     function configuredRoots(saved) {
         const fromEnv = env[policy.rootsEnvName];
-        return fromEnv !== undefined ? fromEnv.split(",").map((root) => root.trim()).filter(Boolean) : saved.siteRoots ?? policy.sourceRoots ?? [];
+        // Saved roots are extras; policy roots remain implicit unless the environment overrides them.
+        return fromEnv !== undefined ? fromEnv.split(",").map((root) => root.trim()).filter(Boolean) : [...(policy.sourceRoots ?? []), ...(saved.siteRoots ?? [])];
     }
     // Prefer explicit settings, never coerce an existing regular file into a directory.
     function assertDirectories(checked) {

package/dist/fs/directory-workspace.js

@@ -85,7 +85,9 @@ export function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName,
         const oldHome = legacy.state === "ok" ? legacy.value?.home : path.join(homeDir, userConfig.legacyDefaultFolder ?? defaultFolder);
         if (typeof oldHome !== "string")
             throw new Error("Legacy directory setting has an invalid home.");
-        return [...new Set([oldHome, ...config.legacyHomes({}), home()])].map((root) => createDirectoryRegistry({ file: fileAt(path.join(root, registryName)), canonicalPath }));
+        // Legacy settings use the same home shorthand contract; current overrides must not redirect the import.
+        const expandedHome = resolveDirectoryHome({ homeDir, defaultFolder, envName, env: {}, setting: oldHome }, { cwd, ...directoryOptions });
+        return [...new Set([expandedHome, ...config.legacyHomes({}), home()])].map((root) => createDirectoryRegistry({ file: fileAt(path.join(root, registryName)), canonicalPath }));
     };
     const importOldCatalog = () => {
         const current = atHome();

package/dist/fs/guarded-reader.d.ts

@@ -1,60 +1,32 @@
 import nodeFs from "node:fs";
-/** Refusal of a malformed, denied, escaped, or over-limit file operation. */
-export declare class FsFilePathError extends Error {
-    constructor({ message }: {
-        message: string;
-    });
-}
-export interface DenyRules {
-    segments: ReadonlySet<string>;
-    filenamePatterns: readonly RegExp[];
-}
-export interface GuardedReaderLimits {
-    maxFileBytes: number;
-    binarySniffBytes: number;
-    maxListedFiles: number;
-    maxWalkDepth: number;
-    maxWalkEntries: number;
-}
-export type GuardedReaderFilesystem = Pick<typeof nodeFs, "existsSync" | "lstatSync" | "readdirSync" | "realpathSync" | "statSync" | "openSync" | "readSync" | "closeSync" | "createReadStream">;
+import { type DenyRules, type GuardedFileReader, type GuardedReaderLimits } from '@jini-ai/core/filesystem';
+export { FsFilePathError, type DenyRules, type GuardedFileReader, type GuardedReaderLimits } from '@jini-ai/core/filesystem';
+/** Optional capabilities needed only when descriptor reads are requested. */
+export type DescriptorCapabilities = Partial<Pick<typeof nodeFs, "fstatSync" | "constants">>;
+export type DescriptorReadPolicy = {
+    /** Require exact permission bits, e.g. 0o600; no subset/superset matching. */
+    exactMode?: number;
+    /** Reject growth beyond the descriptor's initial size even below the byte cap. */
+    rejectGrowth?: boolean;
+};
+/** Additive descriptor policy in the guarded reader's existing options object. */
+export type AddedReaderOptions = {
+    descriptorRead?: DescriptorReadPolicy;
+};
+export type GuardedReaderFilesystem = Pick<typeof nodeFs, "existsSync" | "lstatSync" | "readdirSync" | "realpathSync" | "statSync" | "openSync" | "readSync" | "closeSync" | "createReadStream"> & DescriptorCapabilities;
 /** Native filesystem adapter; callers can replace individual operations for a virtual filesystem. */
 export declare function createNodeGuardedReaderFilesystem(_required: Record<string, never>): GuardedReaderFilesystem;
-export interface GuardedFileReader {
-    resolve(required: {
-        relativePath: string;
-    }): string;
-    read(required: {
-        relativePath: string;
-    }): {
-        content: string;
-        bytes: number;
-    };
-    readBytes(required: {
-        relativePath: string;
-        maxBytes: number;
-    }): Promise<Uint8Array>;
-    list(required: Record<string, never>, optional?: {
-        relativePath?: string;
-    }): {
-        files: string[];
-        truncated: boolean;
-    };
-    isDeniedFileName(required: {
-        fileName: string;
-    }): boolean;
-    isDeniedPathSegment(required: {
-        segmentName: string;
-    }): boolean;
-}
 /** Contains both requested and resolved paths, including symlink aliases and nonexistent descendants.
  * Deny rules and traversal/read limits are host policy and have no implicit defaults.
+ * Opt-in descriptor reads fail closed without fstat/no-follow/nonblocking capabilities. No-follow
+ * protects the final component, not concurrent ancestor-directory replacement.
  */
 export declare function createGuardedFileReader({ rootPath, denyRules, limits, filesystem: fs }: {
     rootPath: string;
     denyRules: DenyRules;
     limits: GuardedReaderLimits;
     filesystem: GuardedReaderFilesystem;
-}, { excludedListingDirs }?: {
+}, { excludedListingDirs, descriptorRead }?: {
     excludedListingDirs?: ReadonlySet<string>;
-}): GuardedFileReader;
+} & AddedReaderOptions): GuardedFileReader;
 //# sourceMappingURL=guarded-reader.d.ts.map

package/dist/fs/guarded-reader.js

@@ -1,22 +1,21 @@
 import nodeFs from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
-// A distinct refusal class lets tool adapters treat rejected paths/content as actionable input
-// problems instead of redacting them as an internal crash.
-/** Refusal of a malformed, denied, escaped, or over-limit file operation. */
-export class FsFilePathError extends Error {
-    constructor({ message }) { super(message); this.name = "FsFilePathError"; }
-}
+import { FsFilePathError } from '@jini-ai/core/filesystem';
+export { FsFilePathError } from '@jini-ai/core/filesystem';
 /** Native filesystem adapter; callers can replace individual operations for a virtual filesystem. */
 export function createNodeGuardedReaderFilesystem(_required) { return nodeFs; }
 /** Contains both requested and resolved paths, including symlink aliases and nonexistent descendants.
  * Deny rules and traversal/read limits are host policy and have no implicit defaults.
+ * Opt-in descriptor reads fail closed without fstat/no-follow/nonblocking capabilities. No-follow
+ * protects the final component, not concurrent ancestor-directory replacement.
  */
-export function createGuardedFileReader({ rootPath, denyRules, limits, filesystem: fs }, { excludedListingDirs = new Set(["node_modules", ".git", "dist"]) } = {}) {
+export function createGuardedFileReader({ rootPath, denyRules, limits, filesystem: fs }, { excludedListingDirs = new Set(["node_modules", ".git", "dist"]), descriptorRead } = {}) {
     if (!rootPath)
         throw new TypeError("rootPath is required");
     for (const value of Object.values(limits))
         if (!Number.isSafeInteger(value) || value <= 0)
             throw new TypeError("reader limits must be positive safe integers");
+    const descriptorFlags = descriptorRead === undefined ? undefined : descriptorOpenFlags({ filesystem: fs, policy: descriptorRead });
     const { existsSync, lstatSync, readdirSync, realpathSync, statSync } = fs;
     const MAX_FS_FILE_BYTES = limits.maxFileBytes, BINARY_SNIFF_BYTES = limits.binarySniffBytes;
     const MAX_LISTED_FILES = limits.maxListedFiles, MAX_WALK_DEPTH = limits.maxWalkDepth, MAX_WALK_ENTRIES = limits.maxWalkEntries;
@@ -250,9 +249,11 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
     }
     // Read one byte past the cap so a file that grew after stat is refused rather than clipped.
     function readBoundedSync(target, relativePath) {
-        const fd = fs.openSync(target, "r");
+        const { fd, maxBytes } = descriptorFlags === undefined
+            ? { fd: fs.openSync(target, "r"), maxBytes: MAX_FS_FILE_BYTES }
+            : openValidatedDescriptor({ target, relativePath, maxBytes: MAX_FS_FILE_BYTES });
         try {
-            const bounded = Buffer.alloc(MAX_FS_FILE_BYTES + 1);
+            const bounded = Buffer.alloc(maxBytes + 1);
             let count = 0;
             while (count < bounded.length) {
                 const read = fs.readSync(fd, bounded, count, bounded.length - count, null);
@@ -260,14 +261,30 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
                     break;
                 count += read;
             }
-            if (count > MAX_FS_FILE_BYTES)
-                throw new FsFilePathError({ message: `file '${relativePath}' exceeds the ${MAX_FS_FILE_BYTES}-byte readable limit` });
+            if (count > maxBytes)
+                throw new FsFilePathError({ message: `file '${relativePath}' exceeds the ${maxBytes}-byte readable limit` });
             return bounded.subarray(0, count);
         }
         finally {
             fs.closeSync(fd);
         }
     }
+    /** Owns the descriptor until validated; every refusal closes it before propagating. */
+    function openValidatedDescriptor({ target, relativePath, maxBytes }) {
+        const fd = openNoFollow({ target, relativePath });
+        try {
+            const stat = fs.fstatSync(fd);
+            assertDescriptorStat({ stat, relativePath, maxBytes }, descriptorRead);
+            return { fd, maxBytes: descriptorRead?.rejectGrowth ? Math.min(maxBytes, stat.size) : maxBytes };
+        }
+        catch (error) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* Preserve the validation error. */ }
+            throw error;
+        }
+    }
     // A stat-only size check can be bypassed by a growing file: bound the stream independently and
     // reject rather than return a clipped image/video. Destroy the stream on success or failure.
     async function openFsFileForRead(required) {
@@ -283,10 +300,11 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
         return readBoundedStream(target, { relativePath, maxBytes });
     }
     async function readBoundedStream(target, { relativePath, maxBytes }) {
-        const stream = fs.createReadStream(target, { highWaterMark: Math.min(64 * 1024, maxBytes + 1) });
+        const opened = createBoundedStream({ target, relativePath, maxBytes });
+        const { stream } = opened;
         try {
             // Own refusals pass through; any other stream failure becomes this reader's refusal class.
-            return await collectBoundedChunks(stream, { relativePath, maxBytes }).catch((error) => Promise.reject(error instanceof FsFilePathError
+            return await collectBoundedChunks(stream, { relativePath, maxBytes: opened.maxBytes }).catch((error) => Promise.reject(error instanceof FsFilePathError
                 ? error
                 : new FsFilePathError({ message: `path '${relativePath}' could not be read: ${errorText(error)}` })));
         }
@@ -294,6 +312,36 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
             stream.destroy();
         }
     }
+    /** O_NOFOLLOW refusals (ELOOP) and other open failures carry absolute host paths; surface only
+     * the caller's relative path, like every other refusal from this reader. */
+    function openNoFollow({ target, relativePath }) {
+        try {
+            return fs.openSync(target, descriptorFlags);
+        }
+        catch {
+            throw new FsFilePathError({ message: `path '${relativePath}' is a symbolic link or could not be opened` });
+        }
+    }
+    /** Transfer ownership to the stream only after construction; it alone closes on end/error. */
+    function createBoundedStream({ target, relativePath, maxBytes }) {
+        const highWaterMark = Math.min(64 * 1024, maxBytes + 1);
+        if (descriptorFlags === undefined)
+            return { stream: fs.createReadStream(target, { highWaterMark }), maxBytes };
+        const opened = openValidatedDescriptor({ target, relativePath, maxBytes });
+        try {
+            return {
+                stream: fs.createReadStream(target, { fd: opened.fd, autoClose: true, highWaterMark: Math.min(highWaterMark, opened.maxBytes + 1) }),
+                maxBytes: opened.maxBytes,
+            };
+        }
+        catch (error) {
+            try {
+                fs.closeSync(opened.fd);
+            }
+            catch { /* Preserve the construction error. */ }
+            throw error;
+        }
+    }
     return {
         resolve: ({ relativePath }) => resolveFsFilePath({ rootPath, relativePath }),
         read: ({ relativePath }) => readFsFile({ rootPath, relativePath }),
@@ -303,6 +351,27 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
         isDeniedPathSegment: ({ segmentName }) => isDeniedFsPathSegment(segmentName),
     };
 }
+/** Validate opt-in capability support without weakening legacy filesystem adapters. */
+function descriptorOpenFlags({ filesystem, policy }) {
+    if (!filesystem.fstatSync || !filesystem.constants)
+        throw new TypeError("descriptorRead requires fstatSync and filesystem constants");
+    const { O_RDONLY, O_NOFOLLOW, O_NONBLOCK } = filesystem.constants;
+    if (!O_NOFOLLOW || !O_NONBLOCK || !Number.isInteger(O_RDONLY))
+        throw new TypeError("descriptorRead requires supported O_RDONLY, O_NOFOLLOW and O_NONBLOCK flags");
+    if (policy.exactMode !== undefined && (!Number.isInteger(policy.exactMode) || policy.exactMode < 0 || policy.exactMode > 0o7777))
+        throw new TypeError("exactMode must contain only permission bits (0o0000 through 0o7777)");
+    return O_RDONLY | O_NOFOLLOW | O_NONBLOCK;
+}
+/** Both read paths validate the opened object, independent of earlier pathname metadata. */
+function assertDescriptorStat({ stat, relativePath, maxBytes }, { exactMode } = {}) {
+    if (!stat.isFile())
+        throw new FsFilePathError({ message: `path '${relativePath}' is not a regular file` });
+    if (!Number.isSafeInteger(stat.size) || stat.size < 0 || stat.size > maxBytes)
+        throw new FsFilePathError({ message: `file '${relativePath}' exceeds the ${maxBytes}-byte descriptor limit` });
+    // Include setuid/setgid/sticky: "exact" 0o600 must refuse a 0o4600 file.
+    if (exactMode !== undefined && (stat.mode & 0o7777) !== exactMode)
+        throw new FsFilePathError({ message: `file '${relativePath}' does not have exact mode ${exactMode.toString(8)}` });
+}
 function errorText(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/index.d.ts

@@ -42,8 +42,8 @@ export type { AtomicCopyFileOptions, AtomicCopyFileResult, RemovePathBestEffortO
 export { atomicCopyFile, pathContains, readLogTail, removePathBestEffort } from "./fs.js";
 export type { HttpWaitOptions } from "./http.js";
 export { waitForHttpOk } from "./http.js";
-export type { FetchWithTimeoutOptions } from "./fetch-with-timeout.js";
-export { FETCH_TIMEOUT_MS, FetchTimeoutError, fetchWithTimeout } from "./fetch-with-timeout.js";
+export type { DeadlineSignalOptions, FetchWithTimeoutOptions } from "./fetch-with-timeout.js";
+export { FETCH_TIMEOUT_MS, FetchTimeoutError, createDeadlineSignal, fetchWithTimeout } from "./fetch-with-timeout.js";
 export type { WellKnownUserToolchainOptions } from "./toolchain.js";
 export { wellKnownUserToolchainBins } from "./toolchain.js";
 export type { BufferedCommandResult } from "./shell.js";

package/dist/index.js

@@ -37,7 +37,7 @@ export { mergeProxyAwareEnv, parseMacosScutilProxyOutput, parseWindowsInternetSe
 export { collectProcessTreePids, createProcessStampArgs, isProcessAlive, listProcessSnapshots, listProcessUsage, matchesProcessStamp, matchesStampedProcess, readFlagValue, readProcessStamp, readProcessStampFromCommand, spawnBackgroundProcess, spawnLoggedProcess, stopProcesses, waitForProcessExit, } from "./process.js";
 export { atomicCopyFile, pathContains, readLogTail, removePathBestEffort } from "./fs.js";
 export { waitForHttpOk } from "./http.js";
-export { FETCH_TIMEOUT_MS, FetchTimeoutError, fetchWithTimeout } from "./fetch-with-timeout.js";
+export { FETCH_TIMEOUT_MS, FetchTimeoutError, createDeadlineSignal, fetchWithTimeout } from "./fetch-with-timeout.js";
 export { wellKnownUserToolchainBins } from "./toolchain.js";
 export { execCommandViaLoginShell, execFileBuffered } from "./shell.js";
 export { AssetCacheError, assertSafePublicUrl, assetCacheKey, assetCacheRewriteUrl, createAssetCache, createAssetCacheDispatcher, createValidatingLookup, isCacheableExternalUrl, } from "./asset-cache.js";

package/dist/mail/adapter-module.d.ts

@@ -12,7 +12,25 @@ export interface MailAdapterKit {
 export interface MailAdapterCreateContext {
     readonly credential: MailAdapterCredential;
     readonly kit: MailAdapterKit;
+    /** Sample at the point of use. Hosts normalize this to the real clock when omitted. */
+    readonly now?: () => Date;
+    /** Per-install configuration; only the provider module owns its schema and validation. */
+    readonly settings?: unknown;
 }
+/**
+ * Normalize a host's module context without inspecting settings or replacing its guarded ports.
+ * The optional fields on {@link MailAdapterCreateContext} preserve legacy direct create calls;
+ * hosts use this boundary to supply both defaults before invoking a provider module.
+ * @param required Sending credential and guarded adapter kit, passed through unchanged.
+ * @param optional Clock and opaque per-install settings. Only undefined selects a default.
+ * @returns A context with a live clock and settings (a fresh empty object when omitted).
+ * @complexity O(1) time and space; does not sample the clock or perform I/O.
+ * @example provider.create(createMailAdapterContext({ credential, kit }, { now, settings }));
+ */
+export declare function createMailAdapterContext(required: {
+    credential: MailAdapterCredential;
+    kit: MailAdapterKit;
+}, { now, settings }?: Pick<MailAdapterCreateContext, "now" | "settings">): Required<MailAdapterCreateContext>;
 /** Provider modules return the ordinary mail port; the shared contract names no vendor. */
 export interface MailAdapterModule {
     /** Optional host-resolved account connection for domain reads only. The host validates the

package/dist/mail/adapter-module.js

@@ -1,2 +1,14 @@
-export {};
+/**
+ * Normalize a host's module context without inspecting settings or replacing its guarded ports.
+ * The optional fields on {@link MailAdapterCreateContext} preserve legacy direct create calls;
+ * hosts use this boundary to supply both defaults before invoking a provider module.
+ * @param required Sending credential and guarded adapter kit, passed through unchanged.
+ * @param optional Clock and opaque per-install settings. Only undefined selects a default.
+ * @returns A context with a live clock and settings (a fresh empty object when omitted).
+ * @complexity O(1) time and space; does not sample the clock or perform I/O.
+ * @example provider.create(createMailAdapterContext({ credential, kit }, { now, settings }));
+ */
+export function createMailAdapterContext(required, { now = () => new Date(), settings = {} } = {}) {
+    return { credential: required.credential, kit: required.kit, now, settings };
+}
 //# sourceMappingURL=adapter-module.js.map

package/dist/mail/email-sender-registry.d.ts

@@ -0,0 +1,15 @@
+import { type ProviderRegistry } from "@jini-ai/core/provider-registry";
+import { type EmailSender, type EmailSenderContext, type EmailSourceSummary } from "./email-sender.js";
+/** Shares the existing keyed-registry admission rules; no plugin contribution category is added. */
+export type EmailSenderRegistry = ProviderRegistry<EmailSender>;
+/** Creates an isolated registry, throwing on invalid ids or duplicate built-in senders.
+ * @complexity O(s) registrations for s senders; keyed lookup remains O(1). */
+export declare function createEmailSenderRegistry(required: {
+    readonly senders: readonly EmailSender[];
+}, _optional?: Record<string, never>): EmailSenderRegistry;
+/** Lists configurable events across all registered senders, with each sender enforcing access.
+ * Refuses a sender claiming another sender's sources. @complexity One list call per sender. */
+export declare function listEmailSources(required: EmailSenderContext & {
+    readonly registry: EmailSenderRegistry;
+}, _optional?: Record<string, never>): Promise<readonly EmailSourceSummary[]>;
+//# sourceMappingURL=email-sender-registry.d.ts.map

package/dist/mail/email-sender-registry.js

@@ -0,0 +1,22 @@
+import { createProviderRegistry } from "@jini-ai/core/provider-registry";
+import { EmailSenderError } from "./email-sender.js";
+/** Creates an isolated registry, throwing on invalid ids or duplicate built-in senders.
+ * @complexity O(s) registrations for s senders; keyed lookup remains O(1). */
+export function createEmailSenderRegistry(required, _optional = {}) {
+    return createProviderRegistry({ contract: "email_sender" }, {
+        seed: required.senders.map(sender => ({ id: sender.id, label: sender.label, provider: sender })),
+    });
+}
+/** Lists configurable events across all registered senders, with each sender enforcing access.
+ * Refuses a sender claiming another sender's sources. @complexity One list call per sender. */
+export async function listEmailSources(required, _optional = {}) {
+    const sources = [];
+    for (const { id, provider } of required.registry.list({})) {
+        const listed = await provider.listSources({ workspaceId: required.workspaceId, principalId: required.principalId });
+        if (listed.some(source => source.senderId !== id))
+            throw new EmailSenderError({ code: "ownership" });
+        sources.push(...listed);
+    }
+    return sources;
+}
+//# sourceMappingURL=email-sender-registry.js.map

package/dist/mail/email-sender.d.ts

@@ -0,0 +1,109 @@
+/**
+ * MOVE: Event data and recipient authority belong to the originating feature, independently of
+ * delivery providers. Hosts bind authorization, templates and persistence; this surface sends nothing.
+ */
+import type { EmailAddress, MailerSendOptions } from "./types.js";
+/** Explicit caller scope, including for background jobs running as a host service principal. */
+export interface EmailSenderContext {
+    readonly workspaceId: string;
+    readonly principalId: string;
+}
+/** A concrete event source; the same event name may occur for several sources or senders. */
+export interface EmailSourceRef {
+    readonly senderId: string;
+    readonly sourceId: string;
+}
+export interface EmailSourceSummary extends EmailSourceRef {
+    readonly label: string;
+    readonly eventName: string;
+}
+/** Token is the exact placeholder name, without braces. Labels are presentation only. */
+export interface EmailSourceField {
+    readonly token: string;
+    readonly label: string;
+    readonly required: boolean;
+}
+/** Recipient ids are source-owned choices, never caller-supplied addresses or expressions. */
+export interface EmailRecipientChoice {
+    readonly id: string;
+    readonly label: string;
+}
+export interface EmailReadiness {
+    readonly ready: boolean;
+    readonly blockers: readonly string[];
+}
+/** Persisted by the sender's existing write owner, never by a template-side relationship. */
+export interface EmailBindingInput {
+    readonly bindingId: string;
+    readonly enabled: boolean;
+    readonly templateId: string;
+    readonly recipientId: string;
+    readonly replyTo: string;
+}
+export interface EmailBinding extends EmailBindingInput {
+    readonly activatedAt: string | null;
+}
+export interface EmailSourceDescription extends EmailSourceSummary {
+    readonly fields: readonly EmailSourceField[];
+    readonly permittedRecipients: readonly EmailRecipientChoice[];
+    readonly purpose: NonNullable<MailerSendOptions["purpose"]>;
+    readonly lane: NonNullable<MailerSendOptions["lane"]>;
+    readonly binding: EmailBinding | null;
+    readonly readiness: EmailReadiness;
+}
+/** Only allowlisted event values and recipients cross this boundary; no stored event row. */
+export interface ResolvedEmailEvent {
+    /** Authoritative ISO event time, compared with the binding's latest activation to prevent backfill. */
+    readonly occurredAt: string;
+    readonly values: Readonly<Record<string, string>>;
+    readonly recipients: readonly {
+        readonly id: string;
+        readonly address: EmailAddress;
+    }[];
+}
+export type EmailSourceRequest = EmailSenderContext & {
+    readonly sourceId: string;
+};
+/** Every operation must authorize its own scope. Resolution also verifies event/source ownership.
+ * No example-listing API: hosts may offer an authorized latest submission or a labeled sample. */
+export interface EmailSender {
+    readonly id: string;
+    readonly label: string;
+    listSources(required: EmailSenderContext, optional?: Record<string, never>): Promise<readonly EmailSourceSummary[]>;
+    describeSource(required: EmailSourceRequest, optional?: Record<string, never>): Promise<EmailSourceDescription>;
+    resolveEvent(required: EmailSourceRequest & {
+        readonly eventId: string;
+    }, optional?: Record<string, never>): Promise<ResolvedEmailEvent>;
+    configureEmail(required: EmailSourceRequest & {
+        readonly binding: EmailBindingInput;
+    }, optional?: Record<string, never>): Promise<EmailBinding>;
+}
+/** Describe must report all placeholders, including those absent from the template declarations.
+ * Render must use send-safe rendering, supplied values only, and refuse a changed version. */
+export interface EmailTemplatePort {
+    describe(required: EmailSenderContext & {
+        readonly templateId: string;
+    }, optional?: Record<string, never>): Promise<{
+        readonly version: string;
+        readonly fields: readonly string[];
+        readonly placeholders: readonly string[];
+    }>;
+    render(required: EmailSenderContext & {
+        readonly templateId: string;
+        readonly version: string;
+        readonly values: Readonly<Record<string, string>>;
+    }, optional?: Record<string, never>): Promise<{
+        readonly subject: string;
+        readonly html: string;
+        readonly text: string;
+        readonly missingFields: readonly string[];
+    }>;
+}
+/** Caller-safe failures never include event values, recipients or credentials. */
+export declare class EmailSenderError extends Error {
+    readonly code: "forbidden" | "not_found" | "ownership" | "configuration" | "not_ready" | "incompatible" | "missing_value";
+    constructor(required: {
+        readonly code: EmailSenderError["code"];
+    }, _optional?: Record<string, never>);
+}
+//# sourceMappingURL=email-sender.d.ts.map

package/dist/mail/email-sender.js

@@ -0,0 +1,10 @@
+/** Caller-safe failures never include event values, recipients or credentials. */
+export class EmailSenderError extends Error {
+    code;
+    constructor(required, _optional = {}) {
+        super(`Email sender: ${required.code}`);
+        this.code = required.code;
+        this.name = "EmailSenderError";
+    }
+}
+//# sourceMappingURL=email-sender.js.map