windows-development-sandbox 1.5.0 → 1.9.0

package/dist/app/features/settings/settings.def.d.ts

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+import { type Page } from '../../kernel/index.js';
+export declare const ScopeSchema: z.ZodEnum<{
+    project: "project";
+    user: "user";
+}>;
+export type Scope = z.output<typeof ScopeSchema>;
+/** One setting as every surface shows it. Values are what the file or the merged settings say, secrets as ***. */
+export declare const SettingRowSchema: z.ZodObject<{
+    id: z.ZodString;
+    key: z.ZodArray<z.ZodString>;
+    label: z.ZodString;
+    category: z.ZodString;
+    section: z.ZodOptional<z.ZodString>;
+    field: z.ZodType<import("../../kernel/fields.js").Field, unknown, z.core.$ZodTypeInternals<import("../../kernel/fields.js").Field, unknown>>;
+    value: z.ZodUnknown;
+    set: z.ZodBoolean;
+    yours: z.ZodUnknown;
+    yoursSet: z.ZodBoolean;
+    inProject: z.ZodOptional<z.ZodUnknown>;
+    default: z.ZodOptional<z.ZodUnknown>;
+    locked: z.ZodBoolean;
+}, z.core.$strip>;
+export type SettingRow = z.output<typeof SettingRowSchema>;
+export declare const SettingsListSchema: z.ZodObject<{
+    scope: z.ZodEnum<{
+        project: "project";
+        user: "user";
+    }>;
+    file: z.ZodString;
+    exists: z.ZodBoolean;
+    dataFolder: z.ZodOptional<z.ZodString>;
+    categories: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+    rows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        key: z.ZodArray<z.ZodString>;
+        label: z.ZodString;
+        category: z.ZodString;
+        section: z.ZodOptional<z.ZodString>;
+        field: z.ZodType<import("../../kernel/fields.js").Field, unknown, z.core.$ZodTypeInternals<import("../../kernel/fields.js").Field, unknown>>;
+        value: z.ZodUnknown;
+        set: z.ZodBoolean;
+        yours: z.ZodUnknown;
+        yoursSet: z.ZodBoolean;
+        inProject: z.ZodOptional<z.ZodUnknown>;
+        default: z.ZodOptional<z.ZodUnknown>;
+        locked: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SettingsList = z.output<typeof SettingsListSchema>;
+export declare const listSettings: import("../../kernel/define.js").QueryDef<z.ZodObject<{
+    scope: z.ZodDefault<z.ZodEnum<{
+        project: "project";
+        user: "user";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    scope: z.ZodEnum<{
+        project: "project";
+        user: "user";
+    }>;
+    file: z.ZodString;
+    exists: z.ZodBoolean;
+    dataFolder: z.ZodOptional<z.ZodString>;
+    categories: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strip>>;
+    rows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        key: z.ZodArray<z.ZodString>;
+        label: z.ZodString;
+        category: z.ZodString;
+        section: z.ZodOptional<z.ZodString>;
+        field: z.ZodType<import("../../kernel/fields.js").Field, unknown, z.core.$ZodTypeInternals<import("../../kernel/fields.js").Field, unknown>>;
+        value: z.ZodUnknown;
+        set: z.ZodBoolean;
+        yours: z.ZodUnknown;
+        yoursSet: z.ZodBoolean;
+        inProject: z.ZodOptional<z.ZodUnknown>;
+        default: z.ZodOptional<z.ZodUnknown>;
+        locked: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>, "settings.list">;
+export declare const getSetting: import("../../kernel/define.js").QueryDef<z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>, "settings.get">;
+export declare const setSetting: import("../../kernel/define.js").OperationDef<z.ZodObject<{
+    scope: z.ZodDefault<z.ZodEnum<{
+        project: "project";
+        user: "user";
+    }>>;
+    key: z.ZodString;
+    value: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    changed: z.ZodBoolean;
+    message: z.ZodString;
+}, z.core.$strip>, "settings.set">;
+export declare const resetSetting: import("../../kernel/define.js").OperationDef<z.ZodObject<{
+    scope: z.ZodDefault<z.ZodEnum<{
+        project: "project";
+        user: "user";
+    }>>;
+    key: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    changed: z.ZodBoolean;
+    message: z.ZodString;
+}, z.core.$strip>, "settings.reset">;
+/** The settings page of one scope: a section per category, each setting with its value and an edit action. */
+export declare function settingsPage(o: SettingsList): Page;
+export declare const settingsView: import("../../kernel/define.js").ViewDef<{
+    settings: import("../../kernel/define.js").QueryDef<z.ZodObject<{
+        scope: z.ZodDefault<z.ZodEnum<{
+            project: "project";
+            user: "user";
+        }>>;
+    }, z.core.$strip>, z.ZodObject<{
+        scope: z.ZodEnum<{
+            project: "project";
+            user: "user";
+        }>;
+        file: z.ZodString;
+        exists: z.ZodBoolean;
+        dataFolder: z.ZodOptional<z.ZodString>;
+        categories: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+        rows: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            key: z.ZodArray<z.ZodString>;
+            label: z.ZodString;
+            category: z.ZodString;
+            section: z.ZodOptional<z.ZodString>;
+            field: z.ZodType<import("../../kernel/fields.js").Field, unknown, z.core.$ZodTypeInternals<import("../../kernel/fields.js").Field, unknown>>;
+            value: z.ZodUnknown;
+            set: z.ZodBoolean;
+            yours: z.ZodUnknown;
+            yoursSet: z.ZodBoolean;
+            inProject: z.ZodOptional<z.ZodUnknown>;
+            default: z.ZodOptional<z.ZodUnknown>;
+            locked: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, "settings.list">;
+}, {
+    scope: Scope;
+}, "settings">;

package/dist/app/features/settings/settings.def.js

@@ -0,0 +1,179 @@
+// Settings: every setting of your own file (all projects) or of this folder's .sandbox-config.json (this project), read
+// from the config schema through Fields, with get, set and reset. Pure: schemas and the view; the rows are made on the
+// Node side (settings-rows.ts) because the config schema is, and secrets never leave it unmasked.
+import { z } from 'zod';
+import { action, defineOperation, defineQuery, defineView, FieldSchema, link, valueText, } from '../../kernel/index.js';
+export const ScopeSchema = z
+    .enum(['user', 'project'])
+    .describe("Your own settings (all projects) or this folder's .sandbox-config.json (this project)");
+const KeySchema = z
+    .string()
+    .regex(/^[A-Za-z0-9_$-]+(\.[A-Za-z0-9_$-]+)*$/)
+    .max(200)
+    .describe('The setting, e.g. sandbox.memoryMb');
+/** One setting as every surface shows it. Values are what the file or the merged settings say, secrets as ***. */
+export const SettingRowSchema = z.object({
+    id: z.string().describe('The setting, e.g. sandbox.memoryMb'),
+    key: z.array(z.string()),
+    label: z.string(),
+    category: z.string(),
+    /** A heading inside the category (Toolchains › Node.js). */
+    section: z.string().optional(),
+    field: FieldSchema,
+    /** In effect in this scope (this project: only what its file says). */
+    value: z.unknown(),
+    /** Written in this scope's file. */
+    set: z.boolean(),
+    /** Your own setting in effect (all projects), and whether your file sets it. */
+    yours: z.unknown(),
+    yoursSet: z.boolean(),
+    /** What this project's file says (undefined: not set there, or a project cannot set it). */
+    inProject: z.unknown().optional(),
+    /** The built-in default (your own settings only). */
+    default: z.unknown().optional(),
+    /** A project can only make this stricter than your own setting. */
+    locked: z.boolean(),
+});
+export const SettingsListSchema = z.object({
+    scope: ScopeSchema,
+    file: z.string().describe('The file this scope edits'),
+    exists: z.boolean(),
+    /** Your own settings: where the data folder is (it has its own flow; its setting is not listed). */
+    dataFolder: z.string().optional(),
+    categories: z.array(z.object({ id: z.string(), label: z.string(), description: z.string() })),
+    rows: z.array(SettingRowSchema),
+});
+export const listSettings = defineQuery({
+    id: 'settings.list',
+    title: 'Settings',
+    summary: 'every setting with its value, by category',
+    input: z.object({ scope: ScopeSchema.default('user') }),
+    output: SettingsListSchema,
+    cli: { name: 'config', action: 'list', json: true },
+});
+export const getSetting = defineQuery({
+    id: 'settings.get',
+    title: 'Get a setting',
+    summary: 'show one setting (secrets as ***)',
+    input: z.object({ key: KeySchema }),
+    output: z.object({ key: z.string(), value: z.unknown() }),
+    text: (o) => (typeof o.value === 'string' ? o.value : JSON.stringify(o.value, null, 2)),
+    surfaces: { except: { menu: 'Settings shows every value', web: 'the Settings page shows every value' } },
+    cli: { name: 'config', action: 'get', positional: ['key'] },
+});
+export const setSetting = defineOperation({
+    id: 'settings.set',
+    title: 'Change a setting',
+    summary: 'change one setting (text is read like the command line: true/on, numbers, JSON)',
+    input: z.object({
+        scope: ScopeSchema.default('user'),
+        key: KeySchema,
+        value: z.unknown().describe('The new value'),
+    }),
+    output: z.object({ key: z.string(), changed: z.boolean(), message: z.string() }),
+    text: (o) => o.message,
+    cli: { name: 'config', action: 'set', positional: ['key', 'value'] },
+});
+export const resetSetting = defineOperation({
+    id: 'settings.reset',
+    title: 'Reset a setting',
+    summary: 'put one setting back to its default (in a project file: remove it)',
+    input: z.object({ scope: ScopeSchema.default('user'), key: KeySchema }),
+    output: z.object({ key: z.string(), changed: z.boolean(), message: z.string() }),
+    text: (o) => o.message,
+    cli: { name: 'config', action: 'reset', positional: ['key'] },
+});
+/** The facts under a setting: its key, your value, the project's, the default, and the lock. */
+function details(row, scope) {
+    const text = (v) => valueText(v, row.field, 40).text;
+    return [
+        'Setting       ' + row.id,
+        'All projects  ' + text(row.yours) + (row.yoursSet ? '  (your file)' : '  (built-in default)'),
+        'This project  ' + (row.inProject === undefined ? 'not set' : text(row.inProject)),
+        ...(scope === 'user' ? ['Default       ' + text(row.default)] : []),
+        ...(scope === 'project' && row.locked ? ['A project can only make this stricter than your own setting.'] : []),
+    ];
+}
+function settingItem(row, scope) {
+    const shown = scope === 'project' && !row.set
+        ? 'all projects: ' + valueText(row.yours, row.field, 40).text
+        : valueText(row.value, row.field).text;
+    const editable = row.field.kind === 'secret' ? '' : row.value;
+    return {
+        id: row.id,
+        label: row.label,
+        hint: shown,
+        ...(row.set ? { tone: scope === 'project' ? 'accent' : 'ok', badges: [{ text: 'set', tone: 'accent' }] } : {}),
+        description: row.field.help,
+        group: row.section,
+        details: details(row, scope),
+        keywords: row.id,
+        cells: { setting: row.id, value: shown },
+        primary: action(setSetting, { scope, key: row.id }, {
+            label: 'Change',
+            verb: 'edit',
+            fields: [{ ...row.field, name: 'value', label: row.label }],
+            initial: { value: editable },
+        }),
+        actions: row.set
+            ? [
+                action(resetSetting, { scope, key: row.id }, { label: scope === 'project' ? 'Remove' : 'Reset to default', verb: 'reset', key: 'r' }),
+            ]
+            : [],
+    };
+}
+/** The Data folder row: where the saved data is; moving it has a flow of its own (menu; sandbox storage move). */
+function dataFolderItem(folder) {
+    return {
+        id: '@data-folder',
+        label: 'Data folder',
+        hint: folder,
+        cells: { setting: 'storage.root', value: folder },
+        description: 'Where your tools, logins, history and logs are kept between sandboxes. Move it with the menu (Settings > Data folder) or sandbox storage move <folder>.',
+        primary: link({ kind: 'command', argv: ['storage'] }, 'Data folder', { verb: 'change' }),
+    };
+}
+/** The settings page of one scope: a section per category, each setting with its value and an edit action. */
+export function settingsPage(o) {
+    const sections = o.categories.map((c) => ({
+        id: c.id,
+        title: c.label,
+        description: c.description,
+        columns: [
+            { key: 'setting', label: 'SETTING' },
+            { key: 'value', label: 'VALUE' },
+        ],
+        columnsOn: 'cli',
+        items: [
+            ...o.rows.filter((r) => r.category === c.id).map((r) => settingItem(r, o.scope)),
+            ...(c.id === 'general' && o.dataFolder ? [dataFolderItem(o.dataFolder)] : []),
+        ],
+    }));
+    return {
+        title: 'Settings',
+        notice: {
+            text: 'Editing ' +
+                o.file +
+                (o.exists ? '' : ' (created when you save)') +
+                (o.scope === 'project' ? ': only what a project may set; needs your approval at the next launch' : ''),
+            tone: o.scope === 'project' ? 'accent' : 'muted',
+        },
+        sections,
+    };
+}
+export const settingsView = defineView({
+    id: 'settings',
+    title: 'Settings',
+    summary: 'Every setting, for all projects or just this project, with its value, default and description.',
+    queries: { settings: listSettings },
+    operations: [setSetting, resetSetting],
+    tabs: {
+        param: 'scope',
+        choices: [
+            { value: 'user', label: 'All projects' },
+            { value: 'project', label: 'This project' },
+        ],
+    },
+    inputs: (params) => ({ settings: { scope: params.scope } }),
+    build: ({ settings }) => settingsPage(settings),
+});

package/dist/app/features/settings/settings.run.d.ts

@@ -0,0 +1,67 @@
+import { type AppContext } from '../../context.js';
+import { type SettingsFiles } from './settings-rows.js';
+/** Your own settings file (the one --config names) and the project file of the current folder. */
+export declare function settingsFiles(ctx: AppContext): SettingsFiles;
+export declare const listSettingsRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").QueryDef<import("zod").ZodObject<{
+    scope: import("zod").ZodDefault<import("zod").ZodEnum<{
+        project: "project";
+        user: "user";
+    }>>;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    scope: import("zod").ZodEnum<{
+        project: "project";
+        user: "user";
+    }>;
+    file: import("zod").ZodString;
+    exists: import("zod").ZodBoolean;
+    dataFolder: import("zod").ZodOptional<import("zod").ZodString>;
+    categories: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        label: import("zod").ZodString;
+        description: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    rows: import("zod").ZodArray<import("zod").ZodObject<{
+        id: import("zod").ZodString;
+        key: import("zod").ZodArray<import("zod").ZodString>;
+        label: import("zod").ZodString;
+        category: import("zod").ZodString;
+        section: import("zod").ZodOptional<import("zod").ZodString>;
+        field: import("zod").ZodType<import("../../kernel/fields.js").Field, unknown, import("zod/v4/core").$ZodTypeInternals<import("../../kernel/fields.js").Field, unknown>>;
+        value: import("zod").ZodUnknown;
+        set: import("zod").ZodBoolean;
+        yours: import("zod").ZodUnknown;
+        yoursSet: import("zod").ZodBoolean;
+        inProject: import("zod").ZodOptional<import("zod").ZodUnknown>;
+        default: import("zod").ZodOptional<import("zod").ZodUnknown>;
+        locked: import("zod").ZodBoolean;
+    }, import("zod/v4/core").$strip>>;
+}, import("zod/v4/core").$strip>, "settings.list">, import("../../../cli/commands/context.js").Context>;
+export declare const getSettingRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").QueryDef<import("zod").ZodObject<{
+    key: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    key: import("zod").ZodString;
+    value: import("zod").ZodUnknown;
+}, import("zod/v4/core").$strip>, "settings.get">, import("../../../cli/commands/context.js").Context>;
+export declare const setSettingRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{
+    scope: import("zod").ZodDefault<import("zod").ZodEnum<{
+        project: "project";
+        user: "user";
+    }>>;
+    key: import("zod").ZodString;
+    value: import("zod").ZodUnknown;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    key: import("zod").ZodString;
+    changed: import("zod").ZodBoolean;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "settings.set">, import("../../../cli/commands/context.js").Context>;
+export declare const resetSettingRun: import("../../kernel/define.js").Implementation<import("../../kernel/define.js").OperationDef<import("zod").ZodObject<{
+    scope: import("zod").ZodDefault<import("zod").ZodEnum<{
+        project: "project";
+        user: "user";
+    }>>;
+    key: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    key: import("zod").ZodString;
+    changed: import("zod").ZodBoolean;
+    message: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, "settings.reset">, import("../../../cli/commands/context.js").Context>;

package/dist/app/features/settings/settings.run.js

@@ -0,0 +1,84 @@
+// The settings feature's work: the rows of a scope, and one setting read, changed or reset. Files are changed one
+// setting at a time with comments kept, and nothing is written unless the whole file stays valid (settings-file.ts).
+import _ from 'lodash';
+import { redactSecrets } from '../../../core/schema/index.js';
+import { fail } from '../../../core/util/index.js';
+import { hereDir } from '../../../cli/commands/projects/here.js';
+import { implement } from '../../context.js';
+import { allowedText, valueFromText } from '../../kernel/index.js';
+import { CATEGORIES } from './categories.def.js';
+import { ConfigFile } from './settings-file.js';
+import { findSetting, masked, settingRows } from './settings-rows.js';
+import { getSetting, listSettings, resetSetting, setSetting } from './settings.def.js';
+/** Your own settings file (the one --config names) and the project file of the current folder. */
+export function settingsFiles(ctx) {
+    return { user: ConfigFile.user(ctx.loaded.configPath), project: ConfigFile.project(hereDir(ctx)) };
+}
+/** A typed or sent value as the setting reads it: text goes through the command line's rules (true/on, numbers ...). */
+function valueFor(node, value) {
+    return typeof value === 'string' ? valueFromText(node, value) : value;
+}
+export const listSettingsRun = implement(listSettings, (ctx, input) => {
+    const files = settingsFiles(ctx);
+    const file = files[input.scope];
+    const rows = settingRows(files, input.scope).filter((r) => input.scope === 'project' || r.id !== 'storage.root');
+    return {
+        scope: input.scope,
+        file: file.file,
+        exists: file.exists,
+        ...(input.scope === 'user' ? { dataFolder: ctx.storageRoot } : {}),
+        categories: CATEGORIES.filter((c) => rows.some((r) => r.category === c.id)).map((c) => ({
+            id: c.id,
+            label: c.label,
+            description: c.description,
+        })),
+        rows,
+    };
+});
+export const getSettingRun = implement(getSetting, (ctx, input) => {
+    const file = settingsFiles(ctx).user;
+    const { key } = findSetting(file, input.key);
+    // Secret values (an agent's API keys) are never shown.
+    return { key: input.key, value: _.get(redactSecrets(file.userConfig()), key) };
+});
+/** The file of a scope, and the setting a key names in it. */
+function target(ctx, scope, name) {
+    const file = settingsFiles(ctx)[scope];
+    return { ...findSetting(file, name), file };
+}
+export const setSettingRun = implement(setSetting, (ctx, input) => {
+    const { key, node, file } = target(ctx, input.scope, input.key);
+    if (node.isSection)
+        fail('"' + input.key + '" is a group of settings.', 'Set one of them, e.g. ' + node.leaves(key)[0]?.key.join('.'));
+    const value = valueFor(node, input.value);
+    const problem = node.check(value);
+    if (problem !== true) {
+        const typed = typeof input.value === 'string' ? input.value : JSON.stringify(masked(key, input.value));
+        fail('"' + typed + '" does not work for ' + input.key + ': ' + problem, allowedText(node));
+    }
+    const outcome = file.set(key, value);
+    if (typeof outcome === 'object')
+        fail('Could not change ' + input.key + ': ' + outcome.problems.join('; '), 'Nothing was written.');
+    return {
+        key: input.key,
+        changed: outcome === 'saved',
+        message: input.key +
+            ' is ' +
+            JSON.stringify(masked(key, value)) +
+            (outcome === 'unchanged' ? ' (it was already)' : '') +
+            '.',
+    };
+});
+export const resetSettingRun = implement(resetSetting, (ctx, input) => {
+    const { key, file } = target(ctx, input.scope, input.key);
+    const outcome = file.set(key, undefined);
+    if (typeof outcome === 'object')
+        fail('Could not reset ' + input.key + ': ' + outcome.problems.join('; '), 'Nothing was written.');
+    return {
+        key: input.key,
+        changed: outcome === 'saved',
+        message: file.isProject
+            ? input.key + ' is not set in ' + file.file + ' any more.'
+            : input.key + ' is back to its default: ' + JSON.stringify(masked(key, file.defaultOf(key))) + '.',
+    };
+});

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

@@ -0,0 +1,143 @@
+import type { z } from 'zod';
+import type { OperationIO } from './io.js';
+import type { Page } from './view.js';
+export type SurfaceName = 'cli' | 'menu' | 'web';
+export declare const SURFACE_NAMES: readonly SurfaceName[];
+/** Where a definition is offered: everywhere, or everywhere but these surfaces (each with the reason). */
+export type Surfaces = 'all' | {
+    readonly except: Readonly<Partial<Record<SurfaceName, string>>>;
+};
+/** The command groups of `sandbox --help` (and the menu's command list). */
+export type CommandGroup = 'Agents' | 'Sessions' | 'Projects & accounts' | 'Data' | 'Web' | 'Health' | 'Advanced';
+/** Lists filled in at run time (the menu's command form offers them). */
+export type DynamicChoices = 'harnesses' | 'accounts' | 'sessions';
+/** How one input field is spelled on the command line (the description comes from the schema's .describe()). */
+export interface CliFlag {
+    readonly flag: `--${string}`;
+    readonly short?: `-${string}`;
+    /** The name --help shows; `flag` stays accepted as a hidden alias. */
+    readonly shownAs?: `--${string}`;
+    /** Placeholder in --help (name for --agent <name>). */
+    readonly value?: string;
+    readonly choices?: DynamicChoices | readonly string[];
+    readonly noMenu?: boolean;
+    readonly advanced?: boolean;
+    readonly label?: string;
+}
+/** The command line for a definition: a command of its own, or an action of an existing command (`config get`). */
+export interface CliHint {
+    readonly name: string;
+    readonly action?: string;
+    /** Required for a command of its own. */
+    readonly group?: CommandGroup;
+    /** --help's one line (default: the definition's summary). */
+    readonly summary?: string;
+    /** Input fields given as positional arguments, in order (after the action, if any). */
+    readonly positional?: readonly string[];
+    readonly flags?: Readonly<Record<string, CliFlag | undefined>>;
+    /** The command takes -y/--yes, which answers its confirmations; the text is its --help line. */
+    readonly yes?: string;
+    /** Offers --json. */
+    readonly json?: boolean;
+    /** Shapes what --json prints (kept as the command printed it before the core); default: the output. */
+    shapeJson?(output: unknown): unknown;
+    readonly examples?: readonly string[];
+}
+/** A CliHint as written in a definition: field names checked against the input, the output typed. */
+export interface TypedCliHint<I, O> extends Omit<CliHint, 'positional' | 'flags' | 'shapeJson'> {
+    readonly positional?: readonly (keyof I & string)[];
+    readonly flags?: {
+        readonly [K in keyof I]?: CliFlag;
+    };
+    shapeJson?(output: O): unknown;
+}
+interface Definition<Id extends string, I extends z.ZodType, O extends z.ZodType> {
+    readonly id: Id;
+    /** Menu row, web button or heading, CLI summary. */
+    readonly title: string;
+    readonly summary: string;
+    readonly input: I;
+    readonly output: O;
+    /** Default: every surface. */
+    readonly surfaces?: Surfaces;
+    readonly cli?: CliHint;
+    /** The output in one text: what an operation did, or a value a query read (CLI output, menu notice, web note). */
+    text?(output: z.output<O>): string;
+}
+/** What a definition is written as: its CLI hint typed against its own schemas. */
+type Written<D extends Definition<string, z.ZodType, z.ZodType>> = Omit<D, 'kind' | 'cli'> & {
+    readonly cli?: TypedCliHint<z.input<D['input']>, z.output<D['output']>>;
+};
+export interface OperationDef<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType, Id extends string = string> extends Definition<Id, I, O> {
+    readonly kind: 'operation';
+    /** Shown as dangerous (red); it asks for its own confirmation through io.confirm. */
+    readonly danger?: boolean;
+}
+export interface QueryDef<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType, Id extends string = string> extends Definition<Id, I, O> {
+    readonly kind: 'query';
+    /** Read again this often while shown (the menu's status line and the web's subscriptions use the same rule). */
+    readonly live?: {
+        readonly everyMs: number;
+    };
+}
+export type AnyDefinition = OperationDef | QueryDef;
+export type InputOf<D extends AnyDefinition> = z.output<D['input']>;
+export type OutputOf<D extends AnyDefinition> = z.output<D['output']>;
+export type QueryMap = Readonly<Record<string, QueryDef>>;
+export type ViewData<Q extends QueryMap> = {
+    readonly [K in keyof Q]: z.output<Q[K]['output']>;
+};
+export type ViewInputs<Q extends QueryMap> = {
+    readonly [K in keyof Q]?: z.input<Q[K]['input']>;
+};
+/** The tabs of a view: which parameter they set, and its values. */
+export interface ViewTabs<P> {
+    readonly param: keyof P & string;
+    readonly choices: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+}
+export interface ViewDef<Q extends QueryMap = QueryMap, P = Record<string, never>, Id extends string = string> {
+    readonly kind: 'view';
+    readonly id: Id;
+    readonly title: string;
+    readonly summary: string;
+    readonly queries: Q;
+    /** Every operation the page may offer (the parity check reads this). */
+    readonly operations: readonly OperationDef[];
+    /** A parameter switched with tabs above the page (Settings: all projects or this project), first choice default. */
+    readonly tabs?: ViewTabs<P>;
+    /** The input of each query for these view parameters (default: each query's defaults). */
+    inputs?(params: P): ViewInputs<Q>;
+    /** Pure: query results in, a Page out. */
+    build(data: ViewData<Q>, params: P): Page;
+}
+export declare function defineOperation<const Id extends string, I extends z.ZodType, O extends z.ZodType>(def: Written<OperationDef<I, O, Id>>): OperationDef<I, O, Id>;
+export declare function defineQuery<const Id extends string, I extends z.ZodType, O extends z.ZodType>(def: Written<QueryDef<I, O, Id>>): QueryDef<I, O, Id>;
+/** Any view, whatever its parameters (a list of views, a view looked up by id); call build with the right ones. */
+export type AnyView = ViewDef<QueryMap, never>;
+export declare function defineView<const Id extends string, Q extends QueryMap, P = Record<string, never>>(def: Omit<ViewDef<Q, P, Id>, 'kind'>): ViewDef<Q, P, Id>;
+/** Why a definition is not on a surface, or undefined when it is. */
+export declare function exemption(def: {
+    readonly surfaces?: Surfaces;
+}, surface: SurfaceName): string | undefined;
+export declare function onSurface(def: {
+    readonly surfaces?: Surfaces;
+}, surface: SurfaceName): boolean;
+/** A definition with its run function (Node side). `Ctx` is what the program gives every run (app/context.ts). */
+export interface Implementation<D extends AnyDefinition = AnyDefinition, Ctx = unknown> {
+    readonly def: D;
+    run(ctx: Ctx, input: InputOf<D>, io: OperationIO): Promise<OutputOf<D>>;
+}
+/** Binds implement() to the program's context type once (app/context.ts), so features write implement(def, run). */
+export declare function implementer<Ctx>(): <D extends AnyDefinition>(def: D, run: (ctx: Ctx, input: InputOf<D>, io: OperationIO) => Promise<OutputOf<D>> | OutputOf<D>) => Implementation<D, Ctx>;
+/** The input as the definition reads it (defaults filled in); a value that does not fit says what is wrong. */
+export declare function parseInput<D extends AnyDefinition>(def: D, input: unknown): InputOf<D>;
+/** Runs an implementation the way every surface must: input checked before, output checked after. */
+export declare function invoke<D extends AnyDefinition, Ctx>(impl: Implementation<D, Ctx>, ctx: Ctx, input: unknown, io: OperationIO): Promise<OutputOf<D>>;
+/** The inputs a view's queries run with for these parameters (defaults filled in). */
+export declare function viewInputs<Q extends QueryMap, P>(view: ViewDef<Q, P>, params: P): {
+    [K in keyof Q]: unknown;
+};
+export {};