funoteka 0.1.0

package/dist/cli/daemon.js

@@ -0,0 +1,192 @@
+import { spawn } from 'node:child_process';
+import { closeSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { entryPoint } from "./entry.js";
+function pidPath(dbPath) {
+    return `${dbPath}.pid`;
+}
+function logPath(dbPath) {
+    return `${dbPath}.log`;
+}
+/**
+ * Whether a process with this pid exists right now. Signal 0 asks and sends nothing.
+ *
+ * `EPERM` is the answer that matters and the one an obvious implementation gets
+ * wrong: it means the process is *there* and this one may not signal it. Reading
+ * it as "gone" would report a running server as stopped and — worse — let the
+ * next start overwrite a claim that was true. The rule is borrowed from
+ * `agensyn`'s runner, where the same check guards the same decision.
+ */
+export function alive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * What the pid file says, if it says anything and the process it names is there.
+ *
+ * Null for a file that is missing, unreadable, or not laid out the way this
+ * wrote it — a file this cannot parse describes nothing it can act on, and
+ * guessing at its contents is how a stop command signals the wrong process.
+ */
+export function running(dbPath) {
+    let record;
+    try {
+        record = JSON.parse(readFileSync(pidPath(dbPath), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof record?.pid !== 'number' || !alive(record.pid))
+        return null;
+    return record;
+}
+/**
+ * Write the claim, once the socket is actually listening.
+ *
+ * Best-effort, and deliberately so: this runs inside the server's `listen`
+ * callback, where a throw would take down a server that is up, listening and
+ * answering. What is lost when the write fails is `stop` and `status` finding
+ * it — which is bad, and is not as bad as the server itself — so the failure is
+ * said on stderr rather than swallowed, and the server keeps serving.
+ */
+export function claim(dbPath, record) {
+    try {
+        writeFileSync(pidPath(dbPath), `${JSON.stringify(record, null, 2)}\n`);
+    }
+    catch (err) {
+        process.stderr.write(`funoteka: serving, but could not write ${pidPath(dbPath)}: ${err.message}\n`);
+    }
+}
+export function release(dbPath) {
+    try {
+        rmSync(pidPath(dbPath), { force: true });
+    }
+    catch {
+        // A file that cannot be removed leaves a claim the next reader will check
+        // against the process table and find false, which is the answer anyway.
+    }
+}
+/**
+ * Start a server that does not belong to this shell.
+ *
+ * The child is the same program with the same arguments minus `--daemon`, so
+ * there is exactly one implementation of serving and no second path that could
+ * drift from it. It is detached and its output goes to the log rather than to a
+ * terminal that will be gone in a moment — a daemon whose output goes nowhere
+ * cannot say why it died.
+ *
+ * Readiness is the child's own report, not a timer: it writes the pid file when
+ * the socket is listening, so this waits for that file rather than for a
+ * number of milliseconds that would be wrong on both a slow and a fast machine.
+ * A child that exits instead is a failure, and its complaint is in the log.
+ */
+export async function start(dbPath, argv, timeoutMs = 15_000) {
+    const existing = running(dbPath);
+    if (existing !== null) {
+        return { ok: false, message: `already running: pid ${existing.pid} on port ${existing.port}` };
+    }
+    // A pid file naming a process that is gone describes a server that is not
+    // there; it is cleared so that this start's readiness check cannot pass on it.
+    release(dbPath);
+    // Where this attempt's output starts. Everything before it belongs to an
+    // earlier run, and a failure reported with a previous run's complaint in it
+    // would send whoever reads it after the wrong problem.
+    const mark = logSize(dbPath);
+    const log = openSync(logPath(dbPath), 'a');
+    const child = spawn(process.execPath, 
+    // The entry point as *this* build spells it — `.ts` beside the sources, `.js`
+    // in the compiled build the npm package ships (see `cli/entry.ts`).
+    [entryPoint('../cli'), 'serve', ...argv], {
+        detached: true,
+        // Nothing on stdin: a daemon that could read a terminal would be waiting
+        // on a prompt nobody is there to answer.
+        stdio: ['ignore', log, log],
+        windowsHide: true,
+        env: process.env,
+    });
+    closeSync(log);
+    let exited = null;
+    child.on('exit', (code) => {
+        exited = code ?? -1;
+    });
+    child.unref();
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (exited !== null)
+            break;
+        const record = running(dbPath);
+        if (record !== null)
+            return { ok: true, message: 'started', record };
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    // What it said on the way out, quoted into the message. A start that failed
+    // with "see the log file" makes the operator open the log to learn a sentence
+    // the daemon already knows, and the sentence is usually the whole answer —
+    // "no credentials", "address already in use".
+    const complaint = lastLine(dbPath, mark);
+    return {
+        ok: false,
+        message: exited === null
+            ? `did not start within ${Math.round(timeoutMs / 1000)}s${complaint} — see ${logPath(dbPath)}`
+            : `exited with ${exited}${complaint} — see ${logPath(dbPath)}`,
+    };
+}
+/** The last thing this attempt wrote to the log, or nothing if it wrote nothing. */
+function lastLine(dbPath, from) {
+    try {
+        const written = readFileSync(logPath(dbPath), 'utf8').slice(from);
+        const lines = written.split(/\r?\n/).filter((line) => line.trim() !== '');
+        const last = lines.at(-1);
+        return last === undefined ? '' : `: ${last.trim()}`;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Stop it.
+ *
+ * The process is killed rather than asked to stop, and on Windows there is no
+ * choice: a signal has no handler to reach, so `SIGTERM` terminates the process
+ * on the spot. That is safe here, and not by luck — the meta layer is SQLite in
+ * WAL mode, which is built to survive a process that stops mid-write, and the
+ * server holds no state that is not already on disk.
+ */
+export async function stop(dbPath, timeoutMs = 10_000) {
+    const record = running(dbPath);
+    if (record === null) {
+        release(dbPath);
+        return { ok: false, message: 'not running' };
+    }
+    try {
+        process.kill(record.pid);
+    }
+    catch (err) {
+        return { ok: false, message: `could not stop pid ${record.pid}: ${err.message}` };
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && alive(record.pid)) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (alive(record.pid)) {
+        return { ok: false, message: `pid ${record.pid} is still there after ${timeoutMs / 1000}s` };
+    }
+    release(dbPath);
+    return { ok: true, message: `stopped pid ${record.pid}` };
+}
+/** How big the log has grown, for `status` to say where the server has been talking. */
+export function logSize(dbPath) {
+    try {
+        return statSync(logPath(dbPath)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+export { logPath, pidPath };

package/dist/cli/entry.js

@@ -0,0 +1,25 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * A sibling entry point, named as *this* build spells it.
+ *
+ * Two places spawn this program as a child: the scanner the admin surface starts
+ * (`POST /scan` and the interval timer), and the daemon's own start. Both used to
+ * name `cli.ts`, which is right in the repository — Node strips the types itself —
+ * and wrong in the compiled build the npm package ships, where the file is
+ * `cli.js` and no `cli.ts` exists. The package would install, answer `--help`, and
+ * then fail to scan or to daemonise, which is the kind of breakage that looks
+ * like a missing feature rather than a missing file.
+ *
+ * Asking the filesystem instead of inferring the answer from the caller's own
+ * extension makes it checkable rather than assumed: the emitted file is preferred
+ * because a tree that has one is a built tree, the source is the fallback, and
+ * neither existing names the source — so the failure reads as "the build did not
+ * run" rather than as a `.js` that was never going to be there.
+ */
+export function entryPoint(relative, from = import.meta.url) {
+    const emitted = fileURLToPath(new URL(`${relative}.js`, from));
+    if (existsSync(emitted))
+        return emitted;
+    return fileURLToPath(new URL(`${relative}.ts`, from));
+}

package/dist/cli/keys.js

@@ -0,0 +1,52 @@
+import { addKey, listKeys, revokeKey } from "../api/keys.js";
+/**
+ * The `keys` command, as text a person reads.
+ *
+ * Kept out of the entry point for the same reason the other reports are: what
+ * the command *says* is testable without spawning a process, and the wording is
+ * the part of a key registry that decides whether anyone dares use it.
+ *
+ * **The environment's key is listed, and it is listed first.** A person asking
+ * "which keys does this server accept" is owed the answer in full — a listing
+ * that showed only the registered ones would say "one key" to a server that
+ * accepts two, and the one it left out is the one every existing client is
+ * probably using. What it says about that key is where it lives, because that is
+ * where it is revoked.
+ */
+export function reportKeys(db, environmentKey) {
+    const lines = [];
+    if (environmentKey !== '') {
+        lines.push('from the environment (FUNOTEKA_APIKEY) — always valid, revoked by editing start.cmd:', `  ${environmentKey}`, '');
+    }
+    else {
+        // **Said even though there is nothing to show.** The daemon is started by
+        // `start.cmd`, which sets this variable in its own process; a person running
+        // this command in an ordinary shell has it unset while the server they are
+        // asking about has it set. Silence here reads as "none" — which is how you
+        // spend an afternoon looking for a key that is working exactly as intended.
+        lines.push('from the environment (FUNOTEKA_APIKEY): not set in this shell.', '  The daemon is started by start.cmd, which sets it in its own process — this', '  command does not read that file. If a client is using a key that is not listed', '  below, that is where it is, and editing that file is how it is revoked.', '');
+    }
+    const keys = listKeys(db);
+    const active = keys.filter((key) => key.revokedAt === null);
+    lines.push(active.length === 0
+        ? 'registered keys: none'
+        : `registered keys (${active.length} active):`, ...active.map((key) => `  #${key.id}  ${key.label}  added ${key.createdAt}\n      ${key.secret}`));
+    const revoked = keys.filter((key) => key.revokedAt !== null);
+    if (revoked.length > 0) {
+        lines.push('', `revoked (${revoked.length}) — kept so that one taken back cannot be added again:`, ...revoked.map((key) => `  #${key.id}  ${key.label}  revoked ${key.revokedAt}`));
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** What `keys add` says: the secret, once, and the id to revoke it by. */
+export function addedKey(key) {
+    return (`#${key.id}  ${key.label}\n` +
+        `  ${key.secret}\n` +
+        '  A client presents this as `apiKey`, on its own — no `u` beside it.\n' +
+        `  Take it back with: funoteka keys revoke ${key.id}\n`);
+}
+/** What `keys revoke` says: the key that stopped being accepted. */
+export function revokedKey(key) {
+    return (`#${key.id}  ${key.label} is revoked as of ${key.revokedAt}.\n` +
+        '  Any client still using it is refused from now on, with no restart.\n');
+}
+export { addKey, revokeKey };