@fnndsc/brasa 0.56.1 → 0.56.2

package/dist/core/argumentKinds.js

@@ -0,0 +1,223 @@
+import { dirname, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { backendInstalled_get } from './backend.js';
+/** The core's kind names, which a core command may use and no other. */
+export const CORE_KIND_NAMES = ['word', 'enum', 'int', 'number', 'cfsPath', 'hostPath', 'variable', 'job'];
+/** A variable's name, as `set` and `${name}` spell it. */
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A joblet as a word names it: `%3`, `3`, `%%`, `%+`, `%`. */
+const JOB_WORD = /^(?:%?\d+|%%|%\+|%)$/;
+/** A whole number as a word writes it. */
+const INT_WORD = /^[+-]?\d+$/;
+/**
+ * Checks a number against an argument's bounds.
+ *
+ * @param value - The number.
+ * @param argument - The argument, with its bounds.
+ * @returns The value, or why it is out of bounds.
+ */
+function bounds_check(value, argument) {
+    if (argument.min !== undefined && value < argument.min)
+        return { ok: false, reason: `at least ${argument.min}` };
+    if (argument.max !== undefined && value > argument.max)
+        return { ok: false, reason: `at most ${argument.max}` };
+    return { ok: true, value };
+}
+/**
+ * A number schema with an argument's bounds.
+ *
+ * @param base - The number schema.
+ * @param argument - The argument, with its bounds.
+ * @returns The schema, bounded.
+ */
+function numberSchema_bound(base, argument) {
+    let schema = base;
+    if (argument.min !== undefined)
+        schema = schema.min(argument.min);
+    if (argument.max !== undefined)
+        schema = schema.max(argument.max);
+    return schema;
+}
+/**
+ * Reads a word as text that is not empty.
+ *
+ * @param word - The word.
+ * @param what - What it should be, for the reason.
+ * @returns The word, or why it is not one.
+ */
+function text_read(word, what) {
+    return word === '' ? { ok: false, reason: `an empty word is not ${what}` } : { ok: true, value: word };
+}
+/**
+ * The candidates among some words that start with what was typed.
+ *
+ * @param words - The words.
+ * @param partial - What was typed.
+ * @returns Those that start with it.
+ */
+export function candidates_filter(words, partial) {
+    return words.filter((word) => word.startsWith(partial));
+}
+/** Any word at all. */
+const WORD_KIND = {
+    name: 'word',
+    summary: 'a word',
+    word_read: (word) => ({ ok: true, value: word }),
+    schema_make: () => z.string(),
+};
+/** One of the words an argument lists. */
+const ENUM_KIND = {
+    name: 'enum',
+    summary: 'one of the listed words',
+    word_read: (word, argument) => {
+        const values = argument.values ?? [];
+        return values.includes(word) ? { ok: true, value: word } : { ok: false, reason: `valid: ${values.join(', ')}` };
+    },
+    schema_make: (argument) => z.enum([...(argument.values ?? [])]),
+    words_complete: async (partial, argument) => candidates_filter(argument.values ?? [], partial),
+};
+/** A whole number. */
+const INT_KIND = {
+    name: 'int',
+    summary: 'a whole number',
+    numeric: true,
+    word_read: (word, argument) => INT_WORD.test(word) ? bounds_check(Number(word), argument) : { ok: false, reason: 'not a whole number' },
+    schema_make: (argument) => numberSchema_bound(z.number().int(), argument),
+};
+/** A number, whole or not. */
+const NUMBER_KIND = {
+    name: 'number',
+    summary: 'a number',
+    numeric: true,
+    word_read: (word, argument) => {
+        const value = word.trim() === '' ? Number.NaN : Number(word);
+        return Number.isFinite(value) ? bounds_check(value, argument) : { ok: false, reason: 'not a number' };
+    },
+    schema_make: (argument) => numberSchema_bound(z.number(), argument),
+};
+/** A path in ChRIS's filesystem (CFS), as the session resolves it. */
+const CFS_PATH_KIND = {
+    name: 'cfsPath',
+    summary: "a path in ChRIS's filesystem",
+    path: true,
+    word_read: (word) => text_read(word, 'a path'),
+    schema_make: () => z.string().min(1),
+    words_complete: async (partial) => {
+        const { cfsPaths_complete } = await import('../lib/completer/cfsPaths.js');
+        return cfsPaths_complete(partial);
+    },
+    words_expand: async (words) => {
+        const { shellWords_expand } = await import('../lib/wildcard.js');
+        const { errorStack } = await import('@fnndsc/fond');
+        const expanded = await shellWords_expand(words, () => true);
+        if (expanded.ok)
+            return { ok: true, words: expanded.value };
+        const reason = errorStack.stack_pop()?.message;
+        return { ok: false, reason: reason ?? 'a wildcard could not be expanded' };
+    },
+};
+/**
+ * The folders and files under a host folder that start with a name, for
+ * completion of a host path.
+ *
+ * The disk is loaded when asked, so parsing a line loads no filesystem.
+ *
+ * @param partial - The path typed so far.
+ * @returns The candidates, a folder ending in `/`; none when the folder cannot be read.
+ */
+async function hostPaths_list(partial) {
+    const { readdirSync } = await import('node:fs');
+    const { homedir } = await import('node:os');
+    const expanded = partial.startsWith('~/') ? join(homedir(), partial.slice(2)) : partial;
+    const folder = expanded.endsWith('/') ? expanded : dirname(expanded);
+    const typedFolder = partial.endsWith('/') ? partial : partial.slice(0, partial.lastIndexOf('/') + 1);
+    const prefix = expanded.endsWith('/') ? '' : expanded.slice(expanded.lastIndexOf('/') + 1);
+    let entries = [];
+    try {
+        entries = readdirSync(resolve(folder === '' ? '.' : folder), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.name.startsWith(prefix))
+        .map((entry) => `${typedFolder}${entry.name}${entry.isDirectory() ? '/' : ''}`)
+        .sort();
+}
+/**
+ * A path on the host the operator's surface sits on. It completes from the
+ * engine's own disk only when that disk is the surface's: under a daemon the
+ * engine's disk is a machine nobody at the surface sits at.
+ */
+const HOST_PATH_KIND = {
+    name: 'hostPath',
+    summary: "a path on this machine's filesystem",
+    path: true,
+    word_read: (word) => text_read(word, 'a path'),
+    schema_make: () => z.string().min(1),
+    words_complete: async (partial) => {
+        const { surface_get } = await import('./surface.js');
+        return surface_get().capabilities.engineFilesystem ? hostPaths_list(partial) : [];
+    },
+};
+/** A session variable's name. */
+const VARIABLE_KIND = {
+    name: 'variable',
+    summary: 'a variable name',
+    word_read: (word) => VARIABLE_NAME.test(word) ? { ok: true, value: word } : { ok: false, reason: 'not a variable name' },
+    schema_make: () => z.string().regex(VARIABLE_NAME),
+    words_complete: async (partial) => {
+        const { variables_list } = await import('./variables.js');
+        return candidates_filter(variables_list().map((variable) => variable.name), partial);
+    },
+};
+/** A joblet: `%3`, `3`, or the most recent, `%%`. */
+const JOB_KIND = {
+    name: 'job',
+    summary: 'a job: %N, or %% for the most recent',
+    word_read: (word) => JOB_WORD.test(word) ? { ok: true, value: word } : { ok: false, reason: 'a job is %N, or %% for the most recent' },
+    schema_make: () => z.string().regex(JOB_WORD),
+    words_complete: async (partial) => {
+        const { joblets_running } = await import('./joblets.js');
+        return candidates_filter(joblets_running().map((joblet) => `%${joblet.number}`), partial);
+    },
+};
+/** The core's kinds, by name. */
+const CORE_KINDS = new Map([WORD_KIND, ENUM_KIND, INT_KIND, NUMBER_KIND, CFS_PATH_KIND, HOST_PATH_KIND, VARIABLE_KIND, JOB_KIND]
+    .map((kind) => [kind.name, kind]));
+/**
+ * Finds a kind: the core's, then the installed backend's.
+ *
+ * @param name - The kind's name.
+ * @returns The kind, or null when neither has it.
+ *
+ * @example
+ * ```ts
+ * argumentKind_get('cfsPath')?.path; // true
+ * ```
+ */
+export function argumentKind_get(name) {
+    const core = CORE_KINDS.get(name);
+    if (core !== undefined)
+        return core;
+    return backendInstalled_get()?.argumentKinds?.find((kind) => kind.name === name) ?? null;
+}
+/**
+ * Checks one word against its argument's kind.
+ *
+ * @param argument - The argument's grammar.
+ * @param word - The word.
+ * @returns The value, or why the word is not one (an unregistered kind says so).
+ *
+ * @example
+ * ```ts
+ * argumentWord_check({ kind: 'enum', values: ['a', 'b'] }, 'c'); // { ok: false, reason: 'valid: a, b' }
+ * ```
+ */
+export function argumentWord_check(argument, word) {
+    const kind = argumentKind_get(argument.kind);
+    if (kind === null)
+        return { ok: false, reason: `this session has no argument kind ${argument.kind}` };
+    return kind.word_read(word, argument);
+}
+//# sourceMappingURL=argumentKinds.js.map

package/dist/core/argumentKinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argumentKinds.js","sourceRoot":"","sources":["../../src/core/argumentKinds.ts"],"names":[],"mappings":"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"}

package/dist/core/backend.d.ts

@@ -17,6 +17,7 @@ import type { PromptContext, CubeTelemetry, JobsStateTelemetry, CommandEnvelope,
 import type { ReferenceValue } from '../lib/parser.js';
 import type { ListingLook, VFSDispatcher } from '@fnndsc/fond';
 import type { ListingItem } from '@fnndsc/menu';
+import type { ArgumentKind } from './argumentKinds.js';
 /**
  * Who a session is and where: the input a host keys the session by (calypso's
  * berth name is `user@where`, normalised).
@@ -212,7 +213,7 @@ export interface BackendFilesystem {
      * cleared): a listing that fails says the path was walked as written.
      */
     readonly unreadLinks_take?: () => Promise<string[]>;
-    /** A folder as the filesystem holds it, links followed, for globbing beneath it; absent, the path as given. */
+    /** A store path with the store's own links followed, at any depth (ChRIS: `.chrislink`s); absent, the path as given. `storePath_resolve` asks it for every read and listing, and globbing for a folder. */
     readonly path_physical?: (path: string) => Promise<string>;
     /** Paths that are always folders, entered without asking (beside the mounts and the folders above them). */
     readonly structural?: ReadonlyArray<string>;
@@ -321,6 +322,8 @@ export interface Backend {
     readonly vfs?: BackendFilesystem;
     /** What it adds to completion. */
     readonly completion?: BackendCompletion;
+    /** The argument kinds its commands declare beside the core's (ChRIS: an anchor's name); a kind is found among the core's first. */
+    readonly argumentKinds?: ReadonlyArray<ArgumentKind>;
     /** How its listings show: the kinds it lists beside the core's, and how a name is coloured. */
     readonly listingLook?: ListingLook;
     /** Whether the backend is debugging (error messages keep their function stamp), or null before it can say. */

package/dist/core/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/core/backend.ts"],"names":[],"mappings":"AA4VA,IAAI,SAAS,GAAmB,IAAI,CAAC;AAErC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,SAAS,GAAG,OAAO,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,uFAAuF,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/core/backend.ts"],"names":[],"mappings":"AA+VA,IAAI,SAAS,GAAmB,IAAI,CAAC;AAErC;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,SAAS,GAAG,OAAO,CAAC;AACtB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,uFAAuF,CAAC,CAAC;IAC3G,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/core/commandDeclaration.d.ts

@@ -0,0 +1,363 @@
+/**
+ * @file A command's declaration: its name, the grammar its line is parsed
+ * against, the kind of every argument, its help prose, what it holds of the
+ * session, and its handler, in one record.
+ *
+ * The grammar is the shell's own: subcommands; operands in order, each
+ * optional or repeated; options with a short name, a long name, or both, and
+ * a value or none. Every argument names a kind (`argumentKinds.ts`), which
+ * checks its value and completes it. The handler receives a typed object the
+ * compiler infers from the grammar, written `as const`: its operands, its
+ * options and, for a subcommand, which one. Reading an undeclared option is a
+ * build error, and the handler never sees the words.
+ *
+ * A command whose arguments form an expression language (`find`) declares
+ * `grammar: 'expression'` instead, keeps its own parser and completion, and
+ * receives its words after references expand.
+ *
+ * Key components:
+ * - CommandGrammar: subcommands, operands and options, as a value.
+ * - CommandDeclaration: the whole record for a parsed command.
+ * - ExpressionDeclaration: the record for an expression-grammar command.
+ * - CommandArguments: the typed object a handler receives.
+ * - SubcommandArguments: one subcommand's share of it.
+ * - command_declare: declares a command, inferring its handler's argument.
+ *
+ * Typical usage:
+ * ```ts
+ * const HELLO_GRAMMAR = {
+ *   operands: [{ name: 'who', kind: 'word', optional: true, summary: 'Whom to greet' }],
+ *   options: { loud: { short: 'l', long: 'loud', summary: 'Shout' } },
+ * } as const satisfies CommandGrammar;
+ * export const helloCommand = command_declare({
+ *   name: 'hello',
+ *   grammar: HELLO_GRAMMAR,
+ *   help: { summary: 'Say hello', description: 'Greets someone.' },
+ *   handler: async (args) => envelope_ok(`hello ${args.operands.who ?? 'world'}${args.options.loud ? '!' : ''}\n`),
+ * });
+ * ```
+ *
+ * Dependencies: types only (`@fnndsc/menu` for the envelope, the registry for
+ * session pieces).
+ *
+ * @module
+ */
+import type { CommandEnvelope } from '@fnndsc/menu';
+import type { SessionPiece } from './commandRegistry.js';
+/**
+ * What an argument is: the kind that checks and completes it, and that
+ * kind's parameters.
+ *
+ * @example
+ * ```ts
+ * const sortField: ArgumentGrammar = { kind: 'enum', values: ['name', 'size'] };
+ * ```
+ */
+export interface ArgumentGrammar {
+    /** The kind's name: a core kind (`word`, `enum`, `int`, `number`, `cfsPath`, `hostPath`, `variable`, `job`) or one a backend registers. */
+    readonly kind: string;
+    /** The words an `enum` takes. */
+    readonly values?: readonly string[];
+    /** Pathname expansion for a `cfsPath` or `hostPath` operand: a wildcard in it matches paths. */
+    readonly glob?: boolean;
+    /** The least an `int` or `number` takes. */
+    readonly min?: number;
+    /** The most an `int` or `number` takes. */
+    readonly max?: number;
+}
+/**
+ * One operand: a word that is not an option, in its place on the line.
+ *
+ * @example
+ * ```ts
+ * const paths: OperandGrammar = { name: 'paths', kind: 'cfsPath', optional: true, repeat: true, glob: true, summary: 'What to list' };
+ * ```
+ */
+export interface OperandGrammar extends ArgumentGrammar {
+    /** Its name: the property the handler reads, and the word usage shows (`<path>`). */
+    readonly name: string;
+    /** One line for help and the schema. */
+    readonly summary: string;
+    /** It may be left out. */
+    readonly optional?: boolean;
+    /** It takes every word left over: at most one operand of a grammar repeats. */
+    readonly repeat?: boolean;
+}
+/** An option's value: an argument with the word usage shows for it (`<field>`). */
+export interface OptionValueGrammar extends ArgumentGrammar {
+    /** The word usage shows: `--sort <field>`. */
+    readonly name: string;
+}
+/**
+ * One option: `-l`, `--long`, or both; a switch, or one that takes a value.
+ *
+ * @example
+ * ```ts
+ * const sort: OptionGrammar = { long: 'sort', summary: 'Sort by', value: { name: 'field', kind: 'enum', values: ['name', 'size'] } };
+ * ```
+ */
+export interface OptionGrammar {
+    /** Its one-character name, without the dash. */
+    readonly short?: string;
+    /** Its long name, without the dashes. */
+    readonly long?: string;
+    /** One line for help and the schema. */
+    readonly summary: string;
+    /** What it takes; absent, it is a switch. */
+    readonly value?: OptionValueGrammar;
+    /** A value option given more than once keeps every value; otherwise the last one counts. */
+    readonly repeat?: boolean;
+}
+/** A grammar's options, by the property the handler reads them as. */
+export type OptionsGrammar = {
+    readonly [key: string]: OptionGrammar;
+};
+/**
+ * A subcommand: the word after the command, with operands and options of its
+ * own. The command's own options hold after it too.
+ *
+ * @example
+ * ```ts
+ * const drop: SubcommandGrammar = { summary: 'Remove one anchor', operands: [{ name: 'name', kind: 'word', summary: 'The anchor' }] };
+ * ```
+ */
+export interface SubcommandGrammar {
+    /** One line for help and the schema. */
+    readonly summary: string;
+    /** Its operands, in order. */
+    readonly operands?: readonly OperandGrammar[];
+    /** Its options. */
+    readonly options?: OptionsGrammar;
+}
+/**
+ * A command's grammar: what its line may hold, as a value. Written `as const`,
+ * so the handler's argument is inferred from it.
+ *
+ * @example
+ * ```ts
+ * const grammar = { operands: [{ name: 'path', kind: 'cfsPath', summary: 'Where' }] } as const satisfies CommandGrammar;
+ * ```
+ */
+export interface CommandGrammar {
+    /** Its operands, in order; with subcommands, the words of the bare command. */
+    readonly operands?: readonly OperandGrammar[];
+    /** Its options, which hold after any subcommand too. */
+    readonly options?: OptionsGrammar;
+    /** Its subcommands, by the word that names each. */
+    readonly subcommands?: {
+        readonly [word: string]: SubcommandGrammar;
+    };
+    /** What the command does with no subcommand; absent, a command with subcommands needs one. */
+    readonly bare?: {
+        readonly summary: string;
+    };
+}
+/**
+ * A command's help prose: what `help` shows beside the usage the grammar
+ * generates.
+ *
+ * @example
+ * ```ts
+ * const prose: CommandProse = { summary: 'List directory contents', description: 'Lists…', category: 'Navigation' };
+ * ```
+ */
+export interface CommandProse {
+    /** One line for listings. */
+    readonly summary: string;
+    /** What the command does, as one paragraph. */
+    readonly description: string;
+    /** Lines `help` shows under EXAMPLES; a `#` starts a comment. */
+    readonly examples?: readonly string[];
+    /** Where `help` lists it: one of the help sections. */
+    readonly category?: string;
+    /** It mirrors a Unix utility: the group `help POSIX` lists it under, and how it differs, in a line. */
+    readonly posix?: {
+        readonly group: 'Files' | 'Text' | 'System' | 'Shell';
+        readonly differs: string;
+    };
+}
+/** A kind's value type: a number for `int` and `number`, the declared words for `enum`, else text. */
+type KindValue<A> = A extends {
+    readonly kind: 'int' | 'number';
+} ? number : A extends {
+    readonly kind: 'enum';
+    readonly values: readonly (infer V extends string)[];
+} ? V : string;
+/** An operand's value: a list when it repeats, possibly absent when optional. */
+type OperandValue<O> = O extends {
+    readonly repeat: true;
+} ? KindValue<O>[] : O extends {
+    readonly optional: true;
+} ? KindValue<O> | undefined : KindValue<O>;
+/** The operands a grammar declares, by name. */
+type OperandsOf<G> = G extends {
+    readonly operands: readonly (infer O)[];
+} ? {
+    readonly [P in O as P extends {
+        readonly name: infer N extends string;
+    } ? N : never]: OperandValue<P>;
+} : Record<never, never>;
+/** The names of a grammar's operands that expand pathnames. */
+type GlobNamesOf<G> = G extends {
+    readonly operands: readonly (infer O)[];
+} ? O extends {
+    readonly glob: true;
+    readonly name: infer N extends string;
+} ? N : never : never;
+/** Whether each globbing operand's words came from pathname expansion. */
+type ExpandedOf<G> = {
+    readonly [N in GlobNamesOf<G>]: boolean;
+};
+/** An option's value: a switch is a boolean; a value option its value, or every value when it repeats. */
+type OptionValue<O> = O extends {
+    readonly value: infer V;
+} ? O extends {
+    readonly repeat: true;
+} ? KindValue<V>[] : KindValue<V> | undefined : boolean;
+/** The options a grammar declares, by property. */
+type OptionsOf<G> = G extends {
+    readonly options: infer M;
+} ? {
+    readonly [K in keyof M]: OptionValue<M[K]>;
+} : Record<never, never>;
+/** One parsed line: what a handler reads, for a grammar and the command's own options. */
+interface ParsedLine<S, G> {
+    /** The operands, by name. */
+    readonly operands: OperandsOf<S>;
+    /** The options, by property: the subcommand's and the command's. */
+    readonly options: OptionsOf<S> & OptionsOf<G>;
+    /** For each operand that globs, whether its words came from pathname expansion. */
+    readonly expanded: ExpandedOf<S>;
+}
+/** The bare command's line, when the grammar allows one. */
+type BareLine<G> = G extends {
+    readonly subcommands: object;
+} ? G extends {
+    readonly bare: object;
+} ? {
+    readonly subcommand: null;
+} & ParsedLine<G, G> : never : {
+    readonly subcommand: null;
+} & ParsedLine<G, G>;
+/** Each subcommand's line. */
+type SubcommandLine<G> = G extends {
+    readonly subcommands: infer S;
+} ? {
+    [K in keyof S & string]: {
+        readonly subcommand: K;
+    } & ParsedLine<S[K], G>;
+}[keyof S & string] : never;
+/**
+ * The typed object a handler receives: which subcommand (null for none), its
+ * operands, its options, and which operands came from pathname expansion.
+ *
+ * @example
+ * ```ts
+ * type LsArguments = CommandArguments<typeof LS_GRAMMAR>;
+ * const paths: string[] = (args as LsArguments).operands.paths;
+ * ```
+ */
+export type CommandArguments<G extends CommandGrammar> = BareLine<G> | SubcommandLine<G>;
+/**
+ * One subcommand's share of a handler's argument, for a function that runs it.
+ *
+ * @example
+ * ```ts
+ * function drop_run(args: SubcommandArguments<typeof BERTH_GRAMMAR, 'drop'>): CommandEnvelope { … }
+ * ```
+ */
+export type SubcommandArguments<G extends CommandGrammar, K extends string> = Extract<CommandArguments<G>, {
+    readonly subcommand: K;
+}>;
+/**
+ * A command parsed against its grammar: the one record that is its help,
+ * its completion, its schema and its dispatch.
+ *
+ * @example
+ * ```ts
+ * const declaration: CommandDeclaration<typeof HELLO_GRAMMAR> = helloCommand;
+ * ```
+ */
+export interface CommandDeclaration<G extends CommandGrammar = CommandGrammar> {
+    /** The word that runs it. */
+    readonly name: string;
+    /** What its line may hold. */
+    readonly grammar: G;
+    /** What `help` says of it. */
+    readonly help: CommandProse;
+    /** The pieces of the session it changes while it runs; absent, it holds the whole session. */
+    readonly holds?: readonly SessionPiece[];
+    /**
+     * Runs it, given the line parsed and checked. A method, so a record of one
+     * grammar stands where any declaration is read.
+     *
+     * @param args - The typed line.
+     * @returns Its outcome.
+     */
+    handler(args: CommandArguments<G>): Promise<CommandEnvelope>;
+}
+/**
+ * A command whose arguments are an expression language of its own (`find`):
+ * it parses and completes them itself, under a ratchet.
+ *
+ * @example
+ * ```ts
+ * const findCommand: ExpressionDeclaration = { name: 'find', grammar: 'expression', help, handler: builtin_find };
+ * ```
+ */
+export interface ExpressionDeclaration {
+    /** The word that runs it. */
+    readonly name: string;
+    /** Says it parses its own words. */
+    readonly grammar: 'expression';
+    /** What `help` says of it; its usage is its own. */
+    readonly help: CommandProse & {
+        readonly usage: string;
+    };
+    /** The pieces of the session it changes while it runs. */
+    readonly holds?: readonly SessionPiece[];
+    /**
+     * Runs it over its words, references expanded and nothing globbed.
+     *
+     * @param args - The words after the command.
+     * @returns Its outcome.
+     */
+    handler(args: string[]): Promise<CommandEnvelope>;
+    /**
+     * Completes one word of its line.
+     *
+     * @param words - The words before the one completed.
+     * @param word - The word typed so far.
+     * @returns The candidates.
+     */
+    complete?(words: readonly string[], word: string): Promise<string[]>;
+}
+/** Any declaration the registry holds. */
+export type AnyCommandDeclaration = CommandDeclaration | ExpressionDeclaration;
+/**
+ * Declares a command. Returns its argument unchanged; what it adds is the
+ * inference: the handler's argument is typed from the grammar beside it.
+ *
+ * @param declaration - The record.
+ * @returns The same record.
+ *
+ * @example
+ * ```ts
+ * export const helloCommand = command_declare({ name: 'hello', grammar: HELLO_GRAMMAR, help, handler: async (args) => … });
+ * ```
+ */
+export declare function command_declare<const G extends CommandGrammar>(declaration: CommandDeclaration<G>): CommandDeclaration<G>;
+/**
+ * Whether a declaration parses its line against a grammar (rather than an
+ * expression language of its own).
+ *
+ * @param declaration - The record.
+ * @returns True for a grammar.
+ *
+ * @example
+ * ```ts
+ * if (declaration_isParsed(declaration)) declaration.grammar.operands;
+ * ```
+ */
+export declare function declaration_isParsed(declaration: AnyCommandDeclaration): declaration is CommandDeclaration;
+export {};

package/dist/core/commandDeclaration.js

@@ -0,0 +1,31 @@
+/**
+ * Declares a command. Returns its argument unchanged; what it adds is the
+ * inference: the handler's argument is typed from the grammar beside it.
+ *
+ * @param declaration - The record.
+ * @returns The same record.
+ *
+ * @example
+ * ```ts
+ * export const helloCommand = command_declare({ name: 'hello', grammar: HELLO_GRAMMAR, help, handler: async (args) => … });
+ * ```
+ */
+export function command_declare(declaration) {
+    return declaration;
+}
+/**
+ * Whether a declaration parses its line against a grammar (rather than an
+ * expression language of its own).
+ *
+ * @param declaration - The record.
+ * @returns True for a grammar.
+ *
+ * @example
+ * ```ts
+ * if (declaration_isParsed(declaration)) declaration.grammar.operands;
+ * ```
+ */
+export function declaration_isParsed(declaration) {
+    return declaration.grammar !== 'expression';
+}
+//# sourceMappingURL=commandDeclaration.js.map

package/dist/core/commandDeclaration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandDeclaration.js","sourceRoot":"","sources":["../../src/core/commandDeclaration.ts"],"names":[],"mappings":"AAoUA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAiC,WAAkC;IAChG,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAkC;IACrE,OAAO,WAAW,CAAC,OAAO,KAAK,YAAY,CAAC;AAC9C,CAAC"}