heedvane 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# heedvane
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect the coding agents on your machine to your Heedvane organization: guardrails, approved-skill
+checks and team memory for Claude Code, Codex, Cursor, Gemini CLI, Hermes, OpenCode and more.
+
+```sh
+npx heedvane
+```
+
+The installer shows the agents it found on your machine. Tick the ones you want, choose what Heedvane
+adds and does, confirm. It installs, starts Heedvane in the background and signs you in through the
+browser. It needs Node.js 22 or newer.
+
+Your dashboard's Agents page has the same command with your server and organization filled in:
+
+```sh
+npx heedvane connect --server https://app.heedvane.com --org <organization id>
+```
+
+## What it changes
+
+- Writes `~/.heed/heed.yaml`, your control file, with your answers. Run `npx heedvane` again to change
+  them.
+- Adds Heedvane's hooks, MCP server entry and skill to each agent you ticked. A config file it edits is
+  backed up first.
+- Starts Heedvane's local listener, which answers the hooks. After a restart the hooks start it again by
+  themselves, at most once a minute. Set `HEED_LISTENER_AUTOSTART=0` to turn that off.
+
+Run `npx heedvane connect --dry-run` to see every file it would touch without writing anything.
+
+## Software factories, CI and containers
+
+Agents that run unattended (a factory looping on a server, a CI job, a container on AWS) use the same
+package without the installer:
+
+```sh
+# Once, when you build the image: install the hooks for the agent the factory runs
+npx -y heedvane connect --server https://app.heedvane.com --org <organization id> --agent claude --yes
+
+# When the container starts: sign in with an organization key from your secret store
+printf '%s' "$HEEDVANE_ORG_KEY" | npx heedvane auth org
+
+# Every agent run: Heedvane answers the hooks for exactly this run
+npx heedvane run -- claude -p "fix the failing tests"
+```
+
+`run` keeps the agent's terminal output and exit code, so your pipeline reads them as before. Heedvane's
+own lines go to stderr and `~/.heed/listener.log`.
+
+- Claude Code runs the hooks in print mode (`claude -p`), but not with `--bare`.
+- Codex runs hooks only after they are trusted.
+- Pi and Flue agents cannot be connected yet.
+
+## Everyday commands
+
+| Command | What it does |
+| --- | --- |
+| `npx heedvane` | Opens the installer: change agents and features any time. |
+| `npx heedvane doctor` | Checks the install and prints a fix for each problem. |
+| `npx heedvane listener start` | Runs the listener in the foreground. |
+| `npx heedvane run -- <command>` | Runs one agent with Heedvane, for CI and containers. |
+| `npx heedvane uninstall` | Removes only the entries Heedvane added. `heed.yaml` stays. |
+| `npx heedvane --help` | Lists every command and flag. |

package/dist/apply.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The transactional config write recipe (REA's pattern, ported):
+ *
+ *   1. Refuse to follow symlinks not owned by the current uid (lstat; if the
+ *      path is a symlink, realpath and require a regular file owned by the
+ *      current uid — else { status: "failed", reason: "unsafe-path" }).
+ *   2. Missing file -> "create".
+ *   3. Malformed existing config -> "invalid" with a remediation string;
+ *      the file is NEVER overwritten.
+ *   4. Semantic compare (sorted-keys deep-equal, key order ignored) ->
+ *      "unchanged" when the desired entry is already current.
+ *   5. Backup via copyFile with COPYFILE_EXCL to <path>.heedvane.backup
+ *      (EEXIST means a backup already exists — proceed, never clobber).
+ *   6. Atomic write via write-file-atomic, mode 0600.
+ *   7. Read back, re-parse, semantic verify — on mismatch RESTORE the
+ *      original bytes and return { status: "failed", reason: "readback" }.
+ *      The backup is kept either way.
+ */
+import { serializeDoc, type ConfigFormat } from "./config-doc.js";
+/** Injectable serializer seam (tests use a broken serializer to force readback failure). */
+export type Serializer = typeof serializeDoc;
+export interface ApplyOptions {
+    serialize?: Serializer;
+}
+export type Inspection = {
+    status: "create";
+} | {
+    status: "update";
+} | {
+    status: "unchanged";
+} | {
+    status: "invalid";
+    remediation: string;
+} | {
+    status: "failed";
+    reason: "unsafe-path";
+    detail: string;
+};
+export type ApplyResult = {
+    status: "create";
+    backupPath?: string;
+} | {
+    status: "update";
+    backupPath: string;
+} | {
+    status: "unchanged";
+} | {
+    status: "invalid";
+    remediation: string;
+} | {
+    status: "failed";
+    reason: "unsafe-path" | "readback" | "write";
+    backupPath?: string;
+};
+export interface ConfigTarget {
+    path: string;
+    format: ConfigFormat;
+}
+/** Which entries (name -> desired value) to inspect or write, inside which container; one file write covers them all. */
+export interface EntrySpec {
+    serversKey: string;
+    entries: Record<string, unknown>;
+}
+/** Write `entries` into `containerKey`, or (uninstall) remove the `remove` entry. */
+export type ApplyEntryRequest = {
+    containerKey: string;
+    entries: Record<string, unknown>;
+} | {
+    containerKey: string;
+    remove: string;
+};
+/** Compat surface (A's ApplyResult): flat shape carrying the path. */
+export type ApplyStatus = "create" | "update" | "unchanged" | "invalid" | "failed";
+export interface ApplyTarget {
+    path: string;
+    format: ConfigFormat;
+}
+export interface ApplyEntryResult {
+    status: ApplyStatus;
+    path: string;
+    backupPath?: string;
+    reason?: string;
+    remediation?: string;
+}
+/**
+ * Compat entry point (A's API) on top of {@link applyClientConfig} /
+ * {@link transactionalWrite}: same recipe, but the result carries `path` and
+ * `remove: true` removes an entry (uninstall). Malformed configs and
+ * unowned symlinks report `invalid` with a remediation, never a write.
+ */
+export declare function applyEntry(target: ApplyTarget, request: ApplyEntryRequest): Promise<ApplyEntryResult>;
+/**
+ * Set (or, with `undefined`, remove) one top-level key of a JSON settings file through the same
+ * transactional recipe; `unchanged` when it already holds that value, or is absent and stays so.
+ */
+export declare function applyTopLevelKey(target: ApplyTarget, key: string, value: unknown): Promise<ApplyEntryResult>;
+/** Read-only inspection: what would applying `desired` to this config do? Never writes. */
+export declare function inspectClient(target: ConfigTarget, spec: EntrySpec): Promise<Inspection>;
+/**
+ * Apply `desired` to the config transactionally. See the module doc for the
+ * recipe. Returns "unchanged" without touching the file when the entry is
+ * already semantically current; never overwrites malformed configs.
+ */
+export declare function applyClientConfig(target: ConfigTarget, spec: EntrySpec, options?: ApplyOptions): Promise<ApplyResult>;

package/dist/apply.js

@@ -0,0 +1,388 @@
+/**
+ * The transactional config write recipe (REA's pattern, ported):
+ *
+ *   1. Refuse to follow symlinks not owned by the current uid (lstat; if the
+ *      path is a symlink, realpath and require a regular file owned by the
+ *      current uid — else { status: "failed", reason: "unsafe-path" }).
+ *   2. Missing file -> "create".
+ *   3. Malformed existing config -> "invalid" with a remediation string;
+ *      the file is NEVER overwritten.
+ *   4. Semantic compare (sorted-keys deep-equal, key order ignored) ->
+ *      "unchanged" when the desired entry is already current.
+ *   5. Backup via copyFile with COPYFILE_EXCL to <path>.heedvane.backup
+ *      (EEXIST means a backup already exists — proceed, never clobber).
+ *   6. Atomic write via write-file-atomic, mode 0600.
+ *   7. Read back, re-parse, semantic verify — on mismatch RESTORE the
+ *      original bytes and return { status: "failed", reason: "readback" }.
+ *      The backup is kept either way.
+ */
+import { constants as fsConstants } from "node:fs";
+import { copyFile, lstat, mkdir, readFile, realpath, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import writeFileAtomicCb from "write-file-atomic";
+import { getServers, parseDoc, removeServer, serializeDoc, withServer, withTopLevelKey, valuesEqual, TOP_LEVEL, entryValue, } from "./config-doc.js";
+import { errorMessage, isRecord } from "./guards.js";
+function writeAtomic(path, data, mode) {
+    return writeFileAtomicCb(path, data, { mode });
+}
+/** The path any backup for `path` will live at. */
+function backupPathFor(path) {
+    return `${path}.heedvane.backup`;
+}
+/** Apply every entry of the spec to the doc (mutated in place, like withServer). */
+function withEntries(doc, format, spec) {
+    for (const [name, desired] of Object.entries(spec.entries))
+        withServer(doc, format, { serversKey: spec.serversKey, name, desired });
+    return doc;
+}
+/**
+ * Compat entry point (A's API) on top of {@link applyClientConfig} /
+ * {@link transactionalWrite}: same recipe, but the result carries `path` and
+ * `remove: true` removes an entry (uninstall). Malformed configs and
+ * unowned symlinks report `invalid` with a remediation, never a write.
+ */
+export async function applyEntry(target, request) {
+    if ("remove" in request)
+        return removeEntry(target, request.containerKey, request.remove);
+    if (request.containerKey === TOP_LEVEL)
+        return applyTopLevelKeys(target, request.entries);
+    const res = await applyClientConfig(target, { serversKey: request.containerKey, entries: request.entries });
+    if (res.status === "invalid")
+        return { status: "invalid", path: target.path, remediation: res.remediation };
+    if (res.status === "failed")
+        return { status: "failed", path: target.path, reason: res.reason, backupPath: res.backupPath };
+    // Only a backup this write actually took is reported.
+    return { status: res.status, path: target.path, backupPath: "backupPath" in res ? res.backupPath : undefined };
+}
+/** The `remove: true` half of applyEntry: remove one entry through the transactional recipe. */
+async function removeEntry(target, containerKey, entryName) {
+    let doc;
+    try {
+        const originalBytes = await readFile(target.path);
+        doc = parseDoc(originalBytes.toString("utf8"), target.format);
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return { status: "unchanged", path: target.path };
+        return {
+            status: "invalid",
+            path: target.path,
+            reason: `existing config does not parse: ${errorMessage(err)}`,
+            remediation: `fix or move aside ${target.path} (we never overwrite malformed configs), then re-run`,
+        };
+    }
+    if (!markerVerifiedPresent(doc, containerKey, entryName)) {
+        return { status: "unchanged", path: target.path };
+    }
+    const next = removeServer(doc, target.format, { serversKey: containerKey, name: entryName });
+    const res = await transactionalWrite(target.path, target.format, () => serializeDoc(next, target.format, undefined));
+    if (!res.ok) {
+        return { status: "failed", path: target.path, backupPath: res.backupPath, reason: res.reason };
+    }
+    return { status: "update", path: target.path, backupPath: res.backupPath };
+}
+/**
+ * Set (or, with `undefined`, remove) one top-level key of a JSON settings file through the same
+ * transactional recipe; `unchanged` when it already holds that value, or is absent and stays so.
+ */
+export async function applyTopLevelKey(target, key, value) {
+    let doc;
+    try {
+        doc = parseDoc((await readFile(target.path)).toString("utf8"), target.format);
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            return { status: "invalid", path: target.path, reason: `existing config does not parse: ${errorMessage(err)}`, remediation: INVALID_REMEDIATION(target.path) };
+        }
+        if (value === undefined)
+            return { status: "unchanged", path: target.path };
+        doc = parseDoc("{}", target.format);
+    }
+    // A higher schema version already in the file is kept (entryValue); any other value is replaced.
+    const kept = entryValue(TOP_LEVEL, doc.value[key], value);
+    if (JSON.stringify(doc.value[key]) === JSON.stringify(kept))
+        return { status: "unchanged", path: target.path };
+    const next = withTopLevelKey(doc, { key, value: kept });
+    const res = await transactionalWrite(target.path, target.format, () => serializeDoc(next, target.format, undefined));
+    if (!res.ok)
+        return { status: "failed", path: target.path, backupPath: res.backupPath, reason: res.reason };
+    return { status: "update", path: target.path, backupPath: res.backupPath };
+}
+/** Every top-level key of `entries`, one transactional write each; the first failure stops the rest. */
+async function applyTopLevelKeys(target, entries) {
+    let worst = { status: "unchanged", path: target.path };
+    for (const [key, value] of Object.entries(entries)) {
+        const res = await applyTopLevelKey(target, key, value);
+        if (res.status === "failed" || res.status === "invalid")
+            return res;
+        if (res.status !== "unchanged")
+            worst = res;
+    }
+    return worst;
+}
+/** Was `entryName` in an object servers table? Present-but-not-an-object → false (nothing marker-verified). */
+function markerVerifiedPresent(doc, containerKey, entryName) {
+    try {
+        const servers = getServers(doc, doc.format, containerKey);
+        return servers !== undefined && entryName in servers;
+    }
+    catch {
+        return false; // container present but not an object — nothing marker-verified to remove
+    }
+}
+const INVALID_REMEDIATION = (path) => `repair ${path} before running setup — heedvane will not overwrite it`;
+/** Was any of the spec's entries already present in `doc.value[serversKey]`? (Pre-mutation.) */
+function entryExistedIn(doc, spec) {
+    const container = doc.value[spec.serversKey];
+    return isRecord(container) && Object.keys(spec.entries).some((name) => name in container);
+}
+/** The recipe's step 1: refuse symlinks / non-regular files we do not own. */
+async function checkPathSafety(filePath) {
+    let lst;
+    try {
+        lst = await lstat(filePath);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return { ok: true }; // missing file, handled as "create"
+        throw e;
+    }
+    if (lst.isSymbolicLink()) {
+        let target;
+        try {
+            target = await realpath(filePath);
+        }
+        catch {
+            return { ok: false, detail: `${filePath} is a symlink but its target does not resolve` };
+        }
+        let st;
+        try {
+            st = await stat(target);
+        }
+        catch {
+            return { ok: false, detail: `symlink ${filePath} -> ${target} does not resolve to an accessible file` };
+        }
+        if (!st.isFile()) {
+            return { ok: false, detail: `symlink ${filePath} -> ${target} does not resolve to a regular file` };
+        }
+        if (process.platform !== "win32" && typeof process.getuid === "function" && st.uid !== process.getuid()) {
+            return { ok: false, detail: `symlink ${filePath} -> ${target} is owned by uid ${st.uid}, not the current uid ${process.getuid()}` };
+        }
+        return { ok: true };
+    }
+    if (!lst.isFile()) {
+        return { ok: false, detail: `${filePath} exists and is not a regular file` };
+    }
+    return { ok: true };
+}
+async function loadExisting(target) {
+    let originalBytes;
+    try {
+        originalBytes = await readFile(target.path);
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return null;
+        throw e;
+    }
+    const originalText = originalBytes.toString("utf8");
+    const originalMode = (await stat(target.path)).mode & 0o777;
+    const doc = parseDoc(originalText, target.format); // throws ConfigParseError / ServersTableError-adjacent
+    return { originalBytes, originalText, originalMode, doc };
+}
+/** COPYFILE_EXCL backup: an existing backup is kept, never clobbered. */
+async function copyBackupExcl(from, to) {
+    try {
+        await copyFile(from, to, fsConstants.COPYFILE_EXCL);
+    }
+    catch (e) {
+        if (e.code === "EEXIST")
+            return; // a backup already exists — keep it
+        throw e;
+    }
+}
+/** Best-effort restore of the original bytes; a failed restore is swallowed by design (the write failure is reported instead). */
+async function restoreOriginal(filePath, original) {
+    try {
+        await writeAtomic(filePath, original.bytes, original.mode);
+    }
+    catch {
+        return; // best-effort restore on a failed write
+    }
+}
+/** Read back, re-parse and semantic-verify the write (recipe step 7). */
+async function verifyWrittenText(filePath, format, nextText) {
+    try {
+        const writtenText = await readFile(filePath, "utf8");
+        const writtenDoc = parseDoc(writtenText, format);
+        const expectedDoc = parseDoc(nextText, format);
+        if (!valuesEqual(writtenDoc.value, expectedDoc.value))
+            return { ok: false };
+        return { ok: true };
+    }
+    catch {
+        return { ok: false }; // unreadable or unparseable after the write — restore below
+    }
+}
+/** Read-only inspection: what would applying `desired` to this config do? Never writes. */
+export async function inspectClient(target, spec) {
+    const safety = await checkPathSafety(target.path);
+    if (!safety.ok)
+        return { status: "failed", reason: "unsafe-path", detail: safety.detail };
+    let loaded;
+    try {
+        loaded = await loadExisting(target);
+    }
+    catch {
+        return { status: "invalid", remediation: INVALID_REMEDIATION(target.path) };
+    }
+    if (loaded === null)
+        return { status: "create" };
+    // Snapshot BEFORE withServer: it mutates the doc in place.
+    const before = structuredClone(loaded.doc.value);
+    const hadEntry = entryExistedIn(loaded.doc, spec);
+    let next;
+    try {
+        next = withEntries(loaded.doc, target.format, spec);
+    }
+    catch {
+        return { status: "invalid", remediation: INVALID_REMEDIATION(target.path) };
+    }
+    if (valuesEqual(before, next.value))
+        return { status: "unchanged" };
+    // Status is entry-level: adding our entry to an existing config is a
+    // "create" of that entry; replacing an existing one is an "update".
+    return hadEntry ? { status: "update" } : { status: "create" };
+}
+/** Atomic write (step 6) then read-back verify (step 7); on failure restore the original bytes. */
+async function writeAndVerify(target, nextText, original) {
+    const mode = original?.mode ?? 0o600;
+    try {
+        // A new config may sit in a folder the agent has not made yet (an agent forced with --agent).
+        if (original === null)
+            await mkdir(dirname(target.path), { recursive: true, mode: 0o700 });
+        await writeAtomic(target.path, nextText, mode);
+    }
+    catch {
+        if (original !== null) {
+            await restoreOriginal(target.path, original);
+        }
+        return { ok: false, reason: "write" };
+    }
+    if ((await verifyWrittenText(target.path, target.format, nextText)).ok)
+        return { ok: true };
+    if (original !== null) {
+        await writeAtomic(target.path, original.bytes, original.mode);
+    }
+    return { ok: false, reason: "readback" };
+}
+/**
+ * Apply `desired` to the config transactionally. See the module doc for the
+ * recipe. Returns "unchanged" without touching the file when the entry is
+ * already semantically current; never overwrites malformed configs.
+ */
+export async function applyClientConfig(target, spec, options = {}) {
+    const serialize = options.serialize ?? serializeDoc;
+    const safety = await checkPathSafety(target.path);
+    if (!safety.ok)
+        return { status: "failed", reason: "unsafe-path" };
+    let loaded = null;
+    try {
+        loaded = await loadExisting(target);
+    }
+    catch {
+        return { status: "invalid", remediation: INVALID_REMEDIATION(target.path) };
+    }
+    const prepared = prepareNext(target, spec, { loaded, serialize });
+    if (prepared.outcome === "invalid")
+        return { status: "invalid", remediation: INVALID_REMEDIATION(target.path) };
+    if (prepared.outcome === "unchanged")
+        return { status: "unchanged" };
+    // Backup (step 5): COPYFILE_EXCL — an existing backup is never clobbered.
+    const backupPath = await backupExisting(target.path, loaded);
+    const original = loaded === null ? null : { bytes: loaded.originalBytes, mode: loaded.originalMode };
+    const outcome = await writeAndVerify(target, prepared.nextText, original);
+    if (!outcome.ok) {
+        if (loaded === null)
+            return { status: "failed", reason: outcome.reason };
+        return { status: "failed", reason: outcome.reason, backupPath };
+    }
+    if (loaded === null)
+        return { status: "create" };
+    return prepared.entryWasPresent
+        ? { status: "update", backupPath: backupPath }
+        : { status: "create", backupPath };
+}
+/** Serialize the mutated doc, or report unchanged / invalid without touching the file. */
+function prepareNext(target, spec, ctx) {
+    const { loaded, serialize } = ctx;
+    if (loaded === null) {
+        // Missing file: serialize a fresh doc carrying only our entry.
+        const fresh = { format: target.format, value: {} };
+        const nextText = serialize(withEntries(fresh, target.format, spec), target.format, undefined);
+        return { outcome: "write", nextText, entryWasPresent: false };
+    }
+    // Snapshot BEFORE withServer: it mutates the doc in place.
+    const before = structuredClone(loaded.doc.value);
+    const entryWasPresent = entryExistedIn(loaded.doc, spec);
+    let next;
+    try {
+        next = withEntries(loaded.doc, target.format, spec);
+    }
+    catch {
+        return { outcome: "invalid" };
+    }
+    if (valuesEqual(before, next.value))
+        return { outcome: "unchanged" };
+    return { outcome: "write", nextText: serialize(next, target.format, loaded.originalText), entryWasPresent };
+}
+/** Copy the current file to its backup path (no-op, undefined, when creating a fresh file). */
+async function backupExisting(path, loaded) {
+    if (loaded === null)
+        return undefined;
+    const backupPath = backupPathFor(path);
+    await copyBackupExcl(path, backupPath);
+    return backupPath;
+}
+/**
+ * Shared transactional write for callers that already computed the new text
+ * (uninstall uses this). Same recipe as applyClientConfig from the backup
+ * step onwards: COPYFILE_EXCL backup, atomic 0600 write, read-back verify,
+ * restore original bytes on any mismatch.
+ */
+async function transactionalWrite(filePath, format, serialize) {
+    const safety = await checkPathSafety(filePath);
+    if (!safety.ok)
+        return { ok: false, reason: "unsafe-path" };
+    const originalState = await readOriginalState(filePath);
+    const originalBytes = originalState.bytes;
+    const nextText = serialize();
+    let backupPath;
+    if (originalBytes !== null) {
+        backupPath = backupPathFor(filePath);
+        await copyBackupExcl(filePath, backupPath);
+    }
+    const original = originalBytes === null ? null : { bytes: originalBytes, mode: originalState.mode };
+    const outcome = await writeAndVerify({ path: filePath, format }, nextText, original);
+    if (!outcome.ok) {
+        if (originalBytes === null)
+            return { ok: false, reason: outcome.reason };
+        return { ok: false, reason: outcome.reason, backupPath };
+    }
+    return { ok: true, backupPath };
+}
+/** The recipe's input snapshot: the file's bytes and mode, or null bytes when it is missing. */
+async function readOriginalState(filePath) {
+    let bytes = null;
+    let mode = 0o600;
+    try {
+        bytes = await readFile(filePath);
+        mode = (await stat(filePath)).mode & 0o777;
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return { bytes, mode }; // missing file — take the create path
+        throw e;
+    }
+    return { bytes, mode };
+}

package/dist/backend/client.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The one door from this machine to the Heedvane API. Every caller is fail-open by contract
+ * (docs/product/agent-integration/steering.md: a hook never blocks work on Heedvane's availability),
+ * so a network failure or timeout answers `null` and the caller lets the agent continue.
+ */
+export interface Backend {
+    url: string;
+    /**
+     * The one credential this machine uses: the signed-in developer's current access token
+     * (`npx heedvane login`), else the organization API key (`npx heedvane auth org`, CI and headless
+     * machines). Never both, so a key of another organization can never stand in for a refused login.
+     */
+    credential: () => Promise<Credential>;
+    /**
+     * Whose sign-in is current, without reading its token: the Heedvane URL and the organization (login)
+     * or key it belongs to; null without any. It names the sign-in even when its token has expired, so
+     * queued data and caches stay with the organization they came from and are never sent or applied
+     * under another.
+     */
+    identity: () => Promise<string | null>;
+}
+/** One snapshot of the current sign-in: the bearer and whose it is always come from the same read. */
+export interface Credential {
+    bearer: string | null;
+    identity: string | null;
+}
+export interface BackendRequest {
+    method: "GET" | "POST";
+    path: string;
+    body?: unknown;
+    timeoutMs: number;
+}
+export interface BackendAnswer {
+    status: number;
+    json: unknown;
+}
+/** One request to Heedvane: its status and decoded body, or null when it never answered in time (or there is no credential). */
+export declare function callHeedvane(backend: Backend, request: BackendRequest): Promise<BackendAnswer | null>;
+/** {@link callHeedvane} with a bearer already read, so the caller can vouch whose it is. */
+export declare function callHeedvaneAs(url: string, bearer: string | null, request: BackendRequest): Promise<BackendAnswer | null>;

package/dist/backend/client.js

@@ -0,0 +1,32 @@
+/** One request to Heedvane: its status and decoded body, or null when it never answered in time (or there is no credential). */
+export async function callHeedvane(backend, request) {
+    return callHeedvaneAs(backend.url, (await backend.credential()).bearer, request);
+}
+/** {@link callHeedvane} with a bearer already read, so the caller can vouch whose it is. */
+export async function callHeedvaneAs(url, bearer, request) {
+    return bearer === null || bearer === "" ? null : send(url, request, bearer);
+}
+async function send(url, request, bearer) {
+    let response;
+    try {
+        response = await fetch(`${url}${request.path}`, {
+            method: request.method,
+            headers: { authorization: `Bearer ${bearer}`, ...(request.body === undefined ? {} : { "content-type": "application/json" }) },
+            body: request.body === undefined ? undefined : JSON.stringify(request.body),
+            signal: AbortSignal.timeout(request.timeoutMs),
+        });
+    }
+    catch {
+        return null; // unreachable or timed out: fail open
+    }
+    const text = await response.text().catch(() => "");
+    return { status: response.status, json: parseJson(text) };
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null; // a non-JSON body (proxy error page): the caller sees no usable answer
+    }
+}

package/dist/backend/credentials.d.ts

@@ -0,0 +1,15 @@
+import type { Backend } from "./client.js";
+import { type LoginTokenOptions } from "./login.js";
+export type CredentialKind = "org";
+export type Credentials = Partial<Record<CredentialKind, string>>;
+export declare function credentialsPath(root: string): string;
+/** Store one key beside the others, 0600. */
+export declare function saveCredential(root: string, kind: CredentialKind, key: string): Promise<void>;
+/** Heedvane at `url` when this machine has a sign-in or a key now, else null. The credential is read again on every call. */
+export declare function backendAt(root: string, url: string, options?: LoginTokenOptions): Promise<Backend | null>;
+/**
+ * The current sign-in's identity: the saved login's organization (else its client) at `url`, else the
+ * saved key's fingerprint; null with neither, or with a login or key file that cannot be read. Read
+ * now, so a login to another organization changes it at once, also for a listener started with a key.
+ */
+export declare function signInIdentity(root: string, url: string): Promise<string | null>;