@onlyne/mcp-gateway 3.1.0 → 3.2.0

package/README.md

@@ -23,6 +23,7 @@ bunx onlyne-mcp-gateway ./gateway.json
     {
       "name": "hindsight",
       "url": "http://localhost:8888/mcp/example-bank/",
+      "allowed_tools": ["recall", "retain"],
       "timeout_ms": 60000,
       "controllers": ["urn:onlyne:agent:main"]
     }
@@ -30,7 +31,25 @@ bunx onlyne-mcp-gateway ./gateway.json
 }
 ```
 
-`headers` adds per-request headers such as an API key and is never logged. `controllers` lists
+`headers` adds per-request headers such as an API key and is never logged. `allowed_tools` limits
+which listed tools may be called; omit it for every listed tool, pass `[]` to deny all. A denied
+tool fails with `forbidden` before any connection or request. A local server uses stdio instead
+of a URL:
+
+```json
+{
+  "name": "filesystem",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+  "cwd": "/tmp",
+  "allowed_tools": ["read_file", "list_directory"],
+  "controllers": ["urn:onlyne:agent:main"]
+}
+```
+
+`command`, `args`, `env` and `cwd` are passed to the child process as separate values; no shell
+string is built. `controllers` lists
 the nodes allowed to call a server's tools; an empty list leaves the node owner alone.
 `language` accepts `en` or `zh-CN` and otherwise follows `ONLYNE_LANG`, `LC_ALL`, or `LANG`.
 
@@ -121,6 +140,11 @@ import { createMcpGateway } from '@onlyne/mcp-gateway';
 
 The result carries the node, the connections, and a `fetch` handler.
 
+`McpGateway.bridge` exposes the read-only MCP resource primitives for hosts: `listResources`,
+`readResource`, `subscribe`, `unsubscribe`, `syncSubscriptions` and `close`. Reads return server
+data only; they never admit a message or write business state. The bridge reports subscription
+loss through its observation callbacks and withdraws every subscription on close.
+
 ## License
 
 MIT.

package/dist/config.d.ts

@@ -0,0 +1,69 @@
+import { type NodeId } from '@onlyne/lib';
+import type { Locale } from '@onlyne/node-host/i18n';
+/** Settings every configured MCP server shares. */
+interface ServerConfigBase {
+    name: string;
+    timeout_ms?: number;
+    /** Who may call this server's tools. Empty means the node owner only. */
+    controllers?: NodeId[];
+    /**
+     * The local tool policy (RFC 0015 §4). Absent allows every tool the server lists; an empty
+     * list allows none. It is checked before a request leaves the gateway.
+     */
+    allowed_tools?: string[];
+}
+/** An HTTP streamable MCP server; the transport is implicit when only `url` is given. */
+export interface HttpServerConfig extends ServerConfigBase {
+    transport?: 'http';
+    url: string;
+    /** Extra request headers (an API key, a bank header); never logged. */
+    headers?: Record<string, string>;
+}
+/** A locally spawned MCP server; `command` and `args` are spawned directly, never through a shell. */
+export interface StdioServerConfig extends ServerConfigBase {
+    transport: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/** One configured MCP server: exactly one of the HTTP and stdio transport contracts. */
+export type ServerConfig = HttpServerConfig | StdioServerConfig;
+/** One locally allowlisted executable a scheduled mount may run: the mount names this id only. */
+export interface MountCommandConfig {
+    id: string;
+    command: string;
+    args?: string[];
+    cwd?: string;
+}
+/** One MCP tool a scheduled mount may call; the server's own controller list still applies. */
+export interface MountToolConfig {
+    server: string;
+    tool: string;
+}
+export interface MountsConfig {
+    /** The nodes that may mount, inspect and cancel tasks on their own scheduler resource. */
+    controllers: NodeId[];
+    commands: MountCommandConfig[];
+    tools: MountToolConfig[];
+    tick_ms: number;
+}
+export interface GatewayConfig {
+    node: {
+        id: NodeId;
+    };
+    server: {
+        bind: string;
+        port: number;
+    };
+    storage_path: string;
+    servers: ServerConfig[];
+    /** Scheduled mounts; absent means the gateway serves no scheduler resource at all. */
+    mounts?: MountsConfig;
+    /** The language of the gateway's own console text; unset follows `ONLYNE_LANG`. */
+    language?: Locale;
+}
+/** Loads the gateway configuration from one JSON file; environment retuning comes later. */
+export declare function loadConfig(path: string): Promise<GatewayConfig>;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAIrD,mDAAmD;AACnD,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,yFAAyF;AACzF,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,sGAAsG;AACtG,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wFAAwF;AACxF,MAAM,MAAM,YAAY,GAAG,gBAAgB,GAAG,iBAAiB,CAAC;AAEhE,kGAAkG;AAClG,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,+FAA+F;AAC/F,MAAM,WAAW,eAAe;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAEjE,MAAM,WAAW,YAAY;IAC3B,0FAA0F;IAC1F,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACrB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,sFAAsF;IACtF,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAoKD,4FAA4F;AAC5F,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAsCrE"}

package/dist/config.js

@@ -0,0 +1,210 @@
+import { OnlyneError } from '@onlyne/lib';
+import { t } from './gateway-text.js';
+import { MOUNTS_RESOURCE_PREFIX } from './mounts.js';
+const requireObject = (value, field) => {
+    if (value === undefined || value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new OnlyneError('invalid_request', t('config.object', { field }));
+    }
+    return value;
+};
+const requireString = (container, field) => {
+    const value = container[field];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new OnlyneError('invalid_request', t('config.string', { field }));
+    }
+    return value;
+};
+const requireStrings = (value, field) => {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || item.length === 0)) {
+        throw new OnlyneError('invalid_request', t('config.stringList', { field }));
+    }
+    return value;
+};
+function parseMounts(raw, owner, servers) {
+    if (raw === undefined)
+        return undefined;
+    const record = requireObject(raw, 'mounts');
+    const controllers = [...new Set(requireStrings(record.controllers, 'mounts.controllers'))];
+    if (controllers.length === 0) {
+        throw new OnlyneError('invalid_request', t('config.mountsControllers'));
+    }
+    if (controllers.includes(owner)) {
+        throw new OnlyneError('invalid_request', t('config.mountsOwner', { owner }));
+    }
+    const commands = (record.commands === undefined ? [] : record.commands);
+    if (!Array.isArray(commands))
+        throw new OnlyneError('invalid_request', t('config.mountsCommands'));
+    const commandIds = new Set();
+    const parsedCommands = commands.map((entry, index) => {
+        const item = requireObject(entry, `mounts.commands[${index}]`);
+        const id = requireString(item, 'id');
+        if (commandIds.has(id))
+            throw new OnlyneError('invalid_request', t('config.mountsDuplicate', { kind: 'command', id }));
+        commandIds.add(id);
+        const args = item.args === undefined ? [] : requireStrings(item.args, `mounts.commands[${index}].args`);
+        const cwd = item.cwd === undefined ? undefined : requireString(item, 'cwd');
+        return {
+            id,
+            command: requireString(item, 'command'),
+            ...(args.length === 0 ? {} : { args }),
+            ...(cwd === undefined ? {} : { cwd }),
+        };
+    });
+    const tools = (record.tools === undefined ? [] : record.tools);
+    if (!Array.isArray(tools))
+        throw new OnlyneError('invalid_request', t('config.mountsTools'));
+    const toolIds = new Set();
+    const parsedTools = tools.map((entry, index) => {
+        const item = requireObject(entry, `mounts.tools[${index}]`);
+        const server = requireString(item, 'server');
+        const tool = requireString(item, 'tool');
+        const configured = servers.get(server);
+        if (configured === undefined) {
+            throw new OnlyneError('invalid_request', t('config.mountsToolServer', { server }));
+        }
+        // A scheduled call runs with the same local policy as a direct resource operation; refusing
+        // a tool the policy already denies at load time keeps the scheduler from starting a task
+        // that can only fail.
+        if (configured.allowed_tools !== undefined && !configured.allowed_tools.includes(tool)) {
+            throw new OnlyneError('invalid_request', `mounts.tools names ${server}/${tool}, which the server's allowed_tools policy denies.`);
+        }
+        const pair = `${server}\u0000${tool}`;
+        if (toolIds.has(pair))
+            throw new OnlyneError('invalid_request', t('config.mountsDuplicate', { kind: 'tool', id: `${server}/${tool}` }));
+        toolIds.add(pair);
+        return { server, tool };
+    });
+    const tick = record.tick_ms === undefined ? 1_000 : record.tick_ms;
+    if (typeof tick !== 'number' || !Number.isInteger(tick) || tick < 100 || tick > 60_000) {
+        throw new OnlyneError('invalid_request', t('config.mountTick'));
+    }
+    return { controllers, commands: parsedCommands, tools: parsedTools, tick_ms: tick };
+}
+/** `language` is exactly `en` or `zh-CN`: a near miss would silently pick a different console language. */
+const parseLanguage = (value) => {
+    if (value === undefined)
+        return undefined;
+    if (value === 'en' || value === 'zh-CN')
+        return value;
+    throw new OnlyneError('invalid_request', t('config.language', { value: JSON.stringify(value) }));
+};
+/** Environment entries are opaque strings; an empty value is legal, a non-string is not. */
+function parseEnvironment(value, field) {
+    if (value === undefined)
+        return undefined;
+    const record = requireObject(value, field);
+    const environment = {};
+    for (const [key, entry] of Object.entries(record)) {
+        if (typeof entry !== 'string') {
+            throw new OnlyneError('invalid_request', t('config.string', { field: `${field}.${key}` }));
+        }
+        environment[key] = entry;
+    }
+    return Object.keys(environment).length === 0 ? undefined : environment;
+}
+/** One `servers[]` entry: the transport decides which fields are required and which are refused. */
+function parseServer(item, index) {
+    const field = `servers[${index}]`;
+    const timeout = item.timeout_ms;
+    const rawAllowed = item.allowed_tools;
+    const allowed = rawAllowed === undefined
+        ? undefined
+        : [...new Set(requireStrings(rawAllowed, `${field}.allowed_tools`))];
+    const controllers = item.controllers;
+    const shared = {
+        name: requireString(item, 'name'),
+        ...(typeof timeout === 'number' ? { timeout_ms: timeout } : {}),
+        ...(allowed === undefined ? {} : { allowed_tools: allowed }),
+        ...(Array.isArray(controllers)
+            ? { controllers: controllers.filter((value) => typeof value === 'string' && value.length > 0) }
+            : {}),
+    };
+    const declared = item.transport;
+    if (declared !== undefined && declared !== 'http' && declared !== 'stdio') {
+        throw new OnlyneError('invalid_request', `${field}.transport is 'http' or 'stdio'.`);
+    }
+    // An existing configuration names only `url`; that stays the HTTP transport without a rewrite.
+    const transport = declared ?? (item.url !== undefined ? 'http' : undefined);
+    if (transport === 'http') {
+        for (const key of ['command', 'args', 'env', 'cwd']) {
+            if (item[key] !== undefined) {
+                throw new OnlyneError('invalid_request', `${field} uses the http transport, so it cannot set ${key}.`);
+            }
+        }
+        const rawHeaders = item.headers === undefined ? undefined : requireObject(item.headers, `${field}.headers`);
+        const headers = rawHeaders === undefined
+            ? undefined
+            : Object.fromEntries(Object.entries(rawHeaders).filter((pair) => typeof pair[1] === 'string'));
+        return {
+            ...shared,
+            transport: 'http',
+            url: requireString(item, 'url'),
+            ...(headers === undefined || Object.keys(headers).length === 0 ? {} : { headers }),
+        };
+    }
+    if (transport === 'stdio') {
+        if (item.url !== undefined) {
+            throw new OnlyneError('invalid_request', `${field} uses the stdio transport, so it cannot set url.`);
+        }
+        if (item.headers !== undefined) {
+            throw new OnlyneError('invalid_request', `${field} uses the stdio transport, so it cannot set headers.`);
+        }
+        const args = item.args === undefined ? [] : requireStrings(item.args, `${field}.args`);
+        const env = parseEnvironment(item.env, `${field}.env`);
+        const cwd = item.cwd === undefined ? undefined : requireString(item, 'cwd');
+        return {
+            ...shared,
+            transport: 'stdio',
+            command: requireString(item, 'command'),
+            ...(args.length === 0 ? {} : { args }),
+            ...(env === undefined ? {} : { env }),
+            ...(cwd === undefined ? {} : { cwd }),
+        };
+    }
+    throw new OnlyneError('invalid_request', `${field} needs transport 'http' with url, or transport 'stdio' with command.`);
+}
+/** Loads the gateway configuration from one JSON file; environment retuning comes later. */
+export async function loadConfig(path) {
+    let file;
+    try {
+        file = JSON.parse(await Bun.file(path).text());
+    }
+    catch {
+        throw new OnlyneError('invalid_request', t('config.unreadable', { path }));
+    }
+    const raw = requireObject(file, 'the configuration root');
+    const node = requireObject(raw.node, 'node');
+    const server = requireObject(raw.server, 'server');
+    const storage = requireObject(raw.storage, 'storage');
+    const language = parseLanguage(raw.language);
+    const owner = requireString(node, 'id');
+    const rawServers = raw.servers === undefined ? [] : raw.servers;
+    if (!Array.isArray(rawServers)) {
+        throw new OnlyneError('invalid_request', t('config.servers'));
+    }
+    const servers = rawServers.map((entry, index) => parseServer(requireObject(entry, `servers[${index}]`), index));
+    const names = new Set();
+    for (const entry of servers) {
+        if (names.has(entry.name))
+            throw new OnlyneError('invalid_request', t('config.duplicateName', { name: entry.name }));
+        if (entry.name.startsWith(MOUNTS_RESOURCE_PREFIX)) {
+            throw new OnlyneError('invalid_request', t('config.reservedName', { name: entry.name, prefix: MOUNTS_RESOURCE_PREFIX }));
+        }
+        names.add(entry.name);
+    }
+    const mounts = parseMounts(raw.mounts, owner, new Map(servers.map(entry => [entry.name, entry])));
+    return {
+        node: { id: owner },
+        server: {
+            bind: typeof server.bind === 'string' && server.bind.length > 0 ? server.bind : '127.0.0.1',
+            port: typeof server.port === 'number' ? server.port : 0,
+        },
+        storage_path: requireString(storage, 'path'),
+        servers,
+        ...(mounts === undefined ? {} : { mounts }),
+        ...(language === undefined ? {} : { language }),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/cron.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A parsed five-field cron expression. Every field becomes a sorted list of the values it
+ * admits, so matching is a membership test and never a re-parse. Time is UTC: a mounted task
+ * must fire at the same instant after a restart, in every process, on every host.
+ */
+export interface CronSchedule {
+    readonly minutes: readonly number[];
+    readonly hours: readonly number[];
+    readonly days: readonly number[];
+    readonly months: readonly number[];
+    readonly weekdays: readonly number[];
+    /** Which of the day fields the expression restricts; both restricted match either (Vixie). */
+    readonly domRestricted: boolean;
+    readonly dowRestricted: boolean;
+}
+/** Parses one five-field expression; throwing `invalid_request` names the offending field. */
+export declare function parseCron(expression: string): CronSchedule;
+/**
+ * The first instant strictly after `fromMs` that the expression admits, to the minute, in UTC.
+ * `undefined` means no occurrence inside the five-year horizon (for example `0 0 31 2 *`).
+ */
+export declare function nextCronTime(schedule: CronSchedule, fromMs: number): number | undefined;
+//# sourceMappingURL=cron.d.ts.map

package/dist/cron.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../src/cron.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,8FAA8F;IAC9F,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAwDD,8FAA8F;AAC9F,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAY1D;AAQD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAwBvF"}

package/dist/cron.js

@@ -0,0 +1,112 @@
+import { OnlyneError } from '@onlyne/lib';
+const FIELDS = [
+    { name: 'minute', min: 0, max: 59 },
+    { name: 'hour', min: 0, max: 23 },
+    { name: 'day-of-month', min: 1, max: 31 },
+    { name: 'month', min: 1, max: 12 },
+    // 7 is Sunday: accepted as an input alias only, and normalized before the schedule is stored.
+    { name: 'day-of-week', min: 0, max: 7 },
+];
+/** `7` is Sunday in the day-of-week field; the schedule normalizes it to `0`. */
+const WEEKDAY_ALIAS = { '7': 0 };
+const RANGE = /^(\d+)-(\d+)$/;
+const NUMBER = /^\d+$/;
+function parseField(text, spec) {
+    if (text.length === 0)
+        throw cronError(`The ${spec.name} field is empty.`);
+    const values = new Set();
+    for (const part of text.split(',')) {
+        if (part.length === 0)
+            throw cronError(`The ${spec.name} field holds an empty list item.`);
+        const [rangeText = '', stepText, extra] = part.split('/');
+        if (extra !== undefined)
+            throw cronError(`The ${spec.name} field step has more than one slash.`);
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step <= 0)
+            throw cronError(`The ${spec.name} field step is a positive integer.`);
+        let from;
+        let to;
+        if (rangeText === '*') {
+            from = spec.min;
+            to = spec.max;
+        }
+        else if (NUMBER.test(rangeText)) {
+            from = Number(rangeText);
+            // A bare number with a step names the range from that number to the field maximum.
+            to = stepText === undefined ? from : spec.max;
+        }
+        else {
+            const range = RANGE.exec(rangeText);
+            if (range === null)
+                throw cronError(`The ${spec.name} field value ${JSON.stringify(rangeText)} is not a number, range or '*'.`);
+            from = Number(range[1]);
+            to = Number(range[2]);
+        }
+        const low = from;
+        const high = to;
+        if (low < spec.min || low > spec.max || high < spec.min || high > spec.max) {
+            throw cronError(`The ${spec.name} field allows ${spec.min}..${spec.max}, not ${from}..${to}.`);
+        }
+        if (low > high)
+            throw cronError(`The ${spec.name} field range ${from}-${to} runs backwards.`);
+        for (let value = low; value <= high; value += step)
+            values.add(WEEKDAY_ALIAS[String(value)] ?? value);
+    }
+    return [...values].sort((a, b) => a - b);
+}
+function cronError(message) {
+    return new OnlyneError('invalid_request', message);
+}
+/** Parses one five-field expression; throwing `invalid_request` names the offending field. */
+export function parseCron(expression) {
+    if (typeof expression !== 'string')
+        throw cronError('A cron expression is a string.');
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== FIELDS.length) {
+        throw cronError(`A cron expression has ${FIELDS.length} fields (minute hour day month weekday), not ${parts.length}.`);
+    }
+    const [minutes, hours, days, months, weekdays] = parts.map((part, index) => parseField(part, FIELDS[index]));
+    return {
+        minutes: minutes, hours: hours, days: days, months: months, weekdays: weekdays,
+        domRestricted: parts[2] !== '*',
+        dowRestricted: parts[4] !== '*',
+    };
+}
+const MINUTE_MS = 60_000;
+const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_000;
+/** Five years covers every Gregorian recurrence, including 29 February on a weekday. */
+const HORIZON_DAYS = 366 * 5;
+/**
+ * The first instant strictly after `fromMs` that the expression admits, to the minute, in UTC.
+ * `undefined` means no occurrence inside the five-year horizon (for example `0 0 31 2 *`).
+ */
+export function nextCronTime(schedule, fromMs) {
+    const dayStart = Math.floor(fromMs / DAY_MS) * DAY_MS;
+    for (let day = 0; day < HORIZON_DAYS; day++) {
+        const base = dayStart + day * DAY_MS;
+        const date = new Date(base);
+        const month = date.getUTCMonth() + 1;
+        if (!schedule.months.includes(month))
+            continue;
+        const dom = date.getUTCDate();
+        const dow = date.getUTCDay();
+        const domMatch = schedule.days.includes(dom);
+        const dowMatch = schedule.weekdays.includes(dow);
+        // Vixie cron: a restricted day-of-month and a restricted day-of-week combine with OR.
+        const dayMatch = schedule.domRestricted && schedule.dowRestricted
+            ? domMatch || dowMatch
+            : domMatch && dowMatch;
+        if (!dayMatch)
+            continue;
+        for (const hour of schedule.hours) {
+            for (const minute of schedule.minutes) {
+                const at = base + hour * HOUR_MS + minute * MINUTE_MS;
+                if (at > fromMs)
+                    return at;
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=cron.js.map

package/dist/cron.js.map

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

package/dist/exec.d.ts

@@ -0,0 +1,33 @@
+/** Output kept per stream: enough for one readable result line, bounded so a chatty script cannot bloat the store. */
+export declare const OUTPUT_CAP = 4096;
+export interface CommandResult {
+    exit_code: number | null;
+    stdout: string;
+    stderr: string;
+    output_bytes: number;
+}
+export interface CommandTarget {
+    command: string;
+    args?: readonly string[];
+    cwd?: string;
+}
+/** A handle the scheduler keeps so it can signal exactly the process it started, never a name match. */
+export interface RunningChild {
+    cancelled: boolean;
+    pid?: number;
+}
+/** Signals the process group the scheduler built: the exact child first, then its verified descendants. */
+export declare function signalTree(child: RunningChild, signal: NodeJS.Signals): Promise<void>;
+/**
+ * Stops one run: SIGTERM for a clean exit, then SIGKILL of the same subtree while its root is
+ * still alive after the grace period. The escalation is not awaited by the caller, so a cancel
+ * answers as soon as the signal is sent; the run settles when its process actually exits.
+ */
+export declare function stopChild(child: RunningChild): void;
+/**
+ * Runs one allowlisted executable with argv directly, never through a shell: no quoting, no
+ * metacharacters, no remote string ever reaches `/bin/sh`. The child's pid is recorded before
+ * any output is read so a cancel that arrives first still has a handle to signal.
+ */
+export declare function runCommand(target: CommandTarget, child: RunningChild): Promise<CommandResult>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../src/exec.ts"],"names":[],"mappings":"AAEA,sHAAsH;AACtH,eAAO,MAAM,UAAU,OAAQ,CAAC;AAIhC,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wGAAwG;AACxG,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAwDD,2GAA2G;AAC3G,wBAAsB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAY3F;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAYnD;AAgBD;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CA6BnG"}