@stratusagent/cli 0.11.2 → 0.11.3

package/dist/commands/update.js

@@ -0,0 +1,291 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { newerStateMessage, pendingStateMigrations, readStateStamp, runStateMigrations, STATE_SCHEMA_VERSION, } from '@stratusagent/state';
+import { installService, readServiceCommand, readServiceStatus, serviceUnitPath, startService, stopService, } from "../service.js";
+import { serviceEnvFor } from "../daemon.js";
+import { writeLine, pathExists } from "../io.js";
+import { defaultPackageVersionFetcher, compareVersions, defaultPackageInstaller, defaultInstalledVersionReader, CLI_VERSION, CLI_PACKAGE_NAME, } from "../npm.js";
+import { FIRST_PARTY_CAPABILITY_PACKAGES, FIRST_PARTY_COMPANION_PACKAGES, } from "../plugin-catalog.js";
+/**
+ * The first-party packages installed beside the CLI, and whether each one
+ * lags the version the CLI is heading for.
+ *
+ * The gap this closes: the CLI and its companions are separate global
+ * installs, so upgrading `@stratusagent/cli` left every one of them at
+ * whatever version was installed the day setup first ran. A Slack adapter
+ * two releases behind the daemon loading it is not a configuration anyone
+ * chose, and nothing reported it — `doctor` says "installed", which was
+ * true of the stale one too.
+ *
+ * Read from each package's own manifest rather than asked of npm: the
+ * question is what this machine has, one registry round trip per package
+ * would answer a different one, and they ship in lockstep so the CLI's
+ * target version is theirs.
+ */
+const readCompanions = async (target, env) => {
+    const read = env.installedVersionReader ?? defaultInstalledVersionReader;
+    const found = [];
+    for (const name of [...FIRST_PARTY_COMPANION_PACKAGES, ...FIRST_PARTY_CAPABILITY_PACKAGES]) {
+        const version = await read(name);
+        if (version !== undefined) {
+            found.push({ name, version, stale: compareVersions(target, version) > 0 });
+        }
+    }
+    return found;
+};
+/**
+ * `stratus update` — the whole upgrade dance, in the order that cannot lose
+ * data: stop the service (so no daemon holds the session database while
+ * state migrates), upgrade the package, run pending migrations, rewrite the
+ * service unit with current paths, restart.
+ *
+ * The unit rewrite is the step that repairs the failure nothing else
+ * surfaces: the unit embeds absolute node and entrypoint paths (a service
+ * manager loads no shell profile, so it must), and upgrading node — under
+ * nvm, a whole new version directory — leaves the unit pointing at an
+ * interpreter that no longer exists. The service stops working and nothing
+ * says so; the agents just stop answering.
+ *
+ * Each step degrades independently: an unreachable npm skips the version
+ * check and package upgrade but still migrates and rewrites the unit —
+ * which is exactly the repair the offline case needs.
+ */
+export const runUpdate = async (command, streams, env) => {
+    const serviceEnv = serviceEnvFor(env);
+    const out = (line) => writeLine(streams.stdout, line);
+    const latest = await (env.packageVersionFetcher ?? defaultPackageVersionFetcher)(CLI_PACKAGE_NAME);
+    const upgradeAvailable = latest !== undefined && compareVersions(latest, CLI_VERSION) > 0;
+    // A stamp from a newer build makes every later step wrong, not just the
+    // migration one: this build would migrate — and stop the daemon to do it —
+    // against a format it does not understand. Checked here, before anything
+    // has a side effect.
+    const stamp = await readStateStamp(env);
+    const stateNewer = stamp.schemaVersion > STATE_SCHEMA_VERSION;
+    const status = await readServiceStatus(serviceEnv).catch(() => undefined);
+    const unit = status?.installed ? await readServiceCommand(serviceEnv) : undefined;
+    const unitNotes = [];
+    if (status?.installed && unit?.execPath !== undefined) {
+        if (!(await pathExists(unit.execPath))) {
+            unitNotes.push(`the unit's interpreter no longer exists: ${unit.execPath} — stratusd cannot start until the unit is rewritten`);
+        }
+        else if (unit.execPath !== process.execPath) {
+            unitNotes.push(`the unit runs ${unit.execPath}; this shell runs ${process.execPath}`);
+        }
+        if (unit.scriptPath !== undefined && !(await pathExists(unit.scriptPath))) {
+            unitNotes.push(`the unit's entrypoint no longer exists: ${unit.scriptPath}`);
+        }
+        else if (unit.scriptPath !== undefined && process.argv[1] !== undefined && unit.scriptPath !== process.argv[1]) {
+            // A versioned package directory can keep the old file alive after an
+            // upgrade — the daemon then runs the old CLI indefinitely with
+            // nothing missing on disk to notice.
+            unitNotes.push(`the unit runs entrypoint ${unit.scriptPath}; this shell runs ${process.argv[1]}`);
+        }
+    }
+    const pending = await pendingStateMigrations(env);
+    // The newer of what npm offers and what this build already is, never just
+    // the registry's answer: a dist-tag rollback, a stale mirror, or a CLI
+    // installed by explicit version all answer with something older, and a
+    // companion matching *that* would read as current while the process
+    // loading it is newer — the exact mismatch this exists to end. Held to
+    // this build, which is also why the target needs no network to be right.
+    const target = latest !== undefined && compareVersions(latest, CLI_VERSION) > 0
+        ? latest
+        : CLI_VERSION;
+    // Against the version this run is heading for, not the one it is on: a
+    // CLI already current still leaves a companion behind, which is the whole
+    // case this reports.
+    const companions = await readCompanions(target, env);
+    const stale = companions.filter((entry) => entry.stale);
+    out(`stratus ${CLI_VERSION}`);
+    out(latest === undefined
+        ? '  latest      unknown — npm did not answer'
+        : `  latest      ${latest}${upgradeAvailable ? ' — update available' : ' — up to date'}`);
+    out(`  state       schema ${stamp.schemaVersion}${stateNewer
+        ? ` — written by a NEWER build than this one (which understands ${STATE_SCHEMA_VERSION})`
+        : `, ${pending.length === 0 ? 'no pending migrations' : `${pending.length} pending migration${pending.length === 1 ? '' : 's'}`}`}`);
+    out(`  service     ${status === undefined
+        ? `no service manager for ${process.platform}`
+        : status.installed
+            ? (status.running === undefined ? 'installed, state unknown' : status.running ? 'installed, running' : 'installed, not running')
+            : 'not installed'}`);
+    for (const note of unitNotes) {
+        out(`  unit        ${note}`);
+    }
+    if (companions.length > 0) {
+        // A count and then only what would change, like every other line here:
+        // this reports state, not an inventory — `stratus plugins` is the
+        // command that lists what is installed.
+        out(`  packages    ${companions.length} first-party alongside the CLI, ${stale.length === 0 ? 'none behind' : `${stale.length} behind`}`);
+        for (const entry of stale) {
+            out(`              ${entry.name} ${entry.version} → ${target}`);
+        }
+    }
+    if (command.check) {
+        for (const migration of pending) {
+            out(`  pending     ${migration.id} — ${migration.description}`);
+        }
+        if (stateNewer) {
+            out('This build cannot update that state — upgrade the package itself (`npm install -g @stratusagent/cli`).');
+            return 1;
+        }
+        const actionable = upgradeAvailable || pending.length > 0 || unitNotes.length > 0 || stale.length > 0;
+        out(actionable
+            ? 'Run `stratus update` to apply the above.'
+            : 'Nothing to do.');
+        // Actionable exits 1, so a cron job or script can notice.
+        return actionable ? 1 : 0;
+    }
+    if (stateNewer) {
+        writeLine(streams.stderr, newerStateMessage(stamp.schemaVersion));
+        return 1;
+    }
+    if (status?.installed && (status.runAtLogin === undefined || status.running === undefined)) {
+        // The rewrite has to re-state the login setting and restore the prior
+        // run state, and the manager could not say what either currently is.
+        // Guessing would let a transient status failure convert a deliberate
+        // --no-login install, or rewrite-and-stop a daemon that was actually
+        // running — refuse instead, before anything has been stopped.
+        writeLine(streams.stderr, `Not updating: whether stratusd ${status.running === undefined ? 'is running' : 'starts at login'} could not be determined (the service manager did not answer), and the unit rewrite would have to guess. Check \`stratus service status\` and retry.`);
+        return 1;
+    }
+    const wasRunning = status?.running === true;
+    if (wasRunning) {
+        // No daemon may hold the session database while state migrates — this
+        // bracket is the one place an update could otherwise lose data.
+        out('Stopping stratusd for the update…');
+        const stopped = await stopService(serviceEnv);
+        for (const message of stopped.messages) {
+            writeLine(stopped.ok ? streams.stdout : streams.stderr, message);
+        }
+        if (!stopped.ok) {
+            writeLine(streams.stderr, 'Not updating while the daemon may still be running.');
+            return 1;
+        }
+    }
+    let upgradeFailed = false;
+    // The CLI and every companion that lags it, in one npm call: they are
+    // one release, and installing them separately leaves a window where the
+    // daemon and the adapter it loads disagree about their own version.
+    //
+    // Nothing at all when the registry did not answer, companions included:
+    // `@latest` cannot resolve without it, so the install would fail after
+    // printing a line promising a version npm never confirmed. Staleness is
+    // still *reported* offline — it is measured against this build, which
+    // needs no network — so `--check` says what an online update would fix.
+    const upgrading = latest === undefined ? [] : [
+        ...(upgradeAvailable ? [`${CLI_PACKAGE_NAME}@latest`] : []),
+        // `@latest` only where latest IS the target. Where this build is the
+        // newer one, `@latest` would install the very version the target just
+        // refused to be, so the companion is asked for by exact version — the
+        // one this CLI shipped alongside.
+        ...stale.map((entry) => `${entry.name}@${target === latest ? 'latest' : target}`),
+    ];
+    if (upgrading.length > 0) {
+        if (upgradeAvailable) {
+            out(`Upgrading ${CLI_PACKAGE_NAME} ${CLI_VERSION} → ${latest}…`);
+        }
+        for (const entry of stale) {
+            out(`Upgrading ${entry.name} ${entry.version} → ${target}…`);
+        }
+        const installed = await (env.packageInstaller ?? defaultPackageInstaller)(upgrading);
+        if (installed.ok) {
+            // This process is still the old build; migrations the new version
+            // adds run when it first starts — which the restart below is.
+            out('Upgraded. Migrations the new version adds run on its first start.');
+        }
+        else {
+            upgradeFailed = true;
+            writeLine(streams.stderr, `npm install failed: ${installed.message || 'unknown error'} — continuing with migrations and the unit rewrite.`);
+        }
+    }
+    else {
+        out(latest === undefined
+            ? 'Skipping the package upgrade — npm did not answer.'
+            : 'Package already up to date.');
+    }
+    let applied;
+    try {
+        applied = await runStateMigrations(env);
+    }
+    catch (error) {
+        // A daemon stopped for an update that then failed must not stay down:
+        // the old unit is still in place (the rewrite has not happened), so
+        // restarting restores the world the update found. The failure is still
+        // a failure — but an offline fleet on top of it is not.
+        writeLine(streams.stderr, `State migration failed: ${error instanceof Error ? error.message : String(error)}`);
+        if (wasRunning) {
+            const restarted = await startService(serviceEnv);
+            for (const message of restarted.messages) {
+                writeLine(restarted.ok ? streams.stdout : streams.stderr, message);
+            }
+            writeLine(streams.stderr, restarted.ok
+                ? 'stratusd was restarted on its previous unit. Fix the migration failure and run `stratus update` again.'
+                : 'stratusd could not be restarted either — bring it back with `stratus service start` once the failure is fixed.');
+        }
+        return 1;
+    }
+    if (applied.length === 0) {
+        out('No pending state migrations.');
+    }
+    for (const migration of applied) {
+        out(`Migrated: ${migration.description}${migration.detail !== undefined ? ` — ${migration.detail}` : ''}`);
+    }
+    if (status?.installed) {
+        out('Rewriting the service unit with current node and entrypoint paths…');
+        // The rewrite overwrites the unit before it bootstraps, so a failure
+        // in between must be able to put the old definition back — otherwise
+        // a stopped daemon is left with neither unit to start from.
+        const previousUnit = await readFile(serviceUnitPath(serviceEnv), 'utf8').catch(() => undefined);
+        const install = await installService(
+        // The unit's own working directory survives the rewrite: relative
+        // paths in the pinned config (a `soul`) resolve against it, so a
+        // rewrite run from some other directory must not substitute its own.
+        unit?.workingDirectory !== undefined ? { ...serviceEnv, cwd: unit.workingDirectory } : serviceEnv, {
+            ...(status.runAtLogin === false ? { runAtLogin: false } : {}),
+            // The config the existing unit was pinned to survives the rewrite —
+            // a unit rewritten onto a different roster is its own outage.
+            ...(unit?.configPath !== undefined ? { configPath: unit.configPath } : {}),
+        });
+        for (const message of install.messages) {
+            writeLine(install.ok ? streams.stdout : streams.stderr, message);
+        }
+        if (!install.ok) {
+            if (wasRunning) {
+                // The fleet was up when the update began and must not stay down
+                // over a failed rewrite: restore the previous unit definition and
+                // start it again. The exit code stays 1 — the update failed — but
+                // the world it found is put back.
+                if (previousUnit !== undefined) {
+                    await writeFile(serviceUnitPath(serviceEnv), previousUnit, { mode: 0o644 }).catch((error) => {
+                        writeLine(streams.stderr, `Could not restore the previous unit either: ${error instanceof Error ? error.message : String(error)}`);
+                    });
+                }
+                const restarted = await startService(serviceEnv);
+                for (const message of restarted.messages) {
+                    writeLine(restarted.ok ? streams.stdout : streams.stderr, message);
+                }
+                writeLine(streams.stderr, restarted.ok
+                    ? 'The unit rewrite failed, so stratusd was restarted on its previous unit. Fix the failure above and run `stratus update` again.'
+                    : 'The unit rewrite failed AND stratusd could not be restarted — bring it back with `stratus service start`, or `stratus service install` to rewrite the unit by hand.');
+            }
+            return 1;
+        }
+        if (!wasRunning) {
+            // installService starts the daemon; a service that was deliberately
+            // stopped before the update stays that way.
+            const stopped = await stopService(serviceEnv);
+            if (!stopped.ok) {
+                // The update itself succeeded, but the user's prior state was not
+                // restored: an intentionally stopped daemon is now running. That
+                // is a failure a script must see, not a footnote.
+                writeLine(streams.stderr, 'stratusd was not running before the update, and stopping it again failed — it is now RUNNING. Stop it with `stratus service stop`.');
+                return 1;
+            }
+            out('stratusd was not running before the update, so it was left stopped.');
+        }
+    }
+    else if (status !== undefined) {
+        out('No service installed — nothing to rewrite. `stratus service install` sets one up.');
+    }
+    return upgradeFailed ? 1 : 0;
+};
+//# sourceMappingURL=update.js.map

package/dist/commands/update.js.map

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

package/dist/daemon.d.ts

@@ -0,0 +1,74 @@
+import type { ServiceEnvironment } from './service.ts';
+import type { CliEnvironment } from './environment.ts';
+/**
+ * The bearer token for a gateway: an explicit flag, the environment, or the
+ * token file this machine's daemon wrote.
+ *
+ * The file is the normal case and the reason `--gateway` needs no ceremony
+ * locally. It is not always right, though: a gateway reached through a tunnel
+ * has its own token, which is what the flag and the variable are for.
+ */
+export declare const gatewayToken: (env: CliEnvironment, explicit: string | undefined) => Promise<string>;
+/** Builds the service view of the CLI environment (home, exec paths, runner). */
+export declare const serviceEnvFor: (env: CliEnvironment) => ServiceEnvironment;
+/** Where a command aimed at "the running daemon" is pointed. */
+interface RunningGatewayTarget {
+    gateway?: string;
+    token?: string;
+}
+/**
+ * The control API base a command should talk to: `--gateway` when given,
+ * else whatever daemon `~/.stratus/gateway.json` says is serving, else
+ * nothing — the file is written when the API binds and removed when it
+ * stops, so its absence means no daemon has said where it is.
+ */
+export declare const runningGatewayBase: (env: CliEnvironment, target: RunningGatewayTarget) => Promise<string | undefined>;
+/** One authenticated call to a daemon's control API, with the network and auth failures said plainly. */
+export declare const callRunningGateway: (env: CliEnvironment, target: RunningGatewayTarget, base: string, pathname: string, body?: Record<string, unknown>, method?: "GET" | "POST") => Promise<Response>;
+/** The API's own sentence for a failure, or the status when it sent none. */
+export declare const gatewayErrorMessage: (response: Response) => Promise<string>;
+export declare const noRunningDaemonMessage: (env: CliEnvironment) => string;
+/** What a running daemon published about itself, if one is running. */
+interface GatewayInfo {
+    url: string;
+    pid?: number;
+}
+export declare const readGatewayInfo: (env: CliEnvironment) => Promise<GatewayInfo | undefined>;
+/** Whether something is actually answering there, as opposed to a stale file. */
+export declare const gatewayAnswering: (env: CliEnvironment, base: string, fetchImpl: typeof fetch) => Promise<boolean>;
+/**
+ * The error for a home another daemon holds (see `claimHome` in
+ * @stratusagent/gateway — the claim is what decides; this only says who).
+ *
+ * The discovery file names the holder when it has one to name: a daemon
+ * that has bound its API. Read for the message alone, and only trusted as
+ * far as a live pid — a daemon still starting has not written it, a
+ * daemon draining its last turn has already removed it, and a SIGKILLed
+ * one leaves it behind for the next pid to inherit. Not probed over HTTP:
+ * a `STRATUS_GATEWAY_TOKEN` exported for some remote gateway would answer
+ * 401 for the local one, and the claim needs no second opinion.
+ */
+/**
+ * `stratus serve` refused because another daemon holds the home. Its own
+ * type so `stratus dashboard` can tell "a daemon is there, wait for it to
+ * publish" from "the daemon could not start".
+ */
+export declare class HomeHeldError extends Error {
+    constructor(message: string);
+}
+/**
+ * Whether a daemon from before the lock existed is serving this home.
+ *
+ * Such a daemon — alive across an upgrade that did not stop it — never
+ * took the claim, so the claim alone cannot see it. The discovery file it
+ * published is its only trace, held to the two proofs the lock made
+ * unnecessary for everything since: the pid it names is alive, and its
+ * URL answers `/health` with this home's own token file — never the
+ * `STRATUS_GATEWAY_TOKEN` override, which names some other gateway and
+ * would make a live daemon read as absent. A stale file fails either
+ * proof and refuses nothing.
+ */
+export declare const legacyDaemonServing: (env: CliEnvironment) => Promise<boolean>;
+export declare const describeHeldHome: (env: CliEnvironment) => Promise<string>;
+export {};
+//# sourceMappingURL=daemon.d.ts.map

package/dist/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GACvB,KAAK,cAAc,EACnB,UAAU,MAAM,GAAG,SAAS,KAC3B,OAAO,CAAC,MAAM,CAgBhB,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,aAAa,GAAI,KAAK,cAAc,KAAG,kBAKlD,CAAC;AAEH,gEAAgE;AAChE,UAAU,oBAAoB;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAU,KAAK,cAAc,EAAE,QAAQ,oBAAoB,KAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAMtH,CAAC;AAEF,yGAAyG;AACzG,eAAO,MAAM,kBAAkB,GAC7B,KAAK,cAAc,EACnB,QAAQ,oBAAoB,EAC5B,MAAM,MAAM,EACZ,UAAU,MAAM,EAChB,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAQ,KAAK,GAAG,MAAe,KAC9B,OAAO,CAAC,QAAQ,CA0BlB,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,GAAU,UAAU,QAAQ,KAAG,OAAO,CAAC,MAAM,CAU5E,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,KAAK,cAAc,KAAG,MAE8C,CAAC;AAE5G,uEAAuE;AACvE,UAAU,WAAW;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,eAAe,GAAU,KAAK,cAAc,KAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAS1F,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,GAC3B,KAAK,cAAc,EACnB,MAAM,MAAM,EACZ,WAAW,OAAO,KAAK,KACtB,OAAO,CAAC,OAAO,CAUjB,CAAC;AAeF;;;;;;;;;;;GAWG;AACH;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAAU,KAAK,cAAc,KAAG,OAAO,CAAC,OAAO,CAmB9E,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAU,KAAK,cAAc,KAAG,OAAO,CAAC,MAAM,CAS1E,CAAC"}

package/dist/daemon.js

@@ -0,0 +1,192 @@
+import { readFile } from 'node:fs/promises';
+import { readNonEmptyString, readProcessEnv, readWorkingDirectory, gatewayInfoPath, gatewayTokenPath, } from '@stratusagent/state';
+/**
+ * The bearer token for a gateway: an explicit flag, the environment, or the
+ * token file this machine's daemon wrote.
+ *
+ * The file is the normal case and the reason `--gateway` needs no ceremony
+ * locally. It is not always right, though: a gateway reached through a tunnel
+ * has its own token, which is what the flag and the variable are for.
+ */
+export const gatewayToken = async (env, explicit) => {
+    const fromEnv = readNonEmptyString(readProcessEnv(env).STRATUS_GATEWAY_TOKEN);
+    if (explicit || fromEnv) {
+        return String(explicit ?? fromEnv);
+    }
+    try {
+        return (await readFile(gatewayTokenPath(env), 'utf8')).trim();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+        throw new Error(`No gateway token: ${gatewayTokenPath(env)} does not exist, and neither --token nor STRATUS_GATEWAY_TOKEN was set. `
+            + 'Start the daemon with `stratus serve` (or `stratus service install`) to create one, or pass the remote gateway\'s token.');
+    }
+};
+/** Builds the service view of the CLI environment (home, exec paths, runner). */
+export const serviceEnvFor = (env) => ({
+    ...(env.homeDir !== undefined ? { homeDir: env.homeDir } : {}),
+    cwd: readWorkingDirectory(env),
+    ...(env.serviceRunner !== undefined ? { run: env.serviceRunner } : {}),
+    ...(env.servicePlatform !== undefined ? { platform: env.servicePlatform } : {}),
+});
+/**
+ * The control API base a command should talk to: `--gateway` when given,
+ * else whatever daemon `~/.stratus/gateway.json` says is serving, else
+ * nothing — the file is written when the API binds and removed when it
+ * stops, so its absence means no daemon has said where it is.
+ */
+export const runningGatewayBase = async (env, target) => {
+    if (target.gateway) {
+        return target.gateway.replace(/\/+$/, '');
+    }
+    const info = await readGatewayInfo(env);
+    return info?.url.replace(/\/+$/, '');
+};
+/** One authenticated call to a daemon's control API, with the network and auth failures said plainly. */
+export const callRunningGateway = async (env, target, base, pathname, body, method = 'POST') => {
+    const token = await gatewayToken(env, target.token);
+    const fetchImpl = env.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('fetch is unavailable, so this runtime cannot reach a daemon.');
+    }
+    let response;
+    try {
+        response = await fetchImpl(`${base}${pathname}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                ...(body ? { 'content-type': 'application/json' } : {}),
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach the gateway at ${base} (${error instanceof Error ? error.message : String(error)}). `
+            + 'Is stratusd running, and does it have @stratusagent/control-api installed?');
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new Error(`The gateway at ${base} rejected this token. Check --token, STRATUS_GATEWAY_TOKEN, or ~/.stratus/gateway-token.`);
+    }
+    return response;
+};
+/** The API's own sentence for a failure, or the status when it sent none. */
+export const gatewayErrorMessage = async (response) => {
+    try {
+        const payload = await response.json();
+        if (payload.error?.message) {
+            return payload.error.message;
+        }
+    }
+    catch {
+        // Not JSON; the status is all there is to say.
+    }
+    return `HTTP ${response.status}`;
+};
+export const noRunningDaemonMessage = (env) => `no running daemon found — ${gatewayInfoPath(env)} does not exist, and no --gateway was given. `
+    + 'Start one with `stratus serve` or `stratus service start`; a daemon loads ~/.stratus/skills at start.';
+export const readGatewayInfo = async (env) => {
+    try {
+        const parsed = JSON.parse(await readFile(gatewayInfoPath(env), 'utf8'));
+        return typeof parsed.url === 'string' ? { url: parsed.url, ...(parsed.pid ? { pid: parsed.pid } : {}) } : undefined;
+    }
+    catch {
+        // No file, or one left behind by a daemon that died without cleaning up.
+        // Either way there is nothing to talk to until the health check says so.
+        return undefined;
+    }
+};
+/** Whether something is actually answering there, as opposed to a stale file. */
+export const gatewayAnswering = async (env, base, fetchImpl) => {
+    try {
+        const token = await gatewayToken(env, undefined);
+        const response = await fetchImpl(`${base}/api/v1/health`, {
+            headers: { authorization: `Bearer ${token}` },
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Whether a process with this pid exists. EPERM is an answer — the process
+ * is there, it is just not ours to signal.
+ */
+const processAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+};
+/**
+ * The error for a home another daemon holds (see `claimHome` in
+ * @stratusagent/gateway — the claim is what decides; this only says who).
+ *
+ * The discovery file names the holder when it has one to name: a daemon
+ * that has bound its API. Read for the message alone, and only trusted as
+ * far as a live pid — a daemon still starting has not written it, a
+ * daemon draining its last turn has already removed it, and a SIGKILLed
+ * one leaves it behind for the next pid to inherit. Not probed over HTTP:
+ * a `STRATUS_GATEWAY_TOKEN` exported for some remote gateway would answer
+ * 401 for the local one, and the claim needs no second opinion.
+ */
+/**
+ * `stratus serve` refused because another daemon holds the home. Its own
+ * type so `stratus dashboard` can tell "a daemon is there, wait for it to
+ * publish" from "the daemon could not start".
+ */
+export class HomeHeldError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HomeHeldError';
+    }
+}
+/**
+ * Whether a daemon from before the lock existed is serving this home.
+ *
+ * Such a daemon — alive across an upgrade that did not stop it — never
+ * took the claim, so the claim alone cannot see it. The discovery file it
+ * published is its only trace, held to the two proofs the lock made
+ * unnecessary for everything since: the pid it names is alive, and its
+ * URL answers `/health` with this home's own token file — never the
+ * `STRATUS_GATEWAY_TOKEN` override, which names some other gateway and
+ * would make a live daemon read as absent. A stale file fails either
+ * proof and refuses nothing.
+ */
+export const legacyDaemonServing = async (env) => {
+    const info = await readGatewayInfo(env);
+    if (info?.pid === undefined || info.pid === process.pid || !processAlive(info.pid)) {
+        return false;
+    }
+    const fetchImpl = env.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        return false;
+    }
+    try {
+        const token = (await readFile(gatewayTokenPath(env), 'utf8')).trim();
+        const response = await fetchImpl(`${info.url}/api/v1/health`, {
+            headers: { authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(2_000),
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+};
+export const describeHeldHome = async (env) => {
+    const info = await readGatewayInfo(env);
+    const holder = info?.pid !== undefined && processAlive(info.pid)
+        ? ` (pid ${info.pid}, ${info.url})`
+        : ' — one that is still starting, or still draining its last turns';
+    return `stratusd is already running for this home${holder}. Two daemons on one ~/.stratus `
+        + 'would each fire the other\'s schedules and re-ask its approvals. Stop it first: `stratus service stop` '
+        + 'if it is the installed service, otherwise Ctrl+C where it runs — and let it finish; it holds the home until '
+        + 'its last turn is written.';
+};
+//# sourceMappingURL=daemon.js.map

package/dist/daemon.js.map

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