@irythill/orq 0.0.0-stage → 0.1.0

package/dist/commands/verify.js

@@ -0,0 +1,123 @@
+// orq verify — tests related to what changed in a worktree (port of herdr-verify), run by the conductor and not by the
+// child (the child hits its 4 GB cap with jest/vitest). One suite at a time on the machine (the "verify" queue,
+// machine.test_slots) under its own memory cap (machine.test_mem_max, or $VERIFY_MEM_MAX). Returns at once: the run goes
+// to a herdr tab, a tmux window or the background (src/terminal.ts); -x runs it here, in the foreground.
+//   output: <prefix>.txt — NEW failures and failures that already exist on the base; <prefix>.done "status=ok|fail new=N".
+//   status=ok only with no new failure. On-demand base check: only if some test fails, the SAME test files run in a
+//   temporary worktree at origin/<base> (fetched right then); whatever fails there is pre-existing.
+// Same protocol as orq agent: `orq wait <prefix>`, or "[HERDR-AGENT DONE] verify <repo> ..." in the conductor's herdr pane.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { getPath, loadConfig } from "../config.js";
+import { m } from "../i18n.js";
+import { dropWorktree, failures, git, inJob, JS_EXT, launchJob, linkModules, runnerArgs, runnerOf, runTests, testCap, today, unsupported } from "../testrun.js";
+export const USAGE = "orq verify -w <workspace> -r <repo> -d <worktree> -b <base> -o <prefix> [-g group] [-x]   tests of the diff, new vs pre-existing failures";
+export async function verify(argv) {
+    if (argv[0] === "--run")
+        return run(JSON.parse(readFileSync(argv[1], "utf8")));
+    const o = {};
+    let here = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-x")
+            here = true;
+        else if (/^-[wrdbog]$/.test(a) && i + 1 < argv.length)
+            o[a[1]] = argv[++i];
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    for (const f of "wrdbo")
+        if (!o[f]) {
+            console.error(`${m("missing", "faltou")} -${f}\n${USAGE}`);
+            return 2;
+        }
+    const out = resolve(o.o);
+    mkdirSync(dirname(out), { recursive: true });
+    rmSync(`${out}.done`, { force: true });
+    rmSync(`${out}.txt`, { force: true });
+    // Title "<ID> verify <repo>" (ID = the prefix's folder, .orquestra/<ID>/) so closing the issue finds the tab.
+    const j = { cmd: "verify", title: `${basename(dirname(out))} verify ${o.r}`, ws: resolve(o.w), repo: o.r, wt: resolve(o.d), base: o.b, out };
+    const { cfg } = loadConfig(j.ws);
+    if (here)
+        return run({ ...j, parent: process.env.HERDR_NOTIFY_PANE ?? "", host: "plain", closeAfter: 0, keep: true });
+    console.log(`[orq verify] ${j.title} → ${launchJob(cfg, j, o.g || "agents")}`);
+    return 0;
+}
+async function run(j) {
+    const O = j.out, R = j.repo, B = j.base, WT = j.wt;
+    const { cfg } = loadConfig(j.ws);
+    let NEW = 0;
+    return inJob(j, `verify ${basename(dirname(O))} ${R}`, Number(getPath(cfg, "machine.test_slots") ?? 1), async (c) => {
+        const diff = git(WT, "diff", "--name-only", "--diff-filter=d", `origin/${B}...HEAD`);
+        if (diff === undefined)
+            throw new Error(m(`git diff against origin/${B} failed in ${WT}`, `o git diff contra origin/${B} falhou em ${WT}`));
+        const files = diff.split(/\r?\n/).filter((f) => JS_EXT.test(f));
+        const head = git(WT, "rev-parse", "--short", "HEAD") ?? "?";
+        if (!files.length) {
+            writeFileSync(`${O}.txt`, `# verify ${R} ${head}: no JS/TS file changed relative to origin/${B}\n`);
+            return true;
+        }
+        const { runner, script } = runnerOf(WT);
+        if (!runner)
+            throw new Error(unsupported(script));
+        const cap = testCap(cfg);
+        // One run → "<file> :: <test>" for each failure (undefined = the runner left no JSON report).
+        const tests = async (dir, mode, list) => {
+            const json = join(tmpdir(), `orq-verify-${process.pid}-${Date.now()}.json`);
+            try {
+                await runTests(dir, runner, runnerArgs(runner, mode, list, json), cap, c);
+                const r = failures(json, dir);
+                if (!r)
+                    c.say(m(`no JSON result in ${dir} (did the runner die? see ${O}.log)`, `sem resultado JSON em ${dir} (o runner morreu? veja ${O}.log)`));
+                return r;
+            }
+            finally {
+                rmSync(json, { force: true });
+            }
+        };
+        const mine = await tests(WT, "related", files);
+        if (!mine)
+            throw new Error(m("the test run failed", "a execução dos testes falhou"));
+        const failed = mine.failed;
+        let baseFailed = [], baseInfo = "no failure on the branch: base not checked";
+        if (failed.length)
+            baseInfo = await onBase(j, c, failed, async (dir, list) => (await tests(dir, "files", list))?.failed, (f) => { baseFailed = f; });
+        const newList = failed.filter((f) => !baseFailed.includes(f)), oldList = failed.filter((f) => baseFailed.includes(f));
+        NEW = newList.length;
+        const text = [`# verify ${R} ${head} ${today()}: ${mine.total} tests related to ${files.length} changed files`, `# base: ${baseInfo}`,
+            "", `## New failures (${NEW})`, ...(newList.length ? newList : ["none"]),
+            "", `## Already failing on origin/${B}`, ...(oldList.length ? oldList : ["none"])].join("\n") + "\n";
+        writeFileSync(`${O}.txt`, text);
+        process.stdout.write(text);
+        return NEW === 0;
+    }, (st) => ({ fields: `status=${st} new=${NEW}`, notice: `verify ${R} status=${st} new=${NEW} answer: ${O}.txt` }));
+}
+/** The failing test files again, on a fresh origin/<base> in a temporary worktree (only those that exist there). */
+async function onBase(j, c, failed, tests, set) {
+    const REPO = join(j.ws, j.repo), B = j.base, BWT = join(j.ws, ".worktrees", `verifybase-${j.repo}-${process.pid}`);
+    if (git(REPO, "fetch", "-q", "origin", B) === undefined)
+        c.say(m(`WARNING: fetching origin/${B} failed; using the local origin/${B}`, `AVISO: o fetch de origin/${B} falhou; usando o origin/${B} local`));
+    if (git(REPO, "worktree", "add", "-q", "--detach", BWT, `origin/${B}`) === undefined)
+        return `WARNING: could not create a worktree at origin/${B}; every failure counts as new`;
+    const drop = () => dropWorktree(REPO, BWT);
+    c.cleanup.push(drop);
+    try {
+        linkModules(REPO, BWT);
+        const files = [...new Set(failed.map((f) => f.replace(/ :: .*/, "")))].filter((f) => existsSync(join(BWT, f)));
+        const info = `${files.length} failing file(s) run on origin/${B} ${git(REPO, "rev-parse", "--short", `origin/${B}`) ?? "?"}`;
+        if (!files.length)
+            return info;
+        const base = await tests(BWT, files);
+        if (!base)
+            return `WARNING: the base run failed (see ${j.out}.log); every failure counts as new`;
+        set(base);
+        return info;
+    }
+    finally {
+        c.cleanup.splice(c.cleanup.indexOf(drop), 1);
+        drop();
+    }
+}

package/dist/commands/wait.js

@@ -0,0 +1,81 @@
+// orq wait — Notifier for any conductor: block until children started by `orq agent` (or orq verify/baseline) write
+// <prefix>.done, then print one line each: "[ORQ AGENT DONE] <title> status=ok rc=0 ... answer: <file>".
+// Exit 0 = all ok, 1 = some failed (or its runner died without .done), 124 = timeout. With --any, returns at the first.
+// Claude Code: run it as a background task; it wakes the conductor when it exits.
+import { existsSync, readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { m } from "../i18n.js";
+import { alive } from "../lock.js";
+export const USAGE = "orq wait [--any] [--timeout <s>] [--answer] <prefix>...   block until child agents finish (exit 1 = one failed)";
+const read = (f) => { try {
+    return readFileSync(f, "utf8");
+}
+catch {
+    return undefined;
+} };
+/** Finished? → its summary line and whether it went well. */
+export function doneLine(prefix) {
+    let done = read(`${prefix}.done`)?.trim();
+    if (done === undefined) {
+        const pid = Number(read(`${prefix}.pid`));
+        if (!pid || alive(pid) || existsSync(`${prefix}.done`))
+            return undefined;
+        done = `status=died ${m("(the runner exited without writing .done)", "(o runner saiu sem escrever .done)")}`;
+    }
+    let title = basename(prefix);
+    try {
+        title = JSON.parse(read(`${prefix}.job.json`) ?? "").title || title;
+    }
+    catch { /* verify/baseline: no job */ }
+    const answer = [`${prefix}.out.md`, `${prefix}.txt`].find(existsSync) ?? prefix;
+    return { line: `[ORQ AGENT DONE] ${title} ${done} answer: ${answer}`, ok: /\bstatus=ok\b/.test(done) };
+}
+export async function wait(argv) {
+    let any = false, timeout = 0, answer = false;
+    const pending = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--any")
+            any = true;
+        else if (a === "--answer")
+            answer = true;
+        else if (a === "--timeout")
+            timeout = Number(argv[++i]);
+        else if (!a.startsWith("-"))
+            pending.push(a.replace(/\.(done|out\.md)$/, ""));
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+    }
+    if (!pending.length || Number.isNaN(timeout)) {
+        console.error(USAGE);
+        return 2;
+    }
+    const end = timeout > 0 ? Date.now() + timeout * 1000 : Infinity;
+    let failed = false;
+    for (;;) {
+        for (const p of [...pending]) {
+            const d = doneLine(p);
+            if (!d)
+                continue;
+            pending.splice(pending.indexOf(p), 1);
+            console.log(d.line);
+            if (answer) {
+                const t = read(`${p}.out.md`);
+                if (t)
+                    console.log(t.trimEnd());
+            }
+            failed ||= !d.ok;
+            if (any)
+                return d.ok ? 0 : 1;
+        }
+        if (!pending.length)
+            return failed ? 1 : 0;
+        if (Date.now() > end) {
+            console.log(m(`still running: ${pending.join(" ")}`, `ainda rodando: ${pending.join(" ")}`));
+            return 124;
+        }
+        await new Promise((r) => setTimeout(r, 1000));
+    }
+}

package/dist/config.js

@@ -0,0 +1,93 @@
+// The orq configuration, merged in layers (each overrides the previous, key by key):
+//   1. built-in defaults (DEFAULTS, below)
+//   2. personal:  $ORQ_CONFIG, or <config dir>/config.toml | config.json
+//   3. workspace: <workspace>/.orq/workspace.toml | workspace.json  (searched from -w or the current folder, upwards)
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { configDir, expand } from "./paths.js";
+import { m } from "./i18n.js";
+export const DEFAULTS = {
+    machine: {
+        agent_mem_max: "4G", // memory cap per agent
+        agent_swap_max: "1G",
+        test_mem_max: "6G", // cap per test suite (orq verify, orq baseline)
+        mem_enforce: "auto", // auto (kernel cap where possible, else watchdog) | kernel | watchdog | off
+        test_slots: 1, // test suites in parallel on the machine
+        close_tab_after: 20, // seconds until a finished child tab closes (0 = never)
+        tui: false, // children in the agent's own screen (-T) by default
+        terminal: "auto", // where children show their output: auto (herdr, else tmux, else plain) | herdr | tmux | plain
+    },
+    agents: {}, // only agents declared here are available; run templates: built in for 5 (src/agents.ts), or `run = ...`
+    policy: {
+        quota_limit: 90, // quota % from which an agent/account is skipped
+        max_rounds: 2, // fix rounds before stopping and calling the user
+        review: "other-vendor", // other-vendor | any
+    },
+    ui: { lang: "auto", theme: "gunmetal" }, // lang: auto | en | pt · theme: gunmetal | chrome | lcd | terminal
+    // Where quota comes from, per agent: "builtin" | "none" | false | { command = "..." } (see src/quota.ts).
+    // "claude" covers every account in claude-accounts.
+    quota: { claude: "builtin", codex: "builtin", opencode: "none", antigravity: "builtin", copilot: "builtin" },
+    tracker: { kind: "none" }, // plane | none
+    repos: {}, // defined by the workspace
+};
+export class ConfigError extends Error {
+}
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+export function merge(base, over) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(over))
+        out[k] = isObj(v) && isObj(out[k]) ? merge(out[k], v) : v;
+    return out;
+}
+function expandAll(v) {
+    if (Array.isArray(v))
+        return v.map(expandAll);
+    if (isObj(v))
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, expandAll(x)]));
+    return typeof v === "string" ? expand(v) : v;
+}
+export function loadFile(path) {
+    const text = readFileSync(path, "utf8");
+    try {
+        return (path.endsWith(".json") ? JSON.parse(text) : parseToml(text));
+    }
+    catch (e) {
+        throw new ConfigError(m(`orq config: error reading ${path}: ${e.message}`, `orq config: erro lendo ${path}: ${e.message}`));
+    }
+}
+const firstFile = (...c) => c.find((f) => f && existsSync(f));
+export function findWorkspace(start) {
+    for (let d = resolve(start);; d = dirname(d)) {
+        const file = firstFile(join(d, ".orq", "workspace.toml"), join(d, ".orq", "workspace.json"));
+        if (file)
+            return { root: d, file };
+        if (dirname(d) === d)
+            return {};
+    }
+}
+export function loadConfig(workspace) {
+    const user = firstFile(process.env.ORQ_CONFIG && expand(process.env.ORQ_CONFIG), join(configDir(), "config.toml"), join(configDir(), "config.json"));
+    const ws = findWorkspace(workspace ?? process.cwd());
+    let cfg = DEFAULTS;
+    const files = [];
+    for (const f of [user, ws.file]) {
+        if (!f)
+            continue;
+        cfg = merge(cfg, loadFile(f));
+        files.push(f);
+    }
+    cfg = expandAll(cfg);
+    cfg._workspace = ws.root ?? null;
+    return { cfg, files };
+}
+/** Value at a dotted path (a.b.c), or undefined. */
+export function getPath(cfg, path) {
+    let v = cfg;
+    for (const part of path.split(".")) {
+        if (!isObj(v) || !(part in v))
+            return undefined;
+        v = v[part];
+    }
+    return v;
+}

package/dist/fsutil.js

@@ -0,0 +1,9 @@
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/** Write via a temp file + rename, so a reader never sees a half-written file. */
+export function writeAtomic(path, text) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, text, "utf8");
+    renameSync(tmp, path);
+}

package/dist/i18n.js

@@ -0,0 +1,21 @@
+export function systemLang() {
+    const e = process.env;
+    const loc = e.LC_ALL || e.LC_MESSAGES || e.LANG || Intl.DateTimeFormat().resolvedOptions().locale || "";
+    return loc.toLowerCase().startsWith("pt") ? "pt" : "en";
+}
+export function detectLang(cfgLang, useEnv = true) {
+    const v = useEnv ? process.env.ORQ_LANG : undefined;
+    if (v === "en" || v === "pt")
+        return v;
+    if (cfgLang === "en" || cfgLang === "pt")
+        return cfgLang;
+    return systemLang();
+}
+let current;
+export function setLang(l) {
+    current = l;
+}
+export function m(en, pt) {
+    current ??= detectLang();
+    return current === "pt" && pt !== undefined ? pt : en;
+}

package/dist/install.js

@@ -0,0 +1,137 @@
+// What a fresh `npm i -g @irythill/orq` still needs, done by `orq setup` on any OS (install.sh is a Linux extra):
+//   skills      orq's skills (skills/*/SKILL.md, shipped in the package) linked into ~/.claude/skills and each Claude
+//               account's skills folder — a junction on Windows (no admin rights), a copy if linking fails. A real
+//               folder, or a link to another live copy (a clone of the repo), is never touched.
+//   workspace   <folder>/.orquestra, .worktrees, CLAUDE.md from the template (only if missing) and the /issue playbook
+//               in the conductor's format (orq instructions)
+//   environment what orq found: git, terminal host, memory cap, keyring, the shell's completion line
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { claudeAccounts } from "./accounts.js";
+import { writeAtomic } from "./fsutil.js";
+import { m } from "./i18n.js";
+import { backend } from "./keyring.js";
+import { hasKernelCap } from "./process.js";
+import { detectHost } from "./terminal.js";
+export const PKG = fileURLToPath(new URL("..", import.meta.url));
+const SKILLS = join(PKG, "skills");
+const real = (p) => { try {
+    return realpathSync(p);
+}
+catch {
+    return undefined;
+} };
+/** Skill folders of every Claude account (~/.claude always, like install.sh). */
+export function skillRoots() {
+    return [...new Set([join(homedir(), ".claude"), ...claudeAccounts().map((a) => a.dir)].map((d) => join(d, "skills")))];
+}
+/** Link each of orq's skills into each root; one line per skill and root. */
+export function installSkills(roots = skillRoots()) {
+    const out = [];
+    const skills = readdirSync(SKILLS).filter((s) => existsSync(join(SKILLS, s, "SKILL.md")));
+    for (const root of roots)
+        for (const s of skills) {
+            const src = join(SKILLS, s), dst = join(root, s);
+            let st;
+            try {
+                st = lstatSync(dst);
+            }
+            catch { /* missing */ }
+            if (st && !st.isSymbolicLink()) {
+                // A copy made by an earlier `orq setup` (no links on this system) is refreshed; anything else is the user's.
+                if (existsSync(join(dst, ".orq-copy"))) {
+                    rmSync(dst, { recursive: true, force: true });
+                    st = undefined;
+                }
+                else {
+                    out.push(`  ${m("skip", "pulei")}    ${dst} ${m("(a real folder, not a link: move it away to install)", "(uma pasta de verdade, não um link: tire-a do caminho para instalar)")}`);
+                    continue;
+                }
+            }
+            if (st) {
+                const to = real(dst);
+                if (to === real(src)) {
+                    out.push(`  ok      ${dst}`);
+                    continue;
+                }
+                if (to && existsSync(join(to, "SKILL.md"))) {
+                    out.push(`  ${m("keep", "mantive")}  ${dst} → ${readlinkSync(dst)}`);
+                    continue;
+                }
+                rmSync(dst, { force: true }); // dangling (e.g. an old node version's global folder)
+            }
+            mkdirSync(root, { recursive: true });
+            try {
+                symlinkSync(src, dst, process.platform === "win32" ? "junction" : "dir");
+                out.push(`  link    ${dst} → ${src}`);
+            }
+            catch {
+                cpSync(src, dst, { recursive: true });
+                writeAtomic(join(dst, ".orq-copy"), m("copied by orq setup; refreshed on every run\n", "copiado pelo orq setup; atualizado a cada execução\n"));
+                out.push(`  ${m("copy", "cópia")}    ${dst}`);
+            }
+        }
+    return out;
+}
+/** Prepare a conductor's workspace folder; `fmt` = claude (SKILL.md) | agents (AGENTS.md). */
+export function prepareWorkspace(dir, fmt, name = basename(resolve(dir))) {
+    const ws = resolve(dir), out = [];
+    for (const d of [".orquestra", ".worktrees"])
+        mkdirSync(join(ws, d), { recursive: true });
+    const map = join(ws, "CLAUDE.md");
+    if (!existsSync(map)) {
+        const t = readFileSync(join(PKG, "templates", "workspace.CLAUDE.md"), "utf8");
+        writeAtomic(map, t.split("{{WORKSPACE}}").join(ws).split("{{NAME}}").join(name));
+        out.push(m(`  created ${map} — fill in repos, group, base branch, Plane and issue standard`, `  criado ${map} — preencha repos, grupo, branch base, Plane e padrão de issue`));
+    }
+    else
+        out.push(m(`  ok      ${map} (kept)`, `  ok      ${map} (mantido)`));
+    const r = spawnSync(process.execPath, [join(PKG, "dist", "cli.js"), "instructions", fmt, "-w", ws], { encoding: "utf8" });
+    out.push(`  ${(r.stdout || r.stderr).trim()}`);
+    return out;
+}
+const SHELLS = ["bash", "zsh", "fish", "powershell"];
+/** The user's shell, from $SHELL (PowerShell on Windows without one). */
+export function userShell() {
+    const s = basename(process.env.SHELL ?? "").replace(/\.exe$/i, "");
+    if (s === "pwsh")
+        return "powershell";
+    if (SHELLS.includes(s))
+        return s;
+    return process.platform === "win32" ? "powershell" : undefined;
+}
+/** The line that turns completion on, per shell. */
+export const completionLine = (s) => ({
+    bash: `echo 'eval "$(orq completion bash)"' >> ~/.bashrc`,
+    zsh: `echo 'eval "$(orq completion zsh)"' >> ~/.zshrc   # ${m("after compinit", "depois do compinit")}`,
+    fish: "orq completion fish > ~/.config/fish/completions/orq.fish",
+    powershell: "Add-Content $PROFILE 'orq completion powershell | Out-String | Invoke-Expression'",
+}[s]);
+/** What orq found on this machine, one line each (required things first). */
+export function environment(cfg) {
+    const has = (c, a = ["--version"]) => spawnSync(c, a, { stdio: "ignore", timeout: 10_000 }).status === 0;
+    const row = (k, v) => `  ${k.padEnd(10)} ${v}`;
+    let host;
+    try {
+        host = detectHost(cfg);
+    }
+    catch (e) {
+        host = e.message;
+    }
+    const mode = String((cfg.machine ?? {}).mem_enforce ?? "auto");
+    const kb = backend(), sh = userShell();
+    return [
+        row("node", process.version),
+        row("git", has("git") ? "ok" : m("MISSING — required (worktrees, diffs, tests): install git", "FALTANDO — obrigatório (worktrees, diffs, testes): instale o git")),
+        row("terminal", `${host} ${m("(children: herdr tab, tmux window or background; machine.terminal)", "(filhos: aba do herdr, janela do tmux ou segundo plano; machine.terminal)")}`),
+        row(m("memory", "memória"), mode === "off" ? "off" : mode === "watchdog" || !hasKernelCap()
+            ? m("watchdog (samples the process tree; machine.mem_enforce)", "vigia (amostra a árvore de processos; machine.mem_enforce)")
+            : m("kernel (systemd scope)", "kernel (scope do systemd)")),
+        row("keyring", kb === "native" ? "ok" : kb === "cli" ? m("OS command (native module did not load)", "comando do SO (o módulo nativo não carregou)")
+            : m("none — Antigravity/macOS Claude quota shows ?", "nenhum — a cota do Antigravity/Claude no macOS mostra ?")),
+        row("shell", sh ? `${sh} — ${m("completion", "autocompletar")}: ${completionLine(sh)}` : m("unknown — orq completion bash|zsh|fish|powershell", "desconhecido — orq completion bash|zsh|fish|powershell")),
+    ];
+}

package/dist/keyring.js

@@ -0,0 +1,51 @@
+// Keyring — read a secret another tool keeps in the OS keyring (Secret Service on Linux, Keychain on macOS, Credential
+// Manager on Windows) through @napi-rs/keyring. orq only reads; it never writes or refreshes someone else's login.
+// The native module may not load (a platform without a prebuilt binary, a broken install): then the OS's own CLI where
+// there is one (Linux secret-tool, macOS security), else nothing. $ORQ_KEYRING = native | cli | off forces a backend.
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+let native;
+function load() {
+    if (native === undefined) {
+        try {
+            native = createRequire(import.meta.url)("@napi-rs/keyring");
+        }
+        catch {
+            native = null;
+        }
+    }
+    return native;
+}
+const cli = () => process.platform === "linux" ? "secret-tool" : process.platform === "darwin" ? "security" : undefined;
+/** Which backend reads secrets here. */
+export function backend() {
+    const want = process.env.ORQ_KEYRING;
+    if (want === "off")
+        return "none";
+    if (want !== "cli" && load())
+        return "native";
+    return cli() && spawnSync(cli(), ["--help"], { stdio: "ignore", timeout: 5000 }).error === undefined ? "cli" : "none";
+}
+/**
+ * The secret stored for (service, account), or undefined. `target` is the Windows credential name when the tool that
+ * wrote it doesn't use the keyring-rs default ("<account>.<service>"), e.g. go-keyring's "<service>:<account>".
+ */
+export function readSecret(service, account, target) {
+    const b = backend();
+    if (b === "native") {
+        try {
+            const e = target && process.platform === "win32" ? load().Entry.withTarget(target, service, account) : new (load().Entry)(service, account);
+            return e.getPassword() ?? undefined;
+        }
+        catch {
+            return undefined;
+        } // no keyring service (headless Linux without D-Bus), locked, denied
+    }
+    if (b === "cli") {
+        const args = process.platform === "linux" ? ["lookup", "service", service, "username", account]
+            : ["find-generic-password", "-s", service, "-a", account, "-w"];
+        const r = spawnSync(cli(), args, { encoding: "utf8", timeout: 10_000, stdio: ["ignore", "pipe", "ignore"] });
+        return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : undefined;
+    }
+    return undefined;
+}

package/dist/lock.js

@@ -0,0 +1,81 @@
+// Portable FIFO lock with N slots (the test queue), made of plain files — no flock, no /proc/locks.
+//   <state dir>/locks/<name>/<ms>-<pid>.json   one entry per process that asked: {pid, label, at, held}
+// Holders are the entries with held = true whose process is alive. A waiter takes a slot when fewer than `slots` are
+// held and it is the oldest live non-held entry, after its file has existed for SETTLE_MS (so an older entry still
+// being written is seen first). Dead processes' entries are swept by whoever looks, so a crash never leaves the queue
+// stuck. Works the same on Linux, macOS and Windows (process.kill(pid, 0) checks liveness everywhere).
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { writeAtomic } from "./fsutil.js";
+import { stateDir } from "./paths.js";
+const SETTLE_MS = 250;
+const dir = (name) => join(stateDir(), "locks", name);
+export function alive(pid) {
+    if (!(pid > 0))
+        return false; // kill(0, …) would signal our own process group and "succeed"
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/** Live entries in queue order (dead ones are removed). */
+export function entries(name) {
+    let files;
+    try {
+        files = readdirSync(dir(name)).filter((f) => f.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        const file = join(dir(name), f);
+        try {
+            const e = { ...JSON.parse(readFileSync(file, "utf8")), file };
+            if (alive(e.pid))
+                out.push(e);
+            else
+                rmSync(file, { force: true });
+        }
+        catch { /* being written or removed: skip this round */ }
+    }
+    return out.sort((a, b) => a.at - b.at || a.pid - b.pid);
+}
+export const status = (name) => {
+    const all = entries(name);
+    return { holders: all.filter((e) => e.held), waiters: all.filter((e) => !e.held) };
+};
+/** Queue `pid` and resolve once it holds a slot. `onWait` is called once if it has to wait. */
+export async function acquire(name, pid, label, slots = 1, onWait, pollMs = 500) {
+    mkdirSync(dir(name), { recursive: true });
+    const mine = entries(name).find((e) => e.pid === pid);
+    if (mine?.held)
+        return; // re-entrant for the same process
+    const at = mine?.at ?? Date.now();
+    const file = mine?.file ?? join(dir(name), `${at}-${pid}.json`);
+    writeAtomic(file, JSON.stringify({ pid, label, at, held: false }));
+    let told = false;
+    for (;;) {
+        const all = entries(name), held = all.filter((e) => e.held).length;
+        const first = all.find((e) => !e.held);
+        const settled = Date.now() - statSync(file).mtimeMs >= SETTLE_MS || Date.now() - at >= SETTLE_MS;
+        if (held < Math.max(1, slots) && first?.pid === pid && settled) {
+            writeAtomic(file, JSON.stringify({ pid, label, at, held: true }));
+            return;
+        }
+        if (!told && (held >= slots || first?.pid !== pid)) {
+            onWait?.(all.findIndex((e) => e.pid === pid) - held + 1);
+            told = true;
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+}
+export function release(name, pid) {
+    const e = entries(name).find((x) => x.pid === pid);
+    if (e)
+        rmSync(e.file, { force: true });
+    return Boolean(e);
+}

package/dist/paths.js

@@ -0,0 +1,34 @@
+// Where orq keeps its files, per OS. Linux/macOS keep the XDG paths the bash/Python scripts always used, so an
+// existing ~/.config/orq and ~/.local/state/orq keep working; Windows uses %APPDATA% / %LOCALAPPDATA%.
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const env = process.env;
+const win = process.platform === "win32";
+export function configDir() {
+    if (env.XDG_CONFIG_HOME)
+        return join(env.XDG_CONFIG_HOME, "orq");
+    if (win)
+        return join(env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "orq");
+    return join(homedir(), ".config", "orq");
+}
+export function stateDir() {
+    if (env.XDG_STATE_HOME)
+        return join(env.XDG_STATE_HOME, "orq");
+    if (win)
+        return join(env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "orq", "state");
+    return join(homedir(), ".local", "state", "orq");
+}
+/** The personal config file to write: $ORQ_CONFIG, else config.json if only that exists, else config.toml. */
+export function userConfigFile() {
+    if (env.ORQ_CONFIG)
+        return env.ORQ_CONFIG;
+    const toml = join(configDir(), "config.toml"), json = join(configDir(), "config.json");
+    return existsSync(json) && !existsSync(toml) ? json : toml;
+}
+/** Expand a leading ~ and $VAR / ${VAR} (unknown variables are left as they are, like Python's expandvars). */
+export function expand(s) {
+    if (s === "~" || s.startsWith("~/") || s.startsWith("~\\"))
+        s = homedir() + s.slice(1);
+    return s.replace(/\$(\w+)|\$\{(\w+)\}/g, (all, a, b) => env[a ?? b] ?? all);
+}