sh3-core 0.6.0

package/dist/shell-shard/scrollback.svelte.js

@@ -0,0 +1,43 @@
+/*
+ * Scrollback store for a single shell.terminal view instance.
+ *
+ * One instance per view mount. Holds ScrollbackEntry[], supports:
+ *   - push(entry): append or coalesce with the previous entry if both
+ *                  are text entries with the same stream.
+ *   - clear(): wipe all entries (local only — does not affect other
+ *              attached views).
+ *   - cap at a per-view limit (default 2000) — oldest trimmed.
+ *
+ * Uses Svelte 5 runes. The backing array is $state() so consumers just
+ * read .entries and reactivity Just Works™.
+ */
+const DEFAULT_CAP = 2000;
+let nextId = 0;
+function mkId() {
+    return `e${++nextId}`;
+}
+export class Scrollback {
+    constructor(cap = DEFAULT_CAP) {
+        this.entries = $state([]);
+        this.cap = cap;
+    }
+    push(entry) {
+        // Coalesce consecutive text entries of the same stream
+        const last = this.entries[this.entries.length - 1];
+        if (last &&
+            last.kind === 'text' &&
+            entry.kind === 'text' &&
+            last.stream === entry.stream) {
+            last.chunks.push(...entry.chunks);
+            return;
+        }
+        const full = Object.assign(Object.assign({}, entry), { id: mkId() });
+        this.entries.push(full);
+        if (this.entries.length > this.cap) {
+            this.entries.splice(0, this.entries.length - this.cap);
+        }
+    }
+    clear() {
+        this.entries.length = 0;
+    }
+}

package/dist/shell-shard/session-client.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { ClientMessage, ServerMessage } from './protocol';
+type MessageHandler = (msg: ServerMessage) => void;
+export declare class SessionClient {
+    private readonly url;
+    private ws;
+    private handlers;
+    private pendingHistoryLogs;
+    private lastSeq;
+    private backoffIndex;
+    private closed;
+    connected: boolean;
+    cwd: string;
+    env: Record<string, string>;
+    history: string[];
+    constructor(url: string);
+    connect(): void;
+    private scheduleReconnect;
+    send(msg: ClientMessage): void;
+    private sendRaw;
+    onMessage(handler: MessageHandler): () => void;
+    close(): void;
+}
+export {};

package/dist/shell-shard/session-client.svelte.js

@@ -0,0 +1,120 @@
+/*
+ * Session client for shell-shard.
+ *
+ * One instance per view mount. Wraps a WebSocket to /api/shell/session.
+ *
+ * Responsibilities:
+ *   - Connect with exponential backoff on initial failure
+ *   - Type-safe send() / onMessage()
+ *   - Reconnect with replayFrom cursor on drop
+ *   - Queue history-log messages while disconnected; flush on reconnect
+ *   - Expose a reactive `connected` signal + latest known cwd/env
+ *
+ * The client does NOT parse message meaning beyond the `t` discriminator —
+ * it's a transport, not a dispatcher. Higher layers (Terminal.svelte) read
+ * messages via onMessage.
+ */
+const BACKOFFS = [1000, 2000, 5000, 10000];
+export class SessionClient {
+    constructor(url) {
+        this.url = url;
+        this.ws = null;
+        this.handlers = new Set();
+        this.pendingHistoryLogs = [];
+        this.lastSeq = 0;
+        this.backoffIndex = 0;
+        this.closed = false;
+        this.connected = $state(false);
+        this.cwd = $state('');
+        this.env = $state({});
+        this.history = $state([]);
+    }
+    connect() {
+        if (this.closed)
+            return;
+        try {
+            this.ws = new WebSocket(this.url);
+        }
+        catch (_a) {
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws.addEventListener('open', () => {
+            this.backoffIndex = 0;
+            this.connected = true;
+            const hello = this.lastSeq > 0
+                ? { t: 'hello', replayFrom: this.lastSeq }
+                : { t: 'hello' };
+            this.sendRaw(hello);
+            // Flush any queued history-log messages accumulated while offline
+            for (const queued of this.pendingHistoryLogs) {
+                this.sendRaw(queued);
+            }
+            this.pendingHistoryLogs = [];
+        });
+        this.ws.addEventListener('message', (evt) => {
+            let msg;
+            try {
+                msg = JSON.parse(evt.data);
+            }
+            catch (_a) {
+                return; // ignore malformed
+            }
+            // Track latest seq for reconnect replay
+            if (msg.t === 'event' && typeof msg.event.seq === 'number') {
+                this.lastSeq = msg.event.seq;
+            }
+            if (msg.t === 'welcome') {
+                this.cwd = msg.cwd;
+                this.env = msg.env;
+                this.lastSeq = msg.seq;
+            }
+            if (msg.t === 'cwd') {
+                this.cwd = msg.cwd;
+            }
+            if (msg.t === 'history') {
+                this.history = msg.lines;
+            }
+            for (const h of this.handlers)
+                h(msg);
+        });
+        this.ws.addEventListener('close', () => {
+            this.connected = false;
+            this.ws = null;
+            this.scheduleReconnect();
+        });
+        this.ws.addEventListener('error', () => {
+            // close event will fire next
+        });
+    }
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        const delay = BACKOFFS[Math.min(this.backoffIndex, BACKOFFS.length - 1)];
+        this.backoffIndex++;
+        setTimeout(() => this.connect(), delay);
+    }
+    send(msg) {
+        if (msg.t === 'history-log' && !this.connected) {
+            // Queue for flush on reconnect
+            this.pendingHistoryLogs.push(msg);
+            return;
+        }
+        this.sendRaw(msg);
+    }
+    sendRaw(msg) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify(msg));
+    }
+    onMessage(handler) {
+        this.handlers.add(handler);
+        return () => this.handlers.delete(handler);
+    }
+    close() {
+        var _a;
+        this.closed = true;
+        (_a = this.ws) === null || _a === void 0 ? void 0 : _a.close();
+        this.ws = null;
+    }
+}

package/dist/shell-shard/shellShard.svelte.d.ts

@@ -0,0 +1,2 @@
+import type { Shard } from '../api';
+export declare const shellShard: Shard;

package/dist/shell-shard/shellShard.svelte.js

@@ -0,0 +1,139 @@
+/*
+ * shell-shard — framework built-in providing the `shell.terminal` view.
+ *
+ * Client half of the terminal/REPL shard. See spec at
+ * docs/superpowers/specs/2026-04-10-shell-shard-design.md.
+ *
+ * activate() is admin-gated: when ctx.isAdmin is false the shard activates
+ * but registers no views, so non-admin users literally cannot mount the
+ * terminal. The server WebSocket endpoint (/api/shell/session) also refuses
+ * non-admin upgrades as a second line of defense.
+ *
+ * autostart() is defined so the shard activates at boot without requiring
+ * a dedicated app to launch it first, matching the __sh3core__ pattern.
+ */
+import { mount, unmount } from 'svelte';
+import { manifest } from './manifest';
+import Terminal from './Terminal.svelte';
+import { listRegisteredApps, getActiveApp } from '../apps/registry.svelte';
+import { launchApp } from '../apps/lifecycle';
+import { registeredShards } from '../shards/activate.svelte';
+import { inspectActiveLayout, focusView, closeTab } from '../layout/inspection';
+import { getUser, isAdmin } from '../auth/index';
+/** Walk a layout tree and collect all tab entries (slotId + viewId + label). */
+function collectTabEntries(node) {
+    if (node.type === 'tabs') {
+        return node.tabs.filter((t) => t.viewId !== null);
+    }
+    if (node.type === 'split') {
+        return node.children.flatMap(collectTabEntries);
+    }
+    // slot node: wrap as a synthetic tab entry if it has a viewId
+    if (node.viewId !== null) {
+        return [{ slotId: node.slotId, viewId: node.viewId, label: node.viewId }];
+    }
+    return [];
+}
+function makeShellApi(_ctx) {
+    return {
+        // → apps/registry.svelte: listRegisteredApps() returns AppManifest[]
+        listApps() {
+            return listRegisteredApps().map((m) => ({ id: m.id, label: m.label }));
+        },
+        // → apps/registry.svelte: getActiveApp() returns AppManifest | null
+        getActiveApp() {
+            const m = getActiveApp();
+            return m ? { id: m.id, label: m.label } : null;
+        },
+        // → apps/lifecycle: launchApp() is async; fire-and-forget to keep ShellApi sync.
+        // Verb handlers display feedback independently via scrollback.
+        launchApp(id) {
+            void launchApp(id);
+        },
+        // → shards/activate.svelte: registeredShards reactive map
+        listShards() {
+            return Array.from(registeredShards.values()).map((s) => ({
+                id: s.manifest.id,
+                label: s.manifest.label,
+                version: s.manifest.version,
+            }));
+        },
+        // → layout/inspection: inspectActiveLayout() + tree walk
+        listViewsInCurrentLayout() {
+            try {
+                const { root } = inspectActiveLayout();
+                return collectTabEntries(root).map((t) => {
+                    var _a;
+                    return ({
+                        slotId: t.slotId,
+                        viewId: (_a = t.viewId) !== null && _a !== void 0 ? _a : '',
+                        label: t.label,
+                    });
+                });
+            }
+            catch (_a) {
+                return [];
+            }
+        },
+        // → layout/inspection: focusView(viewId) returns boolean
+        openViewInCurrentLayout(viewId) {
+            try {
+                const found = focusView(viewId);
+                return found ? { ok: true } : { ok: false, error: `view "${viewId}" not found in current layout` };
+            }
+            catch (err) {
+                return { ok: false, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+        // → layout/inspection: closeTab(slotId) is async (guarded close).
+        // Fire-and-forget; the tab disappears asynchronously. ShellApi stays sync.
+        closeSlot(slotId) {
+            void closeTab(slotId);
+            return { ok: true };
+        },
+        // TODO Phase 10: wire to zone manager when state:manage permission is available.
+        // The shell manifest declares permissions: [] so ctx.zones is undefined.
+        // A future permission grant + ctx.zones.list() would power these.
+        listZones(_shardId) { return []; },
+        readZone(_shardId, _zoneName) { return null; },
+        // → auth/index: getUser() + isAdmin()
+        whoAmI() {
+            var _a;
+            const user = getUser();
+            return {
+                userId: (_a = user === null || user === void 0 ? void 0 : user.id) !== null && _a !== void 0 ? _a : 'guest',
+                admin: isAdmin(),
+            };
+        },
+    };
+}
+export const shellShard = {
+    manifest,
+    activate(ctx) {
+        if (!ctx.isAdmin) {
+            // Non-admin: don't expose the view. Nothing to register.
+            return;
+        }
+        const shell = makeShellApi(ctx);
+        const factory = {
+            mount(container, _context) {
+                const proto = typeof location !== 'undefined' && location.protocol === 'https:' ? 'wss' : 'ws';
+                const host = typeof location !== 'undefined' ? location.host : 'localhost';
+                const wsUrl = `${proto}://${host}/api/shell/session`;
+                const instance = mount(Terminal, {
+                    target: container,
+                    props: { shell, wsUrl },
+                });
+                return {
+                    unmount() {
+                        unmount(instance);
+                    },
+                };
+            },
+        };
+        ctx.registerView('shell:terminal', factory);
+    },
+    autostart() {
+        // Intentionally empty — same pattern as __sh3core__.
+    },
+};

package/dist/shell-shard/verbs/apps.d.ts

@@ -0,0 +1,3 @@
+import type { Verb } from '../registry';
+export declare const appsVerb: Verb;
+export declare const appVerb: Verb;

package/dist/shell-shard/verbs/apps.js

@@ -0,0 +1,50 @@
+import AppsTable from '../rich/AppsTable.svelte';
+import AppCard from '../rich/AppCard.svelte';
+export const appsVerb = {
+    name: 'apps',
+    summary: 'List installed apps. Click a row to launch.',
+    async run(ctx) {
+        const apps = ctx.shell.listApps();
+        ctx.scrollback.push({
+            kind: 'rich',
+            component: AppsTable,
+            props: {
+                data: {
+                    apps,
+                    onClickApp: (id) => {
+                        ctx.shell.launchApp(id);
+                        ctx.scrollback.push({
+                            kind: 'status',
+                            text: `shell: launched app ${id}`,
+                            level: 'info',
+                            ts: Date.now(),
+                        });
+                    },
+                },
+            },
+            ts: Date.now(),
+        });
+    },
+};
+export const appVerb = {
+    name: 'app',
+    summary: 'Show the currently active app.',
+    async run(ctx) {
+        const active = ctx.shell.getActiveApp();
+        if (!active) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'shell: no active app',
+                level: 'info',
+                ts: Date.now(),
+            });
+            return;
+        }
+        ctx.scrollback.push({
+            kind: 'rich',
+            component: AppCard,
+            props: { data: { id: active.id, label: active.label, shards: [] } },
+            ts: Date.now(),
+        });
+    },
+};

package/dist/shell-shard/verbs/clear.d.ts

@@ -0,0 +1,2 @@
+import type { Verb } from '../registry';
+export declare const clearVerb: Verb;

package/dist/shell-shard/verbs/clear.js

@@ -0,0 +1,7 @@
+export const clearVerb = {
+    name: 'clear',
+    summary: 'Clear the scrollback (local only — other views are unaffected).',
+    async run(ctx) {
+        ctx.scrollback.clear();
+    },
+};

package/dist/shell-shard/verbs/help.d.ts

@@ -0,0 +1,2 @@
+import type { Verb, VerbRegistry } from '../registry';
+export declare function makeHelpVerb(registry: VerbRegistry): Verb;

package/dist/shell-shard/verbs/help.js

@@ -0,0 +1,21 @@
+import HelpTable from '../rich/HelpTable.svelte';
+export function makeHelpVerb(registry) {
+    return {
+        name: 'help',
+        summary: 'List verbs or show detail for one.',
+        async run(ctx) {
+            const rows = registry.list().map((v) => ({ name: v.name, summary: v.summary }));
+            ctx.scrollback.push({
+                kind: 'rich',
+                component: HelpTable,
+                props: {
+                    data: {
+                        rows,
+                        onClickName: (name) => ctx.dispatch(name),
+                    },
+                },
+                ts: Date.now(),
+            });
+        },
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { Verb } from '../registry';
+export declare const historyVerb: Verb;

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

@@ -0,0 +1,20 @@
+import HistoryList from '../rich/HistoryList.svelte';
+export const historyVerb = {
+    name: 'history',
+    summary: 'Show the last N history lines. Default 50.',
+    async run(ctx, args) {
+        const n = args[0] ? Math.max(1, parseInt(args[0], 10) || 50) : 50;
+        const lines = ctx.session.history.slice(-n);
+        ctx.scrollback.push({
+            kind: 'rich',
+            component: HistoryList,
+            props: {
+                data: {
+                    lines,
+                    onClickLine: (line) => ctx.dispatch(line),
+                },
+            },
+            ts: Date.now(),
+        });
+    },
+};

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

@@ -0,0 +1,2 @@
+import type { VerbRegistry } from '../registry';
+export declare function registerV1Verbs(registry: VerbRegistry): void;

package/dist/shell-shard/verbs/index.js

@@ -0,0 +1,29 @@
+/*
+ * Bundle of v1 verbs for shell-shard. Call registerV1Verbs(registry) once
+ * at activate time to populate the registry.
+ */
+import { makeHelpVerb } from './help';
+import { clearVerb } from './clear';
+import { historyVerb } from './history';
+import { appsVerb, appVerb } from './apps';
+import { shardsVerb } from './shards';
+import { viewsVerb, openVerb, closeVerb } from './views';
+import { zonesVerb, zoneVerb } from './zones';
+import { pwdVerb, cdVerb, envVerb, whoamiVerb } from './session';
+export function registerV1Verbs(registry) {
+    registry.register(makeHelpVerb(registry));
+    registry.register(clearVerb);
+    registry.register(historyVerb);
+    registry.register(appsVerb);
+    registry.register(appVerb);
+    registry.register(shardsVerb);
+    registry.register(viewsVerb);
+    registry.register(openVerb);
+    registry.register(closeVerb);
+    registry.register(zonesVerb);
+    registry.register(zoneVerb);
+    registry.register(pwdVerb);
+    registry.register(cdVerb);
+    registry.register(envVerb);
+    registry.register(whoamiVerb);
+}

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

@@ -0,0 +1,5 @@
+import type { Verb } from '../registry';
+export declare const pwdVerb: Verb;
+export declare const cdVerb: Verb;
+export declare const envVerb: Verb;
+export declare const whoamiVerb: Verb;

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

@@ -0,0 +1,65 @@
+/*
+ * Session verbs: pwd, cd, env, whoami.
+ *
+ * cd is server-authoritative — the client forwards it as a 'submit' message
+ * so ws.ts can intercept and update session.cwd without spawning a process.
+ */
+import EnvTable from '../rich/EnvTable.svelte';
+export const pwdVerb = {
+    name: 'pwd',
+    summary: 'Show the server session cwd.',
+    async run(ctx) {
+        ctx.scrollback.push({
+            kind: 'text',
+            stream: 'stdout',
+            chunks: [ctx.cwd + '\n'],
+            ts: Date.now(),
+        });
+    },
+};
+export const cdVerb = {
+    name: 'cd',
+    summary: 'Change the session working directory.',
+    async run(ctx, args) {
+        var _a;
+        const path = (_a = args[0]) !== null && _a !== void 0 ? _a : '';
+        if (!path) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: cd <path>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        // cd is server-authoritative. Forward the submit so the server's
+        // dispatcher can intercept it and update session.cwd (see ws.ts).
+        ctx.session.send({ t: 'submit', line: `cd ${path}` });
+    },
+};
+export const envVerb = {
+    name: 'env',
+    summary: 'Show the session environment.',
+    async run(ctx) {
+        const env = ctx.session.env;
+        ctx.scrollback.push({
+            kind: 'rich',
+            component: EnvTable,
+            props: { data: { env } },
+            ts: Date.now(),
+        });
+    },
+};
+export const whoamiVerb = {
+    name: 'whoami',
+    summary: 'Show the current admin user and session info.',
+    async run(ctx) {
+        const me = ctx.shell.whoAmI();
+        ctx.scrollback.push({
+            kind: 'text',
+            stream: 'stdout',
+            chunks: [`${me.userId}${me.admin ? ' (admin)' : ''}\n`],
+            ts: Date.now(),
+        });
+    },
+};

package/dist/shell-shard/verbs/shards.d.ts

@@ -0,0 +1,2 @@
+import type { Verb } from '../registry';
+export declare const shardsVerb: Verb;

package/dist/shell-shard/verbs/shards.js

@@ -0,0 +1,14 @@
+import ShardsTable from '../rich/ShardsTable.svelte';
+export const shardsVerb = {
+    name: 'shards',
+    summary: 'List active shards.',
+    async run(ctx) {
+        const shards = ctx.shell.listShards();
+        ctx.scrollback.push({
+            kind: 'rich',
+            component: ShardsTable,
+            props: { data: { shards } },
+            ts: Date.now(),
+        });
+    },
+};

package/dist/shell-shard/verbs/views.d.ts

@@ -0,0 +1,4 @@
+import type { Verb } from '../registry';
+export declare const viewsVerb: Verb;
+export declare const openVerb: Verb;
+export declare const closeVerb: Verb;

package/dist/shell-shard/verbs/views.js

@@ -0,0 +1,90 @@
+import ViewsTable from '../rich/ViewsTable.svelte';
+export const viewsVerb = {
+    name: 'views',
+    summary: 'List views currently mounted in the active layout.',
+    async run(ctx) {
+        const views = ctx.shell.listViewsInCurrentLayout();
+        ctx.scrollback.push({
+            kind: 'rich',
+            component: ViewsTable,
+            props: {
+                data: {
+                    views,
+                    onClose: (slotId) => {
+                        var _a;
+                        const result = ctx.shell.closeSlot(slotId);
+                        if (!result.ok) {
+                            ctx.scrollback.push({
+                                kind: 'status',
+                                text: `shell: close failed — ${(_a = result.error) !== null && _a !== void 0 ? _a : 'unknown'}`,
+                                level: 'error',
+                                ts: Date.now(),
+                            });
+                        }
+                    },
+                },
+            },
+            ts: Date.now(),
+        });
+    },
+};
+export const openVerb = {
+    name: 'open',
+    summary: 'Open a view from any active shard into the current layout.',
+    async run(ctx, args) {
+        var _a;
+        const viewId = args[0];
+        if (!viewId) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: open <viewId>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const result = ctx.shell.openViewInCurrentLayout(viewId);
+        if (!result.ok) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `shell: open failed — ${(_a = result.error) !== null && _a !== void 0 ? _a : 'unknown'}`,
+                level: 'error',
+                ts: Date.now(),
+            });
+        }
+        else {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `shell: opened ${viewId}`,
+                level: 'info',
+                ts: Date.now(),
+            });
+        }
+    },
+};
+export const closeVerb = {
+    name: 'close',
+    summary: 'Close a view by slot id.',
+    async run(ctx, args) {
+        var _a;
+        const slotId = args[0];
+        if (!slotId) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: 'usage: close <slotId>',
+                level: 'warn',
+                ts: Date.now(),
+            });
+            return;
+        }
+        const result = ctx.shell.closeSlot(slotId);
+        if (!result.ok) {
+            ctx.scrollback.push({
+                kind: 'status',
+                text: `shell: close failed — ${(_a = result.error) !== null && _a !== void 0 ? _a : 'unknown'}`,
+                level: 'error',
+                ts: Date.now(),
+            });
+        }
+    },
+};

package/dist/shell-shard/verbs/zones.d.ts

@@ -0,0 +1,3 @@
+import type { Verb } from '../registry';
+export declare const zonesVerb: Verb;
+export declare const zoneVerb: Verb;