@isomorph.ai/app-sdk 1.3.0 → 1.4.0

package/dist/runtime-hooks.d.ts

@@ -0,0 +1,13 @@
+type ResolveContext = {
+    parentURL?: string;
+    conditions: string[];
+    importAttributes: Record<string, string>;
+};
+type ResolveResult = {
+    url: string;
+    format?: string | null;
+    shortCircuit?: boolean;
+};
+type NextResolve = (specifier: string, context: ResolveContext) => Promise<ResolveResult> | ResolveResult;
+export declare function resolve(specifier: string, context: ResolveContext, nextResolve: NextResolve): Promise<ResolveResult>;
+export {};

package/dist/runtime-hooks.js

@@ -0,0 +1,33 @@
+// Module resolution for the kit runtime (registered by runtime.ts through
+// node:module's register, so it runs on Node's loader thread). Node's type
+// stripping loads a `.ts` file but resolves nothing for it: a relative import
+// written the way the browser code writes it — `../src/isomorph.client`, no
+// extension — fails with "Cannot find module". The first hosted job that
+// imported the app's client died exactly there (fourier smoke app, preview
+// 000006, 2026-09-21). An extensionless relative specifier is tried as the
+// `.ts` file, then as a folder's `index.ts`; anything else, and anything with
+// an extension, is left to Node.
+import { access } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+const candidates = ['.ts', '.mts', '/index.ts'];
+async function exists(url) {
+    try {
+        await access(fileURLToPath(url));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function resolve(specifier, context, nextResolve) {
+    const relative = specifier.startsWith('./') || specifier.startsWith('../');
+    const extensionless = !/\.[A-Za-z0-9]+$/.test(specifier);
+    if (relative && extensionless && context.parentURL?.startsWith('file:')) {
+        const base = new URL(specifier, context.parentURL).href;
+        for (const suffix of candidates) {
+            if (await exists(base + suffix))
+                return nextResolve(base + suffix, context);
+        }
+    }
+    return nextResolve(specifier, context);
+}

package/dist/runtime.d.ts

@@ -56,11 +56,18 @@ export declare class Runs {
         cancelled?: boolean;
     }): Promise<void>;
 }
+/**
+ * What the process runs beside the action server:
+ *   full     the in-process cron scheduler and the queue loop (the default)
+ *   actions  the queue loop only; the platform's CronJobs run the schedules
+ *   gate     nothing: actions only, for the kit gate
+ */
+export type RuntimeMode = 'full' | 'actions' | 'gate';
 export interface RuntimeOptions {
     root: string;
     port: number;
     gatewayUrl: string;
-    mode: 'full' | 'gate';
+    mode: RuntimeMode;
     tokenFile?: string;
     log?: (line: string) => void;
 }
@@ -75,10 +82,19 @@ export declare class Runtime {
     readonly server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
     constructor(options: RuntimeOptions);
     start(): Promise<number>;
+    /**
+     * `--run-job <name>`: one scheduled run of one job, as a CronJob pod runs it.
+     * The run is the scheduler's own (`runScheduled`, the current minute as its
+     * tick), so it is loaded, run and recorded exactly as an in-process tick
+     * would have been. False when the app has no such job or the handler threw;
+     * the log names which.
+     */
+    runJobOnce(name: string, now?: Date): Promise<boolean>;
     stop(): Promise<void>;
     private every;
     private refreshToken;
     private scheduleTick;
+    /** One scheduled run; true when the handler returned, false when it threw or the last tick's run is still going. */
     private runScheduled;
     /** One pass of the queue loop: reclaim expired leases, claim one run, run it. */
     work(): Promise<void>;
@@ -87,3 +103,5 @@ export declare class Runtime {
 }
 /** The runtime's settings from the environment; exported for the entry point and its test. */
 export declare function optionsFromEnvironment(env?: NodeJS.ProcessEnv): RuntimeOptions;
+/** The job named by `--run-job <name>` or `--run-job=<name>`; undefined when the runtime is a server. */
+export declare function runJobFromArguments(argv?: string[]): string | undefined;

package/dist/runtime.js

@@ -10,6 +10,12 @@
 // database or a company system directly: every read and write goes through
 // the App Gateway as the workload identity, the same door the browser uses.
 //
+// Started with `--run-job <name>` it is a CronJob pod instead of a server: it
+// runs that one `jobs/<name>.ts` once for the current minute, the way the
+// in-process scheduler would have, and exits 0 when the handler returned, 1
+// when it threw or the app has no such job. No port is opened, no scheduler
+// or queue loop starts.
+//
 // Environment:
 //   PORT                          the action server's port (default 8080)
 //   ISOMORPH_GATEWAY_URL          the gateway the SDK calls; HARBOUR_GATEWAY_URL
@@ -17,9 +23,17 @@
 //   ISOMORPH_WORKLOAD_TOKEN       the workload's bearer; HARBOUR_WORKLOAD_TOKEN_FILE
 //                                 names a projected token file re-read every minute
 //   ISOMORPH_RUNTIME_MODE=gate    serve actions only: no scheduler, no queue loop
+//   ISOMORPH_JOBS_SCHEDULER=platform
+//                                 the platform runs the cron (one CronJob pod per
+//                                 scheduled job, each `--run-job <name>`): serve
+//                                 actions and work the queue, never tick the
+//                                 in-process scheduler. Set by Provision on the
+//                                 hosted kit-runtime; `isomorph dev` leaves it
+//                                 unset and keeps cron in-process
 //   ISOMORPH_APP_ROOT             the app root (default: the working directory)
 import { createServer } from 'node:http';
 import { readFile, readdir, stat } from 'node:fs/promises';
+import { register } from 'node:module';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createClient, IsomorphError } from './index.js';
@@ -208,14 +222,28 @@ export class Runtime {
         this.log(`serving ${this.inventory.actions.length} action(s) and ${this.inventory.jobs.length} job(s) on port ${port} (${this.options.mode})`);
         if (this.options.tokenFile)
             this.every(TOKEN_REFRESH_MS, () => this.refreshToken());
-        if (this.options.mode === 'full') {
-            if (this.inventory.jobs.some((job) => job.schedule))
-                this.scheduleTick();
-            if (this.inventory.jobs.length > 0 && this.options.gatewayUrl)
-                this.every(QUEUE_POLL_MS, () => this.work());
-        }
+        if (this.options.mode === 'full' && this.inventory.jobs.some((job) => job.schedule))
+            this.scheduleTick();
+        if (this.options.mode !== 'gate' && this.inventory.jobs.length > 0 && this.options.gatewayUrl)
+            this.every(QUEUE_POLL_MS, () => this.work());
         return port;
     }
+    /**
+     * `--run-job <name>`: one scheduled run of one job, as a CronJob pod runs it.
+     * The run is the scheduler's own (`runScheduled`, the current minute as its
+     * tick), so it is loaded, run and recorded exactly as an in-process tick
+     * would have been. False when the app has no such job or the handler threw;
+     * the log names which.
+     */
+    async runJobOnce(name, now = new Date()) {
+        this.inventory = await discover(this.options.root);
+        await this.refreshToken();
+        if (!this.inventory.jobs.some((job) => job.name === name)) {
+            this.log(`this app has no ${JOBS_DIR}/${name}.ts`);
+            return false;
+        }
+        return this.runScheduled(name, new Date(Math.floor(now.getTime() / 60_000) * 60_000));
+    }
     async stop() {
         this.stopped = true;
         for (const timer of this.timers)
@@ -266,20 +294,23 @@ export class Runtime {
             this.scheduleTick();
         }, Math.max(0, next - now)));
     }
+    /** One scheduled run; true when the handler returned, false when it threw or the last tick's run is still going. */
     async runScheduled(name, at) {
         const key = `schedule:${name}`;
         if (this.running.has(key)) {
             this.log(`jobs/${name}.ts is still running; the ${at.toISOString()} tick is skipped`);
-            return;
+            return false;
         }
         this.running.add(key);
         try {
             const handler = await loadHandler(this.options.root, JOBS_DIR, name);
             await handler({ scheduledAt: at.toISOString(), progress: async () => undefined, cancelled: async () => false });
             this.log(`jobs/${name}.ts ran for ${at.toISOString()}`);
+            return true;
         }
         catch (error) {
             this.log(`jobs/${name}.ts failed for ${at.toISOString()}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
         }
         finally {
             this.running.delete(key);
@@ -393,12 +424,27 @@ export function optionsFromEnvironment(env = process.env) {
         root: resolve(env.ISOMORPH_APP_ROOT || process.cwd()),
         port: Number(env.PORT || 8080),
         gatewayUrl: (env.ISOMORPH_GATEWAY_URL || env.HARBOUR_GATEWAY_URL || '').replace(/\/$/, ''),
-        mode: env.ISOMORPH_RUNTIME_MODE === 'gate' ? 'gate' : 'full',
+        mode: env.ISOMORPH_RUNTIME_MODE === 'gate' ? 'gate' : env.ISOMORPH_JOBS_SCHEDULER === 'platform' ? 'actions' : 'full',
         tokenFile: env.HARBOUR_WORKLOAD_TOKEN_FILE || undefined,
     };
 }
+/** The job named by `--run-job <name>` or `--run-job=<name>`; undefined when the runtime is a server. */
+export function runJobFromArguments(argv = process.argv.slice(2)) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const argument = argv[i];
+        if (argument === '--run-job')
+            return argv[i + 1] ?? '';
+        if (argument.startsWith('--run-job='))
+            return argument.slice('--run-job='.length);
+    }
+    return undefined;
+}
 const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : '';
 if (import.meta.url === entry) {
+    // Extensionless relative imports in the app's server code resolve to
+    // their .ts files (runtime-hooks.ts); registered before any app module
+    // is imported.
+    register('./runtime-hooks.js', import.meta.url);
     const options = optionsFromEnvironment();
     if (options.gatewayUrl && !process.env.ISOMORPH_GATEWAY_URL)
         process.env.ISOMORPH_GATEWAY_URL = options.gatewayUrl;
@@ -407,6 +453,14 @@ if (import.meta.url === entry) {
         process.exit(2);
     }
     const runtime = new Runtime(options);
+    const job = runJobFromArguments();
+    if (job !== undefined) {
+        if (!job) {
+            console.error('isomorph runtime: --run-job needs a job name');
+            process.exit(2);
+        }
+        process.exit((await runtime.runJobOnce(job)) ? 0 : 1);
+    }
     const shutdown = () => { void runtime.stop().then(() => process.exit(0)); };
     process.on('SIGTERM', shutdown);
     process.on('SIGINT', shutdown);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "type": "module",
   "repository": {
     "type": "git",