@zhin.js/command 1.1.5 → 1.1.6

package/README.md

@@ -16,7 +16,7 @@ import { defineCommand } from 'zhin.js/command';
 export default defineCommand({
   description: 'List GitHub issues',
   alias: ['issues'],                 // 可多词；owner 不参与用户路由
-  permit: ['adapter(icqq)', 'role(master)'], // 数组 AND；未过则静默未命中
+  permit: ['adapter(icqq)', 'role(master)'], // 数组 AND；失败返回 denied
   // shortcut: { '列 issue': {} },   // 全局整句
   execute: ({ args }) => `issues:${args.join(',')}`,
 });
@@ -27,7 +27,7 @@ export default defineCommand({
 ```text
 commands/gh/pr/[[title]]/index.ts   -> gh pr [title]    （params: { title: { type: 'string', default: 'defaultTitle' } }）
 commands/upload/[asset]/index.ts    -> upload <asset>   （params: { asset: { type: 'image' } }）
-commands/search/[...kw]/index.ts    -> search <...kw>   （params: { kw: { type: 'text' } }，运行时 params.kw 为数组；元素粒度随类型：text 逐消息段，word/string 逐词，number/boolean 逐词转换）
+commands/search/[...kw]/index.ts    -> search <...kw>   （params: { kw: { type: 'text', rest: true } }，运行时 params.kw 为数组；元素粒度随类型：text 逐消息段，word/string 逐词，number/boolean 逐词转换）
 ```
 
 文本类型包括 `string`、`word`、`text`、`number`、`integer`、`float`、`boolean`；结构化
@@ -50,13 +50,58 @@ commands/search/[...kw]/index.ts    -> search <...kw>   （params: { kw: { type:
 可选声明字段：
 
 - `alias`：替换全部本地静态段；owner 不参与用户路由。
-- `permit`：内置 DSL（`adapter|group|private|channel|user|role`）；失败为静默未命中。
+- `permit`：内置 DSL（`adapter|group|private|channel|user|role`）；失败为 denied，委托 PermissionHost。
 - `shortcut`：全局整句精确匹配 → 预填 `params`。
 
 单文件插件可在 `setup({ addCommand })` 中调用
 `addCommand('hello', defineCommand(...))`。它与目录发现共用 CommandIndex；拆成文件后
 可获得单命令 HMR。
 
+
+## 集中声明参数、选项与帮助
+
+目录提供静态命令路径。静态 `commands/remind/index.ts` 可集中声明任意数量的位置参数；
+现有 `commands/foo/[id]/index.ts` 仍绑定同名 `params.id`，后面的参数无需额外动态目录。
+
+```ts
+export default defineCommand({
+  description: '创建提醒',
+  params: {
+    minutes: { type: 'integer', min: 1, max: 1440, description: '分钟数' },
+    note: { type: 'text', default: '休息一下', description: '提醒内容' },
+  },
+  options: {
+    count: { type: 'integer', alias: 'c', default: 1, min: 1, max: 10 },
+    quiet: { type: 'boolean', default: false },
+  },
+  execute: ({ params, options }) => `${params.minutes}:${params.note}:${options.count}`,
+});
+```
+
+`params` 按声明顺序消费输入；参数类型和 `options` 类型自动推导到 `execute`。
+`optional: true` 无默认值时为 `T | undefined`；`rest: true` 为只读数组且必须最后声明。
+`type: 'text'` 保留文本中的引号、空格和换行，消费连续文本；它应放在其他标量参数之后。
+`min` / `max` 表示数值范围或文本长度；`choices`、`pattern` 与同步 `validate(value, session)`
+提供约束。动态默认值与 shortcut 预填也经过同样校验。非法声明在加载前拒绝。
+
+选项支持 `--count 2`、`--count=2`、`-c 2`；布尔 `--quiet` 为 true，
+`--quiet=false` 为 false。选项可在参数之间出现；负数不是选项。`--` 结束选项解析，
+后面的内容作为参数。未知/重复选项拒绝。`remind --help` 从同一声明生成帮助，包含
+Endpoint 前缀及显式插件命名空间，不执行命令；同一权限声明仍约束帮助读取。
+
+`dispatch()` 返回 `status`：`unmatched`（继续普通消息处理）、`invalid`（`issues` +
+`help`）、`denied`（权限拒绝）、`executed`。后三者 `matched: true`，只有 `executed`
+包含业务结果。可靠静态路径匹配后才提示错误；纯动态路由的模糊聊天保持未匹配。
+受限命令没有可鉴权主体时拒绝，Host 可通过 `dispatch` 提供真实 `PermissionSubject`；
+`execute(name)` 无主体不能绕过权限。审批与命令准入独立。
+
+真实消费者：[二维码](../../../plugins/utils/qrcode/README.md)、
+[代码运行](../../../plugins/utils/code-runner/README.md)。
+
+动态目录的路径形态无法被 TypeScript 读取。使用无默认值的 `[[id]]` 时，声明
+`params.id.optional: true`；使用 `[...items]` 时声明 `params.items.rest: true`，
+让执行参数的可选性、数组类型与运行时一致。目录绑定的参数应放在 `params` 第一项。
+
 ## Runtime
 
 definition 在 import 时不注册全局状态。Feature provider 在 generation prepare 阶段完成

package/lib/arguments.d.ts

@@ -0,0 +1,19 @@
+import type { CommandDefinition, CommandParams, CommandOptions, CommandParameterValue, CommandSegment, CommandSession } from './definition.js';
+export interface CommandValidationIssue {
+    readonly field: string;
+    readonly message: string;
+}
+export interface ParsedCommandArguments {
+    readonly params: Readonly<Record<string, CommandParameterValue>>;
+    readonly options: Readonly<Record<string, CommandParameterValue>>;
+    readonly remaining: readonly Readonly<CommandSegment>[];
+    readonly issues: readonly CommandValidationIssue[];
+}
+/** Validate the single declaration used by parsing, help and execution. */
+export declare function validateArgumentSchemas(params?: CommandParams, options?: CommandOptions): void;
+/** Reserved flags use the same quoted-token and option-terminator rules as arguments. */
+export declare function requestsCommandHelp(segments: readonly Readonly<CommandSegment>[]): boolean;
+/** Parse arguments after a route match; the CommandIndex remains the only dispatcher. */
+export declare function parseCommandArguments(definition: CommandDefinition, remaining: readonly Readonly<CommandSegment>[], initial: Readonly<Record<string, CommandParameterValue>>, session: CommandSession): ParsedCommandArguments;
+export declare function commandUsage(name: string, definition: CommandDefinition): string;
+export declare function commandHelp(name: string, definition: CommandDefinition, prefix?: string): string;

package/lib/arguments.js

@@ -0,0 +1,321 @@
+const scalarTypes = new Set(['string', 'word', 'text', 'number', 'integer', 'float', 'boolean']);
+/** Validate the single declaration used by parsing, help and execution. */
+export function validateArgumentSchemas(params, options) {
+    let optional = false;
+    let rest = false;
+    for (const [name, schema] of Object.entries(params ?? {})) {
+        validateSchema(name, schema);
+        if (rest)
+            throw new TypeError('Command rest parameter must be last');
+        if (optional && !schema.optional && schema.default === undefined) {
+            throw new TypeError(`Required Command parameter ${name} cannot follow an optional parameter`);
+        }
+        optional ||= schema.optional === true || schema.default !== undefined;
+        rest = schema.rest === true;
+    }
+    if (options !== undefined && (!options || typeof options !== 'object' || Array.isArray(options))) {
+        throw new TypeError('Command options must be a record');
+    }
+    const aliases = new Set();
+    for (const [name, schema] of Object.entries(options ?? {})) {
+        validateSchema(name, schema);
+        if (!scalarTypes.has(schema.type) || schema.type === 'text') {
+            throw new TypeError(`Command option ${name} requires a scalar type`);
+        }
+        if (name === 'help')
+            throw new TypeError('Command option help is reserved');
+        if (schema.alias !== undefined) {
+            if (!/^[a-zA-Z]$/u.test(schema.alias) || schema.alias === 'h' || aliases.has(schema.alias)) {
+                throw new TypeError(`Invalid or duplicate Command option alias ${schema.alias}`);
+            }
+            aliases.add(schema.alias);
+        }
+    }
+}
+function validateSchema(name, schema) {
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/u.test(name))
+        throw new TypeError(`Invalid Command argument name ${name}`);
+    if (!schema || typeof schema !== 'object')
+        throw new TypeError(`Invalid Command argument ${name}`);
+    if (schema.min !== undefined && !Number.isFinite(schema.min)
+        || schema.max !== undefined && !Number.isFinite(schema.max)
+        || schema.min !== undefined && schema.max !== undefined && schema.min > schema.max) {
+        throw new TypeError(`Invalid Command argument bounds for ${name}`);
+    }
+    if (schema.pattern !== undefined && !(schema.pattern instanceof RegExp)) {
+        throw new TypeError(`Command argument ${name}.pattern must be a RegExp`);
+    }
+    if (schema.validate !== undefined && typeof schema.validate !== 'function') {
+        throw new TypeError(`Command argument ${name}.validate must be a function`);
+    }
+    if (schema.choices !== undefined && !Array.isArray(schema.choices)) {
+        throw new TypeError(`Command argument ${name}.choices must be an array`);
+    }
+    if (schema.default !== undefined && !scalarTypes.has(schema.type))
+        throw new TypeError(`Structured Command argument ${name} cannot declare a default`);
+    if (schema.default !== undefined && typeof schema.default !== 'function') {
+        if (Array.isArray(schema.default) && !schema.rest)
+            throw new TypeError(`Command argument ${name} requires rest: true for an array default`);
+        const values = schema.rest ? schema.default : [schema.default];
+        if (!Array.isArray(values) || values.some((value) => !valueMatches(schema, value))) {
+            throw new TypeError(`Invalid Command argument default for ${name}`);
+        }
+        const defaultSchema = { ...schema, validate: undefined };
+        const issue = validateValue(name, defaultSchema, schema.default, {});
+        if (issue)
+            throw new TypeError(`Invalid Command argument default for ${name}: ${issue.message}`);
+    }
+}
+function isTextToken(value) {
+    return value !== undefined && 'value' in value;
+}
+function tokenize(segments) {
+    return segments.flatMap((segment, segmentIndex) => {
+        if (segment.type !== 'text' || typeof segment.data.text !== 'string')
+            return [segment];
+        const tokens = [];
+        const pattern = /(--?[a-zA-Z][a-zA-Z0-9_-]*=)(?:"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)')|"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|(\S+)/gu;
+        let end = 0;
+        for (const match of segment.data.text.matchAll(pattern)) {
+            const value = match[1] !== undefined ? match[1] + (match[2] ?? match[3] ?? '') : match[4] ?? match[5] ?? match[6] ?? '';
+            tokens.push({ value: value.replace(/\\(["'\\])/gu, '$1'), quoted: match[1] === undefined && match[6] === undefined, raw: match[0], before: segment.data.text.slice(end, match.index), first: tokens.length === 0, segment: segmentIndex });
+            end = (match.index ?? 0) + match[0].length;
+        }
+        const last = tokens.at(-1);
+        if (isTextToken(last))
+            tokens[tokens.length - 1] = { ...last, after: segment.data.text.slice(end) };
+        return tokens;
+    });
+}
+/** Reserved flags use the same quoted-token and option-terminator rules as arguments. */
+export function requestsCommandHelp(segments) {
+    for (const token of tokenize(segments)) {
+        if (!isTextToken(token) || token.quoted)
+            continue;
+        if (token.value === '--')
+            return false;
+        if (token.value === '--help')
+            return true;
+    }
+    return false;
+}
+function segmentsFromTokens(tokens) {
+    const result = [];
+    let lastTextSegment;
+    for (const token of tokens) {
+        if (isTextToken(token)) {
+            const last = result.at(-1);
+            const text = (token.raw ?? token.value) + (token.after ?? '');
+            if (last?.type === 'text' && lastTextSegment === token.segment)
+                result[result.length - 1] = { type: 'text', data: { text: `${last.data.text}${token.before || ' '}${text}` } };
+            else
+                result.push({ type: 'text', data: { text: (token.first ? token.before ?? '' : '') + text } });
+            lastTextSegment = token.segment;
+        }
+        else {
+            result.push(token);
+            lastTextSegment = undefined;
+        }
+    }
+    return Object.freeze(result);
+}
+function convert(schema, token) {
+    if (!token)
+        return undefined;
+    if (isTextToken(token)) {
+        const text = token.value;
+        if (schema.type === 'string' || schema.type === 'word' || schema.type === 'text')
+            return text;
+        if (schema.type === 'boolean')
+            return text === 'true' ? true : text === 'false' ? false : undefined;
+        if (schema.type === 'number' || schema.type === 'integer' || schema.type === 'float') {
+            const value = Number(text);
+            return text !== '' && Number.isFinite(value) && (schema.type !== 'integer' || Number.isInteger(value))
+                && (schema.type !== 'float' || text.includes('.')) ? value : undefined;
+        }
+        return undefined;
+    }
+    const type = typeof token.type === 'string' ? token.type : token.type.name;
+    if (type !== schema.type && !(schema.type === 'mention' && type === 'at'))
+        return undefined;
+    const data = token.data;
+    const value = schema.type === 'image' ? data.media ?? data.file ?? data.url ?? data.src
+        : schema.type === 'mention' ? data.target ?? data.user_id ?? data.qq
+            : schema.type === 'reply' ? data.message_id ?? data.reply_id ?? data.id
+                : schema.type === 'forward' ? data.forward_id ?? data.res_id ?? data.message_id ?? data.id
+                    : schema.type === 'dice' || schema.type === 'rps' ? data.result : data.id;
+    return value;
+}
+function valueMatches(schema, value) {
+    if (schema.type === 'number' || schema.type === 'integer' || schema.type === 'float' || schema.type === 'dice' || schema.type === 'rps') {
+        return typeof value === 'number' && Number.isFinite(value) && (schema.type !== 'integer' || Number.isInteger(value));
+    }
+    if (schema.type === 'mention' || schema.type === 'face' || schema.type === 'reply' || schema.type === 'forward')
+        return typeof value === 'string' || typeof value === 'number' && Number.isFinite(value);
+    if (schema.type === 'boolean')
+        return typeof value === 'boolean';
+    if (schema.type === 'image')
+        return typeof value === 'string' || !!value && typeof value === 'object';
+    return typeof value === 'string';
+}
+function validateValue(field, schema, value, session) {
+    if (schema.rest && !Array.isArray(value))
+        return { field, message: `${field}: expected an array of ${schema.type}` };
+    const values = schema.rest ? (Array.isArray(value) ? value : [value]) : [value];
+    for (const item of values) {
+        if (!valueMatches(schema, item))
+            return { field, message: `${field}: expected ${schema.type}` };
+        const size = typeof item === 'number' ? item : typeof item === 'string' ? item.length : undefined;
+        if (schema.min !== undefined && (size === undefined || size < schema.min))
+            return { field, message: `${field}: minimum ${schema.min}` };
+        if (schema.max !== undefined && (size === undefined || size > schema.max))
+            return { field, message: `${field}: maximum ${schema.max}` };
+        if (schema.choices && !schema.choices.includes(item))
+            return { field, message: `${field}: expected one of ${schema.choices.join(', ')}` };
+        if (schema.pattern) {
+            const pattern = new RegExp(schema.pattern.source, schema.pattern.flags.replace(/[gy]/gu, ''));
+            if (typeof item !== 'string' || !pattern.test(item))
+                return { field, message: `${field}: invalid format` };
+        }
+    }
+    const result = schema.validate?.(value, session);
+    return result === false || typeof result === 'string' ? { field, message: typeof result === 'string' ? result : `${field}: invalid value` } : undefined;
+}
+/** Parse arguments after a route match; the CommandIndex remains the only dispatcher. */
+export function parseCommandArguments(definition, remaining, initial, session) {
+    const params = { __proto__: null, ...initial };
+    const options = { __proto__: null };
+    const issues = [];
+    const tokens = tokenize(remaining);
+    const positional = [];
+    const schemas = definition.options ?? (definition.params === undefined ? undefined : {});
+    const optionNames = new Map(Object.entries(schemas ?? {}).flatMap(([name, schema]) => [[`--${name}`, name], ...(schema.alias ? [[`-${schema.alias}`, name]] : [])]));
+    let terminated = false;
+    for (let index = 0; index < tokens.length; index++) {
+        const token = tokens[index];
+        if (!token)
+            continue;
+        if (!isTextToken(token) || token.quoted || terminated || schemas === undefined) {
+            positional.push(token);
+            continue;
+        }
+        if (token.value === '--') {
+            terminated = true;
+            continue;
+        }
+        if (!/^--?[a-zA-Z]/u.test(token.value)) {
+            positional.push(token);
+            continue;
+        }
+        const [rawFlag, inline] = token.value.split(/=(.*)/u);
+        const flag = rawFlag ?? token.value;
+        const name = optionNames.get(flag);
+        if (!name) {
+            issues.push({ field: flag, message: `Unknown option ${flag}` });
+            continue;
+        }
+        const schema = schemas[name];
+        if (!schema)
+            continue;
+        if (Object.hasOwn(options, name)) {
+            issues.push({ field: name, message: `Duplicate option --${name}` });
+            continue;
+        }
+        let value;
+        if (inline !== undefined)
+            value = convert(schema, { value: inline, quoted: false });
+        else if (schema.type === 'boolean')
+            value = true;
+        else {
+            const next = tokens[index + 1];
+            if (isTextToken(next) && !(!next.quoted && /^--?[a-zA-Z]/u.test(next.value))) {
+                index++;
+                value = convert(schema, next);
+            }
+        }
+        if (value === undefined)
+            issues.push({ field: name, message: `--${name}: expected ${schema.type}` });
+        else
+            options[name] = value;
+    }
+    for (const [name, schema] of Object.entries(schemas ?? {})) {
+        if (!Object.hasOwn(options, name) && schema.default !== undefined)
+            options[name] = typeof schema.default === 'function' ? schema.default(session) : schema.default;
+        if (Object.hasOwn(options, name) && options[name] === undefined)
+            issues.push({ field: name, message: `--${name}: default returned undefined` });
+        else if (options[name] !== undefined) {
+            const issue = validateValue(`--${name}`, schema, options[name], session);
+            if (issue)
+                issues.push(issue);
+        }
+        else if (schema.optional === false)
+            issues.push({ field: name, message: `Missing option --${name}` });
+    }
+    const declared = Object.entries(definition.params ?? {});
+    for (const [name, declaredSchema] of declared) {
+        const schema = definition.$parameter?.name === name ? { ...declaredSchema, optional: definition.$parameter.optional ?? declaredSchema.optional, rest: definition.$parameter.rest ?? declaredSchema.rest } : declaredSchema;
+        if (!Object.hasOwn(params, name)) {
+            let value;
+            if (schema.rest) {
+                const raw = positional.splice(0);
+                const converted = schema.type === 'text'
+                    ? segmentsFromTokens(raw).map((segment) => segment.type === 'text' && typeof segment.data.text === 'string' ? segment.data.text : undefined)
+                    : raw.map((token) => convert(schema, token));
+                if (converted.some((item) => item === undefined))
+                    issues.push({ field: name, message: `${name}: expected ${schema.type}` });
+                else if (converted.length > 0 || schema.optional)
+                    value = converted;
+            }
+            else if (schema.type === 'text') {
+                const raw = [];
+                while (isTextToken(positional[0])) {
+                    const token = positional.shift();
+                    raw.push(`${raw.length > 0 ? token.before || ' ' : ''}${token.raw ?? token.value}${token.after ?? ''}`);
+                }
+                if (raw.length > 0)
+                    value = raw.join('');
+            }
+            else if (positional.length > 0) {
+                value = convert(schema, positional.shift());
+                // Defaults apply to omitted input, never to a supplied value of the wrong type.
+                if (value === undefined) {
+                    issues.push({ field: name, message: `${name}: expected ${schema.type}` });
+                    continue;
+                }
+            }
+            if (value !== undefined)
+                params[name] = value;
+            else if (schema.default !== undefined)
+                params[name] = typeof schema.default === 'function' ? schema.default(session) : schema.default;
+            else if (!schema.optional && !(definition.$parameter?.name === name && definition.$parameter.optional)) {
+                issues.push({ field: name, message: `${name}: expected ${schema.type}` });
+            }
+        }
+        if (Object.hasOwn(params, name) && params[name] === undefined)
+            issues.push({ field: name, message: `${name}: default or shortcut returned undefined` });
+        else if (params[name] !== undefined) {
+            const effective = definition.$parameter?.name === name && definition.$parameter.rest ? { ...schema, rest: true } : schema;
+            const issue = validateValue(name, effective, params[name], session);
+            if (issue)
+                issues.push(issue);
+        }
+    }
+    if (declared.length > 0 && !definition.$parameter && positional.length > 0)
+        issues.push({ field: 'arguments', message: 'Unexpected arguments' });
+    return Object.freeze({ params: Object.freeze(params), options: Object.freeze(options), remaining: schemas === undefined && declared.every(([name]) => Object.hasOwn(initial, name)) ? remaining : segmentsFromTokens(positional), issues: Object.freeze(issues) });
+}
+export function commandUsage(name, definition) {
+    const parameters = Object.entries(definition.params ?? {}).filter(([key]) => key !== definition.$parameter?.name)
+        .map(([key, schema]) => `${schema.optional || schema.default !== undefined ? '[' : '<'}${schema.rest ? '...' : ''}${key}${schema.optional || schema.default !== undefined ? ']' : '>'}`);
+    const options = Object.entries(definition.options ?? {}).map(([key, schema]) => `[--${key}${schema.type === 'boolean' ? '' : ` <${schema.type}>`}]`);
+    return [name, ...parameters, ...options].join(' ');
+}
+export function commandHelp(name, definition, prefix = '') {
+    return [prefix + commandUsage(name, definition), definition.description,
+        ...Object.entries(definition.params ?? {}).map(([key, schema]) => argumentHelp(key, schema)),
+        ...Object.entries(definition.options ?? {}).map(([key, schema]) => argumentHelp(`--${key}${schema.alias ? ` (-${schema.alias})` : ''}`, schema)),
+    ].filter(Boolean).join('\n');
+}
+function argumentHelp(name, schema) {
+    return `  ${name}: ${schema.type}${schema.description ? ` — ${schema.description}` : ''}${schema.default !== undefined ? ` (default: ${typeof schema.default === 'function' ? 'dynamic' : JSON.stringify(schema.default)})` : ''}${schema.choices ? ` (${schema.choices.join(', ')})` : ''}${schema.min !== undefined ? ` min=${schema.min}` : ''}${schema.max !== undefined ? ` max=${schema.max}` : ''}`;
+}

package/lib/command-index.d.ts

@@ -1,5 +1,6 @@
 import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { UserInteractionFactory } from '@zhin.js/interaction';
+import { type CommandValidationIssue } from './arguments.js';
 import { type CommandDefinition, type CommandParameterDefinition, type CommandParameterType, type CommandSegment } from './definition.js';
 export interface CommandParameterDescriptor extends CommandParameterDefinition {
     readonly required: boolean;
@@ -10,6 +11,8 @@ export interface CommandDescriptor {
     readonly adapter?: string;
     readonly source: string;
     readonly parameters: readonly CommandParameterDescriptor[];
+    readonly usage: string;
+    readonly options: NonNullable<CommandDefinition['options']>;
     readonly alias?: readonly string[];
     readonly permit?: readonly string[];
     /** shortcut 触发键列表（不含预填 params）。 */
@@ -17,6 +20,9 @@ export interface CommandDescriptor {
 }
 export interface CommandDispatchResult {
     readonly matched: boolean;
+    readonly status: 'unmatched' | 'invalid' | 'denied' | 'executed';
+    readonly issues?: readonly CommandValidationIssue[];
+    readonly help?: string;
     readonly command?: string;
     readonly owner?: PluginId;
     readonly value?: unknown;
@@ -39,3 +45,8 @@ export declare function isCommandIndex(value: unknown): value is CommandIndex;
 export declare class CommandParameterValueError extends TypeError {
     constructor(name: string, type: CommandParameterType, value: string);
 }
+export declare class CommandArgumentValidationError extends TypeError {
+    readonly issues: readonly CommandValidationIssue[];
+    readonly help: string;
+    constructor(issues: readonly CommandValidationIssue[], help: string);
+}