@the-librarian/cli 1.0.0-rc.21

package/dist/server/deploy-state.js

@@ -0,0 +1,79 @@
+// The NON-SECRET deploy-state file for the `server` command group.
+//
+// `up` runs the container with a chosen bind host, data volume, and ref, but
+// none of that was persisted anywhere — so `update` couldn't recreate the
+// container with the same config and `status` couldn't report the deployed ref
+// reliably (it would have to guess via `git describe`). This file records that
+// config in the deploy dir (default `~/.librarian/server/deploy-state.json`).
+//
+// SECURITY (AGENTS.md / spec §11): this file is NON-SECRET by construction. It
+// carries ONLY the five fields below — a bind host, a volume name, a ref, an
+// image tag, and the container name. It NEVER carries a bearer token, master
+// key, or admin token. `writeDeployState` whitelists exactly those fields, so a
+// caller that accidentally passes extra keys (a smuggled secret) cannot leak
+// them into the file. The master key / admin token are surfaced to stdout once
+// by `up` and persisted nowhere host-side — that contract is unchanged.
+import fs from "node:fs";
+import path from "node:path";
+/** The keys we ever persist — the whitelist that keeps secrets out of the file. */
+const STATE_KEYS = ["containerName", "host", "dataVolume", "ref", "imageTag"];
+/** `<dir>/deploy-state.json` — the deploy-state file path within a deploy dir. */
+export function deployStatePath(dir) {
+    return path.join(dir, "deploy-state.json");
+}
+/**
+ * Write the deploy-state to `<dir>/deploy-state.json`, creating `dir` if absent.
+ *
+ * Only the five declared fields are persisted — a `pick`, not a spread — so no
+ * extra key (e.g. a smuggled token) can ride along into the file. The file is
+ * non-secret, so it gets ordinary (not 0600) permissions.
+ */
+export function writeDeployState(dir, state) {
+    fs.mkdirSync(dir, { recursive: true });
+    // Pick ONLY the whitelisted keys — never spread `state`, which could carry
+    // extra (secret-shaped) properties a caller smuggled in.
+    const safe = {
+        containerName: state.containerName,
+        host: state.host,
+        dataVolume: state.dataVolume,
+        ref: state.ref,
+        imageTag: state.imageTag,
+    };
+    fs.writeFileSync(deployStatePath(dir), `${JSON.stringify(safe, null, 2)}\n`, "utf8");
+}
+/**
+ * Read the deploy-state back, or `null` if the file is absent, unparseable, or
+ * missing any required field. Never throws — a missing/corrupt state file means
+ * the caller falls back (e.g. `status` uses `git describe`), never crashes.
+ */
+export function readDeployState(dir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(deployStatePath(dir), "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const obj = parsed;
+    for (const key of STATE_KEYS) {
+        if (typeof obj[key] !== "string")
+            return null;
+    }
+    return {
+        containerName: obj.containerName,
+        host: obj.host,
+        dataVolume: obj.dataVolume,
+        ref: obj.ref,
+        imageTag: obj.imageTag,
+    };
+}
+//# sourceMappingURL=deploy-state.js.map

package/dist/server/deploy-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-state.js","sourceRoot":"","sources":["../../src/server/deploy-state.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,EAAE;AACF,6EAA6E;AAC7E,0EAA0E;AAC1E,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,gFAAgF;AAChF,6EAA6E;AAC7E,+EAA+E;AAC/E,wEAAwE;AAExE,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAmB7B,mFAAmF;AACnF,MAAM,UAAU,GAAG,CAAC,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,CAAU,CAAC;AAEvF,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,mBAAmB,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,KAAkB;IAC9D,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,2EAA2E;IAC3E,yDAAyD;IACzD,MAAM,IAAI,GAAgB;QACxB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC;IACF,EAAE,CAAC,aAAa,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACvF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/D,MAAM,GAAG,GAAG,MAAiC,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,IAAI,OAAO,GAAG,CAAC,GAAG,CAAC,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;IAChD,CAAC;IACD,OAAO;QACL,aAAa,EAAE,GAAG,CAAC,aAAuB;QAC1C,IAAI,EAAE,GAAG,CAAC,IAAc;QACxB,UAAU,EAAE,GAAG,CAAC,UAAoB;QACpC,GAAG,EAAE,GAAG,CAAC,GAAa;QACtB,QAAQ,EAAE,GAAG,CAAC,QAAkB;KACjC,CAAC;AACJ,CAAC"}

package/dist/server/docker.d.ts

@@ -0,0 +1,37 @@
+import type { RunOptions, RunResult, Runner } from "../exec.js";
+export type { RunOptions, RunResult, Runner } from "../exec.js";
+/** Per-stream chunk handlers for a streaming spawn. Chunks arrive as they do. */
+export interface StreamHandlers {
+    /** Called with each stdout chunk (decoded utf8) as it arrives. */
+    onStdout?: (chunk: string) => void;
+    /** Called with each stderr chunk (decoded utf8) as it arrives. */
+    onStderr?: (chunk: string) => void;
+}
+/**
+ * The streaming counterpart to {@link Runner}. Spawns `cmd args…`, forwards
+ * each stdout/stderr chunk to the handlers LIVE (never buffered to the end),
+ * and resolves with the exit code when the process exits — `null` if it was
+ * signalled (e.g. the user Ctrl-Cs a `-f` follow, or the container stops).
+ */
+export interface Streamer {
+    stream(cmd: string, args: readonly string[], handlers: StreamHandlers, opts?: RunOptions): Promise<number | null>;
+}
+/** Run a command (`docker`/`git`) through the current server runner. */
+export declare function run(cmd: string, args: readonly string[], opts?: RunOptions): Promise<RunResult>;
+/** Resolve a command to its PATH location through the current server runner. */
+export declare function which(cmd: string): Promise<string | null>;
+/**
+ * Stream a command (e.g. `docker logs -f`) through the current server streamer,
+ * forwarding each stdout/stderr chunk to `handlers` LIVE. Resolves with the exit
+ * code when the process exits.
+ */
+export declare function stream(cmd: string, args: readonly string[], handlers: StreamHandlers, opts?: RunOptions): Promise<number | null>;
+/** Swap in a fake runner (tests). Returns the previous runner. */
+export declare function setRunner(runner: Runner): Runner;
+/** Restore the real, process-spawning runner (tests). */
+export declare function resetRunner(): void;
+/** Swap in a fake streamer (tests). Returns the previous streamer. */
+export declare function setStreamer(streamer: Streamer): Streamer;
+/** Restore the real, process-spawning streamer (tests). */
+export declare function resetStreamer(): void;
+//# sourceMappingURL=docker.d.ts.map

package/dist/server/docker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker.d.ts","sourceRoot":"","sources":["../../src/server/docker.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEhE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAIhE,iFAAiF;AACjF,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,CACJ,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,EAAE,cAAc,EACxB,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3B;AA8ED,wEAAwE;AACxE,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAE/F;AAED,gFAAgF;AAChF,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,QAAQ,EAAE,cAAc,EACxB,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAExB;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,yDAAyD;AACzD,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,CAIxD;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}

package/dist/server/docker.js

@@ -0,0 +1,138 @@
+// Injectable `docker` / `git` runner for the `server` command group.
+//
+// Every `server` subcommand (up / update / down / status / logs / boot /
+// admin) drives the host's `docker` and `git` binaries. They go through THIS
+// seam rather than `node:child_process` directly, so tests stub the runner and
+// assert the exact argv each command invokes — WITHOUT spawning a real process
+// or touching a real Docker daemon.
+//
+// This mirrors `src/exec.ts` (the harness CLI runner) deliberately: same
+// `Runner` shape, same `run`/`which`/`setRunner`/`resetRunner` surface. It is a
+// SEPARATE module-level runner, though — the harness commands and the server
+// commands inject independently, so a test that stubs one never disturbs the
+// other. Reusing `exec.ts`'s `Runner`/`RunResult`/`RunOptions` types keeps a
+// single fake (`FakeRunner`) usable for both.
+//
+// Security (AGENTS.md): a command may *carry* a bearer token via an env var its
+// native mechanism reads, but this module never logs, echoes, or persists the
+// streams it returns.
+//
+// Two surfaces, two seams:
+//   - `run` CAPTURES a process's streams and resolves on close. Right for a
+//     command that EXITS on its own (`docker logs` without `-f`, `docker stop`,
+//     `docker info`): you want the whole output, after the fact.
+//   - `stream` does NOT capture — it hands each stdout/stderr chunk to a callback
+//     as it arrives and resolves only when the process exits. Right for a FOLLOW
+//     (`docker logs -f`), which never closes on its own: capturing it would buffer
+//     forever and emit nothing until the user Ctrl-Cs. Each seam injects
+//     independently (`setRunner`/`setStreamer`) so a test stubs exactly what it
+//     exercises, and neither ever spawns a real `docker`.
+import { spawn } from "node:child_process";
+// --- the real, process-spawning runner -----------------------------------
+const realRunner = {
+    run(cmd, args, opts = {}) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(cmd, [...args], {
+                cwd: opts.cwd,
+                env: opts.env ? { ...process.env, ...opts.env } : process.env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            let stdout = "";
+            let stderr = "";
+            child.stdout?.on("data", (chunk) => {
+                stdout += chunk.toString("utf8");
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderr += chunk.toString("utf8");
+            });
+            // ENOENT (binary not on PATH) surfaces here, not as a non-zero exit.
+            child.on("error", reject);
+            child.on("close", (code) => {
+                resolve({ stdout, stderr, code });
+            });
+        });
+    },
+    async which(cmd) {
+        const probe = process.platform === "win32" ? "where" : "which";
+        try {
+            const { stdout, code } = await realRunner.run(probe, [cmd]);
+            if (code !== 0)
+                return null;
+            const first = stdout
+                .split("\n")
+                .map((l) => l.trim())
+                .find((l) => l.length > 0);
+            return first ?? null;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+// --- the real, process-spawning streamer ----------------------------------
+const realStreamer = {
+    stream(cmd, args, handlers, opts = {}) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(cmd, [...args], {
+                cwd: opts.cwd,
+                env: opts.env ? { ...process.env, ...opts.env } : process.env,
+                // pipe (not inherit) so the caller can filter/transform per chunk; the
+                // caller is responsible for writing kept output to the terminal.
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            child.stdout?.on("data", (chunk) => {
+                handlers.onStdout?.(chunk.toString("utf8"));
+            });
+            child.stderr?.on("data", (chunk) => {
+                handlers.onStderr?.(chunk.toString("utf8"));
+            });
+            // ENOENT (binary not on PATH) surfaces here, not as a non-zero exit.
+            child.on("error", reject);
+            // Resolves only when the process EXITS — for `docker logs -f` that means
+            // the container stopped or the user Ctrl-C'd; until then chunks stream.
+            child.on("close", (code) => {
+                resolve(code);
+            });
+        });
+    },
+};
+// --- the swappable module-level runner -----------------------------------
+let current = realRunner;
+let currentStreamer = realStreamer;
+/** Run a command (`docker`/`git`) through the current server runner. */
+export function run(cmd, args, opts) {
+    return current.run(cmd, args, opts);
+}
+/** Resolve a command to its PATH location through the current server runner. */
+export function which(cmd) {
+    return current.which(cmd);
+}
+/**
+ * Stream a command (e.g. `docker logs -f`) through the current server streamer,
+ * forwarding each stdout/stderr chunk to `handlers` LIVE. Resolves with the exit
+ * code when the process exits.
+ */
+export function stream(cmd, args, handlers, opts) {
+    return currentStreamer.stream(cmd, args, handlers, opts);
+}
+/** Swap in a fake runner (tests). Returns the previous runner. */
+export function setRunner(runner) {
+    const prev = current;
+    current = runner;
+    return prev;
+}
+/** Restore the real, process-spawning runner (tests). */
+export function resetRunner() {
+    current = realRunner;
+}
+/** Swap in a fake streamer (tests). Returns the previous streamer. */
+export function setStreamer(streamer) {
+    const prev = currentStreamer;
+    currentStreamer = streamer;
+    return prev;
+}
+/** Restore the real, process-spawning streamer (tests). */
+export function resetStreamer() {
+    currentStreamer = realStreamer;
+}
+//# sourceMappingURL=docker.js.map

package/dist/server/docker.js.map

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

package/dist/server/down.d.ts

@@ -0,0 +1,19 @@
+export interface DownOptions {
+    /** Platform for preflight's daemon hint. Default `process.platform`. */
+    platform?: NodeJS.Platform | undefined;
+}
+/** A teaching error from `down`; the runtime renders `.message` as one stderr line. */
+export declare class DownError extends Error {
+    constructor(message: string);
+}
+export interface DownResult {
+    /** Human-readable report for stdout. */
+    output: string;
+}
+/**
+ * Run `server down`. Preflights docker, then `docker stop the-librarian` — the
+ * ONLY command it ever issues. A not-found/not-running container is a friendly
+ * no-op; any other non-zero exit is a teaching `DownError`.
+ */
+export declare function runDown(options?: DownOptions): Promise<DownResult>;
+//# sourceMappingURL=down.d.ts.map

package/dist/server/down.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"down.d.ts","sourceRoot":"","sources":["../../src/server/down.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC;CACxC;AAED,uFAAuF;AACvF,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;CAChB;AAOD;;;;GAIG;AACH,wBAAsB,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CA+B5E"}

package/dist/server/down.js

@@ -0,0 +1,62 @@
+// `librarian server down` — stop the container. DATA IS SACRED.
+//
+// `down` maps to ONE command: `docker stop the-librarian`. It NEVER removes the
+// container (`docker rm`), never passes `-v`, never touches the data volume
+// (`docker volume rm`), and never force-removes (`rm -f`). A later `up`/`update`
+// brings the SAME memories back from the untouched named volume — that is the
+// whole point (spec §11, success criterion 6).
+//
+// Idempotent-ish: if the container isn't running (or doesn't exist), `docker
+// stop` exits non-zero with a "No such container" message — `down` turns that
+// into a friendly "nothing to stop" outcome rather than a crash or a stack
+// trace. A genuine daemon error (anything that isn't the not-found case) still
+// surfaces as a teaching error.
+//
+// Everything goes through the injectable `docker.ts` runner, so tests assert the
+// exact argv without a real daemon.
+import { run } from "./docker.js";
+import { preflight } from "./preflight.js";
+import { CONTAINER_NAME } from "./up.js";
+/** A teaching error from `down`; the runtime renders `.message` as one stderr line. */
+export class DownError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DownError";
+    }
+}
+/** True when `docker stop`'s failure means the container simply isn't there. */
+function isNotRunning(stderr) {
+    return /no such container|is not running/i.test(stderr);
+}
+/**
+ * Run `server down`. Preflights docker, then `docker stop the-librarian` — the
+ * ONLY command it ever issues. A not-found/not-running container is a friendly
+ * no-op; any other non-zero exit is a teaching `DownError`.
+ */
+export async function runDown(options = {}) {
+    await preflight(options.platform ? { platform: options.platform } : {});
+    // The single, data-safe command. No `rm`, no `-v`, no `volume`, no `-f`.
+    const result = await run("docker", ["stop", CONTAINER_NAME]);
+    if (result.code === 0) {
+        return {
+            output: [
+                `Stopped ${CONTAINER_NAME}.`,
+                "The data volume is preserved — `librarian server up` brings the same memories back.",
+            ].join("\n"),
+        };
+    }
+    const detail = result.stderr.trim();
+    if (isNotRunning(detail)) {
+        return {
+            output: [
+                `${CONTAINER_NAME} is not running — nothing to stop.`,
+                "The data volume (if any) is untouched.",
+            ].join("\n"),
+        };
+    }
+    // A real failure (daemon error, permission, etc.) — teach, don't crash.
+    throw new DownError(`\`docker stop ${CONTAINER_NAME}\` failed (exit ${result.code ?? "signal"})` +
+        (detail ? `:\n${detail}` : ".") +
+        "\n\nResolve the error above, then re-run `librarian server down`.");
+}
+//# sourceMappingURL=down.js.map

package/dist/server/down.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"down.js","sourceRoot":"","sources":["../../src/server/down.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,iFAAiF;AACjF,8EAA8E;AAC9E,+CAA+C;AAC/C,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,2EAA2E;AAC3E,+EAA+E;AAC/E,gCAAgC;AAChC,EAAE;AACF,iFAAiF;AACjF,oCAAoC;AAEpC,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAOzC,uFAAuF;AACvF,MAAM,OAAO,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAOD,gFAAgF;AAChF,SAAS,YAAY,CAAC,MAAc;IAClC,OAAO,mCAAmC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,UAAuB,EAAE;IACrD,MAAM,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAExE,yEAAyE;IACzE,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAE7D,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO;YACL,MAAM,EAAE;gBACN,WAAW,cAAc,GAAG;gBAC5B,qFAAqF;aACtF,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACpC,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,MAAM,EAAE;gBACN,GAAG,cAAc,oCAAoC;gBACrD,wCAAwC;aACzC,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC;IACJ,CAAC;IAED,wEAAwE;IACxE,MAAM,IAAI,SAAS,CACjB,iBAAiB,cAAc,mBAAmB,MAAM,CAAC,IAAI,IAAI,QAAQ,GAAG;QAC1E,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAC/B,mEAAmE,CACtE,CAAC;AACJ,CAAC"}

package/dist/server/index.d.ts

@@ -0,0 +1,8 @@
+/** The `server` subcommands, in the order they appear in the surface (§4). */
+export declare const SERVER_SUBCOMMANDS: readonly ["up", "update", "down", "status", "logs", "enable-boot", "disable-boot", "admin"];
+export type ServerSubcommand = (typeof SERVER_SUBCOMMANDS)[number];
+/** The `librarian server` command surface (spec §4). */
+export declare function serverUsage(): string;
+/** True iff `name` is one of the known `server` subcommands. */
+export declare function isServerSubcommand(name: string): name is ServerSubcommand;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAYA,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,6FASrB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,wDAAwD;AACxD,wBAAgB,WAAW,IAAI,MAAM,CAmBpC;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAEzE"}

package/dist/server/index.js

@@ -0,0 +1,48 @@
+// The `librarian server` command group — self-host the Librarian from the CLI.
+//
+// S1 lays the foundation the later slices build on: the command SURFACE (the
+// help table from spec §4), the `docker.ts` seam, and `preflight()`. The
+// individual subcommands (up / update / down / status / logs / enable-boot /
+// disable-boot / admin) are implemented in their own slices; here they resolve
+// to a clear "arrives in a later slice" notice so the surface is honest about
+// what exists today.
+//
+// `server` with NO subcommand prints the surface; `librarian --help` reveals
+// this group alongside the harness commands (wired in `runtime.ts`).
+/** The `server` subcommands, in the order they appear in the surface (§4). */
+export const SERVER_SUBCOMMANDS = [
+    "up",
+    "update",
+    "down",
+    "status",
+    "logs",
+    "enable-boot",
+    "disable-boot",
+    "admin",
+];
+/** The `librarian server` command surface (spec §4). */
+export function serverUsage() {
+    return [
+        "Usage: librarian server <subcommand> [flags]",
+        "",
+        "Self-host the Librarian server (build + run the all-in-one container),",
+        "then hand its MCP URL + agent token to `librarian install` on clients.",
+        "",
+        "Subcommands:",
+        "  up            Build + run the server; print the MCP URL + agent token",
+        "  update        Re-pin to a release, rebuild, recreate (data volume kept)",
+        "  down          Stop the container (the data volume is preserved)",
+        "  status        Running? healthy? deployed version vs latest release",
+        "  logs          Tail the container logs ([-f] [--service mcp|dashboard|all])",
+        "  enable-boot   Start the server on boot (Linux systemd; macOS deferred)",
+        "  disable-boot  Reverse enable-boot",
+        "  admin         Run an admin command in the container (backup|restore|auth|rebuild)",
+        "",
+        "Run `librarian server <subcommand> --help` for flags (per subcommand).",
+    ].join("\n");
+}
+/** True iff `name` is one of the known `server` subcommands. */
+export function isServerSubcommand(name) {
+    return SERVER_SUBCOMMANDS.includes(name);
+}
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,6EAA6E;AAC7E,+EAA+E;AAC/E,8EAA8E;AAC9E,qBAAqB;AACrB,EAAE;AACF,6EAA6E;AAC7E,qEAAqE;AAErE,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,IAAI;IACJ,QAAQ;IACR,MAAM;IACN,QAAQ;IACR,MAAM;IACN,aAAa;IACb,cAAc;IACd,OAAO;CACC,CAAC;AAIX,wDAAwD;AACxD,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,8CAA8C;QAC9C,EAAE;QACF,wEAAwE;QACxE,wEAAwE;QACxE,EAAE;QACF,cAAc;QACd,yEAAyE;QACzE,2EAA2E;QAC3E,mEAAmE;QACnE,sEAAsE;QACtE,8EAA8E;QAC9E,0EAA0E;QAC1E,qCAAqC;QACrC,qFAAqF;QACrF,EAAE;QACF,wEAAwE;KACzE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAQ,kBAAwC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAClE,CAAC"}

package/dist/server/logs.d.ts

@@ -0,0 +1,50 @@
+/** The services `--service` can target. `all` (default) is unfiltered. */
+export type LogsService = "mcp" | "dashboard" | "all";
+export interface LogsOptions {
+    /** Follow the log output (`-f` / `--follow`). */
+    follow?: boolean | undefined;
+    /** Which service to show. Default `all` (unfiltered). */
+    service?: string | undefined;
+    /** Platform for preflight's daemon hint. Default `process.platform`. */
+    platform?: NodeJS.Platform | undefined;
+    /**
+     * Where a FOLLOW (`-f`) writes its (service-filtered) lines, AS THEY ARRIVE.
+     * Defaults to `process.stdout` so a live tail reaches the terminal directly —
+     * never buffered to the end. Injectable so tests observe ordering without a
+     * real terminal. Unused by the one-shot path (it returns its output instead).
+     */
+    write?: ((chunk: string) => void) | undefined;
+}
+/** A teaching error from `logs`; the runtime renders `.message` as one stderr line. */
+export declare class LogsError extends Error {
+    constructor(message: string);
+}
+export interface LogsResult {
+    /**
+     * The (service-filtered) log output for stdout. Populated by the one-shot
+     * (no-`-f`) path; EMPTY for a follow, which streams its lines live via
+     * `write` rather than returning them.
+     */
+    output: string;
+    /**
+     * The followed process's exit code (`-f` path), or `0` for the one-shot path.
+     * `null` when the follow was signalled (e.g. Ctrl-C / container stop).
+     */
+    exitCode: number | null;
+}
+/**
+ * Run `server logs`. Preflights docker, then either:
+ *   - FOLLOW (`-f`): streams `docker logs -f the-librarian` through the streaming
+ *     seam, writing each service-matching line to `write` (default
+ *     `process.stdout`) AS IT ARRIVES, resolving with the process's exit code
+ *     when the follow ends (Ctrl-C / container stop). Output is empty (already
+ *     streamed live).
+ *   - ONE-SHOT (no `-f`): captures `docker logs the-librarian` via the capturing
+ *     runner (it exits on its own), service-filters the captured output, and
+ *     returns it for stdout.
+ *
+ * An unknown `--service` is a teaching error; a non-zero one-shot `docker logs`
+ * exit surfaces its stderr as a teaching error (e.g. "No such container").
+ */
+export declare function runLogs(options?: LogsOptions): Promise<LogsResult>;
+//# sourceMappingURL=logs.d.ts.map

package/dist/server/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../src/server/logs.ts"],"names":[],"mappings":"AAmCA,0EAA0E;AAC1E,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,WAAW,GAAG,KAAK,CAAC;AAItD,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC;IACvC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC/C;AAED,uFAAuF;AACvF,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAoFD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,OAAO,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CA8B5E"}

package/dist/server/logs.js

@@ -0,0 +1,162 @@
+// `librarian server logs [-f] [--service mcp|dashboard|all]`.
+//
+// Maps to `docker logs [-f] the-librarian`. The all-in-one image runs BOTH
+// services (mcp-server + dashboard) in ONE container under `docker/supervisor.mjs`,
+// which spawns its children with `stdio: "inherit"` — so it emits NO per-service
+// prefix. The two streams are interleaved with no supervisor-added label.
+//
+// How `--service` filtering works, given that constraint:
+//   - The mcp-server logs structured pino NDJSON — every line is a JSON object
+//     carrying `"service":"the-librarian"` (see packages/mcp-server/src/logging.ts).
+//   - The dashboard (Next.js standalone `server.js`) logs plain text.
+//   So we distinguish them by SHAPE: a line that parses as a JSON object is an
+//   mcp-server line; anything else is a dashboard line. `--service mcp` keeps the
+//   NDJSON lines; `--service dashboard` keeps the rest; `all` (default) is
+//   unfiltered. This is the most reliable signal available without changing the
+//   image to prefix each child's output.
+//
+// `-f` (follow) vs one-shot — two different `docker.ts` seams, because the two
+// commands have opposite lifetimes:
+//   - WITHOUT `-f`, `docker logs the-librarian` prints what's there and EXITS.
+//     The capturing `run()` seam is right: it resolves on close with the whole
+//     output, which we then service-filter and return for stdout.
+//   - WITH `-f`, `docker logs -f the-librarian` NEVER closes on its own — it
+//     tails until the container stops or the user Ctrl-Cs. Capturing it would
+//     buffer forever and emit nothing until then (the old bug). So `-f` uses the
+//     STREAMING seam (`stream()`): each line is service-filtered and written to
+//     the terminal AS IT ARRIVES, and the call resolves with the process's exit
+//     code when the follow ends. Both paths apply the identical JSON-shape
+//     `--service` filter; only the delivery (buffered-then-returned vs.
+//     live-per-line) differs.
+import { run, stream } from "./docker.js";
+import { preflight } from "./preflight.js";
+import { CONTAINER_NAME } from "./up.js";
+const SERVICES = ["mcp", "dashboard", "all"];
+/** A teaching error from `logs`; the runtime renders `.message` as one stderr line. */
+export class LogsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LogsError";
+    }
+}
+/** Validate + default the `--service` value, or throw a teaching error. */
+function resolveService(raw) {
+    if (raw === undefined)
+        return "all";
+    if (SERVICES.includes(raw))
+        return raw;
+    throw new LogsError(`Unknown --service '${raw}'. Valid values: mcp, dashboard, all (default). ` +
+        "`mcp` shows the MCP server's structured logs, `dashboard` shows the Next.js " +
+        "dashboard's, `all` shows both.");
+}
+/**
+ * True iff a log line is an mcp-server line — i.e. it parses as a JSON object
+ * (the pino NDJSON shape). The dashboard's plain-text lines do not parse as JSON
+ * objects, so they're treated as `dashboard`.
+ */
+function isMcpLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{"))
+        return false;
+    try {
+        const parsed = JSON.parse(trimmed);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True iff a single line belongs to `service`. `all` keeps everything; `mcp`
+ * keeps the NDJSON lines; `dashboard` keeps the non-NDJSON, non-blank lines.
+ * The SAME predicate drives both the buffered and the streaming paths.
+ */
+function keepLine(line, service) {
+    if (service === "all")
+        return true;
+    if (service === "mcp")
+        return isMcpLine(line);
+    // dashboard: everything that isn't an mcp NDJSON line, skipping blanks so the
+    // output isn't padded.
+    return line.trim().length > 0 && !isMcpLine(line);
+}
+/** Keep only the lines belonging to `service` (preserving order + blanks for `all`). */
+function filterByService(text, service) {
+    if (service === "all")
+        return text;
+    return text
+        .split("\n")
+        .filter((l) => keepLine(l, service))
+        .join("\n");
+}
+/**
+ * A streaming line filter: feed it raw stdout chunks (which may split mid-line),
+ * and it emits each COMPLETE line that belongs to `service` to `write` as soon
+ * as the line is whole — never buffering to the end. Returns a `flush()` for any
+ * trailing partial line left when the stream closes.
+ */
+function makeLineFilter(service, write) {
+    let buffer = "";
+    const emit = (line) => {
+        if (keepLine(line, service))
+            write(line + "\n");
+    };
+    return {
+        push(chunk) {
+            buffer += chunk;
+            let nl = buffer.indexOf("\n");
+            while (nl !== -1) {
+                emit(buffer.slice(0, nl));
+                buffer = buffer.slice(nl + 1);
+                nl = buffer.indexOf("\n");
+            }
+        },
+        flush() {
+            if (buffer.length > 0) {
+                emit(buffer);
+                buffer = "";
+            }
+        },
+    };
+}
+/**
+ * Run `server logs`. Preflights docker, then either:
+ *   - FOLLOW (`-f`): streams `docker logs -f the-librarian` through the streaming
+ *     seam, writing each service-matching line to `write` (default
+ *     `process.stdout`) AS IT ARRIVES, resolving with the process's exit code
+ *     when the follow ends (Ctrl-C / container stop). Output is empty (already
+ *     streamed live).
+ *   - ONE-SHOT (no `-f`): captures `docker logs the-librarian` via the capturing
+ *     runner (it exits on its own), service-filters the captured output, and
+ *     returns it for stdout.
+ *
+ * An unknown `--service` is a teaching error; a non-zero one-shot `docker logs`
+ * exit surfaces its stderr as a teaching error (e.g. "No such container").
+ */
+export async function runLogs(options = {}) {
+    const service = resolveService(options.service);
+    await preflight(options.platform ? { platform: options.platform } : {});
+    if (options.follow) {
+        // Live tail: stream line-by-line, never buffer to close.
+        const write = options.write ?? ((chunk) => process.stdout.write(chunk));
+        const filter = makeLineFilter(service, write);
+        const exitCode = await stream("docker", ["logs", "-f", CONTAINER_NAME], {
+            onStdout: (chunk) => filter.push(chunk),
+            // `docker logs` writes the container's stderr stream here too; service
+            // filtering applies the same way so it isn't lost or unfiltered.
+            onStderr: (chunk) => filter.push(chunk),
+        });
+        filter.flush();
+        return { output: "", exitCode };
+    }
+    // One-shot: `docker logs` exits on its own, so capture + filter is correct.
+    const result = await run("docker", ["logs", CONTAINER_NAME]);
+    if (result.code !== 0) {
+        const detail = result.stderr.trim() || result.stdout.trim();
+        throw new LogsError(`\`docker logs ${CONTAINER_NAME}\` failed (exit ${result.code ?? "signal"})` +
+            (detail ? `:\n${detail}` : ".") +
+            "\n\nIs the server up? Run `librarian server status`.");
+    }
+    return { output: filterByService(result.stdout, service), exitCode: result.code };
+}
+//# sourceMappingURL=logs.js.map