@zhin.js/command 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @zhin.js/command
+
+Zhin Plugin Runtime 的 Command Feature。它把 `commands/**/*.ts` 的目录层级映射为命令
+路径，并支持 `[name:type=default]` 参数文件名、owner-scoped Config/Resource 与确定性匹配。
+
+```ts
+import { defineCommand } from '@zhin.js/command';
+
+export default defineCommand({
+  description: 'Show runtime status',
+  execute: ({ args }) => args.join(' '),
+});
+```
+
+definition 在 import 时不注册全局状态；Feature provider 在 generation prepare 阶段发现、
+校验并投影 `CommandIndex`。生产 manifest 指向 `lib/provider.js`。
+
+验证：`pnpm --filter @zhin.js/command test && pnpm --filter @zhin.js/command build`。
+
+命令目录契约见 [Plugin Runtime 原位迁移](../../../docs/architecture/target-implementation/in-place-migration.md)。

package/lib/command-index.d.ts

@@ -0,0 +1,31 @@
+import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type CommandDefinition, type CommandParameterDefinition, type CommandParameterType } from './definition.js';
+export interface CommandParameterDescriptor extends CommandParameterDefinition {
+    readonly required: boolean;
+}
+export interface CommandDescriptor {
+    readonly name: string;
+    readonly description?: string;
+    readonly source: string;
+    readonly parameters: readonly CommandParameterDescriptor[];
+}
+export interface CommandDispatchResult {
+    readonly matched: boolean;
+    readonly command?: string;
+    readonly owner?: PluginId;
+    readonly value?: unknown;
+}
+export declare class CommandIndex {
+    #private;
+    private readonly snapshot;
+    readonly $projection: "zhin.command-index/1";
+    constructor(slots: readonly Readonly<CapabilitySlot<CommandDefinition>>[], snapshot: RuntimeSnapshot);
+    list(): readonly CommandDescriptor[];
+    has(name: string): boolean;
+    execute(name: string, args?: readonly string[]): Promise<unknown>;
+    dispatch(input: string, source?: unknown): Promise<CommandDispatchResult>;
+}
+export declare function isCommandIndex(value: unknown): value is CommandIndex;
+export declare class CommandParameterValueError extends TypeError {
+    constructor(name: string, type: CommandParameterType, value: string);
+}

package/lib/command-index.js

@@ -0,0 +1,167 @@
+import { createCommandContext, } from './definition.js';
+export class CommandIndex {
+    snapshot;
+    $projection = 'zhin.command-index/1';
+    #commands;
+    #staticCommands = new Map();
+    #dynamicCommands = new Map();
+    constructor(slots, snapshot) {
+        this.snapshot = snapshot;
+        const commands = [];
+        for (const slot of slots) {
+            const segments = runtimeSegments(slot.owner, slot.localName);
+            const parameter = slot.definition.$parameter;
+            assertParameterSegment(segments, parameter, slot.source);
+            const name = displayName(segments, parameter);
+            const record = Object.freeze({
+                name,
+                description: slot.definition.description,
+                source: slot.source,
+                parameters: Object.freeze(parameter ? [{
+                        ...parameter,
+                        required: parameter.defaultValue === undefined,
+                    }] : []),
+                slot,
+                segments: Object.freeze(segments),
+                parameter,
+            });
+            if (!parameter) {
+                const key = segments.join(' ');
+                if (this.#staticCommands.has(key))
+                    throw duplicateCommand(key);
+                this.#staticCommands.set(key, record);
+            }
+            else {
+                const shape = routeShape(segments);
+                if (this.#dynamicCommands.has(shape))
+                    throw duplicateCommand(name);
+                this.#dynamicCommands.set(shape, record);
+            }
+            commands.push(record);
+        }
+        this.#commands = Object.freeze(commands);
+    }
+    list() {
+        return this.#commands.map(toDescriptor);
+    }
+    has(name) {
+        try {
+            return this.#match(name) !== undefined;
+        }
+        catch (error) {
+            if (error instanceof CommandParameterValueError)
+                return false;
+            throw error;
+        }
+    }
+    async execute(name, args = []) {
+        const match = this.#match(name);
+        if (!match)
+            throw new Error(`Unknown Command: ${name}`);
+        return match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, match.params));
+    }
+    async dispatch(input, source = undefined) {
+        const words = splitCommand(input);
+        for (let consumed = words.length; consumed > 0; consumed -= 1) {
+            const match = this.#match(words.slice(0, consumed).join(' '));
+            if (!match)
+                continue;
+            const args = words.slice(consumed);
+            const value = await match.command.slot.definition.execute(createCommandContext(this.snapshot, match.command.slot.owner, args, match.params, source));
+            return Object.freeze({
+                matched: true,
+                command: match.command.name,
+                owner: match.command.slot.owner,
+                value,
+            });
+        }
+        return Object.freeze({ matched: false });
+    }
+    #match(name) {
+        const words = splitCommand(name);
+        // A literal file such as list.ts always wins over [name:string].ts.
+        const staticCommand = this.#staticCommands.get(words.join(' '));
+        if (staticCommand)
+            return { command: staticCommand, params: Object.freeze({}) };
+        for (const command of this.#dynamicCommands.values()) {
+            const parameter = command.parameter;
+            const optional = parameter.defaultValue !== undefined;
+            if (words.length !== command.segments.length &&
+                !(optional && words.length === command.segments.length - 1))
+                continue;
+            const parameterIndex = command.segments.findIndex((segment) => segment.startsWith('$'));
+            if (!command.segments.every((segment, index) => index === parameterIndex || segment === words[index]))
+                continue;
+            const rawValue = words[parameterIndex];
+            const value = rawValue === undefined
+                ? parameter.defaultValue
+                : parseRuntimeValue(parameter, rawValue);
+            return {
+                command,
+                params: Object.freeze({ [parameter.name]: value }),
+            };
+        }
+        return undefined;
+    }
+}
+export function isCommandIndex(value) {
+    return !!value && typeof value === 'object'
+        && value.$projection === 'zhin.command-index/1';
+}
+function runtimeSegments(owner, localName) {
+    const ownerSegments = owner === 'root'
+        ? []
+        : owner.slice('root/'.length).split('/');
+    return [...ownerSegments, ...localName.split('/')];
+}
+function assertParameterSegment(segments, parameter, source) {
+    const dynamicSegments = segments.filter((segment) => segment.startsWith('$'));
+    if (!parameter && dynamicSegments.length === 0)
+        return;
+    if (parameter && dynamicSegments.length === 1 &&
+        dynamicSegments[0] === `$${parameter.name}` &&
+        segments.at(-1) === dynamicSegments[0])
+        return;
+    throw new Error(`Broken dynamic Command identity for ${source}`);
+}
+function displayName(segments, parameter) {
+    return segments.map((segment) => {
+        if (!segment.startsWith('$'))
+            return segment;
+        return parameter?.defaultValue === undefined
+            ? `<${segment.slice(1)}>`
+            : `[${segment.slice(1)}]`;
+    }).join(' ');
+}
+function routeShape(segments) {
+    return segments.map((segment) => segment.startsWith('$') ? '$' : segment).join(' ');
+}
+function splitCommand(value) {
+    const normalized = value.trim();
+    return normalized ? normalized.split(/\s+/) : [];
+}
+function parseRuntimeValue(parameter, value) {
+    if (parameter.type === 'string')
+        return value;
+    if (parameter.type === 'number') {
+        const number = Number(value);
+        if (value.trim().length > 0 && Number.isFinite(number))
+            return number;
+    }
+    else if (value === 'true' || value === 'false') {
+        return value === 'true';
+    }
+    throw new CommandParameterValueError(parameter.name, parameter.type, value);
+}
+function toDescriptor({ slot: _slot, segments: _segments, parameter: _parameter, ...descriptor }) {
+    return descriptor;
+}
+function duplicateCommand(name) {
+    return new Error(`Duplicate runtime Command: ${name}`);
+}
+export class CommandParameterValueError extends TypeError {
+    constructor(name, type, value) {
+        super(`Invalid value for Command parameter ${name}:${type}: ${value}`);
+        this.name = 'CommandParameterValueError';
+    }
+}

package/lib/definition.d.ts

@@ -0,0 +1,26 @@
+import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type CapabilityContext } from '@zhin.js/feature-kit';
+declare const commandBrand: "zhin.command/1";
+export type CommandParameterType = 'string' | 'number' | 'boolean';
+export type CommandParameterValue = string | number | boolean;
+export interface CommandParameterDefinition {
+    readonly name: string;
+    readonly type: CommandParameterType;
+    readonly defaultValue?: CommandParameterValue;
+}
+export interface CommandContext<TConfig = unknown, TInput = unknown> extends CapabilityContext<TConfig> {
+    readonly args: readonly string[];
+    readonly params: Readonly<Record<string, CommandParameterValue>>;
+    readonly input: TInput;
+}
+export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput = unknown> {
+    readonly $feature: typeof commandBrand;
+    readonly $parameter?: CommandParameterDefinition;
+    readonly description?: string;
+    execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
+}
+export declare function defineCommand<TConfig = unknown, TResult = unknown, TInput = unknown>(definition: Omit<CommandDefinition<TConfig, TResult, TInput>, '$feature' | '$parameter'>): Readonly<CommandDefinition<TConfig, TResult, TInput>>;
+export declare function bindCommandParameter<TConfig, TResult, TInput>(definition: CommandDefinition<TConfig, TResult, TInput>, parameter: CommandParameterDefinition | undefined): Readonly<CommandDefinition<TConfig, TResult, TInput>>;
+export declare function parseCommandDefinition(value: unknown): CommandDefinition;
+export declare function createCommandContext(snapshot: RuntimeSnapshot, ownerId: PluginId, args: readonly string[], params?: Readonly<Record<string, CommandParameterValue>>, input?: unknown): CommandContext;
+export {};

package/lib/definition.js

@@ -0,0 +1,32 @@
+import { createCapabilityContext, } from '@zhin.js/feature-kit';
+const commandBrand = 'zhin.command/1';
+export function defineCommand(definition) {
+    if (typeof definition.execute !== 'function') {
+        throw new TypeError('Command execute must be a function');
+    }
+    return Object.freeze({ $feature: commandBrand, ...definition });
+}
+export function bindCommandParameter(definition, parameter) {
+    if (!parameter)
+        return definition;
+    return Object.freeze({ ...definition, $parameter: Object.freeze({ ...parameter }) });
+}
+export function parseCommandDefinition(value) {
+    if (!value || typeof value !== 'object') {
+        throw new TypeError('Command module must default-export defineCommand(...)');
+    }
+    const definition = value;
+    if (definition.$feature !== commandBrand || typeof definition.execute !== 'function') {
+        throw new TypeError('Command module must default-export defineCommand(...)');
+    }
+    return definition;
+}
+export function createCommandContext(snapshot, ownerId, args, params = Object.freeze({}), input = undefined) {
+    const context = createCapabilityContext(snapshot, ownerId);
+    return Object.freeze({
+        ...context,
+        args: Object.freeze([...args]),
+        params: Object.freeze({ ...params }),
+        input,
+    });
+}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from './command-index.js';
+export * from './definition.js';
+export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
+export { default } from './provider.js';

package/lib/index.js

@@ -0,0 +1,4 @@
+export * from './command-index.js';
+export * from './definition.js';
+export { CommandPathSyntaxError, commandFeatureId, default as commandFeature, } from './provider.js';
+export { default } from './provider.js';

package/lib/provider.d.ts

@@ -0,0 +1,7 @@
+import { CommandIndex } from './command-index.js';
+export declare const commandFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
+export declare class CommandPathSyntaxError extends TypeError {
+    constructor(file: string, detail?: string);
+}
+declare const commandFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").CommandDefinition<unknown, unknown, unknown>, CommandIndex>>;
+export default commandFeature;

package/lib/provider.js

@@ -0,0 +1,94 @@
+import { basename, join, parse } from 'node:path';
+import { featureId } from '@zhin.js/plugin-runtime';
+import { defineFeatureProvider, } from '@zhin.js/feature-kit';
+import { CommandIndex } from './command-index.js';
+import { bindCommandParameter, parseCommandDefinition, } from './definition.js';
+export const commandFeatureId = featureId('zhin.command');
+const commandFiles = {
+    id: 'commands-ts',
+    async *discover(context) {
+        const directory = join(context.packageRoot, 'commands');
+        yield* discoverCommandDirectory(context, directory, []);
+    },
+    async load(source, context) {
+        const module = await context.host.loadModule(source.source);
+        const definition = parseCommandDefinition(module.default);
+        const file = parseCommandFile(basename(source.source));
+        return bindCommandParameter(definition, file?.parameter);
+    },
+};
+async function* discoverCommandDirectory(context, directory, ancestors) {
+    const entries = [...await context.host.list(directory)]
+        .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const entry of entries) {
+        if (entry.kind === 'directory' && isCommandSegment(entry.name)) {
+            yield* discoverCommandDirectory(context, join(directory, entry.name), [...ancestors, entry.name]);
+            continue;
+        }
+        if (entry.kind !== 'file')
+            continue;
+        const file = parseCommandFile(entry.name);
+        if (!file)
+            continue;
+        yield {
+            localName: [...ancestors, file.localSegment].join('/'),
+            source: join(directory, entry.name),
+            target: 'server',
+        };
+    }
+}
+function isCommandSegment(value) {
+    return /^[a-z0-9][a-z0-9-]*$/.test(value);
+}
+const dynamicCommandFilePattern = /^\[([a-z][a-zA-Z0-9]*):(string|number|boolean)(?:=([^\]]*))?\]\.tsx?$/;
+function parseCommandFile(value) {
+    if (/^[a-z0-9][a-z0-9-]*\.tsx?$/.test(value)) {
+        return { localSegment: parse(value).name };
+    }
+    const match = dynamicCommandFilePattern.exec(value);
+    if (match) {
+        const [, name, type, rawDefault] = match;
+        // Metadata can change during HMR while $name keeps the Capability identity stable.
+        const parameter = rawDefault === undefined
+            ? { name, type }
+            : { name, type, defaultValue: parseParameterValue(name, type, rawDefault, value) };
+        return { localSegment: `$${name}`, parameter };
+    }
+    if (value.startsWith('[') || value.includes(']')) {
+        throw new CommandPathSyntaxError(value);
+    }
+    return undefined;
+}
+function parseParameterValue(name, type, value, source) {
+    if (type === 'string')
+        return value;
+    if (type === 'number') {
+        const number = Number(value);
+        if (value.trim().length > 0 && Number.isFinite(number))
+            return number;
+    }
+    else if (value === 'true' || value === 'false') {
+        return value === 'true';
+    }
+    throw new CommandPathSyntaxError(source, `default for ${name}:${type} is invalid`);
+}
+export class CommandPathSyntaxError extends TypeError {
+    constructor(file, detail = 'expected [name:string|number|boolean=default].ts(x)') {
+        super(`Invalid Command path ${file}: ${detail}`);
+        this.name = 'CommandPathSyntaxError';
+    }
+}
+const commandFeature = defineFeatureProvider({
+    protocol: 1,
+    id: commandFeatureId,
+    authoring: {
+        conventions: [commandFiles],
+        validate: parseCommandDefinition,
+    },
+    runtime: {
+        project(slots, context) {
+            return { value: new CommandIndex(slots, context.snapshot) };
+        },
+    },
+});
+export default commandFeature;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@zhin.js/command",
+  "version": "1.0.0",
+  "description": "Convention-based Command Feature for Zhin Plugin Runtime",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@zhin.js/feature-kit": "1.0.0",
+    "@zhin.js/plugin-runtime": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "feature",
+    "entry": "./lib/provider.js",
+    "engine": "^1.0.0",
+    "featureApi": "1.0.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/command"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/command/tests"
+  }
+}

package/src/command-index.ts

@@ -0,0 +1,241 @@
+import type {
+  CapabilitySlot,
+  PluginId,
+  RuntimeSnapshot,
+} from '@zhin.js/plugin-runtime';
+import {
+  createCommandContext,
+  type CommandDefinition,
+  type CommandParameterDefinition,
+  type CommandParameterType,
+  type CommandParameterValue,
+} from './definition.js';
+
+export interface CommandParameterDescriptor extends CommandParameterDefinition {
+  readonly required: boolean;
+}
+
+export interface CommandDescriptor {
+  readonly name: string;
+  readonly description?: string;
+  readonly source: string;
+  readonly parameters: readonly CommandParameterDescriptor[];
+}
+
+export interface CommandDispatchResult {
+  readonly matched: boolean;
+  readonly command?: string;
+  readonly owner?: PluginId;
+  readonly value?: unknown;
+}
+
+interface CommandRecord extends CommandDescriptor {
+  readonly slot: Readonly<CapabilitySlot<CommandDefinition>>;
+  readonly segments: readonly string[];
+  readonly parameter?: CommandParameterDefinition;
+}
+
+interface CommandMatch {
+  readonly command: CommandRecord;
+  readonly params: Readonly<Record<string, CommandParameterValue>>;
+}
+
+export class CommandIndex {
+  readonly $projection = 'zhin.command-index/1' as const;
+  readonly #commands: readonly CommandRecord[];
+  readonly #staticCommands = new Map<string, CommandRecord>();
+  readonly #dynamicCommands = new Map<string, CommandRecord>();
+
+  constructor(
+    slots: readonly Readonly<CapabilitySlot<CommandDefinition>>[],
+    private readonly snapshot: RuntimeSnapshot,
+  ) {
+    const commands: CommandRecord[] = [];
+    for (const slot of slots) {
+      const segments = runtimeSegments(slot.owner, slot.localName);
+      const parameter = slot.definition.$parameter;
+      assertParameterSegment(segments, parameter, slot.source);
+      const name = displayName(segments, parameter);
+      const record = Object.freeze({
+        name,
+        description: slot.definition.description,
+        source: slot.source,
+        parameters: Object.freeze(parameter ? [{
+          ...parameter,
+          required: parameter.defaultValue === undefined,
+        }] : []),
+        slot,
+        segments: Object.freeze(segments),
+        parameter,
+      });
+      if (!parameter) {
+        const key = segments.join(' ');
+        if (this.#staticCommands.has(key)) throw duplicateCommand(key);
+        this.#staticCommands.set(key, record);
+      } else {
+        const shape = routeShape(segments);
+        if (this.#dynamicCommands.has(shape)) throw duplicateCommand(name);
+        this.#dynamicCommands.set(shape, record);
+      }
+      commands.push(record);
+    }
+    this.#commands = Object.freeze(commands);
+  }
+
+  list(): readonly CommandDescriptor[] {
+    return this.#commands.map(toDescriptor);
+  }
+
+  has(name: string): boolean {
+    try {
+      return this.#match(name) !== undefined;
+    } catch (error) {
+      if (error instanceof CommandParameterValueError) return false;
+      throw error;
+    }
+  }
+
+  async execute(name: string, args: readonly string[] = []): Promise<unknown> {
+    const match = this.#match(name);
+    if (!match) throw new Error(`Unknown Command: ${name}`);
+    return match.command.slot.definition.execute(
+      createCommandContext(
+        this.snapshot,
+        match.command.slot.owner,
+        args,
+        match.params,
+      ),
+    );
+  }
+
+  async dispatch(input: string, source: unknown = undefined): Promise<CommandDispatchResult> {
+    const words = splitCommand(input);
+    for (let consumed = words.length; consumed > 0; consumed -= 1) {
+      const match = this.#match(words.slice(0, consumed).join(' '));
+      if (!match) continue;
+      const args = words.slice(consumed);
+      const value = await match.command.slot.definition.execute(
+        createCommandContext(
+          this.snapshot,
+          match.command.slot.owner,
+          args,
+          match.params,
+          source,
+        ),
+      );
+      return Object.freeze({
+        matched: true,
+        command: match.command.name,
+        owner: match.command.slot.owner,
+        value,
+      });
+    }
+    return Object.freeze({ matched: false });
+  }
+
+  #match(name: string): CommandMatch | undefined {
+    const words = splitCommand(name);
+    // A literal file such as list.ts always wins over [name:string].ts.
+    const staticCommand = this.#staticCommands.get(words.join(' '));
+    if (staticCommand) return { command: staticCommand, params: Object.freeze({}) };
+
+    for (const command of this.#dynamicCommands.values()) {
+      const parameter = command.parameter as CommandParameterDefinition;
+      const optional = parameter.defaultValue !== undefined;
+      if (words.length !== command.segments.length &&
+        !(optional && words.length === command.segments.length - 1)) continue;
+      const parameterIndex = command.segments.findIndex((segment) => segment.startsWith('$'));
+      if (!command.segments.every((segment, index) =>
+        index === parameterIndex || segment === words[index])) continue;
+      const rawValue = words[parameterIndex];
+      const value = rawValue === undefined
+        ? parameter.defaultValue as CommandParameterValue
+        : parseRuntimeValue(parameter, rawValue);
+      return {
+        command,
+        params: Object.freeze({ [parameter.name]: value }),
+      };
+    }
+    return undefined;
+  }
+}
+
+export function isCommandIndex(value: unknown): value is CommandIndex {
+  return !!value && typeof value === 'object'
+    && (value as { readonly $projection?: unknown }).$projection === 'zhin.command-index/1';
+}
+
+function runtimeSegments(owner: string, localName: string): string[] {
+  const ownerSegments = owner === 'root'
+    ? []
+    : owner.slice('root/'.length).split('/');
+  return [...ownerSegments, ...localName.split('/')];
+}
+
+function assertParameterSegment(
+  segments: readonly string[],
+  parameter: CommandParameterDefinition | undefined,
+  source: string,
+): void {
+  const dynamicSegments = segments.filter((segment) => segment.startsWith('$'));
+  if (!parameter && dynamicSegments.length === 0) return;
+  if (parameter && dynamicSegments.length === 1 &&
+    dynamicSegments[0] === `$${parameter.name}` &&
+    segments.at(-1) === dynamicSegments[0]) return;
+  throw new Error(`Broken dynamic Command identity for ${source}`);
+}
+
+function displayName(
+  segments: readonly string[],
+  parameter: CommandParameterDefinition | undefined,
+): string {
+  return segments.map((segment) => {
+    if (!segment.startsWith('$')) return segment;
+    return parameter?.defaultValue === undefined
+      ? `<${segment.slice(1)}>`
+      : `[${segment.slice(1)}]`;
+  }).join(' ');
+}
+
+function routeShape(segments: readonly string[]): string {
+  return segments.map((segment) => segment.startsWith('$') ? '$' : segment).join(' ');
+}
+
+function splitCommand(value: string): readonly string[] {
+  const normalized = value.trim();
+  return normalized ? normalized.split(/\s+/) : [];
+}
+
+function parseRuntimeValue(
+  parameter: CommandParameterDefinition,
+  value: string,
+): CommandParameterValue {
+  if (parameter.type === 'string') return value;
+  if (parameter.type === 'number') {
+    const number = Number(value);
+    if (value.trim().length > 0 && Number.isFinite(number)) return number;
+  } else if (value === 'true' || value === 'false') {
+    return value === 'true';
+  }
+  throw new CommandParameterValueError(parameter.name, parameter.type, value);
+}
+
+function toDescriptor({
+  slot: _slot,
+  segments: _segments,
+  parameter: _parameter,
+  ...descriptor
+}: CommandRecord): CommandDescriptor {
+  return descriptor;
+}
+
+function duplicateCommand(name: string): Error {
+  return new Error(`Duplicate runtime Command: ${name}`);
+}
+
+export class CommandParameterValueError extends TypeError {
+  constructor(name: string, type: CommandParameterType, value: string) {
+    super(`Invalid value for Command parameter ${name}:${type}: ${value}`);
+    this.name = 'CommandParameterValueError';
+  }
+}

package/src/definition.ts

@@ -0,0 +1,74 @@
+import type { PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import {
+  createCapabilityContext,
+  type CapabilityContext,
+} from '@zhin.js/feature-kit';
+
+const commandBrand = 'zhin.command/1' as const;
+
+export type CommandParameterType = 'string' | 'number' | 'boolean';
+export type CommandParameterValue = string | number | boolean;
+
+export interface CommandParameterDefinition {
+  readonly name: string;
+  readonly type: CommandParameterType;
+  readonly defaultValue?: CommandParameterValue;
+}
+
+export interface CommandContext<TConfig = unknown, TInput = unknown>
+  extends CapabilityContext<TConfig> {
+  readonly args: readonly string[];
+  readonly params: Readonly<Record<string, CommandParameterValue>>;
+  readonly input: TInput;
+}
+
+export interface CommandDefinition<TConfig = unknown, TResult = unknown, TInput = unknown> {
+  readonly $feature: typeof commandBrand;
+  readonly $parameter?: CommandParameterDefinition;
+  readonly description?: string;
+  execute(context: CommandContext<TConfig, TInput>): TResult | Promise<TResult>;
+}
+
+export function defineCommand<TConfig = unknown, TResult = unknown, TInput = unknown>(
+  definition: Omit<CommandDefinition<TConfig, TResult, TInput>, '$feature' | '$parameter'>,
+): Readonly<CommandDefinition<TConfig, TResult, TInput>> {
+  if (typeof definition.execute !== 'function') {
+    throw new TypeError('Command execute must be a function');
+  }
+  return Object.freeze({ $feature: commandBrand, ...definition });
+}
+
+export function bindCommandParameter<TConfig, TResult, TInput>(
+  definition: CommandDefinition<TConfig, TResult, TInput>,
+  parameter: CommandParameterDefinition | undefined,
+): Readonly<CommandDefinition<TConfig, TResult, TInput>> {
+  if (!parameter) return definition;
+  return Object.freeze({ ...definition, $parameter: Object.freeze({ ...parameter }) });
+}
+
+export function parseCommandDefinition(value: unknown): CommandDefinition {
+  if (!value || typeof value !== 'object') {
+    throw new TypeError('Command module must default-export defineCommand(...)');
+  }
+  const definition = value as Partial<CommandDefinition>;
+  if (definition.$feature !== commandBrand || typeof definition.execute !== 'function') {
+    throw new TypeError('Command module must default-export defineCommand(...)');
+  }
+  return definition as CommandDefinition;
+}
+
+export function createCommandContext(
+  snapshot: RuntimeSnapshot,
+  ownerId: PluginId,
+  args: readonly string[],
+  params: Readonly<Record<string, CommandParameterValue>> = Object.freeze({}),
+  input: unknown = undefined,
+): CommandContext {
+  const context = createCapabilityContext(snapshot, ownerId);
+  return Object.freeze({
+    ...context,
+    args: Object.freeze([...args]),
+    params: Object.freeze({ ...params }),
+    input,
+  });
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './command-index.js';
+export * from './definition.js';
+export {
+  CommandPathSyntaxError,
+  commandFeatureId,
+  default as commandFeature,
+} from './provider.js';
+export { default } from './provider.js';

package/src/provider.ts

@@ -0,0 +1,135 @@
+import { basename, join, parse } from 'node:path';
+import { featureId } from '@zhin.js/plugin-runtime';
+import {
+  defineFeatureProvider,
+  type DiscoveryContext,
+  type DiscoveredSource,
+  type SourceConvention,
+} from '@zhin.js/feature-kit';
+import { CommandIndex } from './command-index.js';
+import {
+  bindCommandParameter,
+  parseCommandDefinition,
+  type CommandParameterDefinition,
+  type CommandParameterType,
+  type CommandParameterValue,
+} from './definition.js';
+
+export const commandFeatureId = featureId('zhin.command');
+
+const commandFiles: SourceConvention = {
+  id: 'commands-ts',
+  async *discover(context) {
+    const directory = join(context.packageRoot, 'commands');
+    yield* discoverCommandDirectory(context, directory, []);
+  },
+  async load(source, context) {
+    const module = await context.host.loadModule<{ default?: unknown }>(source.source);
+    const definition = parseCommandDefinition(module.default);
+    const file = parseCommandFile(basename(source.source));
+    return bindCommandParameter(definition, file?.parameter);
+  },
+};
+
+async function* discoverCommandDirectory(
+  context: DiscoveryContext,
+  directory: string,
+  ancestors: readonly string[],
+): AsyncIterable<DiscoveredSource> {
+  const entries = [...await context.host.list(directory)]
+    .sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  for (const entry of entries) {
+    if (entry.kind === 'directory' && isCommandSegment(entry.name)) {
+      yield* discoverCommandDirectory(
+        context,
+        join(directory, entry.name),
+        [...ancestors, entry.name],
+      );
+      continue;
+    }
+    if (entry.kind !== 'file') continue;
+    const file = parseCommandFile(entry.name);
+    if (!file) continue;
+    yield {
+      localName: [...ancestors, file.localSegment].join('/'),
+      source: join(directory, entry.name),
+      target: 'server',
+    };
+  }
+}
+
+function isCommandSegment(value: string): boolean {
+  return /^[a-z0-9][a-z0-9-]*$/.test(value);
+}
+
+interface ParsedCommandFile {
+  readonly localSegment: string;
+  readonly parameter?: CommandParameterDefinition;
+}
+
+const dynamicCommandFilePattern =
+  /^\[([a-z][a-zA-Z0-9]*):(string|number|boolean)(?:=([^\]]*))?\]\.tsx?$/;
+
+function parseCommandFile(value: string): ParsedCommandFile | undefined {
+  if (/^[a-z0-9][a-z0-9-]*\.tsx?$/.test(value)) {
+    return { localSegment: parse(value).name };
+  }
+  const match = dynamicCommandFilePattern.exec(value);
+  if (match) {
+    const [, name, type, rawDefault] = match as RegExpExecArray & {
+      readonly 1: string;
+      readonly 2: CommandParameterType;
+    };
+    // Metadata can change during HMR while $name keeps the Capability identity stable.
+    const parameter = rawDefault === undefined
+      ? { name, type }
+      : { name, type, defaultValue: parseParameterValue(name, type, rawDefault, value) };
+    return { localSegment: `$${name}`, parameter };
+  }
+  if (value.startsWith('[') || value.includes(']')) {
+    throw new CommandPathSyntaxError(value);
+  }
+  return undefined;
+}
+
+function parseParameterValue(
+  name: string,
+  type: CommandParameterType,
+  value: string,
+  source: string,
+): CommandParameterValue {
+  if (type === 'string') return value;
+  if (type === 'number') {
+    const number = Number(value);
+    if (value.trim().length > 0 && Number.isFinite(number)) return number;
+  } else if (value === 'true' || value === 'false') {
+    return value === 'true';
+  }
+  throw new CommandPathSyntaxError(
+    source,
+    `default for ${name}:${type} is invalid`,
+  );
+}
+
+export class CommandPathSyntaxError extends TypeError {
+  constructor(file: string, detail = 'expected [name:string|number|boolean=default].ts(x)') {
+    super(`Invalid Command path ${file}: ${detail}`);
+    this.name = 'CommandPathSyntaxError';
+  }
+}
+
+const commandFeature = defineFeatureProvider({
+  protocol: 1,
+  id: commandFeatureId,
+  authoring: {
+    conventions: [commandFiles],
+    validate: parseCommandDefinition,
+  },
+  runtime: {
+    project(slots, context) {
+      return { value: new CommandIndex(slots, context.snapshot) };
+    },
+  },
+});
+
+export default commandFeature;