@owlmeans/viable-sdk 0.1.18-rc.1

package/build/executor/git.js

@@ -0,0 +1,353 @@
+import { execFile } from 'node:child_process';
+import fsp from 'node:fs/promises';
+import p from 'node:path';
+import { SlotGitCommand } from '@owlmeans/viable-common';
+import { GitDirtyTree, LocalGitError } from './errors.js';
+import { MAX_OUTPUT_BUFFER } from './spawn.js';
+/**
+ * The git half of the local executor, over the `git` CLI.
+ *
+ * The platform's own implementation is `@owlmeans/git`, which is private and carries `simple-git`
+ * and a GitHub client — neither of which may reach a package a developer installs to drive their
+ * own machine. So the semantics are ported and the two constants below are copied, with this
+ * comment as the record of where they came from: a connector that invented its own author name
+ * would produce a history that does not match what the platform writes for the same project in a
+ * slot.
+ */
+const DEFAULT_BRANCH = 'main';
+const DEFAULT_GIT_USER_NAME = 'OwlMeans Viable';
+const DEFAULT_GIT_USER_EMAIL = 'agent@owlmeans.com';
+const LOG_LIMIT = 20;
+const STATUS_FILES_CAP = 50;
+/**
+ * The runtime safety net `ensure` appends, so a first commit never captures dependencies, build
+ * output, secrets or the connector's own scratch files.
+ *
+ * `.viable/connect.json` is deliberately NOT here: it is the project's identity, it holds no
+ * secret, and a developer who clones their own repository elsewhere should find it. The two files
+ * beside it are — a run record names pids on one machine, and the local keypair is a credential.
+ */
+const IGNORE_BASELINE = [
+    'node_modules/',
+    'dist/',
+    'build/',
+    '.env',
+    '.viable/run.json',
+    '.viable/local.json',
+    'tsconfig.tsbuildinfo',
+];
+/**
+ * Why a local repository is never pushed, pulled or given a remote.
+ *
+ * DELIBERATE DIFFERENCE from the publisher, which does all three against a token the platform
+ * holds. A slot's volume is the platform's and its remote is a repository the platform created;
+ * a developer's checkout is THEIRS, its remote is whatever they configured, and pushing to it
+ * would mean the platform writing to a repository nobody here was asked about — with the
+ * developer's own credential helper supplying the authentication. So the platform touches none
+ * of it: whoever owns the directory owns its remotes.
+ */
+const REMOTE_REFUSAL = 'This project lives on your own machine, so the platform does not touch its '
+    + 'git remotes. Push, pull and remote configuration are yours to run.';
+/**
+ * Why a local target is never cloned into.
+ *
+ * A clone exists for one case — the platform fetching an origin repository onto a slot's volume it
+ * owns — and a local target has already answered that question: the directory the connector was
+ * started in IS the origin, and there is nothing to fetch. Overwriting it with a remote tree would
+ * replace a developer's working copy, including whatever they had not committed.
+ *
+ * Answered as TEXT beside {@link REMOTE_REFUSAL} and never thrown, for the same reason: a caller
+ * that received an exception would retry something that can never succeed, while a `cloned: false`
+ * in the shape it already parses is a fact its next step can read.
+ */
+const CLONE_REFUSAL = 'This project is the directory the connector was started in, so there is '
+    + 'nothing to clone into it. Its sources are already here.';
+/**
+ * Tail of the serialization chain per working directory.
+ *
+ * Git takes `.git/*.lock` files for the duration of a write, so two concurrent operations on one
+ * repository fail with `could not lock config file .git/config: File exists`. That is not
+ * hypothetical: every command here calls `ensure()` first, and two unsynchronized producers
+ * routinely overlap — an explicit status call and whatever status the connector rides along with
+ * its own reporting.
+ */
+const _chains = new Map();
+const serialize = async (dir, op) => {
+    // Chain onto whatever is already queued for this dir, running `op` whether the previous command
+    // resolved or rejected so one failure never poisons the queue behind it.
+    const previous = _chains.get(dir) ?? Promise.resolve();
+    const result = previous.then(op, op);
+    const tail = result.then(() => undefined, () => undefined);
+    _chains.set(dir, tail);
+    // Drop the entry once nothing else has queued behind it, so the map cannot grow without bound.
+    void tail.then(() => {
+        if (_chains.get(dir) === tail) {
+            _chains.delete(dir);
+        }
+    });
+    return await result;
+};
+/**
+ * Run one git command.
+ *
+ * `core.quotePath=false` so a path with a non-ASCII character comes back as itself rather than as
+ * an escaped C string nothing downstream un-escapes. `GIT_TERMINAL_PROMPT=0` so a command that
+ * wants credentials fails instead of blocking on a prompt no one can answer.
+ */
+const git = async (dir, args) => await new Promise(resolve => {
+    execFile('git', ['-c', 'core.quotePath=false', ...args], {
+        cwd: dir,
+        maxBuffer: MAX_OUTPUT_BUFFER,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    }, (error, stdout, stderr) => resolve({ ok: error == null, out: stdout, err: stderr }));
+});
+// Unit separator: it cannot appear in any of the fields, so a subject with tabs or spaces in it
+// still parses.
+const LOG_FORMAT = '--format=%H%x1f%h%x1f%an%x1f%ae%x1f%cI%x1f%s';
+const parseCommits = (out) => out
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line !== '')
+    .map(line => {
+    const [hash, shortHash, authorName, authorEmail, committedAt, ...subject] = line.split('\x1f');
+    return {
+        hash, shortHash, authorName, authorEmail, committedAt, subject: subject.join('\x1f'),
+    };
+});
+const headInfo = async (dir) => {
+    const result = await git(dir, ['log', '-1', LOG_FORMAT]);
+    return result.ok ? parseCommits(result.out)[0] ?? null : null;
+};
+/**
+ * Whether the tree has anything uncommitted, untracked files included.
+ *
+ * Asked before `add -A` rather than after, so a clean tree is reported as clean instead of
+ * producing an empty commit.
+ */
+const isDirty = async (dir) => {
+    const result = await git(dir, ['status', '--porcelain', '-u']);
+    return result.out.trim() !== '';
+};
+const parseStatus = (out) => {
+    const lines = out.split('\n').filter(line => line !== '');
+    let branch = DEFAULT_BRANCH;
+    let ahead = null;
+    let behind = null;
+    const files = [];
+    for (const line of lines) {
+        if (line.startsWith('## ')) {
+            let rest = line.slice(3);
+            const tracking = /\s\[(.+)\]$/.exec(rest);
+            if (tracking != null) {
+                rest = rest.slice(0, tracking.index);
+                const aheadMatch = /ahead (\d+)/.exec(tracking[1]);
+                const behindMatch = /behind (\d+)/.exec(tracking[1]);
+                if (aheadMatch != null)
+                    ahead = parseInt(aheadMatch[1]);
+                if (behindMatch != null)
+                    behind = parseInt(behindMatch[1]);
+                // A branch with an upstream but no divergence reports neither word; both are zero.
+                if (aheadMatch == null && behindMatch == null && !/gone/.test(tracking[1])) {
+                    ahead = 0;
+                    behind = 0;
+                }
+            }
+            // `## No commits yet on main` is what an unborn branch says about itself.
+            branch = rest.split('...')[0].replace(/^No commits yet on /, '').trim();
+            if (branch === '' || branch === 'HEAD (no branch)')
+                branch = DEFAULT_BRANCH;
+            continue;
+        }
+        const status = `${line[0] ?? ''}${line[1] ?? ''}`.trim();
+        const raw = line.slice(3);
+        // A rename reads `R  old -> new`; the new path is the one that exists.
+        const path = raw.includes(' -> ') ? raw.slice(raw.indexOf(' -> ') + 4) : raw;
+        files.push({ path, status });
+    }
+    return { branch, files, ahead, behind };
+};
+/**
+ * Ahead/behind against the remote-tracking ref, when porcelain did not say.
+ *
+ * A branch with no upstream configured still has an `origin/<branch>` ref after a fetch, and that
+ * is what a caller wants to know about.
+ */
+const localCounts = async (dir, branch) => {
+    const result = await git(dir, [
+        'rev-list', '--left-right', '--count', `${branch}...origin/${branch}`
+    ]);
+    if (!result.ok) {
+        return { ahead: null, behind: null };
+    }
+    const parts = result.out.trim().split(/\s+/);
+    return parts.length === 2
+        ? { ahead: parseInt(parts[0]), behind: parseInt(parts[1]) }
+        : { ahead: null, behind: null };
+};
+/**
+ * Make the directory a repository the platform can work in, and change nothing else.
+ *
+ * DELIBERATE DIFFERENCE from the publisher on two points, both because this history belongs to a
+ * person rather than to a slot:
+ *
+ * - **No baseline commit.** The publisher snapshots a pre-git slot into a first commit so its
+ *   history starts clean. Here the first commit is the developer's to make (or not) — a tool that
+ *   committed a working tree it found is a tool that decided what their project's history says.
+ * - **An identity only when there is none.** `git config user.name` consults local, global and
+ *   system, so a developer with a global identity keeps authoring as themselves. Writing the
+ *   platform's name unconditionally would rewrite the author of every commit made in that
+ *   directory afterwards, including ones the platform had nothing to do with.
+ */
+const ensure = async (dir) => {
+    const created = await fsp.stat(p.join(dir, '.git')).then(() => false, () => true);
+    if (created) {
+        const init = await git(dir, ['init', '-b', DEFAULT_BRANCH]);
+        if (!init.ok) {
+            // `-b` arrived in git 2.28; an older one still initializes and is then pointed at `main`.
+            const fallback = await git(dir, ['init']);
+            if (!fallback.ok) {
+                throw new LocalGitError(`git init failed in ${dir}: ${fallback.err.trim()}`);
+            }
+            await git(dir, ['symbolic-ref', 'HEAD', `refs/heads/${DEFAULT_BRANCH}`]);
+        }
+    }
+    for (const [key, value] of [
+        ['user.name', DEFAULT_GIT_USER_NAME], ['user.email', DEFAULT_GIT_USER_EMAIL]
+    ]) {
+        const current = await git(dir, ['config', '--get', key]);
+        if (!current.ok || current.out.trim() === '') {
+            await git(dir, ['config', '--local', key, value]);
+        }
+    }
+    const ignorePath = p.join(dir, '.gitignore');
+    const existing = await fsp.readFile(ignorePath, 'utf8').catch(() => '');
+    const lines = new Set(existing.split('\n').map(line => line.trim()));
+    const missing = IGNORE_BASELINE.filter(entry => !lines.has(entry));
+    if (missing.length > 0) {
+        const prefix = existing === '' || existing.endsWith('\n') ? existing : `${existing}\n`;
+        await fsp.writeFile(ignorePath, `${prefix}${missing.join('\n')}\n`);
+    }
+};
+const status = async (dir) => {
+    const porcelain = await git(dir, ['status', '--porcelain=v1', '-b', '-u']);
+    const { branch, files, ahead, behind } = parseStatus(porcelain.out);
+    const remote = await git(dir, ['remote', 'get-url', 'origin']);
+    const remoteUrl = remote.ok && remote.out.trim() !== '' ? remote.out.trim() : null;
+    const counts = ahead != null || behind != null
+        ? { ahead, behind }
+        : await localCounts(dir, branch);
+    return {
+        initialized: true,
+        head: await headInfo(dir),
+        branch,
+        dirty: files.length > 0,
+        changedFiles: files.length,
+        files: files.slice(0, STATUS_FILES_CAP),
+        remoteUrl,
+        ahead: counts.ahead,
+        behind: counts.behind,
+    };
+};
+export const dispatchGitCommand = async (dir, command, args) => await serialize(dir, async () => await _dispatch(dir, command, args));
+const _dispatch = async (dir, command, args) => {
+    switch (command) {
+        case SlotGitCommand.Ensure:
+            await ensure(dir);
+            return {};
+        case SlotGitCommand.Status:
+            await ensure(dir);
+            return await status(dir);
+        case SlotGitCommand.Commit: {
+            await ensure(dir);
+            if (!await isDirty(dir)) {
+                return { commit: null };
+            }
+            const add = await git(dir, ['add', '-A']);
+            if (!add.ok) {
+                throw new LocalGitError(`git add failed: ${add.err.trim()}`);
+            }
+            const message = typeof args?.message === 'string' && args.message !== ''
+                ? args.message
+                : 'chore: update project';
+            const commit = await git(dir, ['commit', '-m', message]);
+            if (!commit.ok) {
+                throw new LocalGitError(`git commit failed: ${(commit.err || commit.out).trim()}`);
+            }
+            return { commit: await headInfo(dir) };
+        }
+        case SlotGitCommand.Log: {
+            await ensure(dir);
+            const result = await git(dir, ['log', `--max-count=${LOG_LIMIT}`, LOG_FORMAT]);
+            return { commits: result.ok ? parseCommits(result.out) : [] };
+        }
+        case SlotGitCommand.Discard: {
+            await ensure(dir);
+            // On an unborn branch HEAD does not exist — there is nothing to reset to, and a `clean`
+            // there would delete a tree nobody has committed yet.
+            if (await headInfo(dir) == null) {
+                return await status(dir);
+            }
+            await git(dir, ['reset', '--hard', 'HEAD']);
+            // `.viable/` is excluded by name: the marker is what identifies this directory as a
+            // platform project at all, it is untracked until someone commits it, and a discard that
+            // swept it would leave a tree no connector can recognize afterwards.
+            await git(dir, ['clean', '-fd', '-e', '.viable']);
+            return await status(dir);
+        }
+        case SlotGitCommand.RevertTo: {
+            await ensure(dir);
+            const hash = typeof args?.hash === 'string' ? args.hash : '';
+            if (hash === '') {
+                throw new LocalGitError('revert-no-hash');
+            }
+            // A revert overwrites the working tree, so uncommitted work would be lost with no way back.
+            if (await isDirty(dir)) {
+                throw new GitDirtyTree(dir);
+            }
+            const target = await git(dir, ['log', '-1', '--format=%h%x1f%s', hash]);
+            if (!target.ok) {
+                throw new LocalGitError(`invalid-hash:${hash}`);
+            }
+            const [shortHash, ...subjectParts] = target.out.trim().split('\x1f');
+            const subject = subjectParts.join('\x1f');
+            // APPEND-ONLY. `read-tree` restores the old content as a NEW commit on top of the current
+            // history, so nothing that ever happened is unmade — a reset would rewrite history a person
+            // may already have pushed or be working from.
+            const read = await git(dir, ['read-tree', '-u', '--reset', hash]);
+            if (!read.ok) {
+                throw new LocalGitError(`revert-failed: ${read.err.trim()}`);
+            }
+            // Reverting to what HEAD already holds changes nothing; answering with the current head is
+            // the honest result, and an empty commit would only add noise to the history.
+            if (!await isDirty(dir)) {
+                return { commit: await headInfo(dir) };
+            }
+            const commit = await git(dir, ['commit', '-m', `revert: restore ${shortHash} — ${subject}`]);
+            if (!commit.ok) {
+                throw new LocalGitError(`revert-commit-failed: ${(commit.err || commit.out).trim()}`);
+            }
+            const head = await headInfo(dir);
+            if (head == null) {
+                throw new LocalGitError('revert-no-head');
+            }
+            return { commit: head };
+        }
+        // The three that touch a remote. Answered as TEXT rather than thrown: this is a policy, not a
+        // failure, and a caller that treats it as an error would retry something that can never
+        // succeed. The `GitSyncResult` fields travel beside it so a caller reading that shape finds
+        // the fields it expects instead of `undefined`.
+        case SlotGitCommand.SetRemote:
+        case SlotGitCommand.Push:
+        case SlotGitCommand.Pull:
+            return { result: REMOTE_REFUSAL, status: 'no-remote', ahead: null, behind: null, message: REMOTE_REFUSAL };
+        // The fourth, refused in the same shape and for the same reason — see CLONE_REFUSAL. The
+        // convert pipeline skips its clone step on a local target, so this is the belt to that
+        // braces: a command that arrives anyway answers a fact rather than failing a run.
+        case SlotGitCommand.Clone:
+            return { cloned: false, branch: '', head: null, result: CLONE_REFUSAL };
+        default:
+            throw new LocalGitError(`Unknown git command: ${String(command)}`);
+    }
+};
+export { CLONE_REFUSAL, ensure as ensureGitRepo, IGNORE_BASELINE, REMOTE_REFUSAL };
+//# sourceMappingURL=git.js.map

package/build/executor/git.js.map

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

package/build/executor/health.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Reading the target's own health endpoint, and deciding what its answer means.
+ *
+ * Two callers need it and they must agree: the boot check, which waits for a boot to resolve one
+ * way or the other, and the local run's status, which is the only thing that ever notices a target
+ * that came up and then stopped being able to serve. The classifier is pure and the IO is a thin
+ * wrapper over it.
+ */
+/** The shape a target's `/api/healtz` answers with. Every field is optional by contract. */
+export interface TargetHealthBody {
+    phase?: string;
+    error?: string;
+    bootId?: string;
+    db?: {
+        ok?: boolean;
+        error?: string;
+        summary?: string;
+    };
+    /**
+     * The target's own verdict on its job queue store, reported exactly like `db`.
+     *
+     * Absent from every target that has no queue — most of them — so an omitted value means
+     * "nothing to report", never "unhealthy".
+     */
+    valkey?: {
+        ok?: boolean;
+        error?: string;
+        summary?: string;
+    };
+}
+export interface TargetHealthInput {
+    /** Boot id handed to the current child; '' when none was minted. */
+    bootId: string;
+    /** Whether a TCP connect to the port succeeded at all. */
+    listening: boolean;
+    /** HTTP status of the answer; null when the request never completed. */
+    status: number | null;
+    /** Parsed body, or null when there was none or it was not JSON. */
+    body: TargetHealthBody | null;
+    /** Why the request failed, when it did. */
+    failure?: string;
+}
+export interface TargetHealthReading {
+    /** The target says it is serving. */
+    ready: boolean;
+    /** No amount of waiting changes this answer — the caller must act. */
+    terminal: boolean;
+    /** Human-readable cause, '' when ready. */
+    reason: string;
+    /** The answer came from a process this connector did not start. */
+    foreign: boolean;
+    /** The phase the target reported, when it reported one. */
+    phase?: string;
+    dbOk?: boolean;
+    valkeyOk?: boolean;
+}
+/** Where the api answers. The worker has a health port but no api base in front of it. */
+export declare const TARGET_HEALTH_PATH = "/api/healtz";
+/**
+ * What a target's answer means.
+ *
+ * The order of these checks is the contract, not a style choice:
+ *
+ * 1. **Identity outranks health.** A leftover process answering `200 ok` is still a leftover, and
+ *    everything it reports describes the build IT was started with. Terminal, because waiting
+ *    never turns another process's health into ours — the port has to be taken back.
+ * 2. **A non-2xx is a failure even when the body cannot be parsed.** This is what made a target
+ *    answering 503 with an HTML error page read as *ready*: an unparseable body left `phase`
+ *    undefined, and undefined meant "an old target that only listens once it is up".
+ * 3. **A target that says it failed is terminal**, and its own message is the reason.
+ * 4. **A database the target cannot reach is a failure it will not report any other way.** It
+ *    answers `200 {status:'OK'}` with `db.ok: false`, which by rule 2's fallback would also have
+ *    read as ready. Not terminal: a database that went away can come back.
+ * 5. **A queue store it cannot reach is the same failure with a different dependency** — an app
+ *    whose jobs cannot be enqueued serves pages and silently does none of the work behind them.
+ * 6. Only then does a missing phase mean "an older target, and a reachable port is the answer".
+ */
+export declare const classifyTargetHealth: (input: TargetHealthInput) => TargetHealthReading;
+export interface TargetHealthProbes {
+    probe?: (port: number) => Promise<boolean>;
+    fetch?: typeof globalThis.fetch;
+    /** The worker answers the same contract at a path of its own. */
+    path?: string;
+}
+/**
+ * Ask the target how it is, and classify the answer.
+ *
+ * The TCP probe runs first and short-circuits: there is no point spending a request timeout on a
+ * port nothing is listening on, and a target mid-restart is exactly when this is called most.
+ */
+export declare const readTargetHealth: (port: number, bootId: string, timeoutMs: number, probes?: TargetHealthProbes) => Promise<TargetHealthReading>;
+//# sourceMappingURL=health.d.ts.map

package/build/executor/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/executor/health.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,EAAE,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvD;;;;;OAKG;IACH,MAAM,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5D;AAED,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAA;IACd,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAA;IAClB,wEAAwE;IACxE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,mEAAmE;IACnE,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAA;IAC7B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAA;IACd,sEAAsE;IACtE,QAAQ,EAAE,OAAO,CAAA;IACjB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAA;IAChB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,0FAA0F;AAC1F,eAAO,MAAM,kBAAkB,gBAA+B,CAAA;AAQ9D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,UAAW,iBAAiB,KAAG,mBA8D/D,CAAA;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1C,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,SACrB,MAAM,UAAU,MAAM,aAAa,MAAM,WAAU,kBAAkB,KAC1E,OAAO,CAAC,mBAAmB,CAwB7B,CAAA"}

package/build/executor/health.js

@@ -0,0 +1,98 @@
+import { TARGET_API_BASE } from '@owlmeans/viable-common';
+import { probeListening } from './spawn.js';
+/** Where the api answers. The worker has a health port but no api base in front of it. */
+export const TARGET_HEALTH_PATH = `/${TARGET_API_BASE}/healtz`;
+const ok = () => ({ ready: true, terminal: false, reason: '', foreign: false });
+const not = (reason, terminal = false, extra = {}) => ({ ready: false, terminal, reason, foreign: false, ...extra });
+/**
+ * What a target's answer means.
+ *
+ * The order of these checks is the contract, not a style choice:
+ *
+ * 1. **Identity outranks health.** A leftover process answering `200 ok` is still a leftover, and
+ *    everything it reports describes the build IT was started with. Terminal, because waiting
+ *    never turns another process's health into ours — the port has to be taken back.
+ * 2. **A non-2xx is a failure even when the body cannot be parsed.** This is what made a target
+ *    answering 503 with an HTML error page read as *ready*: an unparseable body left `phase`
+ *    undefined, and undefined meant "an old target that only listens once it is up".
+ * 3. **A target that says it failed is terminal**, and its own message is the reason.
+ * 4. **A database the target cannot reach is a failure it will not report any other way.** It
+ *    answers `200 {status:'OK'}` with `db.ok: false`, which by rule 2's fallback would also have
+ *    read as ready. Not terminal: a database that went away can come back.
+ * 5. **A queue store it cannot reach is the same failure with a different dependency** — an app
+ *    whose jobs cannot be enqueued serves pages and silently does none of the work behind them.
+ * 6. Only then does a missing phase mean "an older target, and a reachable port is the answer".
+ */
+export const classifyTargetHealth = (input) => {
+    if (!input.listening) {
+        return not('The target backend is running but never bound its port');
+    }
+    if (input.failure != null) {
+        // A timeout is materially different from a refused connection: the port answered, so
+        // something is there — it just cannot serve its own health endpoint. Say which.
+        const timedOut = /timeout|aborted/i.test(input.failure);
+        return not(timedOut
+            ? 'The target backend bound its port but its health endpoint did not answer in time'
+            : `The target backend health check failed: ${input.failure}`);
+    }
+    const body = input.body;
+    if (input.bootId !== '' && typeof body?.bootId === 'string' && body.bootId !== ''
+        && body.bootId !== input.bootId) {
+        return not('The backend port is held by a leftover process running an older build', true, { foreign: true, phase: body.phase });
+    }
+    if (input.status != null && (input.status < 200 || input.status >= 300)) {
+        const detail = body?.error ?? body?.db?.error;
+        return not(`The target backend health endpoint answered ${input.status}`
+            + (detail != null && detail !== '' ? `: ${detail}` : ''), false, { phase: body?.phase });
+    }
+    if (body?.phase === 'failed') {
+        const reason = body.error ?? body.db?.error ?? body.valkey?.error ?? 'unknown error';
+        return not(`The target backend failed to initialize: ${reason}`, true, {
+            phase: body.phase, dbOk: body.db?.ok, valkeyOk: body.valkey?.ok,
+        });
+    }
+    if (body?.db?.ok === false) {
+        const detail = body.db.error ?? body.db.summary ?? 'unknown error';
+        return not(`The target backend cannot reach its database: ${detail}`, false, {
+            phase: body.phase, dbOk: false, valkeyOk: body.valkey?.ok,
+        });
+    }
+    if (body?.valkey?.ok === false) {
+        const detail = body.valkey.error ?? body.valkey.summary ?? 'unknown error';
+        return not(`The target backend cannot reach its queue store: ${detail}`, false, {
+            phase: body.phase, dbOk: body.db?.ok, valkeyOk: false,
+        });
+    }
+    if (body?.phase == null || body.phase === 'ready') {
+        return { ...ok(), phase: body?.phase, dbOk: body?.db?.ok, valkeyOk: body?.valkey?.ok };
+    }
+    return not('The target backend is still initializing', false, {
+        phase: body.phase, dbOk: body.db?.ok, valkeyOk: body.valkey?.ok,
+    });
+};
+/**
+ * Ask the target how it is, and classify the answer.
+ *
+ * The TCP probe runs first and short-circuits: there is no point spending a request timeout on a
+ * port nothing is listening on, and a target mid-restart is exactly when this is called most.
+ */
+export const readTargetHealth = async (port, bootId, timeoutMs, probes = {}) => {
+    const probe = probes.probe ?? probeListening;
+    const doFetch = probes.fetch ?? globalThis.fetch;
+    if (!await probe(port)) {
+        return classifyTargetHealth({ bootId, listening: false, status: null, body: null });
+    }
+    try {
+        const response = await doFetch(`http://127.0.0.1:${port}${probes.path ?? TARGET_HEALTH_PATH}`, { signal: AbortSignal.timeout(timeoutMs) });
+        const body = await response.json().catch(() => null);
+        return classifyTargetHealth({ bootId, listening: true, status: response.status, body });
+    }
+    catch (e) {
+        const error = e;
+        return classifyTargetHealth({
+            bootId, listening: true, status: null, body: null,
+            failure: error?.name === 'TimeoutError' ? 'TimeoutError' : String(error?.message ?? e),
+        });
+    }
+};
+//# sourceMappingURL=health.js.map

package/build/executor/health.js.map

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

package/build/executor/index.d.ts

@@ -0,0 +1,39 @@
+import type { SlotCommandPayload, TargetIntegrityReport, TargetPaths } from '@owlmeans/viable-common';
+export * from './errors.js';
+export * from './layout.js';
+export * from './integrity.js';
+export * from './files.js';
+export * from './env.js';
+export * from './health.js';
+export * from './boot-check.js';
+export * from './shell.js';
+export * from './git.js';
+export { BUILD_TIMEOUT, MAX_OUTPUT_BUFFER, failureOutput, isAlive, killGroupAndWait, probeListening, runCommand, runScript, signalGroup, waitForPortFree, withDeadline } from './spawn.js';
+export interface LocalSlotExecutorOptions {
+    /** Where the executor's own diagnostics go. NEVER stdout for a stdio MCP server. */
+    log?: (line: string) => void;
+}
+export interface LocalSlotExecutor {
+    /** Answer one slot command against the local tree. */
+    execute: (payload: SlotCommandPayload) => Promise<unknown>;
+    /** Which tree this directory holds, re-read per call. */
+    layout: () => TargetPaths;
+    /** Whether the tree is still the generated application. */
+    integrity: () => Promise<TargetIntegrityReport>;
+    dir: string;
+}
+/**
+ * Answer the platform's slot commands against a directory on this machine.
+ *
+ * The dispatcher is the publisher's, switch for switch, and that is the point: the platform's
+ * remote helpers parse the ANSWERS, and they have no way to know whether a pod or a laptop
+ * produced one. So an ordinary failure is never thrown here — it comes back in the same shape the
+ * publisher would have sent, error text and all — and only an unknown command, which is a
+ * protocol fault rather than a project fault, escapes as an exception.
+ *
+ * Everything is resolved per call rather than closed over: a re-initialization replaces the tree
+ * under a running connector, and a remembered layout would then resolve every path into a
+ * directory that no longer exists.
+ */
+export declare const makeLocalSlotExecutor: (dir: string, opts?: LocalSlotExecutorOptions) => LocalSlotExecutor;
+//# sourceMappingURL=index.d.ts.map

package/build/executor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,kBAAkB,EAAoD,qBAAqB,EAC3F,WAAW,EACZ,MAAM,yBAAyB,CAAA;AAShC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,OAAO,EACL,aAAa,EAAE,iBAAiB,EAAE,aAAa,EAAE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAC1F,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAClE,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,wBAAwB;IACvC,oFAAoF;IACpF,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,sDAAsD;IACtD,OAAO,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1D,yDAAyD;IACzD,MAAM,EAAE,MAAM,WAAW,CAAA;IACzB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAA;IAC/C,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,QAC3B,MAAM,SAAQ,wBAAwB,KAC1C,iBA4LF,CAAA"}