brainchain-worker 0.1.0 → 0.2.1

package/dist/index.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { BaseError, formatEther, formatUnits, HttpRequestError, parseUnits } from "viem";
+import { join as joinPath } from "node:path";
+import { formatEther, formatUnits, parseUnits } from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
-import { ApplicationState, createChain } from "./chain.js";
+import { ApplicationState, createChain, faucetReopens, reason, unhealthy } from "./chain.js";
 import { resolveNetwork } from "./network.js";
-import { createWork, shellCommand } from "./work.js";
+import { fileStore, lock, stateDir } from "./state.js";
+import { createWork, shellCommand, stopper } from "./work.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 const USAGE = `brainchain-worker ${version}
 
@@ -14,26 +16,35 @@ Usage:
   brainchain-worker new-key                 Print a fresh private key and its address.
   brainchain-worker join --name <name> --about <text> [--price <tUSDG>]
                                             Stake the minimum and apply to take tasks.
-  brainchain-worker run --exec "<command>" [--format prompt|json] [--once]
+  brainchain-worker run --exec "<command>" [--format prompt|json] [--timeout <minutes>] [--once]
                                             Do every task Jev hires you for: the command reads the
-                                            task on stdin and prints the deliverable on stdout.
-  brainchain-worker status                  Stake, application, record and earnings.
+                                            task on stdin and prints the deliverable on stdout, within
+                                            --timeout minutes (20 by default, at most 1440).
+  brainchain-worker status                  Stake, tBRAIN balance, application, record and earnings.
   brainchain-worker price <tUSDG>           Change your asking price per task.
   brainchain-worker leave                   Start unstaking (3-day cooldown).
   brainchain-worker withdraw                Withdraw stake once the cooldown has passed.
+  brainchain-worker --version               Print the version.
 
 Environment:
   BRAINCHAIN_WORKER_KEY   Private key of the worker's wallet, 64 hex characters with or without 0x.
   BRAINCHAIN_NETWORK      testnet (the default, and the only network open to outside workers today).
   BRAINCHAIN_RPC_URL      Overrides the network's RPC.
+  BRAINCHAIN_SERVICE_URL  Overrides the BrainChain service that keeps results: https, or http on
+                          localhost or 127.0.0.1.
+
+The command sees the worker's environment without any BRAINCHAIN_ variable, plus BRAINCHAIN_TASK_ID.
+Unfinished work is kept in ~/.config/brainchain-worker/<address>.json across restarts, and one
+run at a time works for each address.
 
 Docs: https://docs.usebrainchain.com/run-a-worker`;
+/** A mistake in the command line. Every other error is printed after the program's name. */
 class UsageError extends Error {
 }
 /** The flags each command takes; `true` marks a switch, which takes no value. */
 const FLAGS = {
     join: { name: false, about: false, price: false },
-    run: { exec: false, format: false, once: true },
+    run: { exec: false, format: false, timeout: false, once: true },
     status: {},
     price: {},
     leave: {},
@@ -43,7 +54,7 @@ const POSITIONAL = { price: 1 };
 function parse(command, args) {
     const known = FLAGS[command];
     if (known === undefined)
-        throw new UsageError(`Unknown command "${command}". Run brainchain-worker help.`);
+        throw new UsageError(`Unknown command "${command}" (see brainchain-worker help)`);
     const positional = [];
     const values = new Map();
     const switches = new Set();
@@ -56,7 +67,7 @@ function parse(command, args) {
         const [name, inline] = arg.slice(2).split(/=(.*)/s, 2);
         const isSwitch = known[name];
         if (isSwitch === undefined)
-            throw new UsageError(`${command} has no --${name} flag. Run brainchain-worker help.`);
+            throw new UsageError(`The ${command} command has no --${name} flag (see brainchain-worker help)`);
         if (isSwitch) {
             switches.add(name);
             continue;
@@ -67,23 +78,25 @@ function parse(command, args) {
         values.set(name, value);
     }
     if (positional.length > (POSITIONAL[command] ?? 0))
-        throw new UsageError(`Unexpected "${positional.at(-1)}". Run brainchain-worker help.`);
+        throw new UsageError(`Unexpected "${positional.at(-1)}" (see brainchain-worker help)`);
     return { positional, values, switches };
 }
-function account() {
+function signer() {
     const raw = process.env.BRAINCHAIN_WORKER_KEY?.trim();
     if (!raw)
-        throw new UsageError("Set BRAINCHAIN_WORKER_KEY to the worker's private key. `npx brainchain-worker new-key` makes one.");
+        throw new Error("Set BRAINCHAIN_WORKER_KEY to the worker's private key. `npx brainchain-worker new-key` makes one.");
     const hex = raw.startsWith("0x") ? raw.slice(2) : raw;
     if (!/^[0-9a-fA-F]{64}$/.test(hex))
-        throw new UsageError("BRAINCHAIN_WORKER_KEY must be 64 hex characters, with or without 0x");
+        throw new Error("BRAINCHAIN_WORKER_KEY must be 64 hex characters, with or without 0x");
+    const key = `0x${hex.toLowerCase()}`;
     try {
-        return privateKeyToAccount(`0x${hex}`);
+        return { key, account: privateKeyToAccount(key) };
     }
     catch {
-        throw new UsageError("BRAINCHAIN_WORKER_KEY is not a valid private key. `npx brainchain-worker new-key` makes one.");
+        throw new Error("BRAINCHAIN_WORKER_KEY is not a valid private key. `npx brainchain-worker new-key` makes one.");
     }
 }
+const DEFAULT_PRICE = "0.20";
 /** A price in the bounty token, which has 6 decimals. */
 function price(value) {
     if (!/^\d{1,6}(\.\d{1,6})?$/.test(value)) {
@@ -94,19 +107,39 @@ function price(value) {
 const stake = (network, amount) => `${formatUnits(amount, 18)} ${network.stakeSymbol}`;
 const usdg = (network, amount) => `${formatUnits(amount, 6)} ${network.bountySymbol}`;
 const when = (seconds) => new Date(Number(seconds) * 1000).toISOString().replace(".000Z", "Z");
-async function needGas(chain, network) {
-    if ((await chain.ethBalance()) > 0n)
-        return;
-    throw new UsageError(`${chain.account} has no ETH on ${network.name} for gas. Get Robinhood Chain testnet ETH from https://faucet.testnet.chain.robinhood.com ` +
+const RUN = '`npx brainchain-worker run --exec "<command>"`';
+function noGas(chain, network) {
+    return new Error(`${chain.account} has no ETH on ${network.name} for gas. Get Robinhood Chain testnet ETH from https://faucet.testnet.chain.robinhood.com ` +
         `and bridge some at ${network.explorer}; 0.001 ETH is plenty.`);
 }
-/** Why the worker can or cannot be hired right now, in one line. */
-async function hireable(chain, network) {
+async function needGas(chain, network) {
+    if ((await chain.ethBalance()) === 0n)
+        throw noGas(chain, network);
+}
+/** The worker's standing with the board and the staking contract, and what join would do about it. */
+async function snapshot(chain) {
     const [allowed, w, min, { applications, change }] = await Promise.all([chain.allowed(), chain.stake(), chain.minStake(), chain.applications()]);
+    const pending = change !== undefined && !change.executed && !change.vetoed;
+    const open = applications.find((a) => a.state === ApplicationState.Open);
+    return {
+        allowed,
+        w,
+        min,
+        applications,
+        change,
+        pending,
+        open,
+        applying: !allowed && !pending && open === undefined,
+        // Below the minimum after leave or a slash, an allowed worker cannot be hired until it stakes again.
+        toStake: w.staked >= min ? 0n : min - w.staked,
+    };
+}
+/** Why the worker can or cannot be hired right now, in one line. */
+function hireable({ allowed, w, min, applications, change, pending }, network) {
     if (allowed)
         return w.staked >= min ? "yes" : `no: your stake is below the minimum of ${stake(network, min)}. Run join to stake again.`;
     // An allowed application waiting out its timelock outranks anything filed after it.
-    if (change && !change.executed && !change.vetoed)
+    if (change && pending)
         return `no: Jev allowed this worker; it can be hired after ${when(change.eta)}`;
     const last = applications.at(-1);
     if (last === undefined)
@@ -115,39 +148,45 @@ async function hireable(chain, network) {
         return `no: application ${last.id} is waiting for Jev`;
     if (last.state === ApplicationState.Burned)
         return `no: Jev did not allow application ${last.id}, and its bond was burned. Run join to apply again.`;
-    if (change?.vetoed)
-        return `no: the guardian vetoed application ${last.id}`;
+    if (change?.vetoed) {
+        // A vetoed call can never be queued again, so the veto still stands for applications filed after it.
+        const vetoed = applications.find((a) => a.decisionId === change.decisionId);
+        return `no: the guardian vetoed ${vetoed ? `application ${vetoed.id}` : "allowing this worker"}`;
+    }
     return `no: application ${last.id} closed without a decision; its bond was returned. Run join to apply again.`;
 }
 async function join(chain, network, values) {
-    const name = values.get("name")?.trim();
+    const name = values.get("name")?.trim() ?? "";
     const about = values.get("about")?.trim() ?? "";
-    if (!name || name.length > 60)
+    if (!name)
         throw new UsageError("--name is required, up to 60 characters");
-    if (!about || about.length > 500) {
-        throw new UsageError("--about is required, up to 500 characters: say what work your agent does. Jev reads it to decide, and refuses an empty application.");
+    if (name.length > 60)
+        throw new UsageError("--name is at most 60 characters");
+    if (!about) {
+        throw new UsageError("--about is required: say what work your agent does in up to 500 characters, since Jev reads it to decide and refuses an empty application");
     }
-    const asking = price(values.get("price") ?? "0.20");
+    if (about.length > 500)
+        throw new UsageError("--about is at most 500 characters");
+    const requested = values.has("price") ? price(values.get("price")) : undefined;
     await needGas(chain, network);
-    if (await chain.allowed()) {
-        console.log("This worker can already be hired. Start it with `npx brainchain-worker run`.");
-        return;
-    }
-    const { applications, change } = await chain.applications();
-    if (change && !change.executed && !change.vetoed) {
-        console.log(`Jev already allowed this worker. It can be hired after ${when(change.eta)}; keep \`npx brainchain-worker run\` going until then.`);
-        return;
-    }
-    const open = applications.find((a) => a.state === ApplicationState.Open);
-    const [w, min, bond, balance] = await Promise.all([chain.stake(), chain.minStake(), chain.bond(), chain.stakeBalance()]);
-    const toStake = w.staked >= min ? 0n : min - w.staked;
-    const needed = toStake + (open ? 0n : bond);
-    if (balance < needed) {
+    const { allowed, w, change, pending, open, applying, toStake } = await snapshot(chain);
+    // A worker that has staked keeps its price unless --price changes it.
+    const asking = requested ?? (w.registered ? w.price : price(DEFAULT_PRICE));
+    const [bond, balance] = await Promise.all([chain.bond(), chain.stakeBalance()]);
+    const need = toStake + (applying ? bond : 0n);
+    if (balance < need) {
         console.log(`Claiming ${network.stakeSymbol} from the testnet faucet...`);
-        await chain.claimStakeToken();
+        await chain.claimStakeToken().catch((error) => {
+            const opensAt = faucetReopens(error);
+            if (opensAt === undefined)
+                throw error;
+            const unstaking = w.unstaking > 0n ? `, or run withdraw after ${when(w.unlocksAt)} and join with the ${stake(network, w.unstaking)} it returns` : "";
+            throw new Error(`The wallet holds ${stake(network, balance)} of the ${stake(network, need)} join needs, and the faucet allows one claim a day: ` +
+                `this wallet can claim again at ${when(opensAt)}. Run join again then${unstaking}.`);
+        });
     }
     if (toStake > 0n) {
-        console.log(`Staking ${stake(network, toStake)} at ${usdg(network, asking)} per task...`);
+        console.log(`Staking ${stake(network, toStake)}${w.staked > 0n ? " more, up to the minimum," : ""} at ${usdg(network, asking)} per task...`);
         await chain.approve(network.contracts.stakeToken, network.contracts.staking, toStake);
         await chain.stakeTokens(toStake, asking);
     }
@@ -155,6 +194,14 @@ async function join(chain, network, values) {
         console.log(`Setting your price to ${usdg(network, asking)} per task...`);
         await chain.setPrice(asking);
     }
+    if (allowed) {
+        console.log(`${toStake > 0n ? "Staked back to the minimum, so this worker can be hired again." : "This worker can already be hired."} Start it with ${RUN}.`);
+        return;
+    }
+    if (change && pending) {
+        console.log(`Jev already allowed this worker. It can be hired after ${when(change.eta)}; keep ${RUN} going until then.`);
+        return;
+    }
     if (open) {
         console.log(`Application ${open.id} is already waiting for Jev.`);
         return;
@@ -164,38 +211,88 @@ async function join(chain, network, values) {
     const profile = Buffer.from(JSON.stringify({ name, about })).toString("base64");
     await chain.apply(`data:application/json;base64,${profile}`);
     console.log("\nApplied. Jev usually decides within a few minutes. If it allows the worker, it can be hired once a 2-hour timelock passes.\n" +
-        "Start `npx brainchain-worker run` now so it takes its first task as soon as it is hired, and follow the application\n" +
-        "with `npx brainchain-worker status`. New workers are offered house tasks first, which BrainChain pays for.");
+        `Start ${RUN} now so it takes its first task as soon as it is hired, and follow\n` +
+        "the application with `npx brainchain-worker status`. New workers are offered house tasks first, which BrainChain pays for.");
+}
+/** The wallet's tBRAIN and, below the minimum stake, where join would find what it needs. */
+function wallet(network, s, balance, bond, faucet, now) {
+    const has = stake(network, balance);
+    if (s.toStake === 0n)
+        return has;
+    const need = s.toStake + (s.applying ? bond : 0n);
+    if (balance >= need)
+        return `${has}, enough for the ${stake(network, need)} join needs`;
+    if (now >= faucet.opensAt)
+        return `${has}; join needs ${stake(network, need)} and claims the rest from the faucet, which gives ${stake(network, faucet.amount)} a day`;
+    const unstaking = s.w.unstaking > 0n ? `, and the ${stake(network, s.w.unstaking)} unstaking can be withdrawn ${now >= s.w.unlocksAt ? "now" : `after ${when(s.w.unlocksAt)}`}` : "";
+    return `${has}; join needs ${stake(network, need)}. The faucet opens again for this wallet at ${when(faucet.opensAt)}${unstaking}`;
 }
 async function status(chain, network) {
-    const [gas, w, min, held, record, balance, line] = await Promise.all([
+    const [gas, s, held, record, bountyBalance, stakeBalance, bond, faucet, now] = await Promise.all([
         chain.ethBalance(),
-        chain.stake(),
-        chain.minStake(),
-        chain.inFlight(),
+        snapshot(chain),
+        chain.held(),
         chain.record(),
         chain.bountyBalance(),
-        hireable(chain, network),
+        chain.stakeBalance(),
+        chain.bond(),
+        chain.faucet(),
+        chain.now(),
     ]);
+    const { w, min } = s;
     const unstaking = w.unstaking > 0n ? `, ${stake(network, w.unstaking)} unstaking until ${when(w.unlocksAt)}` : "";
     console.log(`Worker ${chain.account} on ${network.name}
-  Hireable  ${line}
+  Hireable  ${hireable(s, network)}
   Stake     ${stake(network, w.staked)} (minimum ${stake(network, min)})${unstaking}
+  Wallet    ${wallet(network, s, stakeBalance, bond, faucet, now)}
   Price     ${w.registered ? `${usdg(network, w.price)} per task` : "not set until you join"}
   Record    ${record.accepted} accepted, ${record.refunded} refunded, ${record.inFlight} in flight${held > 0 ? " (stake held until they settle)" : ""}
-  Earned    ${usdg(network, record.earned)} after fees; wallet holds ${usdg(network, balance)}
+  Earned    ${usdg(network, record.earned)} after fees; wallet holds ${usdg(network, bountyBalance)}
   Gas       ${formatEther(gas)} ETH`);
 }
-async function run(chain, network, values, once) {
+async function run(network, { key, account }, values, once) {
     const exec = values.get("exec");
     if (!exec)
         throw new UsageError(`--exec is required: the command that does the work, such as --exec 'claude -p --tools ""'`);
     const format = values.get("format") ?? "prompt";
     if (format !== "prompt" && format !== "json")
         throw new UsageError("--format is prompt or json");
-    const log = (message) => console.log(`${new Date().toISOString().slice(11, 19)} ${message}`);
-    const work = createWork({ chain, command: shellCommand(exec), format, log });
-    log(`worker ${chain.account} on ${network.name}; hireable: ${await hireable(chain, network)}`);
+    const minutes = values.get("timeout") ?? "20";
+    if (!/^\d{1,4}(\.\d+)?$/.test(minutes) || Number(minutes) <= 0 || Number(minutes) > 1440) {
+        throw new UsageError("--timeout is the most minutes the command may spend on one task: more than 0, at most 1440, and 20 by default");
+    }
+    const file = joinPath(stateDir(), account.address);
+    lock(`${file}.lock`);
+    const store = fileStore(`${file}.json`, network.contracts.taskBoard);
+    const chain = createChain(network, account, store);
+    const log = (message) => console.log(`${new Date().toISOString().slice(11, 19)}Z ${message}`);
+    const command = shellCommand(exec);
+    const stop = stopper({ busy: () => work.busy(), kill: command.kill, log, exit: (code) => process.exit(code) });
+    const work = createWork({
+        chain,
+        command,
+        format,
+        log,
+        timeoutMs: Number(minutes) * 60_000,
+        secrets: [key, key.slice(2)],
+        store,
+        stopping: stop.stopping,
+    });
+    process.on("SIGINT", stop.signal);
+    process.on("SIGTERM", stop.signal);
+    const gas = await chain.ethBalance().catch((error) => {
+        log(`could not read the wallet's ETH balance: ${reason(error)}`);
+        return undefined;
+    });
+    if (gas === 0n)
+        throw noGas(chain, network);
+    const [line, sick] = await Promise.all([
+        snapshot(chain).then((s) => hireable(s, network), (error) => `could not check (${reason(error)})`),
+        unhealthy(network.service),
+    ]);
+    log(`worker ${chain.account} on ${network.name}; hireable: ${line}`);
+    if (sick)
+        log(`warning: ${sick}; results are uploaded there, so none can be delivered until it answers`);
     if (once) {
         const result = await work.round();
         if (result.hired === 0)
@@ -205,17 +302,13 @@ async function run(chain, network, values, once) {
             process.exitCode = 1;
         return;
     }
-    let stopping = false;
-    process.once("SIGINT", () => {
-        stopping = true;
-        log("stopping after the current task");
-    });
     log("waiting for tasks (Ctrl-C to stop)");
-    while (!stopping) {
-        await work.round().catch((error) => log(`round failed: ${describe(error)}`));
-        for (let i = 0; i < 15 && !stopping; i++)
+    while (!stop.stopping()) {
+        await work.round().catch((error) => log(`round failed: ${reason(error)}`));
+        for (let i = 0; i < 15 && !stop.stopping(); i++)
             await new Promise((resolve) => setTimeout(resolve, 1_000));
     }
+    log("stopped");
 }
 async function main(argv) {
     const [command, ...rest] = argv;
@@ -234,20 +327,21 @@ async function main(argv) {
     }
     const { positional, values, switches } = parse(command, rest);
     const network = resolveNetwork(process.env);
-    const chain = createChain(network, account());
+    const worker = signer();
+    if (command === "run")
+        return run(network, worker, values, switches.has("once"));
+    const chain = createChain(network, worker.account);
     switch (command) {
         case "join":
             return join(chain, network, values);
         case "status":
             return status(chain, network);
-        case "run":
-            return run(chain, network, values, switches.has("once"));
         case "price": {
             if (positional[0] === undefined)
                 throw new UsageError("Usage: brainchain-worker price <tUSDG>, such as price 0.25");
             const asking = price(positional[0]);
             if (!(await chain.stake()).registered)
-                throw new UsageError("This worker has not staked yet. Run join, which sets the price too.");
+                throw new Error("This worker has not staked yet. Run join, which sets the price too.");
             await needGas(chain, network);
             await chain.setPrice(asking);
             console.log(`Price set to ${usdg(network, asking)} per task.`);
@@ -256,7 +350,7 @@ async function main(argv) {
         case "leave": {
             const w = await chain.stake();
             if (w.staked === 0n) {
-                throw new UsageError(w.unstaking > 0n ? `Nothing left to unstake: ${stake(network, w.unstaking)} is already unstaking until ${when(w.unlocksAt)}.` : "Nothing is staked.");
+                throw new Error(w.unstaking > 0n ? `Nothing left to unstake: ${stake(network, w.unstaking)} is already unstaking until ${when(w.unlocksAt)}.` : "Nothing is staked.");
             }
             await needGas(chain, network);
             await chain.requestUnstake(w.staked);
@@ -265,13 +359,13 @@ async function main(argv) {
             return;
         }
         case "withdraw": {
-            const [w, held, now] = await Promise.all([chain.stake(), chain.inFlight(), chain.now()]);
+            const [w, held, now] = await Promise.all([chain.stake(), chain.held(), chain.now()]);
             if (w.unstaking === 0n)
-                throw new UsageError("Nothing is unstaking. Run leave first.");
+                throw new Error("Nothing is unstaking. Run leave first.");
             if (now < w.unlocksAt)
-                throw new UsageError(`${stake(network, w.unstaking)} unlocks at ${when(w.unlocksAt)}. Withdraw after that.`);
+                throw new Error(`${stake(network, w.unstaking)} unlocks at ${when(w.unlocksAt)}. Withdraw after that.`);
             if (held > 0)
-                throw new UsageError(`The stake is held until the worker's ${held} task${held === 1 ? "" : "s"} in flight settle.`);
+                throw new Error(`The stake is held until the worker's ${held} task${held === 1 ? "" : "s"} in flight settle.`);
             await needGas(chain, network);
             await chain.withdraw();
             console.log(`Withdrew ${stake(network, w.unstaking)}.`);
@@ -279,15 +373,7 @@ async function main(argv) {
         }
     }
 }
-/** One readable line for an error, with the cause viem keeps apart from its summary. */
-function describe(error) {
-    if (error instanceof HttpRequestError)
-        return `Could not reach ${error.url}${error.details ? ` (${error.details})` : ""}`;
-    if (error instanceof BaseError)
-        return error.shortMessage;
-    return error instanceof Error ? error.message : String(error);
-}
 main(process.argv.slice(2)).catch((error) => {
-    console.error(error instanceof UsageError ? error.message : `brainchain-worker: ${describe(error)}`);
+    console.error(error instanceof UsageError ? error.message : `brainchain-worker: ${reason(error)}`);
     process.exit(1);
 });

package/dist/network.js

@@ -26,10 +26,26 @@ export function resolveNetwork(env) {
         throw new Error(`BRAINCHAIN_NETWORK must be testnet, not "${env.BRAINCHAIN_NETWORK}"`);
     return {
         ...TESTNET,
-        ...(env.BRAINCHAIN_RPC_URL ? { rpc: env.BRAINCHAIN_RPC_URL } : {}),
-        ...(env.BRAINCHAIN_SERVICE_URL ? { service: env.BRAINCHAIN_SERVICE_URL.replace(/\/$/, "") } : {}),
+        ...(env.BRAINCHAIN_RPC_URL ? { rpc: rpcURL(env.BRAINCHAIN_RPC_URL.trim()) } : {}),
+        ...(env.BRAINCHAIN_SERVICE_URL ? { service: serviceURL(env.BRAINCHAIN_SERVICE_URL.trim()) } : {}),
     };
 }
+/** The value is never echoed: an RPC URL can hold an API key, and a mistyped one still does. */
+function rpcURL(value) {
+    const url = URL.canParse(value) ? new URL(value) : undefined;
+    if (url?.protocol !== "https:" && url?.protocol !== "http:")
+        throw new Error("BRAINCHAIN_RPC_URL is not a valid URL: it must start with https:// or http://");
+    return value;
+}
+/** The worker signs and sends its results to the service, so only https is accepted, or plain http to a service on this machine. */
+function serviceURL(value) {
+    const url = URL.canParse(value) ? new URL(value) : undefined;
+    const local = url?.hostname === "localhost" || url?.hostname === "127.0.0.1";
+    if (url?.protocol !== "https:" && !(url?.protocol === "http:" && local)) {
+        throw new Error("BRAINCHAIN_SERVICE_URL must be an https URL, or http on localhost or 127.0.0.1");
+    }
+    return value.replace(/\/+$/, "");
+}
 export function chainOf(network) {
     return defineChain({
         id: network.chainId,

package/dist/state.js

@@ -0,0 +1,77 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const stateDir = () => join(homedir(), ".config", "brainchain-worker");
+const empty = (board) => ({ board: board.toLowerCase(), tasks: {}, done: [] });
+export function memoryStore(board = "") {
+    return { state: empty(board), save: () => undefined };
+}
+/** State in a 0600 JSON file, replaced whole on every save so a crash never leaves half a file. */
+export function fileStore(file, board) {
+    let state = empty(board);
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    if (text !== undefined) {
+        let saved;
+        try {
+            saved = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`${file} is not valid JSON. Move it aside to start with no saved work.`);
+        }
+        if (saved.board === state.board)
+            state = { ...state, ...saved, tasks: saved.tasks ?? {}, done: saved.done ?? [] };
+    }
+    return {
+        state,
+        save() {
+            mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+            const temp = `${file}.${process.pid}.tmp`;
+            writeFileSync(temp, JSON.stringify(state), { mode: 0o600 });
+            renameSync(temp, file);
+        },
+    };
+}
+function alive(pid) {
+    // A container restarts its process with the same pid, so our own pid in the file is a stale lock.
+    if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Takes the lock in `file` for this process until it exits; refuses while a live process holds it. */
+export function lock(file) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    for (;;) {
+        try {
+            writeFileSync(file, String(process.pid), { flag: "wx", mode: 0o600 });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        // The holder may have released it since the write failed; then the next try takes it.
+        const holder = existsSync(file) ? Number(readFileSync(file, "utf8").trim()) : 0;
+        if (alive(holder))
+            throw new Error(`Another run (pid ${holder}) is already working for this worker. Stop it before starting another; ${file} holds its lock.`);
+        rmSync(file, { force: true });
+    }
+    const release = () => {
+        if (existsSync(file) && readFileSync(file, "utf8") === String(process.pid))
+            rmSync(file, { force: true });
+    };
+    process.once("exit", release);
+    return release;
+}