@celestea/studio 2.7.1

package/dist/deployment.d.ts

@@ -0,0 +1,92 @@
+/**
+ * W782 — the deployment facts the system prompt is allowed to state, and the
+ * ONE place each of them is written down.
+ *
+ * Why this module exists. The `environment` prompt section (order 200) used to
+ * spell out this checkout's absolute paths BY HAND:
+ *
+ *   "…the TypeScript service in /src/celestea_studio-ts (Hono, systemd unit
+ *    celestea-studio-ts on 127.0.0.1:3777; public site https://studio.celestea.top).
+ *    … the frontend is /src/celestea_studio-ts/apps/web …"
+ *
+ * The same fact therefore existed TWICE and independently: once in the real
+ * deployment (the systemd unit, the config, this checkout) and once as prose in
+ * a prompt template. Nothing tied them together, so when the repo moved
+ * (`celestea_studio` -> `celestea_studio-ts`), when the frontend was merged in
+ * (`frontend/` -> `apps/web`) and when the data dir moved out of the tree
+ * (W781), the template had to be edited by hand each time — and a forgotten edit
+ * makes the agent confidently describe a layout that no longer exists. W768 was
+ * exactly that failure (`pwd` was one workspace while the prompt named another).
+ *
+ * The rule this module enforces: **derive what can be derived, and keep the one
+ * irreducible literal in a single named constant.** The template may only
+ * reference `{{...}}` variables; `apps/studio/src/store/prompts.test.ts` fails
+ * the build if an absolute path literal ever reappears in a template string.
+ *
+ * Derivation precedence, per fact:
+ *   repo root   <- this file's own location, walked up to the workspace marker
+ *                  (never the cwd, never an env var, never a literal)
+ *   frontend    <- repo root + apps/web
+ *   static root <- `config.paths.staticRoot` (already an operator setting)
+ *   bind        <- `config.bind` (already an operator setting)
+ *   unit name   <- CELESTEA_SERVICE_NAME ?? /proc/self/cgroup ?? [SERVICE_FALLBACK]
+ *   public site <- [PUBLIC_SITE] (irreducible: nothing in this process knows
+ *                  which DNS name the tunnel/Nginx answers on)
+ */
+/**
+ * Operator override for the systemd unit name stated in the prompt. Set it in
+ * the unit (`Environment=CELESTEA_SERVICE_NAME=…`) when the unit is renamed;
+ * this beats both the cgroup guess and [SERVICE_FALLBACK].
+ */
+export declare const ENV_SERVICE_NAME = "CELESTEA_SERVICE_NAME";
+/**
+ * The ONLY hand-written copy of this deployment's unit name. Used when neither
+ * `CELESTEA_SERVICE_NAME` nor `/proc/self/cgroup` yields one (e.g. a bare
+ * `tsx src/main.ts` outside systemd). If you rename the unit, either set the env
+ * var or update this line — it must never be repeated anywhere else.
+ */
+export declare const SERVICE_FALLBACK = "celestea-studio-ts.service";
+/**
+ * The public site. Irreducible from inside this process: it is a DNS/tunnel
+ * fact, not a fact about this checkout. The ONLY copy; templates reference
+ * `{{studio_site}}`.
+ */
+export declare const PUBLIC_SITE = "https://studio.celestea.top";
+/** Parse a systemd unit out of `/proc/self/cgroup` text (pure, testable). */
+export declare function systemdUnitNameFromCgroup(text: string): string | null;
+export declare function studioRepoRoot(): string;
+/** The bundled frontend root (`<package>/webdist`) when the build staged one. */
+export declare function packagedWebDist(): string | null;
+/** What the prompt may say about this deployment — every field derived. */
+export interface DeploymentFacts {
+    /** `{{studio_repo}}` — this checkout's root. */
+    repo: string;
+    /** `{{studio_frontend_dir}}` — where the frontend sources live. */
+    frontendDir: string;
+    /** `{{studio_static_root}}` — where the built frontend is served from. */
+    staticRoot: string;
+    /** `{{studio_service}}` — the systemd unit name. */
+    service: string;
+    /** `{{studio_bind}}` — host:port the backend listens on. */
+    bind: string;
+    /** `{{studio_site}}` — the public site. */
+    publicSite: string;
+}
+/**
+ * The two operator settings this module reads, taken STRUCTURALLY rather than as
+ * `StudioConfig`. `config.ts` derives its default static root from
+ * `studioRepoRoot()` in this file, so importing `StudioConfig` here would make
+ * the two modules depend on each other (`no-circular`). A structural parameter
+ * keeps the edge one-way.
+ */
+export interface DeploymentConfigInput {
+    bind: string;
+    paths: {
+        staticRoot: string;
+    };
+}
+/**
+ * Resolve every fact the `environment` section states. `env` is read for the
+ * unit-name override only; `config` supplies the two operator settings.
+ */
+export declare function deploymentFacts(config: DeploymentConfigInput, env?: NodeJS.ProcessEnv): DeploymentFacts;

package/dist/deployment.js

@@ -0,0 +1,154 @@
+/**
+ * W782 — the deployment facts the system prompt is allowed to state, and the
+ * ONE place each of them is written down.
+ *
+ * Why this module exists. The `environment` prompt section (order 200) used to
+ * spell out this checkout's absolute paths BY HAND:
+ *
+ *   "…the TypeScript service in /src/celestea_studio-ts (Hono, systemd unit
+ *    celestea-studio-ts on 127.0.0.1:3777; public site https://studio.celestea.top).
+ *    … the frontend is /src/celestea_studio-ts/apps/web …"
+ *
+ * The same fact therefore existed TWICE and independently: once in the real
+ * deployment (the systemd unit, the config, this checkout) and once as prose in
+ * a prompt template. Nothing tied them together, so when the repo moved
+ * (`celestea_studio` -> `celestea_studio-ts`), when the frontend was merged in
+ * (`frontend/` -> `apps/web`) and when the data dir moved out of the tree
+ * (W781), the template had to be edited by hand each time — and a forgotten edit
+ * makes the agent confidently describe a layout that no longer exists. W768 was
+ * exactly that failure (`pwd` was one workspace while the prompt named another).
+ *
+ * The rule this module enforces: **derive what can be derived, and keep the one
+ * irreducible literal in a single named constant.** The template may only
+ * reference `{{...}}` variables; `apps/studio/src/store/prompts.test.ts` fails
+ * the build if an absolute path literal ever reappears in a template string.
+ *
+ * Derivation precedence, per fact:
+ *   repo root   <- this file's own location, walked up to the workspace marker
+ *                  (never the cwd, never an env var, never a literal)
+ *   frontend    <- repo root + apps/web
+ *   static root <- `config.paths.staticRoot` (already an operator setting)
+ *   bind        <- `config.bind` (already an operator setting)
+ *   unit name   <- CELESTEA_SERVICE_NAME ?? /proc/self/cgroup ?? [SERVICE_FALLBACK]
+ *   public site <- [PUBLIC_SITE] (irreducible: nothing in this process knows
+ *                  which DNS name the tunnel/Nginx answers on)
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The workspace marker that identifies this repository's root. */
+const REPO_MARKER = "pnpm-workspace.yaml";
+/** `{{studio_frontend_dir}}` is the repo root plus this, and nothing else. */
+const FRONTEND_SUBDIR = ["apps", "web"];
+/**
+ * Operator override for the systemd unit name stated in the prompt. Set it in
+ * the unit (`Environment=CELESTEA_SERVICE_NAME=…`) when the unit is renamed;
+ * this beats both the cgroup guess and [SERVICE_FALLBACK].
+ */
+export const ENV_SERVICE_NAME = "CELESTEA_SERVICE_NAME";
+/**
+ * The ONLY hand-written copy of this deployment's unit name. Used when neither
+ * `CELESTEA_SERVICE_NAME` nor `/proc/self/cgroup` yields one (e.g. a bare
+ * `tsx src/main.ts` outside systemd). If you rename the unit, either set the env
+ * var or update this line — it must never be repeated anywhere else.
+ */
+export const SERVICE_FALLBACK = "celestea-studio-ts.service";
+/**
+ * The public site. Irreducible from inside this process: it is a DNS/tunnel
+ * fact, not a fact about this checkout. The ONLY copy; templates reference
+ * `{{studio_site}}`.
+ */
+export const PUBLIC_SITE = "https://studio.celestea.top";
+/** Parse a systemd unit out of `/proc/self/cgroup` text (pure, testable). */
+export function systemdUnitNameFromCgroup(text) {
+    // Each line is `hierarchy:controllers:/path`; the unit is the LAST path
+    // segment of whichever line names one (`0::/system.slice/foo.service`).
+    for (const line of text.split("\n")) {
+        const path = line.slice(line.lastIndexOf(":") + 1).trim();
+        const segment = path.slice(path.lastIndexOf("/") + 1);
+        if (segment.endsWith(".service"))
+            return segment;
+    }
+    return null;
+}
+/** `/proc/self/cgroup` of this process, or null when unreadable. */
+function cgroupUnitName() {
+    try {
+        return systemdUnitNameFromCgroup(readFileSync("/proc/self/cgroup", "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The repository root, derived from THIS file's location: `src/deployment.ts`
+ * sits directly under `apps/studio`, so walking up until the workspace marker
+ * appears is stable under any cwd, any symlinked launcher and any rename of the
+ * checkout directory. Falls back to walking up from the cwd, then throws —
+ * a wrong prompt is worse than a loud startup failure.
+ */
+/** The checkout root (marker found), or null when running from an install. */
+function workspaceMarkerRoot() {
+    const starts = [dirname(fileURLToPath(import.meta.url)), process.cwd()];
+    for (const start of starts) {
+        for (let dir = start;;) {
+            if (existsSync(join(dir, REPO_MARKER)))
+                return dir;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+/**
+ * H (packaging): the installed package root. After `npm i -g celestea-agent`
+ * there is no `pnpm-workspace.yaml`, so the nearest `package.json` above this
+ * module IS the deployment root. Never throws; null when nothing matches.
+ */
+function packageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 8; i++) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+export function studioRepoRoot() {
+    const workspace = workspaceMarkerRoot();
+    if (workspace !== null)
+        return workspace;
+    const packaged = packageRoot();
+    if (packaged !== null)
+        return packaged;
+    throw new Error(`cannot derive the studio repo root: no ${REPO_MARKER} above ${fileURLToPath(import.meta.url)} or ${process.cwd()}`);
+}
+/** The bundled frontend root (`<package>/webdist`) when the build staged one. */
+export function packagedWebDist() {
+    const root = packageRoot();
+    if (root === null)
+        return null;
+    const candidate = join(root, "webdist");
+    return existsSync(join(candidate, "index.html")) ? candidate : null;
+}
+/**
+ * Resolve every fact the `environment` section states. `env` is read for the
+ * unit-name override only; `config` supplies the two operator settings.
+ */
+export function deploymentFacts(config, env = process.env) {
+    const repo = studioRepoRoot();
+    const override = env[ENV_SERVICE_NAME];
+    return {
+        repo,
+        frontendDir: join(repo, ...FRONTEND_SUBDIR),
+        staticRoot: config.paths.staticRoot,
+        service: override !== undefined && override !== "" ? override : (cgroupUnitName() ?? SERVICE_FALLBACK),
+        bind: config.bind,
+        publicSite: PUBLIC_SITE,
+    };
+}

package/dist/fake-runtime-adapter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Fake `RuntimeAdapter` — the P4 stand-in for the engine.
+ *
+ * The real runtime arrives on another workstream; until it does, this adapter
+ * lets the whole HTTP contract be exercised end to end: it owns the
+ * single-concurrency slot, emits the contract SSE events on a scripted turn,
+ * and answers the worker/compact/status calls deterministically.
+ *
+ * W513: the fake models the same SESSION-SCOPED contract as the real adapter —
+ * one busy slot per session, `inject()` for a busy session (the interjection is
+ * recorded and asserted by the HTTP tests), `ensureSession()` for activate — so
+ * the handler tests exercise the real routing rules.
+ *
+ * It is a *test/development* adapter, never a production engine: the scripted
+ * turn is an echo and no model is ever called.
+ */
+import { type ContextMessageView, type EngineProfile, type RuntimeAdapter, type ToolInfo } from "./runtime-adapter.js";
+export interface FakeRuntimeOptions {
+    profile?: Partial<EngineProfile>;
+    tools?: readonly ToolInfo[];
+    /** Yield between scripted frames so a test can observe the stream. */
+    stepDelayMs?: number;
+    /**
+     * W725: scripted context snapshot. The fake owns no session log, so the
+     * "model-visible context" is whatever the test plants; absent = the profile's
+     * system prompt with no history.
+     */
+    context?: {
+        system?: string;
+        messages?: readonly ContextMessageView[];
+    };
+}
+/** `RuntimeAdapter` plus the test hook that waits for a scripted turn to end. */
+export interface FakeRuntimeAdapter extends RuntimeAdapter {
+    whenIdle(): Promise<void>;
+}
+export declare function createFakeRuntimeAdapter(opts?: FakeRuntimeOptions): FakeRuntimeAdapter;

package/dist/fake-runtime-adapter.js

@@ -0,0 +1,276 @@
+/**
+ * Fake `RuntimeAdapter` — the P4 stand-in for the engine.
+ *
+ * The real runtime arrives on another workstream; until it does, this adapter
+ * lets the whole HTTP contract be exercised end to end: it owns the
+ * single-concurrency slot, emits the contract SSE events on a scripted turn,
+ * and answers the worker/compact/status calls deterministically.
+ *
+ * W513: the fake models the same SESSION-SCOPED contract as the real adapter —
+ * one busy slot per session, `inject()` for a busy session (the interjection is
+ * recorded and asserted by the HTTP tests), `ensureSession()` for activate — so
+ * the handler tests exercise the real routing rules.
+ *
+ * It is a *test/development* adapter, never a production engine: the scripted
+ * turn is an echo and no model is ever called.
+ */
+import { TurnBusyError, } from "./runtime-adapter.js";
+const DEFAULT_TOOLS = [
+    { name: "http_request", description: "Send an HTTP(S) request and return {status, headers(subset), body, truncated}." },
+    { name: "list_dir", description: "List the entry names in a directory." },
+    { name: "read_file", description: "Read a UTF-8 text file and return its contents as a string." },
+    { name: "write_file", description: "Write a UTF-8 text file." },
+    { name: "run_shell", description: "Run a shell command." },
+];
+function zeroUsage() {
+    const block = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0, cache_read: 0, cache_hit_ratio: 0, reasoning_tokens: 0 };
+    return { ...block, total: { ...block } };
+}
+function defaultProfile(over) {
+    return {
+        model: "unknown",
+        base_url: "http://127.0.0.1:3001/v1",
+        reasoning_effort: null,
+        max_steps: 4096,
+        max_parallel_tool_calls: 4,
+        max_output_tokens: null,
+        context_window: 1_000_000,
+        api_key_env: "CELESTEA_API_KEY",
+        system_prompt: "",
+        ...over,
+    };
+}
+function countBy(rows, key) {
+    const out = {};
+    for (const w of rows)
+        out[w[key]] = (out[w[key]] ?? 0) + 1;
+    return out;
+}
+class FakeRuntime {
+    name = "fake-runtime-adapter";
+    engineProfile;
+    toolList;
+    workers = new Map();
+    transcripts = new Map();
+    delay;
+    /** W725: the scripted model-visible context of `sessionContext()`. */
+    context;
+    bus = null;
+    busy = false;
+    turn = 0;
+    idleWaiters = [];
+    /** Session -> its own turn counter (W513). */
+    turns = new Map();
+    /** Session -> messages delivered into a running turn (W513). */
+    injected = new Map();
+    /** Session -> live runtime (W513 registry stand-in). */
+    live = new Set();
+    constructor(opts) {
+        this.engineProfile = defaultProfile(opts.profile ?? {});
+        this.toolList = opts.tools ?? DEFAULT_TOOLS;
+        this.delay = opts.stepDelayMs ?? 0;
+        this.context = opts.context ?? {};
+    }
+    attach(next) {
+        this.bus = next;
+    }
+    isBusy(_session) {
+        return this.busy;
+    }
+    /** Same decision table as the real adapter: busy+steer -> steering, else queued. */
+    inject(req) {
+        const key = req.session ?? "";
+        const queued = this.injected.get(key) ?? [];
+        queued.push(req.input);
+        this.injected.set(key, queued);
+        // W847: the same lane split as the real adapter (an explicit "queue" never steers).
+        const steering = this.busy && req.mode !== "queue";
+        const placement = steering ? "steering" : "queued";
+        this.emit("status", { phase: "progress", placement, statusline: this.statusline() }, this.turns.get(key) ?? 0, req.session);
+        return { turn: this.turns.get(key) ?? 0, injected: steering, pending: queued.length, placement, duplicate: false };
+    }
+    /** Messages injected into the given session's turn (test assertion hook). */
+    injectedInto(session) {
+        return [...(this.injected.get(session ?? "") ?? [])];
+    }
+    ensureSession(session) {
+        const created = !this.live.has(session ?? "");
+        this.live.add(session ?? "");
+        return { runtime: created ? "created" : "reused", busy: this.busy, rebuilt: false };
+    }
+    liveSessions() {
+        return [...this.live].filter((id) => id !== "");
+    }
+    busySessions() {
+        return this.busy ? this.liveSessions() : [];
+    }
+    profile() {
+        return this.engineProfile;
+    }
+    async configure(patch) {
+        this.engineProfile = { ...this.engineProfile, ...patch };
+        return this.engineProfile;
+    }
+    tools() {
+        return [...this.toolList];
+    }
+    /** W729: the fake owns no per-session generation, so every session sees the
+     *  same scripted face (P0: identical in both modes, §1.2). */
+    sessionTools(_session) {
+        return this.tools();
+    }
+    /** W725: the scripted context snapshot (this fake owns no engine log). */
+    sessionContext(_session) {
+        return {
+            model: this.engineProfile.model,
+            system: this.context.system ?? this.engineProfile.system_prompt,
+            tools: this.toolList.map(toolView),
+            messages: [...(this.context.messages ?? [])],
+        };
+    }
+    statusline() {
+        return {
+            model: this.engineProfile.model,
+            reasoning_effort: this.engineProfile.reasoning_effort,
+            steps: 0,
+            tokens_per_sec: 0,
+            // W755 vocabulary: this double drives no engine loop, so it has neither a
+            // provider sample nor an assembly -> `none` ("unknown"), never the retired
+            // char-vs-token `session_event_chars`.
+            context_usage: contextUsageOf(this.engineProfile.context_window),
+            usage: zeroUsage(),
+        };
+    }
+    emit(event, payload, envelopeTurn = this.turn, session = null) {
+        this.bus?.emit(event, envelopeTurn, payload, session);
+    }
+    settle() {
+        this.busy = false;
+        const waiters = this.idleWaiters;
+        this.idleWaiters = [];
+        for (const w of waiters)
+            w();
+    }
+    whenIdle() {
+        return this.busy ? new Promise((resolve) => this.idleWaiters.push(resolve)) : Promise.resolve();
+    }
+    async pause() {
+        if (this.delay > 0)
+            await new Promise((r) => setTimeout(r, this.delay));
+    }
+    /** Scripted turn: start -> text -> done -> turn_end -> completed. */
+    async runTurn(req) {
+        const session = req.session;
+        try {
+            this.emit("text", { delta: `echo: ${req.input}` }, this.turn, session);
+            await this.pause();
+            this.emit("done", { text: `echo: ${req.input}`, tool_calls: [] }, this.turn, session);
+            this.emit("turn_end", { outcome: "completed", error: null }, this.turn, session);
+            this.emit("status", { phase: "completed", statusline: this.statusline() }, this.turn, session);
+        }
+        finally {
+            this.settle();
+        }
+    }
+    async startTurn(req) {
+        if (this.busy)
+            throw new TurnBusyError();
+        this.busy = true;
+        const key = req.session ?? "";
+        this.live.add(key);
+        this.turn += 1;
+        this.turns.set(key, this.turn);
+        this.emit("status", { phase: "start", statusline: this.statusline() }, this.turn, req.session);
+        setTimeout(() => void this.runTurn(req), 0);
+        return { turn: this.turn, placement: "context" };
+    }
+    cancel(_session) {
+        if (!this.busy)
+            return false;
+        this.settle();
+        this.emit("status", { phase: "cancelled", statusline: this.statusline() });
+        return true;
+    }
+    async clear(_session) {
+        return { cleared: true };
+    }
+    async compact(session) {
+        return { compacted: false, note: "历史不足，无需压缩", session, rebound: false };
+    }
+    workerRows() {
+        return [...this.workers.values()].map((w) => ({
+            id: `worker:${w.sessionId}`,
+            workspace: "engine",
+            kind: "worker",
+            title: w.title,
+            model: null,
+            // The fake keeps no session metadata: a scripted worker is `standard`.
+            mode: "standard",
+            size: this.transcripts.get(w.sessionId)?.length ?? 0,
+            modified: 0,
+            active: false,
+            wid: w.wid,
+            status: w.status,
+            state: w.state,
+        }));
+    }
+    workerSessions() {
+        return this.workerRows();
+    }
+    async workerSpawn(req) {
+        const sessionId = `session-${this.workers.size + 1}`;
+        const title = req.title !== undefined && req.title !== "" ? req.title : req.brief.slice(0, 40);
+        this.workers.set(req.wid, { wid: req.wid, sessionId, title, status: "RUNNING", state: "idle", brief: req.brief });
+        this.transcripts.set(sessionId, [{ role: "user", content: req.brief }]);
+        return { ok: true, sessionId, title, wid: req.wid };
+    }
+    async workerSend(req) {
+        const hit = [...this.workers.values()].find((w) => w.sessionId === req.target || w.wid === req.target);
+        if (hit === undefined)
+            return { ok: false, delivered: false, error: `unknown worker target '${req.target}'` };
+        const log = this.transcripts.get(hit.sessionId) ?? [];
+        log.push({ role: "user", content: req.content });
+        this.transcripts.set(hit.sessionId, log);
+        return { ok: true, delivered: true, target: req.target, wid: hit.wid };
+    }
+    workerStatus(wid) {
+        const all = [...this.workers.values()];
+        const by_status = { DONE: 0, FAILED: 0, RUNNING: 0, ...countBy(all, "status") };
+        const by_state = { idle: 0, "in-turn": 0, running: 0, ...countBy(all, "state") };
+        if (wid === undefined)
+            return { ok: all.length > 0, total: all.length, by_status, by_state, workers: all };
+        const hit = all.filter((w) => w.wid === wid);
+        if (hit.length === 0)
+            return { ok: false, total: 0, by_status, by_state, workers: [], wid, error: `no worker ${wid} in registry` };
+        return { ok: true, total: hit.length, by_status, by_state, workers: hit, wid };
+    }
+    workerMessages(sessionId) {
+        const sid = sessionId.startsWith("worker:") ? sessionId.slice("worker:".length) : sessionId;
+        return this.transcripts.get(sid) ?? null;
+    }
+}
+/**
+ * W755: the fake engine measures nothing (no provider frame, no assembly), so
+ * its context_usage is the honest "unknown" branch: `used:0`, `method:"none"`,
+ * and — W755 Fix C — `window:0` (the profile's 1,000,000 is a DISPLAY default,
+ * not a real capacity, so it must never become a denominator).
+ */
+function contextUsageOf(contextWindow) {
+    const known = Number.isFinite(contextWindow) && contextWindow > 0;
+    return {
+        used: 0,
+        window: 0,
+        ratio: 0,
+        estimated: true,
+        method: "none",
+        projected: false,
+        window_source: known ? "fallback" : "unknown",
+    };
+}
+/** The five scripted tools carry no schema of their own: an empty object one. */
+function toolView(tool) {
+    return { name: tool.name, description: tool.description, parameters: { type: "object", properties: {} } };
+}
+export function createFakeRuntimeAdapter(opts = {}) {
+    return new FakeRuntime(opts);
+}

package/dist/handlers/auth.d.ts

@@ -0,0 +1,24 @@
+/**
+ * W767 — the three endpoints of Studio's OWN login-cookie gate.
+ *
+ *   GET  /login        the self-contained login page (always reachable)
+ *   POST /auth/login   verify against Studio's password file, then Set-Cookie
+ *   GET  /auth/check   200/401 for nginx `auth_request` (the actual gate)
+ *
+ * nginx asks `/auth/check` for every other path and rewrites a 401 into a
+ * redirect to `/login`; these three are the only paths exempted there. The
+ * backend therefore stays usable from localhost with no cookie (the engine's own
+ * API is unchanged) while the public host is gated by the cookie.
+ *
+ * Hard rules kept here:
+ *   - the password is verified through `htpasswd -vbi` (stdin, never argv);
+ *   - a SUCCESSFUL login answers 200 with `Set-Cookie` AND the navigation in the
+ *     same response (never a 302 — some mobile clients drop the cookie on a
+ *     redirect);
+ *   - the cookie value never reaches a log line, and a wrong password and an
+ *     unknown user are indistinguishable (401 both ways).
+ */
+import type { Hono } from "hono";
+import type { RouteTable } from "../routes.js";
+import { type Deps } from "./common.js";
+export declare function registerAuth(app: Hono, deps: Deps, table: RouteTable): string[];