@isomorph.ai/cli 0.9.5 → 0.10.0

package/dist/packages/harbour-cli/src/agent-setup.js

@@ -104,7 +104,7 @@ This guide is for one job: an app that runs on Isomorph (a folder with \`.isomor
 
 The person may not be a developer: they say what they want in plain English; you build it and run every command (they type none but the sign-in below). Use \`--json\`; never paste JSON, logs or file contents at them.
 
-Rules live beside this file: \`core.md\` before the first edit; \`integrations.md\`, \`ai.md\`, \`jobs.md\` before the work each names.
+Rules live beside this file: \`core.md\` before the first edit; \`integrations.md\`, \`ai.md\`, \`jobs.md\`, \`server.md\` before the work each names.
 
 ## Getting ready
 
@@ -124,6 +124,7 @@ Rules live beside this file: \`core.md\` before the first edit; \`integrations.m
 | "make it live" | only after they have tried the preview: \`isomorph promote --operation <ref> --app-root . --confirm-tested --json\`. Report the production link, or that operator approval is pending. |
 | "stop it" | \`isomorph stop --app-root .\` (data kept); \`isomorph dev --app-root . --reset\` only when they ask to start over. |
 | "every day at 2pm", "send this automatically" | read \`jobs.md\` beside this skill first (a job cannot email as a person); write the job, run it once with \`isomorph jobs run\`, and say its sentence. |
+| "call this API", "a key for it", "run it in the background" | read \`server.md\` beside this skill first; server code goes in \`actions/\` or \`jobs/\`, a key by its name only. |
 
 A refusal names its layer, its reason and its fix: change that one thing, then run it again. A wait timeout is not a failure — work is still running: run the command it prints (\`${continueCommand("<ref>")}\`); never start a second deploy while one is running.
 

package/dist/packages/harbour-cli/src/dev.js

@@ -3,10 +3,10 @@ import { closeSync, openSync } from "node:fs";
 import { mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createForwarder } from "./forwarder.js";
-import { readKitLock } from "./kit.js";
 import { GovernanceClient, ensureLinkedApp, fileDeclaredRequests, IDENTITY_WORDS, renderGrantGroup } from "./integrations.js";
-import { acquireDevLock, allocatePorts, assertMigrationNames, installDependencies, LocalRuntime, nodePackageCommand, pidAlive, readDevLock, recordDevChildren, releaseDevLock, runCommand } from "./local-runtime.js";
-import { accessDigest, kitPaths } from "./kit.js";
+import { acquireDevLock, allocatePorts, assertMigrationNames, installDependencies, LocalRuntime, nodePackageCommand, pidAlive, readDevLock, recordDevChildren, releaseDevLock, runCommand, hasServerModules } from "./local-runtime.js";
+import { accessDigest, kitPaths, readDeclaration, readKitLock } from "./kit.js";
+import { startJobFixture } from "./job-fixture.js";
 import { CliError, safeError } from "./output.js";
 /**
  * Signed in at startup: link the app and file the access request for every
@@ -95,10 +95,12 @@ export async function startDev(root, options) {
     await acquireDevLock(root, ports);
     let vite;
     let forwarder;
+    let fixture;
     const stop = async () => {
         forwarder?.close();
         vite?.kill("SIGTERM");
         await runtime.stop();
+        await fixture?.close();
         await releaseDevLock(root);
     };
     try {
@@ -119,11 +121,20 @@ export async function startDev(root, options) {
         // table exists; nothing to create or restart.
         if (watched > 0)
             options.output(`Installed the Isomorph realtime outbox for ${watched} table(s) (isomorph.realtime change events).`);
+        await runtime.installJobRuns();
         const origin = `http://127.0.0.1:${ports.origin}`;
+        // The app's server side: the kit runtime behind a loopback of its own in
+        // front of the session's gateway (job-fixture.ts: canned AI, company
+        // systems refused), exactly what `isomorph jobs run` gives one job.
+        if (await hasServerModules(root)) {
+            fixture = await startJobFixture({ upstreamPort: ports.gateway, real: false, declaration: await readDeclaration(root) });
+            if (await runtime.startKitRuntime(session, fixture.url, options.output))
+                options.output("Started the app's server side (actions/ and jobs/) on the kit runtime.");
+        }
         const npm = nodePackageCommand("npm", ["run", "dev", "--", ...viteDevArguments(ports.vite)]);
         vite = spawn(npm.command, npm.args, { cwd: root, env: { ...env, ISOMORPH_LOCAL_ORIGIN: origin, ISOMORPH_VITE_PORT: String(ports.vite) }, stdio: ["ignore", "inherit", "inherit"] });
         vite.on("error", () => options.output("Vite could not be started; is npm installed and `npm install` done?"));
-        await recordDevChildren(root, { ...(vite.pid ? { vite: vite.pid } : {}), ...(runtime.gatewayPid ? { gateway: runtime.gatewayPid } : {}) });
+        await recordDevChildren(root, { ...(vite.pid ? { vite: vite.pid } : {}), ...(runtime.gatewayPid ? { gateway: runtime.gatewayPid } : {}), ...(runtime.runtimePid ? { runtime: runtime.runtimePid } : {}) });
         const company = options.company;
         let warnedAuth = false;
         let lockAppId = (await readKitLock(root))?.appId || undefined;

package/dist/packages/harbour-cli/src/guide.js

@@ -13,7 +13,7 @@ export const GUIDE_MODULES = {
 
 ## The SDK is the only door
 
-\`@isomorph.ai/app-sdk\` (exported by \`src/isomorph.client.ts\`) is the whole path: \`isomorph.identity.current()\`, \`isomorph.data.from(table)\`, \`isomorph.files.*\`, \`isomorph.realtime.*\`, \`isomorph.integrations.execute\` (integrations.md), \`isomorph.ai.chat\` (ai.md). No database, bucket or company URL from browser code; no backend, auth library, deployment config, provider key or other SDK; no secrets, tokens, \`.env\` values or fetched company content in source. Commit \`.isomorph/\`, never \`.isomorph/local/\`.
+\`@isomorph.ai/app-sdk\` (exported by \`src/isomorph.client.ts\`) is the whole path: \`isomorph.identity.current()\`, \`isomorph.data.from(table)\`, \`isomorph.files.*\`, \`isomorph.realtime.*\`, \`isomorph.integrations.execute\` (integrations.md), \`isomorph.ai.chat\` (ai.md), \`isomorph.actions.invoke\` and \`isomorph.jobs.*\` (server.md). No database, bucket or company URL from browser code; no other backend, auth library, deployment config, provider key or other SDK; no secrets, tokens, \`.env\` values or fetched company content in source. Commit \`.isomorph/\`, never \`.isomorph/local/\`.
 
 ## Identity
 
@@ -82,7 +82,7 @@ A send (\`slack.message.post\`, \`gmail.message.send\`) runs only from an explic
 \`execute("company-slack", { …, mode: "app" })\` posts as the bot under \`slack.displayName\`/\`iconEmoji\` in \`.isomorph/app.json\`; \`mode: "user"\` posts as the person after consent (\`USER_RECONNECT_REQUIRED\`: offer Connect again). One mode per connection (\`MODE_REQUIRED\`); an unapproved mode is \`MODE_NOT_GRANTED\`, never swapped. \`RESOURCE_NOT_APPROVED\` on a post: the bot is not in the channel; \`/invite @Isomorph AI\`.`,
     ai: `# Governed AI
 
-AI goes through \`isomorph.ai\` only: one \`isomorph.ai.chat({ messages, maxTokens })\` call on the app's one client (\`src/isomorph.client.ts\`), never through a wrapper function (the gate reads only the direct call), behind a control the person presses — never on load, in an effect or a timer. Never add an OpenAI/Anthropic/Gemini key, SDK or URL: the governed AI gateway holds the key and IT sees every call. Send \`messages\` and \`maxTokens\` and nothing else; a refusal with \`unsupported_request_capability\` names a field the company's AI route does not accept — remove that field. A refusal with \`AI_NOT_ENABLED\` means IT has not enabled an AI provider yet: say so in one line and keep the app working without AI.
+AI goes through \`isomorph.ai\` only: one \`isomorph.ai.chat({ messages, maxTokens })\` call on the app's one client (\`src/isomorph.client.ts\`), never through a wrapper function (the gate reads only the direct call), behind a control the person presses when called from the browser — never on page load, in an effect or a browser timer; server code (server.md) may call it as the app. Never add an OpenAI/Anthropic/Gemini key, SDK or URL: the governed AI gateway holds the key and IT sees every call. Send \`messages\` and \`maxTokens\` and nothing else; a refusal with \`unsupported_request_capability\` names a field the company's AI route does not accept — remove that field. A refusal with \`AI_NOT_ENABLED\` means IT has not enabled an AI provider yet: say so in one line and keep the app working without AI.
 
 \`\`\`ts
 const reply = await isomorph.ai.chat({ messages: [{ role: "user", content: \`Summarise these notes in three lines:\\n\${notes.map(n => n.title).join("\\n")}\` }], maxTokens: 200 });
@@ -93,9 +93,24 @@ The starter calls no AI; add the one call when the person asks. The check's gene
 
 A job runs as the app, never as a person: Gmail and user-mode Slack cannot run in one; \`slack.message.post\` declared \`"identity": "app"\` and warehouse reads can. Say so before building a scheduled email.
 
-Scheduled work lives only in \`jobs/<name>.ts\`: export one literal UTC cron as \`schedule\` and one default async handler. Never use \`setInterval\`, an effect or a browser timer as a scheduler; Isomorph runs the same declaration automatically after deployment, and the deployed Kubernetes schedule owns the real clock. Test it immediately: start \`isomorph dev\`, then \`isomorph jobs run <name> --app-root . --scheduled-at <matching-UTC-time> --json\` — local data, canned AI, company systems refused, nothing sent. Use \`--real\` only when the person explicitly asks to test the company action now and the exact action has development approval.
+Scheduled work lives only in \`jobs/<name>.ts\`: export one literal UTC cron as \`schedule\` and one default async handler. Never use \`setInterval\`, an effect or a browser timer as a scheduler; Isomorph runs the same declaration automatically after deployment on the app's server process, which owns the real clock. A job may call \`isomorph.ai.chat\` and app-identity company operations. A job with no \`schedule\` runs only when enqueued (server.md). Test it immediately: start \`isomorph dev\`, then \`isomorph jobs run <name> --app-root . --scheduled-at <matching-UTC-time> --json\` — local data, canned AI, company systems refused, nothing sent. Use \`--real\` only when the person explicitly asks to test the company action now and the exact action has development approval.
 
 A real scheduled send requires the person's explicit request, the exact operation and destination declared in \`.isomorph/integrations.json\`, and a grant for that environment; use one deterministic idempotency key for the business period and destination so a replay does not silently repost.
 
-Tell them: "Your scheduled task is ready. I can test the app on your computer now. Company messages will start after the app is online and access is approved."`
+Tell them: "Your scheduled task is ready. I can test the app on your computer now. Company messages will start after the app is online and access is approved."`,
+    server: `# Server code: actions, queued runs, outside APIs
+
+Isomorph runs one server process for the app, started by \`isomorph dev\`, the check and the deployment. It serves \`actions/<name>.ts\` and \`jobs/<name>.ts\`; both use the same \`isomorph\` client and nothing else — no database driver, no \`process.env.DATABASE_URL\`, no HTTP framework.
+
+## Actions
+
+\`actions/<name>.ts\` exports one default async handler \`(input, ctx)\`; \`ctx.user\` is the signed-in person, \`ctx.tenant\` and \`ctx.app\` the app. The browser calls it as \`isomorph.actions.invoke("<name>", input)\` — a string literal, the file's name; the check refuses a name with no file. Names starting with \`isomorph-\` are Isomorph's own.
+
+## Queued runs
+
+For work the person starts and waits on: \`isomorph.jobs.enqueue("<job>", input)\` answers \`{ id }\`; \`isomorph.jobs.get(id)\` shows \`status\` (queued, running, succeeded, failed, cancelled), \`progress\`, \`note\`, \`result\`; \`isomorph.jobs.cancel(id)\`. The job's handler receives \`input\`, \`runId\`, \`progress(percent, note)\` and \`cancelled()\`; a failed run is retried three times. Poll \`get\` from the page to show progress.
+
+## Outside APIs and keys
+
+A key is read as \`process.env.<NAME>\` in server code only, its name listed in \`.env.example\`, never a value in source or in browser code. On this machine put \`NAME=value\` in \`.isomorph/local/secrets.env\`; after deployment Isomorph asks IT for the value once. Vendor SDKs (a payments or email client) follow the same rule from server code. Not available: a route the outside world calls (webhooks) and a sign-in flow with another provider — say so and ask before designing around them.`
 };

package/dist/packages/harbour-cli/src/jobs.js

@@ -2,11 +2,12 @@ import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { CliError } from "./output.js";
-import { parseSessionEnv, readDevLock, runCommand } from "./local-runtime.js";
+import { parseSessionEnv, readDevLock, readLocalSecrets, runCommand } from "./local-runtime.js";
 import { kitPaths, readDeclaration } from "./kit.js";
 import { personRefusal, runsAsPerson, startJobFixture } from "./job-fixture.js";
 const jobName = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 const scheduleDeclaration = /^export\s+const\s+schedule\s*=\s*["']([^"']+)["']\s*;?\s*$/m;
+const scheduleExport = /\bexport\s+const\s+schedule\b/;
 export async function discoverJobs(root) {
     const directory = join(root, "jobs");
     const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
@@ -19,12 +20,14 @@ export async function discoverJobs(root) {
             throw new CliError("JOB_INVALID", `jobs/${entry.name}: the file name must be a lowercase logical name.`);
         const path = join(directory, entry.name);
         const source = await readFile(path, "utf8");
+        // A schedule is optional (a job without one runs only when enqueued);
+        // a declared one must be a literal, so the clock reads what was written.
         const schedule = source.match(scheduleDeclaration)?.[1];
-        if (!schedule)
+        if (!schedule && scheduleExport.test(source))
             throw new CliError("JOB_INVALID", `jobs/${entry.name}: export one literal schedule, for example export const schedule = \"0 9 * * 1-5\".`);
         if (!/^export\s+default\s+/m.test(source))
             throw new CliError("JOB_INVALID", `jobs/${entry.name}: export one default job handler.`);
-        jobs.push({ name, schedule, path });
+        jobs.push({ name, ...(schedule ? { schedule } : {}), path });
     }
     return jobs.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -41,7 +44,7 @@ export async function runJob(root, name, scheduledAt, run = runCommand, real = f
     const lock = await readDevLock(root);
     if (!session || !lock)
         throw new CliError("DEV_NOT_RUNNING", "Start `isomorph dev` before running a job so it uses the same local data and identity boundary.");
-    const env = parseSessionEnv(session);
+    const env = { ...parseSessionEnv(session), ...(await readLocalSecrets(root)) };
     const runner = `const module = await import(${JSON.stringify(pathToFileURL(job.path).href)}); if (typeof module.default !== "function") throw new Error("job has no default handler"); await module.default({scheduledAt: process.env.ISOMORPH_SCHEDULED_AT});`;
     // The job talks to a loopback origin of its own (job-fixture.ts) in front of
     // the session's gateway, or of the dev origin under `--real`.
@@ -55,7 +58,7 @@ export async function runJob(root, name, scheduledAt, run = runCommand, real = f
     }
     if (result.code !== 0)
         throw new CliError("JOB_FAILED", `Job ${name} failed: ${jobFailureReason(result.stderr)}`, undefined, "Fix what the error names in jobs/<name>.ts, then run this again; `details.stderr` carries the last lines.", undefined, { details: { stderr: result.stderr.trim().split("\n").slice(-20) } });
-    return { name, schedule: job.schedule, scheduledAt: timestamp, mode: real ? "real" : "local" };
+    return { name, ...(job.schedule ? { schedule: job.schedule } : {}), scheduledAt: timestamp, mode: real ? "real" : "local" };
 }
 /**
  * The line of a failed job's stderr that says what went wrong. Node prints

package/dist/packages/harbour-cli/src/kit-bundle.manifest.js

@@ -1,28 +1,28 @@
 export const PUBLISHED_KIT_BUNDLE = {
     "schema": "isomorph.kit-bundle/1.0",
-    "kitVersion": "0.9.5",
+    "kitVersion": "0.10.0",
     "sdk": {
         "package": "@isomorph.ai/app-sdk",
-        "version": "1.2.2",
-        "tarballSha256": "8953bb7eb6846bcddf48fd5407c098a13c8ad2cf249d702c35b5666d5af0ad53",
-        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:8953bb7eb6846bcddf48fd5407c098a13c8ad2cf249d702c35b5666d5af0ad53"
+        "version": "1.3.0",
+        "tarballSha256": "8e134408de3113d63e704685be4ed841e20a3b4cc0b5ccfedaa997da1d86cc72",
+        "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:8e134408de3113d63e704685be4ed841e20a3b4cc0b5ccfedaa997da1d86cc72"
     },
     "images": {
-        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:b17015a157a1088cb9f8018ece85836771214973fd7cd7bda0eb665f6f3d9882",
-        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:0ea09cffdb5fce2347253912eca7980dccedd4c6b0be528760634a648c2db096"
+        "appGateway": "public.ecr.aws/y6t4p3i8/harbour-app-gateway@sha256:8ab5a1d63704761379c4cac74a8415875476aa3febbab39054e980398c071e03",
+        "sessionFixture": "public.ecr.aws/y6t4p3i8/harbour-session-fixture@sha256:f44a7e13b48053c4984fd499ae83251420987fab7eadc5737212a143b1b3f049"
     },
     "nativeRuntime": {
         "darwinArm64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:1550be418b37f207cf2d0f2446dfe92a71cb1c1704b8d040f13e07f236611d9d",
-            "sha256": "1550be418b37f207cf2d0f2446dfe92a71cb1c1704b8d040f13e07f236611d9d"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:7bc2a1df6b02105f49eda825430ca0719482c4a2a06b26c333493ed80f2cf1eb",
+            "sha256": "7bc2a1df6b02105f49eda825430ca0719482c4a2a06b26c333493ed80f2cf1eb"
         },
         "linuxX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:7d49f0ed9cd274117108e97a3f076aa02f7b281aaf2726aa856b2c660d57f7eb",
-            "sha256": "7d49f0ed9cd274117108e97a3f076aa02f7b281aaf2726aa856b2c660d57f7eb"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:3737565cdf396e7747e2e5dccc028b88cc05c1505ef369f517363570e266010c",
+            "sha256": "3737565cdf396e7747e2e5dccc028b88cc05c1505ef369f517363570e266010c"
         },
         "windowsX64": {
-            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:629172baf63a6c5e92fbd16453eb00888cedfbb39fd05de3c3e6f7daca6220aa",
-            "sha256": "629172baf63a6c5e92fbd16453eb00888cedfbb39fd05de3c3e6f7daca6220aa"
+            "url": "https://public.ecr.aws/v2/y6t4p3i8/harbour-kit-bundle/blobs/sha256:e7232bf46d03c7bb7598276c0d0d45f65fd9633762dc8051efef339b5115c0b0",
+            "sha256": "e7232bf46d03c7bb7598276c0d0d45f65fd9633762dc8051efef339b5115c0b0"
         }
     },
     "brief": {

package/dist/packages/harbour-cli/src/local-runtime.js

@@ -89,7 +89,13 @@ export function nativeGatewayConfig(project, ports, stateDir) {
         ...config.bindings[0],
         databaseUrl: `postgresql://${LOCAL.gatewayRole}:${LOCAL.dbPassword}@127.0.0.1:${ports.postgres}/${LOCAL.database}?sslmode=disable`,
         publicBaseUrl: `http://127.0.0.1:${ports.origin}`,
-        localFilesDirectory: join(stateDir, "files")
+        localFilesDirectory: join(stateDir, "files"),
+        // The app's own server side (actions/, jobs/) is the kit runtime on its
+        // port; the gateway forwards /_harbour/actions/<name> there with the
+        // verified identity, as the hosted gateway does. An app with no server
+        // modules has no runtime and the route answers "unavailable".
+        capabilities: ["data", "files", "realtime", "telemetry", "actions"],
+        actionBaseUrl: `http://127.0.0.1:${ports.runtime}`
     };
     config.localSession = {
         ...config.localSession,
@@ -128,8 +134,8 @@ export async function freePort() {
     });
 }
 export async function allocatePorts() {
-    const [postgres, minio, gateway, vite, origin] = await Promise.all([freePort(), freePort(), freePort(), freePort(), freePort()]);
-    return { postgres: postgres, minio: minio, gateway: gateway, vite: vite, origin: origin };
+    const [postgres, minio, gateway, vite, origin, runtime] = await Promise.all([freePort(), freePort(), freePort(), freePort(), freePort(), freePort()]);
+    return { postgres: postgres, minio: minio, gateway: gateway, vite: vite, origin: origin, runtime: runtime };
 }
 /** Acquires `.isomorph/local/dev.lock`; a lock whose process is gone is stale and replaced. */
 export async function acquireDevLock(root, ports, isAlive = pidAlive) {
@@ -185,11 +191,82 @@ catch {
     return false;
 } }
 // ---- Native lifecycle -----------------------------------------------------------------
+/**
+ * The platform-owned runs table the kit runtime works (app-sdk runtime.ts):
+ * one row per enqueued run, readable and writable by the person who started
+ * it and by the workload identity the runtime calls the gateway as. Applied
+ * after the app's migrations by `isomorph dev`; the deployment pipeline
+ * appends the same text (byte for byte — tests/cli-job-runs.test.ts pins its
+ * digest) to the app's migrations as 9999_zzzz_isomorph_job_runs.sql.
+ */
+export const JOB_RUNS_MIGRATION = `CREATE TABLE IF NOT EXISTS public.isomorph_job_runs (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  job text NOT NULL,
+  input jsonb,
+  status text NOT NULL DEFAULT 'queued',
+  attempt integer NOT NULL DEFAULT 0,
+  max_attempts integer NOT NULL DEFAULT 3,
+  progress integer NOT NULL DEFAULT 0,
+  note text,
+  result jsonb,
+  error text,
+  owner_subject text NOT NULL,
+  cancel_requested boolean NOT NULL DEFAULT false,
+  lease_until timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS isomorph_job_runs_queue ON public.isomorph_job_runs (status, created_at);
+ALTER TABLE public.isomorph_job_runs ENABLE ROW LEVEL SECURITY;
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname = 'public' AND tablename = 'isomorph_job_runs' AND policyname = 'isomorph_job_runs_access') THEN
+    CREATE POLICY isomorph_job_runs_access ON public.isomorph_job_runs
+      USING (owner_subject = current_setting('harbour.user_id', true) OR current_setting('harbour.user_id', true) LIKE 'workload:%')
+      WITH CHECK (owner_subject = current_setting('harbour.user_id', true) OR current_setting('harbour.user_id', true) LIKE 'workload:%');
+  END IF;
+END $$;
+`;
+/** The kit runtime inside the app's installed SDK (app-sdk runtime.ts). */
+export const KIT_RUNTIME_SCRIPT = "node_modules/@isomorph.ai/app-sdk/dist/runtime.js";
+/** Whether the app has server-side modules for the kit runtime to serve. */
+export async function hasServerModules(root) {
+    for (const dir of ["actions", "jobs"]) {
+        const entries = await readdir(join(root, dir)).catch(() => []);
+        if (entries.some(name => name.endsWith(".ts")))
+            return true;
+    }
+    return false;
+}
+/**
+ * `.isomorph/local/secrets.env`: `NAME=value` lines (an optional `export `,
+ * `#` comments, single or double quotes around the value), the values a
+ * builder's server code reads as `process.env.NAME` on their machine. The
+ * file is under the git-ignored local directory; deployed, the same names are
+ * the secrets IT sets.
+ */
+export async function readLocalSecrets(root) {
+    const text = await readFile(join(kitPaths(root).local, "secrets.env"), "utf8").catch(() => "");
+    const values = {};
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        let value = match[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+            value = value.slice(1, -1);
+        values[match[1]] = value;
+    }
+    return values;
+}
 export class LocalRuntime {
     root;
     run;
     project;
     postgres;
+    kitRuntime;
     windowsPgCtl;
     gateway;
     gates = new Map();
@@ -203,6 +280,36 @@ export class LocalRuntime {
     }
     /** The App Gateway process this runtime started, for the dev lock. */
     get gatewayPid() { return this.gateway?.pid; }
+    get runtimePid() { return this.kitRuntime?.pid; }
+    /**
+     * Starts the app's kit runtime (its actions and jobs) with node, the way
+     * the hosted pod and the gate run it: from the app root, the session's
+     * identities and workload token in its environment, the local secrets, and
+     * the gateway it talks to. Answers false when the installed SDK has no
+     * runtime (a kit older than 0.10.0): the app runs without server code.
+     */
+    async startKitRuntime(env, gatewayUrl, output) {
+        if (!this.ports)
+            throw new CliError("LOCAL_RUNTIME_FAILED", "The local runtime was not prepared.");
+        const script = join(this.root, ...KIT_RUNTIME_SCRIPT.split("/"));
+        if (!(await exists(script))) {
+            output?.("The app's SDK has no kit runtime, so actions/ and jobs/ are not served; run `isomorph init --upgrade`.");
+            return false;
+        }
+        const secrets = await readLocalSecrets(this.root);
+        this.kitRuntime = spawn(process.execPath, ["--experimental-strip-types", script], {
+            cwd: this.root,
+            env: { ...process.env, ...env, ...secrets, PORT: String(this.ports.runtime), ISOMORPH_GATEWAY_URL: gatewayUrl, ISOMORPH_APP_ROOT: this.root, NODE_NO_WARNINGS: "1" },
+            stdio: ["ignore", "inherit", "inherit"]
+        });
+        return true;
+    }
+    /** Applies the platform-owned runs table (JOB_RUNS_MIGRATION); idempotent. */
+    async installJobRuns() {
+        const result = await this.psql(JOB_RUNS_MIGRATION);
+        if (result.code !== 0)
+            throw new CliError("MIGRATION_FAILED", `The Isomorph runs table could not be created: ${result.stderr.trim().split("\n").at(-1) ?? "psql error"}`);
+    }
     async writeFiles(bundle, ports) {
         const paths = kitPaths(this.root);
         await mkdir(paths.state, { recursive: true });
@@ -308,6 +415,7 @@ export class LocalRuntime {
      * address pools have been fully subnetted").
      */
     async down() {
+        this.kitRuntime?.kill("SIGTERM");
         this.gateway?.kill("SIGTERM");
         for (const child of this.gates.values())
             child.kill("SIGTERM");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/cli",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "description": "Isomorph development kit CLI",
   "type": "module",
   "bin": {
@@ -38,7 +38,7 @@
   "harbour": {
     "kitBundle": {
       "repository": "public.ecr.aws/y6t4p3i8/harbour-kit-bundle",
-      "version": "0.9.5"
+      "version": "0.10.0"
     }
   }
 }