sh3-server 0.6.0

package/dist/routes/docs.js

@@ -0,0 +1,133 @@
+/**
+ * Document backend API routes.
+ *
+ * Maps the DocumentBackend interface to HTTP endpoints backed by the
+ * local filesystem. Files are stored at {dataDir}/docs/{tenant}/{shard}/{path}.
+ *
+ * GET    /api/docs/:tenant/:shard          → list
+ * GET    /api/docs/:tenant/:shard/*path    → read
+ * HEAD   /api/docs/:tenant/:shard/*path    → exists
+ * PUT    /api/docs/:tenant/:shard/*path    → write (auth required)
+ * DELETE /api/docs/:tenant/:shard/*path    → delete (auth required)
+ */
+import { Hono } from 'hono';
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync, statSync, readdirSync, } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+export function createDocsRouter(dataDir) {
+    const router = new Hono();
+    const docsDir = join(dataDir, 'docs');
+    function resolvePath(tenant, shard, filePath) {
+        // Prevent path traversal
+        const resolved = join(docsDir, tenant, shard, filePath);
+        if (!resolved.startsWith(join(docsDir, tenant, shard))) {
+            throw new Error('Path traversal detected');
+        }
+        return resolved;
+    }
+    function collectFiles(dir, base) {
+        const results = [];
+        if (!existsSync(dir))
+            return results;
+        const entries = readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                results.push(...collectFiles(full, base));
+            }
+            else {
+                const stat = statSync(full);
+                results.push({
+                    path: relative(base, full).replace(/\\/g, '/'),
+                    size: stat.size,
+                    lastModified: stat.mtimeMs,
+                });
+            }
+        }
+        return results;
+    }
+    // List documents for a tenant/shard
+    router.get('/:tenant/:shard', (c) => {
+        const { tenant, shard } = c.req.param();
+        const dir = join(docsDir, tenant, shard);
+        const files = collectFiles(dir, dir);
+        return c.json(files);
+    });
+    // Read a document
+    router.get('/:tenant/:shard/*', (c) => {
+        const { tenant, shard } = c.req.param();
+        const filePath = c.req.path.replace(`/api/docs/${tenant}/${shard}/`, '');
+        if (!filePath)
+            return c.json({ error: 'Missing file path' }, 400);
+        let resolved;
+        try {
+            resolved = resolvePath(tenant, shard, filePath);
+        }
+        catch {
+            return c.json({ error: 'Invalid path' }, 400);
+        }
+        if (!existsSync(resolved)) {
+            return c.notFound();
+        }
+        const content = readFileSync(resolved);
+        // Detect binary vs text heuristically: if the file can be decoded as
+        // UTF-8 without replacement characters, treat as text.
+        const text = new TextDecoder('utf-8', { fatal: true });
+        try {
+            const str = text.decode(content);
+            return c.text(str);
+        }
+        catch {
+            return new Response(content, {
+                headers: { 'Content-Type': 'application/octet-stream' },
+            });
+        }
+    });
+    // Check existence via HEAD request
+    router.on('HEAD', '/:tenant/:shard/*', (c) => {
+        const { tenant, shard } = c.req.param();
+        const filePath = c.req.path.replace(`/api/docs/${tenant}/${shard}/`, '');
+        let resolved;
+        try {
+            resolved = resolvePath(tenant, shard, filePath);
+        }
+        catch {
+            return new Response(null, { status: 400 });
+        }
+        return new Response(null, { status: existsSync(resolved) ? 200 : 404 });
+    });
+    // Write a document (auth required via middleware)
+    router.put('/:tenant/:shard/*', async (c) => {
+        const { tenant, shard } = c.req.param();
+        const filePath = c.req.path.replace(`/api/docs/${tenant}/${shard}/`, '');
+        if (!filePath)
+            return c.json({ error: 'Missing file path' }, 400);
+        let resolved;
+        try {
+            resolved = resolvePath(tenant, shard, filePath);
+        }
+        catch {
+            return c.json({ error: 'Invalid path' }, 400);
+        }
+        mkdirSync(dirname(resolved), { recursive: true });
+        const body = await c.req.arrayBuffer();
+        writeFileSync(resolved, Buffer.from(body));
+        return c.json({ ok: true });
+    });
+    // Delete a document (auth required via middleware)
+    router.delete('/:tenant/:shard/*', (c) => {
+        const { tenant, shard } = c.req.param();
+        const filePath = c.req.path.replace(`/api/docs/${tenant}/${shard}/`, '');
+        let resolved;
+        try {
+            resolved = resolvePath(tenant, shard, filePath);
+        }
+        catch {
+            return c.json({ error: 'Invalid path' }, 400);
+        }
+        if (existsSync(resolved)) {
+            unlinkSync(resolved);
+        }
+        return c.json({ ok: true });
+    });
+    return router;
+}

package/dist/routes/env-state.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Environment state routes — generic per-shard JSON storage.
+ *
+ * Server stores env state as files under {dataDir}/env-state/{shardId}.json.
+ * GET is public (read by all clients). PUT is admin-gated (blanket /api/* auth).
+ */
+import { Hono } from 'hono';
+export declare function createEnvStateRouter(dataDir: string): Hono;

package/dist/routes/env-state.js

@@ -0,0 +1,62 @@
+/**
+ * Environment state routes — generic per-shard JSON storage.
+ *
+ * Server stores env state as files under {dataDir}/env-state/{shardId}.json.
+ * GET is public (read by all clients). PUT is admin-gated (blanket /api/* auth).
+ */
+import { Hono } from 'hono';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Validate shard ID — alphanumeric, hyphens, underscores, colons, @ (scoped packages). */
+function isValidShardId(id) {
+    return /^[a-zA-Z0-9_:@-]+$/.test(id) && id.length <= 128;
+}
+export function createEnvStateRouter(dataDir) {
+    const envDir = join(dataDir, 'env-state');
+    const router = new Hono();
+    router.get('/:shardId', (c) => {
+        const shardId = c.req.param('shardId');
+        if (!isValidShardId(shardId)) {
+            return c.json({ error: 'Invalid shard ID' }, 400);
+        }
+        const resolved = join(envDir, `${shardId}.json`);
+        if (!resolved.startsWith(envDir)) {
+            return c.json({ error: 'Invalid shard ID' }, 400);
+        }
+        if (!existsSync(resolved)) {
+            return c.json({});
+        }
+        try {
+            const raw = readFileSync(resolved, 'utf-8');
+            return c.json(JSON.parse(raw));
+        }
+        catch (err) {
+            console.warn(`[sh3] Corrupt env state for "${shardId}":`, err);
+            return c.json({});
+        }
+    });
+    router.put('/:shardId', async (c) => {
+        const shardId = c.req.param('shardId');
+        if (!isValidShardId(shardId)) {
+            return c.json({ error: 'Invalid shard ID' }, 400);
+        }
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            return c.json({ error: 'Invalid JSON body' }, 400);
+        }
+        if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+            return c.json({ error: 'Body must be a JSON object' }, 400);
+        }
+        const resolved = join(envDir, `${shardId}.json`);
+        if (!resolved.startsWith(envDir)) {
+            return c.json({ error: 'Invalid shard ID' }, 400);
+        }
+        mkdirSync(envDir, { recursive: true });
+        writeFileSync(resolved, JSON.stringify(body, null, 2));
+        return c.json({ ok: true });
+    });
+    return router;
+}

package/dist/sessions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * In-memory session store. Sessions don't survive server restart.
+ * Token format: sh3s_<random hex>
+ */
+export interface Session {
+    token: string;
+    userId: string;
+    role: 'admin' | 'user';
+    createdAt: number;
+    expiresAt: number;
+}
+export declare class SessionStore {
+    #private;
+    /** @param defaultTTLHours — default session lifetime in hours. */
+    constructor(defaultTTLHours?: number);
+    /** Create a session for a user. Returns the new session. */
+    create(userId: string, role: 'admin' | 'user', ttlHours?: number): Session;
+    /** Validate a token. Returns the session if valid and not expired, else null. */
+    validate(token: string): Session | null;
+    /** Revoke a session by token. */
+    revoke(token: string): boolean;
+    /** Purge all expired sessions. Call periodically. */
+    cleanup(): number;
+    /** Update the default TTL (called when settings change). */
+    setDefaultTTL(hours: number): void;
+}

package/dist/sessions.js

@@ -0,0 +1,59 @@
+/**
+ * In-memory session store. Sessions don't survive server restart.
+ * Token format: sh3s_<random hex>
+ */
+import { randomBytes } from 'node:crypto';
+export class SessionStore {
+    #sessions = new Map();
+    #defaultTTL;
+    /** @param defaultTTLHours — default session lifetime in hours. */
+    constructor(defaultTTLHours = 24) {
+        this.#defaultTTL = defaultTTLHours * 3600 * 1000;
+    }
+    /** Create a session for a user. Returns the new session. */
+    create(userId, role, ttlHours) {
+        const token = `sh3s_${randomBytes(32).toString('hex')}`;
+        const now = Date.now();
+        const ttl = ttlHours ? ttlHours * 3600 * 1000 : this.#defaultTTL;
+        const session = {
+            token,
+            userId,
+            role,
+            createdAt: now,
+            expiresAt: now + ttl,
+        };
+        this.#sessions.set(token, session);
+        return session;
+    }
+    /** Validate a token. Returns the session if valid and not expired, else null. */
+    validate(token) {
+        const session = this.#sessions.get(token);
+        if (!session)
+            return null;
+        if (Date.now() > session.expiresAt) {
+            this.#sessions.delete(token);
+            return null;
+        }
+        return session;
+    }
+    /** Revoke a session by token. */
+    revoke(token) {
+        return this.#sessions.delete(token);
+    }
+    /** Purge all expired sessions. Call periodically. */
+    cleanup() {
+        const now = Date.now();
+        let removed = 0;
+        for (const [token, session] of this.#sessions) {
+            if (now > session.expiresAt) {
+                this.#sessions.delete(token);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /** Update the default TTL (called when settings change). */
+    setDefaultTTL(hours) {
+        this.#defaultTTL = hours * 3600 * 1000;
+    }
+}

package/dist/settings.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Global settings — persisted to {dataDir}/settings.json.
+ * Provides typed access with defaults for missing fields.
+ */
+export interface GlobalSettings {
+    auth: {
+        required: boolean;
+        guestAllowed: boolean;
+        sessionTTL: number;
+        selfRegistration: boolean;
+    };
+}
+export declare class SettingsStore {
+    #private;
+    constructor(dataDir: string);
+    /** Get current settings. */
+    get(): GlobalSettings;
+    /** Patch settings. Only provided fields are updated. */
+    update(patch: {
+        auth?: Partial<GlobalSettings['auth']>;
+    }): GlobalSettings;
+}

package/dist/settings.js

@@ -0,0 +1,63 @@
+/**
+ * Global settings — persisted to {dataDir}/settings.json.
+ * Provides typed access with defaults for missing fields.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+const DEFAULTS = {
+    auth: {
+        required: true,
+        guestAllowed: false,
+        sessionTTL: 24,
+        selfRegistration: false,
+    },
+};
+export class SettingsStore {
+    #path;
+    #settings;
+    constructor(dataDir) {
+        this.#path = `${dataDir}/settings.json`;
+        this.#settings = this.#load();
+    }
+    #load() {
+        if (!existsSync(this.#path))
+            return structuredClone(DEFAULTS);
+        try {
+            const raw = JSON.parse(readFileSync(this.#path, 'utf-8'));
+            return {
+                auth: {
+                    required: raw.auth?.required ?? DEFAULTS.auth.required,
+                    guestAllowed: raw.auth?.guestAllowed ?? DEFAULTS.auth.guestAllowed,
+                    sessionTTL: raw.auth?.sessionTTL ?? DEFAULTS.auth.sessionTTL,
+                    selfRegistration: raw.auth?.selfRegistration ?? DEFAULTS.auth.selfRegistration,
+                },
+            };
+        }
+        catch {
+            return structuredClone(DEFAULTS);
+        }
+    }
+    #save() {
+        mkdirSync(dirname(this.#path), { recursive: true });
+        writeFileSync(this.#path, JSON.stringify(this.#settings, null, 2));
+    }
+    /** Get current settings. */
+    get() {
+        return structuredClone(this.#settings);
+    }
+    /** Patch settings. Only provided fields are updated. */
+    update(patch) {
+        if (patch.auth) {
+            if (patch.auth.required !== undefined)
+                this.#settings.auth.required = patch.auth.required;
+            if (patch.auth.guestAllowed !== undefined)
+                this.#settings.auth.guestAllowed = patch.auth.guestAllowed;
+            if (patch.auth.sessionTTL !== undefined)
+                this.#settings.auth.sessionTTL = patch.auth.sessionTTL;
+            if (patch.auth.selfRegistration !== undefined)
+                this.#settings.auth.selfRegistration = patch.auth.selfRegistration;
+        }
+        this.#save();
+        return this.get();
+    }
+}

package/dist/shard-router.d.ts

@@ -0,0 +1,68 @@
+import { Hono } from 'hono';
+import type { MiddlewareHandler } from 'hono';
+import type { KeyStore } from './keys.js';
+import type { SettingsStore } from './settings.js';
+export interface MountContext {
+    pkgDir: string;
+    keys: KeyStore;
+    settings: SettingsStore;
+    /**
+     * Register a WebSocket upgrade handler on a path under this shard's
+     * route prefix. The returned value is a Hono middleware handler that
+     * can be passed directly as the handler argument to `router.get(path, ...)`.
+     *
+     * The `ws` argument passed to `onConnect` is the server-side WebSocket
+     * from `@hono/node-ws` (which wraps the `ws` package). `@hono/node-ws`
+     * does not re-export a type name for it and `@types/ws` is not a
+     * dependency, so we use `any` per the plan's explicit fallback rule.
+     * The returned handler is likewise typed as `any` — its concrete type
+     * is Hono's internal `MiddlewareHandler<..., { outputFormat: "ws" }>`,
+     * which would leak Hono ws internals into every shard that touches it.
+     *
+     * The `c` argument is the Hono `Context` for the upgrade request.
+     * Shards can read `c.get('session')` to route the connection to the
+     * correct per-user state (e.g. `manager.getOrCreate(session.userId)`).
+     *
+     * @param onConnect Called with the raw WebSocket and request Context
+     *                  when a client connects. Attach listeners in the body;
+     *                  return nothing.
+     */
+    wsRegister(onConnect: (ws: any, c: any) => void): any;
+}
+/** Middleware that requires admin session OR valid API key. */
+export declare function adminOnly(keys: KeyStore, settings: SettingsStore): MiddlewareHandler;
+/**
+ * Dynamic shard route manager. Holds a Map of shard Hono sub-apps
+ * and delegates requests from a single wildcard route.
+ */
+export declare class ShardRouter {
+    private shards;
+    /**
+     * Import a server.js bundle and mount its routes.
+     * Throws on import failure — caller is responsible for rollback.
+     */
+    mount(shardId: string, serverJsPath: string, ctx: MountContext): Promise<void>;
+    /**
+     * Mount a shard server module that is already imported (e.g. a framework
+     * built-in bundled with sh3-server, not discovered from the package store).
+     * Skips the `import()` call and goes straight to `routes()` wiring.
+     */
+    mountStatic(shardId: string, mod: {
+        id: string;
+        routes: (router: Hono, ctx: any) => void | Promise<void>;
+    }, ctx: MountContext): Promise<void>;
+    /** Remove a shard's routes. */
+    unmount(shardId: string): boolean;
+    /**
+     * Hono handler for the wildcard route.
+     * Looks up the shard sub-app and delegates with path stripping.
+     */
+    handler(): (c: any, next: () => Promise<void>) => Promise<Response | void>;
+    /** List all routes across all mounted shards (for /api/routes). */
+    listRoutes(): Array<{
+        method: string;
+        path: string;
+    }>;
+    /** Check if a shard is currently mounted. */
+    has(shardId: string): boolean;
+}

package/dist/shard-router.js

@@ -0,0 +1,145 @@
+// packages/sh3-server/src/shard-router.ts
+import { Hono } from 'hono';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** Middleware that requires admin session OR valid API key. */
+export function adminOnly(keys, settings) {
+    return async (c, next) => {
+        // When auth is disabled (--no-auth), skip admin checks entirely
+        if (!settings.get().auth.required) {
+            return next();
+        }
+        // Session-based admin — forwarded from upstream sessionAuth via env
+        const session = c.get('session') ?? c.env?.session;
+        if (session?.role === 'admin') {
+            return next();
+        }
+        // Fallback: API key (for external tools / CLI)
+        const authHeader = c.req.header('Authorization');
+        if (authHeader?.startsWith('Bearer sh3_')) {
+            const token = authHeader.slice(7);
+            if (keys.validate(token)) {
+                return next();
+            }
+        }
+        return c.json({ error: 'Admin privileges required' }, 403);
+    };
+}
+/**
+ * Dynamic shard route manager. Holds a Map of shard Hono sub-apps
+ * and delegates requests from a single wildcard route.
+ */
+export class ShardRouter {
+    shards = new Map();
+    /**
+     * Import a server.js bundle and mount its routes.
+     * Throws on import failure — caller is responsible for rollback.
+     */
+    async mount(shardId, serverJsPath, ctx) {
+        const fileUrl = pathToFileURL(serverJsPath).href + `?t=${Date.now()}`;
+        const mod = await import(fileUrl);
+        const shard = mod.default ?? mod;
+        if (typeof shard.id !== 'string' || typeof shard.routes !== 'function') {
+            throw new Error(`${shardId}/server.js invalid export shape — expected { id, routes }`);
+        }
+        const shardDataDir = join(ctx.pkgDir, 'data');
+        const router = new Hono();
+        const shardCtx = {
+            shardId: shard.id,
+            dataDir: shardDataDir,
+            adminOnly: adminOnly(ctx.keys, ctx.settings),
+            wsRegister: ctx.wsRegister,
+        };
+        await shard.routes(router, shardCtx);
+        // Create data dir only after routes() succeeds — so a failure
+        // doesn't leave behind a dir that prevents install rollback cleanup.
+        mkdirSync(shardDataDir, { recursive: true });
+        this.shards.set(shardId, router);
+        console.log(`[sh3]   ${shardId} — server routes mounted at /api/${shardId}/`);
+    }
+    /**
+     * Mount a shard server module that is already imported (e.g. a framework
+     * built-in bundled with sh3-server, not discovered from the package store).
+     * Skips the `import()` call and goes straight to `routes()` wiring.
+     */
+    async mountStatic(shardId, mod, ctx) {
+        if (typeof mod.id !== 'string' || typeof mod.routes !== 'function') {
+            throw new Error(`${shardId} static mount — expected { id, routes }, got ${typeof mod}`);
+        }
+        const shardDataDir = join(ctx.pkgDir, 'data');
+        const router = new Hono();
+        const shardCtx = {
+            shardId: mod.id,
+            dataDir: shardDataDir,
+            adminOnly: adminOnly(ctx.keys, ctx.settings),
+            wsRegister: ctx.wsRegister,
+        };
+        await mod.routes(router, shardCtx);
+        mkdirSync(shardDataDir, { recursive: true });
+        this.shards.set(shardId, router);
+        console.log(`[sh3]   ${shardId} — static server routes mounted at /api/${shardId}/`);
+    }
+    /** Remove a shard's routes. */
+    unmount(shardId) {
+        const removed = this.shards.delete(shardId);
+        if (removed) {
+            console.log(`[sh3]   ${shardId} — server routes unmounted`);
+        }
+        return removed;
+    }
+    /**
+     * Hono handler for the wildcard route.
+     * Looks up the shard sub-app and delegates with path stripping.
+     */
+    handler() {
+        return async (c, next) => {
+            const shardId = c.req.param('shardId');
+            const shardApp = this.shards.get(shardId);
+            if (!shardApp) {
+                return next();
+            }
+            try {
+                // Build a new URL with the shard prefix stripped.
+                // Original: /api/<shardId>/items/5 → shard sees: /items/5
+                const url = new URL(c.req.url);
+                const prefix = `/api/${shardId}`;
+                url.pathname = url.pathname.slice(prefix.length) || '/';
+                const strippedRequest = new Request(url.toString(), {
+                    method: c.req.method,
+                    headers: c.req.raw.headers,
+                    body: c.req.raw.body,
+                    // @ts-expect-error duplex needed for streaming bodies
+                    duplex: 'half',
+                });
+                // Forward session from upstream sessionAuth so shard middleware can see it
+                const env = { ...c.env, session: c.get('session') ?? null };
+                return await shardApp.fetch(strippedRequest, env);
+            }
+            catch (err) {
+                console.error(`[sh3] Shard "${shardId}" runtime error:`, err);
+                return c.json({ error: `Shard "${shardId}" encountered an error` }, 500);
+            }
+        };
+    }
+    /** List all routes across all mounted shards (for /api/routes). */
+    listRoutes() {
+        const routes = [];
+        const seen = new Set();
+        for (const [shardId, app] of this.shards) {
+            for (const r of app.routes) {
+                const path = `/api/${shardId}${r.path}`;
+                const key = `${r.method} ${path}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                routes.push({ method: r.method, path });
+            }
+        }
+        return routes;
+    }
+    /** Check if a shard is currently mounted. */
+    has(shardId) {
+        return this.shards.has(shardId);
+    }
+}

package/dist/shell-shard/history-store.d.ts

@@ -0,0 +1,11 @@
+export declare class HistoryStore {
+    private readonly path;
+    private readonly max;
+    private buffer;
+    constructor(dataDir: string, userId: string, historyMaxLines: number);
+    /** Read the capped in-memory view — most recent `historyMaxLines` lines. */
+    read(): string[];
+    /** Append a new line to both the on-disk file and the in-memory buffer. */
+    append(line: string): void;
+    private loadBuffer;
+}

package/dist/shell-shard/history-store.js

@@ -0,0 +1,65 @@
+/*
+ * Per-user append-only history store for the shell-shard server.
+ *
+ * Storage format: JSONL at <dataDir>/history-<userId>.jsonl.
+ * Each line: { "ts": <ms>, "line": "<command>" }.
+ *
+ * The store holds a capped in-memory view (most recent `historyMaxLines`)
+ * that is served to clients on attach. The on-disk file is not rotated
+ * in v1 — rotation is in the deferred list. If the file exceeds 2× the
+ * cap, a warning is logged on load but the store still functions.
+ *
+ * A corrupt tail line (partial write from a crash mid-append) is skipped
+ * on load with a warning.
+ */
+import { existsSync, appendFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export class HistoryStore {
+    path;
+    max;
+    buffer;
+    constructor(dataDir, userId, historyMaxLines) {
+        this.path = join(dataDir, `history-${userId}.jsonl`);
+        this.max = historyMaxLines;
+        this.buffer = this.loadBuffer();
+    }
+    /** Read the capped in-memory view — most recent `historyMaxLines` lines. */
+    read() {
+        return [...this.buffer];
+    }
+    /** Append a new line to both the on-disk file and the in-memory buffer. */
+    append(line) {
+        const record = { ts: Date.now(), line };
+        appendFileSync(this.path, JSON.stringify(record) + '\n', 'utf-8');
+        this.buffer.push(line);
+        if (this.buffer.length > this.max) {
+            this.buffer.splice(0, this.buffer.length - this.max);
+        }
+    }
+    loadBuffer() {
+        if (!existsSync(this.path))
+            return [];
+        const raw = readFileSync(this.path, 'utf-8');
+        const lines = raw.split('\n');
+        const parsed = [];
+        for (const rawLine of lines) {
+            if (!rawLine.trim())
+                continue;
+            try {
+                const record = JSON.parse(rawLine);
+                if (typeof record.line === 'string') {
+                    parsed.push(record.line);
+                }
+            }
+            catch {
+                // Corrupt tail line — skip silently. Log at debug level only.
+                console.warn(`[shell-shard/history] skipped corrupt line in ${this.path}`);
+            }
+        }
+        if (parsed.length > this.max * 2) {
+            console.warn(`[shell-shard/history] ${this.path} has ${parsed.length} lines; ` +
+                `cap is ${this.max}. Rotation is deferred — see spec § Deferred.`);
+        }
+        return parsed.slice(-this.max);
+    }
+}

package/dist/shell-shard/index.d.ts

@@ -0,0 +1,14 @@
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+import type { WsLike } from './session-manager.js';
+export interface ShellServerContext {
+    shardId: string;
+    dataDir: string;
+    adminOnly: any;
+    wsRegister: (onConnect: (ws: WsLike, c: Context) => void) => any;
+}
+declare const _default: {
+    id: string;
+    routes(app: Hono, ctx: ShellServerContext): Promise<void>;
+};
+export default _default;