sh3-server 0.6.0

package/dist/shell-shard/index.js

@@ -0,0 +1,51 @@
+/*
+ * Server half of shell-shard — statically mounted by sh3-server at boot.
+ *
+ * Routes:
+ *   GET /api/shell/history — JSON, admin-only. Returns persisted history
+ *                            for the authenticated user.
+ *   GET /api/shell/session — WebSocket upgrade, admin-only. Attaches the
+ *                            client to the per-user session.
+ */
+import { LocalRunner } from './runner.js';
+import { SessionManager } from './session-manager.js';
+import { handleClientMessage } from './ws.js';
+function sessionUser(c) {
+    const session = c.get('session') ?? c.env?.session;
+    return session?.userId ?? 'admin';
+}
+export default {
+    id: 'shell',
+    async routes(app, ctx) {
+        // Default config — overridable via shard env state in a future pass.
+        const cfg = { ringSize: 500, historyMaxLines: 10_000, defaultCwd: '' };
+        const runner = new LocalRunner();
+        const manager = new SessionManager(ctx.dataDir, runner, cfg);
+        // NOTE: the JSON /history endpoint is convenience — the authoritative
+        // delivery of history is via the `history` server message sent on WS
+        // attach. Clients can skip the REST endpoint entirely. Kept for
+        // symmetry with the spec's WebSocket protocol section. Reads the
+        // same HistoryStore the session uses, so it reflects live state.
+        app.get('/history', ctx.adminOnly, (c) => {
+            const user = sessionUser(c);
+            const session = manager.getOrCreate(user);
+            return c.json({ lines: session.readHistory() });
+        });
+        app.get('/session', ctx.adminOnly, ctx.wsRegister((ws, c) => {
+            // Route this connection to the per-user ShellSession. sessionUser
+            // reads from the upgrade Context forwarded by wsRegister, so two
+            // admin users get isolated sessions with their own history, cwd,
+            // and running process.
+            const userId = sessionUser(c);
+            const session = manager.getOrCreate(userId);
+            session.attach(ws);
+            // Wire incoming frames through the dispatch layer.
+            ws.addEventListener?.('message', (evt) => {
+                handleClientMessage(session, ws, String(evt.data));
+            });
+            ws.addEventListener?.('close', () => {
+                session.detach(ws);
+            });
+        }));
+    },
+};

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

@@ -0,0 +1,22 @@
+import { EventEmitter } from 'node:events';
+export interface RunnerStartOpts {
+    cmd: string;
+    cwd: string;
+    env: Record<string, string>;
+}
+export interface RunnerHandle {
+    /** Send bytes to the process's stdin. No-op for LocalRunner in v1. */
+    write(data: string): void;
+    /** Send a signal. SIGINT kills the process; EOF closes stdin. */
+    signal(sig: 'SIGINT' | 'EOF'): void;
+    /** Force-close the handle and stop emitting events. */
+    close(): Promise<void>;
+    /** Event emitter: 'stdout' (string), 'stderr' (string), 'exit' ({code, signal}). */
+    readonly events: EventEmitter;
+}
+export interface Runner {
+    start(opts: RunnerStartOpts): Promise<RunnerHandle>;
+}
+export declare class LocalRunner implements Runner {
+    start(opts: RunnerStartOpts): Promise<RunnerHandle>;
+}

package/dist/shell-shard/runner.js

@@ -0,0 +1,84 @@
+/*
+ * Runner interface — abstraction over "how a command runs".
+ *
+ * v1 implementation: LocalRunner (child_process.spawn against PATH).
+ *
+ * Deferred implementation: SshRunner (ssh2-based, per-session connection
+ * to a remote host). The SshRunner slots in without any client, protocol,
+ * or view changes — only a new verb (`:connect user@host`) switches the
+ * active runner for a session. See spec § Deferred.
+ */
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { tokenize } from './tokenize.js';
+export class LocalRunner {
+    async start(opts) {
+        const events = new EventEmitter();
+        let child;
+        try {
+            const [bin, ...args] = tokenize(opts.cmd);
+            if (!bin) {
+                // Empty command — emit an error exit without spawning
+                queueMicrotask(() => {
+                    events.emit('stderr', 'shell: empty command\n');
+                    events.emit('exit', { code: null, signal: 'spawn-error' });
+                });
+                return {
+                    write: () => { },
+                    signal: () => { },
+                    close: async () => { },
+                    events,
+                };
+            }
+            child = spawn(bin, args, {
+                cwd: opts.cwd,
+                env: opts.env,
+                shell: false,
+            });
+        }
+        catch (err) {
+            const message = err.message ?? String(err);
+            queueMicrotask(() => {
+                events.emit('stderr', `shell: ${message}\n`);
+                events.emit('exit', { code: null, signal: 'spawn-error' });
+            });
+            return {
+                write: () => { },
+                signal: () => { },
+                close: async () => { },
+                events,
+            };
+        }
+        child.stdout?.setEncoding('utf-8');
+        child.stderr?.setEncoding('utf-8');
+        child.stdout?.on('data', (data) => events.emit('stdout', data));
+        child.stderr?.on('data', (data) => events.emit('stderr', data));
+        child.on('error', (err) => {
+            events.emit('stderr', `shell: ${err.message}\n`);
+            events.emit('exit', { code: null, signal: 'spawn-error' });
+        });
+        child.on('exit', (code, signal) => {
+            events.emit('exit', { code, signal });
+        });
+        return {
+            write: (_data) => {
+                // Stdin piping is deferred in v1 — see spec § Deferred.
+                // When implemented, this becomes: child.stdin?.write(_data)
+            },
+            signal: (sig) => {
+                if (sig === 'SIGINT') {
+                    child.kill('SIGINT');
+                }
+                else if (sig === 'EOF') {
+                    child.stdin?.end();
+                }
+            },
+            close: async () => {
+                if (!child.killed && child.exitCode === null) {
+                    child.kill('SIGKILL');
+                }
+            },
+            events,
+        };
+    }
+}

package/dist/shell-shard/session-manager.d.ts

@@ -0,0 +1,56 @@
+import type { Runner } from './runner.js';
+import type { ServerEvent } from 'sh3-core';
+import { HistoryStore } from './history-store.js';
+export interface SessionConfig {
+    ringSize: number;
+    historyMaxLines: number;
+    defaultCwd: string;
+}
+/**
+ * Minimal WebSocket interface — any object with .send(string) satisfies it.
+ * The server's real WS implementation (from @hono/node-ws) provides a richer
+ * surface; we intentionally narrow it here so tests can use plain mocks.
+ */
+export interface WsLike {
+    send(data: string): void;
+    close(): void;
+}
+export declare class ShellSession {
+    readonly userId: string;
+    cwd: string;
+    env: Record<string, string>;
+    private readonly history;
+    private readonly runner;
+    private readonly ringSize;
+    private ring;
+    private readonly clients;
+    private nextSeq;
+    private running;
+    private starting;
+    constructor(userId: string, runner: Runner, history: HistoryStore, cfg: SessionConfig);
+    attach(ws: WsLike): void;
+    detach(ws: WsLike): void;
+    broadcast(event: ServerEvent): void;
+    /**
+     * Submit a command line. Ignored if a process is already running.
+     * Appends the line to history and starts the runner. Stdout/stderr/
+     * exit are broadcast as events.
+     */
+    submit(line: string, _fromWs: WsLike): Promise<void>;
+    /** Record a line in history without running anything (for local SH3 verbs). */
+    historyLog(line: string): void;
+    /** Read the persisted history buffer — used by the JSON /history endpoint. */
+    readHistory(): string[];
+    /** Forward a signal to the running process, if any. */
+    signal(sig: 'SIGINT' | 'EOF'): void;
+    /** Change cwd and broadcast a cwd update to every attached client. */
+    setCwd(cwd: string): void;
+}
+export declare class SessionManager {
+    private readonly sessions;
+    private readonly dataDir;
+    private readonly runner;
+    private readonly cfg;
+    constructor(dataDir: string, runner: Runner, cfg: SessionConfig);
+    getOrCreate(userId: string): ShellSession;
+}

package/dist/shell-shard/session-manager.js

@@ -0,0 +1,161 @@
+/*
+ * Session manager for shell-shard.
+ *
+ * One ShellSession per admin user. Every shell view the user opens
+ * attaches to the same session. The session outlives individual views
+ * and dies only on server restart (v1 — see spec § Deferred for
+ * persistence across restart).
+ *
+ * A session holds:
+ *   - cwd, env (runtime state)
+ *   - HistoryStore (persistent append-only JSONL)
+ *   - a circular ring buffer of recent events for replay on attach
+ *   - the set of currently attached WebSocket clients
+ *   - at most one running RunnerHandle
+ */
+import { HistoryStore } from './history-store.js';
+export class ShellSession {
+    userId;
+    cwd;
+    env;
+    history;
+    runner;
+    ringSize;
+    ring = [];
+    clients = new Set();
+    nextSeq = 1;
+    running = null;
+    starting = false;
+    constructor(userId, runner, history, cfg) {
+        this.userId = userId;
+        this.runner = runner;
+        this.history = history;
+        this.ringSize = cfg.ringSize;
+        this.cwd = cfg.defaultCwd || process.cwd();
+        this.env = { ...process.env, FORCE_COLOR: '1' };
+    }
+    attach(ws) {
+        this.clients.add(ws);
+        const welcome = {
+            t: 'welcome',
+            userId: this.userId,
+            cwd: this.cwd,
+            env: this.env,
+            seq: this.nextSeq - 1,
+        };
+        ws.send(JSON.stringify(welcome));
+        const replay = { t: 'replay', events: [...this.ring] };
+        ws.send(JSON.stringify(replay));
+        const history = { t: 'history', lines: this.history.read() };
+        ws.send(JSON.stringify(history));
+    }
+    detach(ws) {
+        this.clients.delete(ws);
+        // Do NOT kill running process on detach — sessions outlive views.
+    }
+    broadcast(event) {
+        const stamped = { ...event, seq: this.nextSeq++ };
+        // Append to ring, trim from head if over capacity
+        this.ring.push(stamped);
+        if (this.ring.length > this.ringSize) {
+            this.ring.splice(0, this.ring.length - this.ringSize);
+        }
+        // Fan out to every attached client
+        const msg = { t: 'event', event: stamped };
+        const wire = JSON.stringify(msg);
+        for (const ws of this.clients) {
+            ws.send(wire);
+        }
+    }
+    /**
+     * Submit a command line. Ignored if a process is already running.
+     * Appends the line to history and starts the runner. Stdout/stderr/
+     * exit are broadcast as events.
+     */
+    async submit(line, _fromWs) {
+        if (this.running || this.starting) {
+            console.warn(`[shell-shard] submit while running — ignored (user=${this.userId})`);
+            return;
+        }
+        // Claim the start slot synchronously so a concurrent submit during
+        // the `await runner.start()` below cannot slip past the lock check.
+        this.starting = true;
+        try {
+            this.history.append(line);
+            // Emit a prompt event so every attached client echoes the line
+            this.broadcast({
+                kind: 'prompt',
+                line,
+                cwd: this.cwd,
+                ts: Date.now(),
+                seq: 0,
+            });
+            const handle = await this.runner.start({
+                cmd: line,
+                cwd: this.cwd,
+                env: this.env,
+            });
+            this.running = handle;
+            handle.events.on('stdout', (data) => {
+                this.broadcast({ kind: 'stdout', data, ts: Date.now(), seq: 0 });
+            });
+            handle.events.on('stderr', (data) => {
+                this.broadcast({ kind: 'stderr', data, ts: Date.now(), seq: 0 });
+            });
+            handle.events.on('exit', (info) => {
+                this.broadcast({
+                    kind: 'exit',
+                    code: info.code,
+                    signal: info.signal,
+                    ts: Date.now(),
+                    seq: 0,
+                });
+                this.running = null;
+            });
+        }
+        finally {
+            this.starting = false;
+        }
+    }
+    /** Record a line in history without running anything (for local SH3 verbs). */
+    historyLog(line) {
+        this.history.append(line);
+    }
+    /** Read the persisted history buffer — used by the JSON /history endpoint. */
+    readHistory() {
+        return this.history.read();
+    }
+    /** Forward a signal to the running process, if any. */
+    signal(sig) {
+        this.running?.signal(sig);
+    }
+    /** Change cwd and broadcast a cwd update to every attached client. */
+    setCwd(cwd) {
+        this.cwd = cwd;
+        const msg = { t: 'cwd', cwd };
+        const wire = JSON.stringify(msg);
+        for (const ws of this.clients) {
+            ws.send(wire);
+        }
+    }
+}
+export class SessionManager {
+    sessions = new Map();
+    dataDir;
+    runner;
+    cfg;
+    constructor(dataDir, runner, cfg) {
+        this.dataDir = dataDir;
+        this.runner = runner;
+        this.cfg = cfg;
+    }
+    getOrCreate(userId) {
+        let session = this.sessions.get(userId);
+        if (!session) {
+            const history = new HistoryStore(this.dataDir, userId, this.cfg.historyMaxLines);
+            session = new ShellSession(userId, this.runner, history, this.cfg);
+            this.sessions.set(userId, session);
+        }
+        return session;
+    }
+}

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

@@ -0,0 +1 @@
+export declare function tokenize(line: string): string[];

package/dist/shell-shard/tokenize.js

@@ -0,0 +1,68 @@
+/*
+ * Minimal argv tokenizer for shell-shard.
+ *
+ * Splits a command line into argv tokens. Supports:
+ *   - Bare tokens separated by whitespace
+ *   - Double-quoted strings ("…") with backslash-escapes (\" and \\)
+ *   - Single-quoted strings ('…') with no escapes (literal content)
+ *
+ * Does NOT support (deferred; see spec § Deferred):
+ *   - Pipes, redirections, glob expansion, env var expansion
+ *   - Subshells, backticks, $(…)
+ *
+ * Users who need shell features can wrap commands with `bash -c '…'`.
+ *
+ * Throws on unterminated quoted strings.
+ */
+export function tokenize(line) {
+    const tokens = [];
+    let i = 0;
+    const n = line.length;
+    while (i < n) {
+        // Skip whitespace between tokens
+        while (i < n && isSpace(line[i]))
+            i++;
+        if (i >= n)
+            break;
+        let current = '';
+        while (i < n && !isSpace(line[i])) {
+            const ch = line[i];
+            if (ch === '"') {
+                i++; // consume opening quote
+                while (i < n && line[i] !== '"') {
+                    if (line[i] === '\\' && i + 1 < n) {
+                        // Escaped char — keep the next character literally
+                        current += line[i + 1];
+                        i += 2;
+                    }
+                    else {
+                        current += line[i];
+                        i++;
+                    }
+                }
+                if (i >= n)
+                    throw new Error('tokenize: unterminated double-quoted string');
+                i++; // consume closing quote
+            }
+            else if (ch === "'") {
+                i++; // consume opening quote
+                while (i < n && line[i] !== "'") {
+                    current += line[i];
+                    i++;
+                }
+                if (i >= n)
+                    throw new Error('tokenize: unterminated single-quoted string');
+                i++; // consume closing quote
+            }
+            else {
+                current += ch;
+                i++;
+            }
+        }
+        tokens.push(current);
+    }
+    return tokens;
+}
+function isSpace(ch) {
+    return ch === ' ' || ch === '\t';
+}

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

@@ -0,0 +1,2 @@
+import type { ShellSession, WsLike } from './session-manager.js';
+export declare function handleClientMessage(session: ShellSession, ws: WsLike, raw: string): void;

package/dist/shell-shard/ws.js

@@ -0,0 +1,78 @@
+/*
+ * WebSocket message dispatch for shell-shard.
+ *
+ * Decodes incoming ClientMessage frames and calls the appropriate method
+ * on the ShellSession. Narrow, pure: this file has no Hono/ws specifics —
+ * it just routes decoded messages to sessions. The routes() function in
+ * `index.ts` wires the real sockets through this.
+ */
+import { resolve, isAbsolute } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+export function handleClientMessage(session, ws, raw) {
+    let msg;
+    try {
+        msg = JSON.parse(raw);
+    }
+    catch {
+        // Malformed frame — ignore, do not crash the session.
+        return;
+    }
+    switch (msg.t) {
+        case 'hello':
+            // attach() already sent welcome+replay+history at connection time.
+            // The only meaningful thing here is a late hello with replayFrom,
+            // which v1 ignores — the client can resync by reconnecting.
+            return;
+        case 'submit': {
+            const trimmed = msg.line.trim();
+            if (trimmed.startsWith('cd ') || trimmed === 'cd') {
+                // Server-managed cd — don't spawn, update session cwd directly.
+                const target = trimmed === 'cd' ? '' : trimmed.slice(3).trim();
+                handleCd(session, target);
+                return;
+            }
+            void session.submit(msg.line, ws);
+            return;
+        }
+        case 'signal':
+            session.signal(msg.sig);
+            return;
+        case 'history-log':
+            session.historyLog(msg.line);
+            return;
+        case 'cwd-query':
+            // Re-emit a cwd update message (reuses setCwd() broadcast path).
+            session.setCwd(session.cwd);
+            return;
+        default: {
+            // Exhaustiveness check. If a new ClientMessage variant is added to
+            // the protocol without a handler here, TypeScript flags this line.
+            const _exhaustive = msg;
+            void _exhaustive;
+            return;
+        }
+    }
+}
+/**
+ * Handle a `cd` command server-side: resolve the target path, validate it
+ * exists and is a directory, then update session.cwd via setCwd() which
+ * broadcasts a 'cwd' message to every attached client.
+ */
+function handleCd(session, target) {
+    const dest = target === '' || target === '~'
+        ? homedir()
+        : isAbsolute(target)
+            ? target
+            : resolve(session.cwd, target);
+    if (!existsSync(dest) || !statSync(dest).isDirectory()) {
+        session.broadcast({
+            seq: 0,
+            kind: 'stderr',
+            data: `cd: no such directory: ${target}\n`,
+            ts: Date.now(),
+        });
+        return;
+    }
+    session.setCwd(dest);
+}

package/dist/users.d.ts

@@ -0,0 +1,44 @@
+/**
+ * User management — CRUD with bcrypt password hashing.
+ * Persists to {dataDir}/users.json.
+ */
+export interface StoredUser {
+    id: string;
+    username: string;
+    displayName: string;
+    passwordHash: string;
+    role: 'admin' | 'user';
+    createdAt: string;
+    updatedAt: string;
+}
+/** Public user shape — never exposes passwordHash. */
+export type PublicUser = Omit<StoredUser, 'passwordHash'>;
+export declare class UserStore {
+    #private;
+    constructor(dataDir: string);
+    /** True when no users exist (first boot). */
+    isEmpty(): boolean;
+    /** Create a user. Returns the public user + the raw password (for first-boot printing). */
+    create(opts: {
+        username: string;
+        displayName: string;
+        password: string;
+        role: 'admin' | 'user';
+    }): Promise<PublicUser>;
+    /** Verify username + password. Returns public user or null. */
+    authenticate(username: string, password: string): Promise<PublicUser | null>;
+    /** List all users (public shape). */
+    list(): PublicUser[];
+    /** Get a user by ID (public shape). */
+    get(id: string): PublicUser | null;
+    /** Update a user. Returns updated public user or null if not found. */
+    update(id: string, patch: {
+        displayName?: string;
+        password?: string;
+        role?: 'admin' | 'user';
+    }): Promise<PublicUser | null>;
+    /** Delete a user by ID. Returns true if found and removed. */
+    delete(id: string): boolean;
+    /** Generate a random temporary password. */
+    static generatePassword(): string;
+}

package/dist/users.js

@@ -0,0 +1,113 @@
+/**
+ * User management — CRUD with bcrypt password hashing.
+ * Persists to {dataDir}/users.json.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID, randomBytes } from 'node:crypto';
+// Lazy-load bcrypt — the native addon is unavailable in Node SEA builds
+// (Tauri sidecar). That's fine: Tauri never hits auth code paths.
+let _bcrypt = null;
+async function getBcrypt() {
+    if (!_bcrypt)
+        _bcrypt = await import('bcrypt');
+    return _bcrypt;
+}
+const SALT_ROUNDS = 10;
+export class UserStore {
+    #path;
+    #users = [];
+    constructor(dataDir) {
+        this.#path = `${dataDir}/users.json`;
+        this.#load();
+    }
+    #load() {
+        if (existsSync(this.#path)) {
+            try {
+                this.#users = JSON.parse(readFileSync(this.#path, 'utf-8'));
+            }
+            catch {
+                this.#users = [];
+            }
+        }
+    }
+    #save() {
+        mkdirSync(dirname(this.#path), { recursive: true });
+        writeFileSync(this.#path, JSON.stringify(this.#users, null, 2));
+    }
+    /** True when no users exist (first boot). */
+    isEmpty() {
+        return this.#users.length === 0;
+    }
+    /** Create a user. Returns the public user + the raw password (for first-boot printing). */
+    async create(opts) {
+        const lower = opts.username.toLowerCase();
+        if (this.#users.some(u => u.username === lower)) {
+            throw new Error(`Username "${lower}" already exists`);
+        }
+        const now = new Date().toISOString();
+        const user = {
+            id: randomUUID(),
+            username: lower,
+            displayName: opts.displayName,
+            passwordHash: await (await getBcrypt()).hash(opts.password, SALT_ROUNDS),
+            role: opts.role,
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.#users.push(user);
+        this.#save();
+        return this.#toPublic(user);
+    }
+    /** Verify username + password. Returns public user or null. */
+    async authenticate(username, password) {
+        const user = this.#users.find(u => u.username === username.toLowerCase());
+        if (!user)
+            return null;
+        if (!(await (await getBcrypt()).compare(password, user.passwordHash)))
+            return null;
+        return this.#toPublic(user);
+    }
+    /** List all users (public shape). */
+    list() {
+        return this.#users.map(u => this.#toPublic(u));
+    }
+    /** Get a user by ID (public shape). */
+    get(id) {
+        const user = this.#users.find(u => u.id === id);
+        return user ? this.#toPublic(user) : null;
+    }
+    /** Update a user. Returns updated public user or null if not found. */
+    async update(id, patch) {
+        const user = this.#users.find(u => u.id === id);
+        if (!user)
+            return null;
+        if (patch.displayName !== undefined)
+            user.displayName = patch.displayName;
+        if (patch.password !== undefined)
+            user.passwordHash = await (await getBcrypt()).hash(patch.password, SALT_ROUNDS);
+        if (patch.role !== undefined)
+            user.role = patch.role;
+        user.updatedAt = new Date().toISOString();
+        this.#save();
+        return this.#toPublic(user);
+    }
+    /** Delete a user by ID. Returns true if found and removed. */
+    delete(id) {
+        const before = this.#users.length;
+        this.#users = this.#users.filter(u => u.id !== id);
+        if (this.#users.length < before) {
+            this.#save();
+            return true;
+        }
+        return false;
+    }
+    /** Generate a random temporary password. */
+    static generatePassword() {
+        return randomBytes(6).toString('base64url');
+    }
+    #toPublic(user) {
+        const { passwordHash: _, ...pub } = user;
+        return pub;
+    }
+}