windows-development-sandbox 1.5.0 → 1.9.0

package/dist/app/kernel/io.js

@@ -0,0 +1,126 @@
+// The only way an operation talks to the person using it: progress and log lines, and questions (confirm, choose,
+// text, secret, path, checklist). Each surface answers them its own way (the CLI with prompts, the menu with dialogs,
+// the web with modals over RPC); a feature never knows which. Questions are plain data (QuestionSchema), so the web can
+// receive them; every surface builds its OperationIO from one `Asker` with ioFromAsker().
+import { z } from 'zod';
+const Lines = z.array(z.string()).optional();
+const ChoiceSchema = z.strictObject({ value: z.string(), label: z.string(), description: z.string().optional() });
+export const ConfirmQuestionSchema = z.strictObject({
+    kind: z.literal('confirm'),
+    title: z.string(),
+    lines: Lines,
+    /** The word on the yes button ("Stop"). */
+    yes: z.string().optional(),
+    danger: z.boolean().optional(),
+    /** A stronger confirmation: yes means typing this word (another user's name). */
+    typed: z.string().optional(),
+    /**
+     * A command typed on purpose is answer enough: the CLI does not ask (the menu and web still do). Without it the CLI
+     * asks on a terminal, takes --yes, and fails without a terminal (with `noTerminal`, or "Add --yes").
+     */
+    implied: z.boolean().optional(),
+    noTerminal: z.strictObject({ message: z.string(), fix: z.string() }).optional(),
+});
+export const ChooseQuestionSchema = z.strictObject({
+    kind: z.literal('choose'),
+    title: z.string(),
+    lines: Lines,
+    choices: z.array(ChoiceSchema).min(1),
+    initial: z.string().optional(),
+});
+export const TextQuestionSchema = z.strictObject({
+    kind: z.literal('text'),
+    title: z.string(),
+    lines: Lines,
+    initial: z.string().optional(),
+    allowEmpty: z.boolean().optional(),
+    /** What was wrong with the last answer (asked again). */
+    problem: z.string().optional(),
+});
+export const SecretQuestionSchema = z.strictObject({
+    kind: z.literal('secret'),
+    title: z.string(),
+    lines: Lines,
+    problem: z.string().optional(),
+});
+export const PathQuestionSchema = z.strictObject({
+    kind: z.literal('path'),
+    title: z.string(),
+    lines: Lines,
+    pathKind: z.enum(['dir', 'file']),
+    initial: z.string().optional(),
+    /** Words allowed instead of a path ("auto"). */
+    literals: z.array(z.string()).optional(),
+    problem: z.string().optional(),
+});
+export const ChecklistQuestionSchema = z.strictObject({
+    kind: z.literal('checklist'),
+    title: z.string(),
+    lines: Lines,
+    choices: z.array(ChoiceSchema),
+    checked: z.array(z.string()).optional(),
+});
+export const QuestionSchema = z.discriminatedUnion('kind', [
+    ConfirmQuestionSchema,
+    ChooseQuestionSchema,
+    TextQuestionSchema,
+    SecretQuestionSchema,
+    PathQuestionSchema,
+    ChecklistQuestionSchema,
+]);
+/** The wire shape of an answer for each kind (the server checks what the browser sends). */
+export const ANSWER_SCHEMAS = {
+    confirm: z.boolean(),
+    choose: z.string().max(1000).optional(),
+    text: z.string().max(10000).optional(),
+    secret: z.string().max(10000).optional(),
+    path: z.string().max(2000).optional(),
+    checklist: z.array(z.string().max(1000)).max(1000).optional(),
+};
+/** Asks a typed question until `validate` accepts the answer (each new try names the problem). */
+async function untilValid(asker, question, validate) {
+    for (let q = question;;) {
+        const answer = (await asker(q));
+        if (answer === undefined || !validate)
+            return answer;
+        const verdict = validate(answer);
+        if (verdict === true)
+            return answer;
+        q = { ...q, problem: verdict };
+    }
+}
+/** An OperationIO from one way of asking and one place for output lines. */
+export function ioFromAsker(asker, sink) {
+    return {
+        progress: (text) => sink.progress(text),
+        log: (text, tone) => sink.log(text, tone),
+        confirm: (q) => asker({ ...q, kind: 'confirm' }),
+        choose: (q) => asker({ ...q, kind: 'choose' }),
+        text: ({ validate, ...q }) => untilValid(asker, { ...q, kind: 'text' }, validate),
+        secret: ({ validate, ...q }) => untilValid(asker, { ...q, kind: 'secret' }, validate),
+        path: ({ validate, ...q }) => untilValid(asker, { ...q, kind: 'path' }, validate),
+        checklist: (q) => asker({ ...q, kind: 'checklist' }),
+    };
+}
+/**
+ * An OperationIO for tests: answers come from a list in order (a function gets the question). Running out of answers
+ * fails the test with the question that had none.
+ */
+export function fakeIO(answers = []) {
+    const queue = [...answers];
+    const seen = { questions: [], progress: [], logs: [] };
+    const asker = (question) => {
+        seen.questions.push(question);
+        if (!queue.length)
+            return Promise.reject(new Error('No answer for: ' + question.title));
+        const next = queue.shift();
+        return Promise.resolve((typeof next === 'function' ? next(question) : next));
+    };
+    const io = ioFromAsker(asker, {
+        progress: (text) => seen.progress.push(text),
+        log: (text, tone) => seen.logs.push({ text, ...(tone ? { tone } : {}) }),
+    });
+    return { io, seen };
+}
+/** For reads that never ask (queries): output is dropped, and a question is a bug. */
+export const NO_QUESTIONS = ioFromAsker((question) => Promise.reject(new Error('A query asked a question: ' + question.title)), { progress: () => undefined, log: () => undefined });

package/dist/app/kernel/rpc.d.ts

@@ -0,0 +1,156 @@
+import { z } from 'zod';
+import { type OperationIO } from './io.js';
+/** One call or subscription on the socket (chosen by the browser, unique while it runs). */
+export declare const RpcIdSchema: z.ZodString;
+/** A definition's id (sessions.restart). */
+export declare const DefinitionIdSchema: z.ZodString;
+export declare const CallMessageSchema: z.ZodObject<{
+    t: z.ZodLiteral<"call">;
+    id: z.ZodString;
+    op: z.ZodString;
+    input: z.ZodUnknown;
+}, z.core.$strict>;
+export declare const AnswerMessageSchema: z.ZodObject<{
+    t: z.ZodLiteral<"answer">;
+    id: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strict>;
+export declare const SubscribeMessageSchema: z.ZodObject<{
+    t: z.ZodLiteral<"subscribe">;
+    id: z.ZodString;
+    query: z.ZodString;
+    input: z.ZodUnknown;
+}, z.core.$strict>;
+export declare const UnsubscribeMessageSchema: z.ZodObject<{
+    t: z.ZodLiteral<"unsubscribe">;
+    id: z.ZodString;
+}, z.core.$strict>;
+/** Browser -> server. */
+export declare const ClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    t: z.ZodLiteral<"call">;
+    id: z.ZodString;
+    op: z.ZodString;
+    input: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"answer">;
+    id: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"subscribe">;
+    id: z.ZodString;
+    query: z.ZodString;
+    input: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"unsubscribe">;
+    id: z.ZodString;
+}, z.core.$strict>], "t">;
+export type ClientMessage = z.output<typeof ClientMessageSchema>;
+/** Server -> browser. */
+export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    t: z.ZodLiteral<"progress">;
+    id: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"log">;
+    id: z.ZodString;
+    text: z.ZodString;
+    tone: z.ZodOptional<z.ZodEnum<{
+        ok: "ok";
+        muted: "muted";
+        warn: "warn";
+        danger: "danger";
+        accent: "accent";
+    }>>;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"ask">;
+    id: z.ZodString;
+    question: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"confirm">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        yes: z.ZodOptional<z.ZodString>;
+        danger: z.ZodOptional<z.ZodBoolean>;
+        typed: z.ZodOptional<z.ZodString>;
+        implied: z.ZodOptional<z.ZodBoolean>;
+        noTerminal: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            fix: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"choose">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        choices: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        initial: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        initial: z.ZodOptional<z.ZodString>;
+        allowEmpty: z.ZodOptional<z.ZodBoolean>;
+        problem: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"secret">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        problem: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"path">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        pathKind: z.ZodEnum<{
+            file: "file";
+            dir: "dir";
+        }>;
+        initial: z.ZodOptional<z.ZodString>;
+        literals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        problem: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"checklist">;
+        title: z.ZodString;
+        lines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        choices: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        checked: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"result">;
+    id: z.ZodString;
+    output: z.ZodUnknown;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"error">;
+    id: z.ZodString;
+    error: z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            cancelled: "cancelled";
+            invalid: "invalid";
+            bug: "bug";
+        }>;
+        message: z.ZodString;
+        fix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    t: z.ZodLiteral<"data">;
+    id: z.ZodString;
+    output: z.ZodUnknown;
+}, z.core.$strict>], "t">;
+export type ServerMessage = z.output<typeof ServerMessageSchema>;
+/** Most calls and subscriptions one socket may have open at once. */
+export declare const MAX_OPEN_PER_SOCKET = 32;
+/** What the RPC endpoint needs from the program: the definitions allowed on the web, and a way to run them. */
+export interface RpcHost {
+    /** 'operation' or 'query' when the id is registered and allowed on the web, else undefined. */
+    kind(id: string): 'operation' | 'query' | undefined;
+    /** How often a query is read again while subscribed (undefined: once). */
+    liveMs(id: string): number | undefined;
+    /** Runs an allowed definition (input and output checked). */
+    run(id: string, input: unknown, io: OperationIO): Promise<unknown>;
+}

package/dist/app/kernel/rpc.js

@@ -0,0 +1,47 @@
+// The messages of the web UI's RPC socket (/api/rpc), shared by the server and the browser. The browser calls
+// operations and queries by id, answers questions, and subscribes to live queries; the server streams progress, log
+// lines and questions, then a result or an error. A subscription gets `data` whenever the result changes (an `error`
+// does not end it; `unsubscribe` does). The server checks every message against these schemas.
+import { z } from 'zod';
+import { WireErrorSchema } from './errors.js';
+import { QuestionSchema } from './io.js';
+/** One call or subscription on the socket (chosen by the browser, unique while it runs). */
+export const RpcIdSchema = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/);
+/** A definition's id (sessions.restart). */
+export const DefinitionIdSchema = z
+    .string()
+    .regex(/^[a-z][A-Za-z0-9]*(\.[a-z][A-Za-z0-9]*)+$/)
+    .max(80);
+const ToneSchema = z.enum(['ok', 'warn', 'danger', 'muted', 'accent']);
+export const CallMessageSchema = z.strictObject({
+    t: z.literal('call'),
+    id: RpcIdSchema,
+    op: DefinitionIdSchema,
+    input: z.unknown(),
+});
+export const AnswerMessageSchema = z.strictObject({ t: z.literal('answer'), id: RpcIdSchema, value: z.unknown() });
+export const SubscribeMessageSchema = z.strictObject({
+    t: z.literal('subscribe'),
+    id: RpcIdSchema,
+    query: DefinitionIdSchema,
+    input: z.unknown(),
+});
+export const UnsubscribeMessageSchema = z.strictObject({ t: z.literal('unsubscribe'), id: RpcIdSchema });
+/** Browser -> server. */
+export const ClientMessageSchema = z.discriminatedUnion('t', [
+    CallMessageSchema,
+    AnswerMessageSchema,
+    SubscribeMessageSchema,
+    UnsubscribeMessageSchema,
+]);
+/** Server -> browser. */
+export const ServerMessageSchema = z.discriminatedUnion('t', [
+    z.strictObject({ t: z.literal('progress'), id: RpcIdSchema, text: z.string() }),
+    z.strictObject({ t: z.literal('log'), id: RpcIdSchema, text: z.string(), tone: ToneSchema.optional() }),
+    z.strictObject({ t: z.literal('ask'), id: RpcIdSchema, question: QuestionSchema }),
+    z.strictObject({ t: z.literal('result'), id: RpcIdSchema, output: z.unknown() }),
+    z.strictObject({ t: z.literal('error'), id: RpcIdSchema, error: WireErrorSchema }),
+    z.strictObject({ t: z.literal('data'), id: RpcIdSchema, output: z.unknown() }),
+]);
+/** Most calls and subscriptions one socket may have open at once. */
+export const MAX_OPEN_PER_SOCKET = 32;

package/dist/{cli/menu/settings → app/kernel}/schema-node.d.ts

@@ -20,6 +20,7 @@ type ZodLike = z.ZodType & {
     description?: string;
     minValue?: number | null;
     maxValue?: number | null;
+    isInt?: boolean;
 };
 /** The editor a setting gets. */
 export type EditorKind = 'boolean' | 'choice' | 'union' | 'number' | 'string' | 'string-list' | 'choice-list' | 'object-list' | 'string-map' | 'object-map' | 'object' | 'json';
@@ -35,6 +36,14 @@ export declare class SchemaNode {
     get description(): string | undefined;
     get min(): number | undefined;
     get max(): number | undefined;
+    /** A number that must be whole. */
+    get integer(): boolean;
+    /** A secret (an API key): shown as ***, typed with each character hidden. */
+    get secret(): boolean;
+    /** May the setting be left out (optional or with a default)? */
+    get optional(): boolean;
+    /** The numbers allowed, in words: "1 to 65535", "at least 2048", "more than 0", "" without limits. */
+    rangeText(): string;
     /** The fields of an object, in schema order. */
     children(): [string, SchemaNode][];
     child(name: string): SchemaNode | undefined;

package/dist/{cli/menu/settings → app/kernel}/schema-node.js

@@ -35,6 +35,32 @@ export class SchemaNode {
     get max() {
         return this.inner.maxValue ?? undefined;
     }
+    /** A number that must be whole. */
+    get integer() {
+        return Boolean(this.inner.isInt);
+    }
+    /** A secret (an API key): shown as ***, typed with each character hidden. */
+    get secret() {
+        const meta = (z) => z.meta?.();
+        return meta(this.schema)?.secret === true || meta(this.inner)?.secret === true;
+    }
+    /** May the setting be left out (optional or with a default)? */
+    get optional() {
+        return ['optional', 'default'].includes(this.schema._zod.def.type);
+    }
+    /** The numbers allowed, in words: "1 to 65535", "at least 2048", "more than 0", "" without limits. */
+    rangeText() {
+        const checks = (this.inner._zod.def.checks ?? []).map((c) => c._zod.def);
+        const lower = checks.find((c) => c.check === 'greater_than');
+        const upper = checks.find((c) => c.check === 'less_than');
+        const lo = lower?.value;
+        const hi = upper?.value;
+        if (lo !== undefined && hi !== undefined && lower?.inclusive !== false && upper?.inclusive !== false)
+            return lo + ' to ' + hi;
+        const low = lo === undefined ? '' : (lower?.inclusive === false ? 'more than ' : 'at least ') + lo;
+        const high = hi === undefined ? '' : (upper?.inclusive === false ? 'less than ' : 'at most ') + hi;
+        return [low, high].filter(Boolean).join(' and ');
+    }
     /** The fields of an object, in schema order. */
     children() {
         return Object.entries(this.inner.shape ?? {})

package/dist/app/kernel/text.d.ts

@@ -0,0 +1,6 @@
+/** "just now", "5 min ago", "3 h ago", "2 d ago". */
+export declare function ago(then: number | string | Date, now?: number): string;
+/** "1 session", "2 sessions". */
+export declare function plural(n: number, noun: string, many?: string): string;
+/** "memoryMb" -> "Memory MB", "vGpu" -> "V GPU": a readable label from a setting's key. */
+export declare function humanize(key: string): string;

package/dist/app/kernel/text.js

@@ -0,0 +1,57 @@
+// Small text helpers every surface formats with the same way: times as "5 min ago", keys as readable labels, counts
+// with the right noun. Pure (the browser bundle imports them too).
+/** "just now", "5 min ago", "3 h ago", "2 d ago". */
+export function ago(then, now = Date.now()) {
+    const secs = Math.max(0, Math.round((now - new Date(then).getTime()) / 1000));
+    if (Number.isNaN(secs))
+        return '';
+    if (secs < 45)
+        return 'just now';
+    if (secs < 3600)
+        return Math.round(secs / 60) + ' min ago';
+    if (secs < 86400)
+        return Math.round(secs / 3600) + ' h ago';
+    return Math.round(secs / 86400) + ' d ago';
+}
+/** "1 session", "2 sessions". */
+export function plural(n, noun, many = noun + 's') {
+    return n + ' ' + (n === 1 ? noun : many);
+}
+/** Words written in capitals wherever they appear in a key. */
+const UPPER = new Set([
+    'mb',
+    'gb',
+    'cpu',
+    'gpu',
+    'jdk',
+    'sdk',
+    'id',
+    'url',
+    'ui',
+    'npm',
+    'msvc',
+    'uv',
+    'api',
+    'ssh',
+    'vm',
+    'io',
+]);
+/** "harness" is the code's word for an agent; screens say agent. */
+const PLAIN = { harness: 'agent', harnesses: 'agents' };
+/** "memoryMb" -> "Memory MB", "vGpu" -> "V GPU": a readable label from a setting's key. */
+export function humanize(key) {
+    const words = key
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .split(' ')
+        .filter(Boolean)
+        .map((w) => PLAIN[w.toLowerCase()] ?? w);
+    return words
+        .map((w, i) => {
+        const lower = w.toLowerCase();
+        if (UPPER.has(lower))
+            return w.toUpperCase();
+        return i === 0 ? w[0].toUpperCase() + w.slice(1) : lower;
+    })
+        .join(' ');
+}

package/dist/app/kernel/view.d.ts

@@ -0,0 +1,146 @@
+import type { z } from 'zod';
+import type { OperationDef } from './define.js';
+import type { Field } from './fields.js';
+/** The one palette: the TUI theme and the web colours both map these. */
+export type Tone = 'ok' | 'warn' | 'danger' | 'muted' | 'accent';
+/** A short label the web shows as a pill next to an item ("running"); the menu and the CLI show the hint. */
+export interface Badge {
+    readonly text: string;
+    readonly tone?: Tone;
+}
+/** Where a link goes. Each surface maps a target to what it can do (attach / terminal page / a command to type). */
+export type Target = 
+/** A running session's terminal: the menu attaches, the web opens its terminal page. */
+{
+    readonly kind: 'terminal';
+    readonly session: string;
+}
+/** Start an agent: the menu runs `launch`, the web opens its new-session dialog. */
+ | {
+    readonly kind: 'start-agent';
+    readonly agent: string;
+}
+/** A command line of an area that is not a feature yet: the menu runs it, the web does not offer it. */
+ | {
+    readonly kind: 'command';
+    readonly argv: readonly string[];
+}
+/** Another view. */
+ | {
+    readonly kind: 'view';
+    readonly view: string;
+};
+interface ActionBase {
+    /** The words on a button or a row ("Stop the sandbox…"). */
+    readonly label: string;
+    /** One word for a key bar or an Enter hint ("stop"). */
+    readonly verb?: string;
+    /** The menu key that does it (one letter). */
+    readonly key?: string;
+    /** How long it survives in a narrow key bar: 0 never goes, bigger goes earlier (menu). */
+    readonly importance?: number;
+    readonly description?: string;
+}
+/** Runs an operation with this input (plus the answers to `fields`, asked first). */
+export interface OperationAction extends ActionBase {
+    readonly kind: 'operation';
+    readonly op: string;
+    readonly input: Readonly<Record<string, unknown>>;
+    /** Asks for a confirmation before running (from the operation's `danger`). */
+    readonly danger?: boolean;
+    /** Values to ask for before running; each answer goes into the input under the field's name. */
+    readonly fields?: readonly Field[];
+    /** What `fields` start as (the current value of a setting), by field name. */
+    readonly initial?: Readonly<Record<string, unknown>>;
+}
+export interface LinkAction extends ActionBase {
+    readonly kind: 'link';
+    readonly target: Target;
+}
+export type Action = OperationAction | LinkAction;
+/** One label: value line (a status fact, a setting). */
+export interface Fact {
+    readonly id: string;
+    readonly label: string;
+    readonly value: string;
+    readonly tone?: Tone;
+    readonly description?: string;
+    readonly details?: readonly string[];
+}
+/** A column of a section shown as a table (CLI table, web table); items fill it through `cells`. */
+export interface Column {
+    readonly key: string;
+    readonly label: string;
+}
+/** One entry of a list. */
+export interface Item {
+    readonly id: string;
+    readonly label: string;
+    /** The right-hand text (a state, a value). */
+    readonly hint?: string;
+    readonly tone?: Tone;
+    readonly badges?: readonly Badge[];
+    readonly description?: string;
+    /** Extra lines (the menu's details pane, the CLI's indented lines, the web's card body). */
+    readonly details?: readonly string[];
+    /** A heading inside the section ("This folder's project"). */
+    readonly group?: string;
+    /** Marked as "the one this is about" (the project of this folder): `*` in the CLI. */
+    readonly marked?: boolean;
+    /** The values for the section's columns. */
+    readonly cells?: Readonly<Record<string, string>>;
+    /** What Enter / a click does. */
+    readonly primary?: Action;
+    readonly actions?: readonly Action[];
+    /** Why it cannot be used now. */
+    readonly disabled?: string;
+    /** More words a search finds it by. */
+    readonly keywords?: string;
+}
+/** A line under a section; `only` limits it to one surface (a CLI flag hint). */
+export interface Note {
+    readonly text: string;
+    readonly tone?: Tone;
+    readonly only?: 'cli' | 'menu' | 'web';
+}
+export interface Section {
+    readonly id: string;
+    readonly title?: string;
+    /** A short line next to the title ("2 folders guarded"). */
+    readonly summary?: string;
+    readonly description?: string;
+    readonly facts?: readonly Fact[];
+    readonly items?: readonly Item[];
+    /** Show the items as a table with these columns where a surface can (CLI, web). */
+    readonly columns?: readonly Column[];
+    /** Where `columns` is used: everywhere (default), or only on the command line (the web lists the items in full). */
+    readonly columnsOn?: 'all' | 'cli';
+    readonly actions?: readonly Action[];
+    readonly notes?: readonly Note[];
+}
+/** What a page shows when it has nothing: the text and the next step (the CLI prints `cliText`, naming a command). */
+export interface Empty {
+    readonly title?: string;
+    readonly text: string;
+    readonly action?: Action;
+    readonly cliText?: string;
+}
+export interface Page {
+    readonly title: string;
+    /** One line above everything (whose sandbox this is). */
+    readonly notice?: Note;
+    readonly sections: readonly Section[];
+    /** Actions for the whole page (refresh-like, start). */
+    readonly actions?: readonly Action[];
+    /** Shown instead of the sections when they have no facts and no items. */
+    readonly empty?: Empty;
+}
+/** An action that runs `def` with `input` (typed from its input schema; `fields` may ask for the rest). */
+export declare function action<I extends z.ZodType, O extends z.ZodType>(def: OperationDef<I, O>, input: Partial<z.input<I>>, extra?: Partial<Omit<OperationAction, 'kind' | 'op' | 'input'>>): OperationAction;
+/** An action that goes somewhere. */
+export declare function link(target: Target, label: string, extra?: Partial<Omit<LinkAction, 'kind' | 'target'>>): LinkAction;
+/** Does the page show anything besides its empty state? */
+export declare function pageHasContent(page: Page): boolean;
+/** Every action a page offers, wherever it sits (for parity checks and key bars). */
+export declare function pageActions(page: Page): Action[];
+export {};

package/dist/app/kernel/view.js

@@ -0,0 +1,28 @@
+/** An action that runs `def` with `input` (typed from its input schema; `fields` may ask for the rest). */
+export function action(def, input, extra = {}) {
+    return {
+        kind: 'operation',
+        op: def.id,
+        input: input,
+        label: def.title,
+        ...(def.danger ? { danger: true } : {}),
+        ...extra,
+    };
+}
+/** An action that goes somewhere. */
+export function link(target, label, extra = {}) {
+    return { kind: 'link', target, label, ...extra };
+}
+/** Does the page show anything besides its empty state? */
+export function pageHasContent(page) {
+    return page.sections.some((s) => (s.facts?.length ?? 0) > 0 || (s.items?.length ?? 0) > 0);
+}
+/** Every action a page offers, wherever it sits (for parity checks and key bars). */
+export function pageActions(page) {
+    const fromItem = (i) => [...(i.primary ? [i.primary] : []), ...(i.actions ?? [])];
+    return [
+        ...(page.actions ?? []),
+        ...(page.empty?.action ? [page.empty.action] : []),
+        ...page.sections.flatMap((s) => [...(s.actions ?? []), ...(s.items ?? []).flatMap(fromItem)]),
+    ];
+}

package/dist/app/registry.d.ts

@@ -0,0 +1,10 @@
+import type { AppContext } from './context.js';
+import { type AnyDefinition, type Implementation, type OperationIO, type OutputOf, type QueryDef, type RpcHost } from './kernel/index.js';
+export declare const IMPLEMENTATIONS: readonly Implementation<AnyDefinition, AppContext>[];
+export declare function implementationOf(id: string): Implementation<AnyDefinition, AppContext> | undefined;
+/** Runs a definition by id: input checked before, output checked after. */
+export declare function runDefinition(id: string, ctx: AppContext, input: unknown, io: OperationIO): Promise<unknown>;
+/** Reads a query in-process (the menu): typed output, and no questions. */
+export declare function readQuery<D extends QueryDef>(def: D, ctx: AppContext, input?: unknown): Promise<OutputOf<D>>;
+/** What the web server may run: the registered definitions whose surfaces include the web. */
+export declare function createRpcHost(ctx: AppContext): RpcHost;