@zhin.js/command 1.1.7 → 1.1.9

package/src/execution-runtime.ts

@@ -0,0 +1,202 @@
+/** Internal composition contract. Not part of the command authoring facade. */
+import { createToken, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { CommandExecutionLimit, CommandExecutionPolicy } from './execution-policy.js';
+
+interface ConversationIdentity {
+  readonly endpoint: { readonly adapter: string; readonly id: string };
+  readonly kind: string;
+  readonly id: string;
+  readonly parent?: { readonly kind: string; readonly id: string };
+  readonly threadId?: string;
+}
+
+interface AdmissionReader {
+  admit(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined;
+  /**
+   * Programmatic call with no inbound source (e.g. `CommandIndex.execute`). The policy is keyed by command only:
+   * there is no sender or conversation to budget, and no reply channel for progress feedback.
+   * On success the caller must invoke `release` once the execution settles.
+   */
+  admitDirect(capability: string, policy: CommandExecutionPolicy): DirectAdmission;
+}
+
+type DirectAdmission = { readonly limit: CommandExecutionLimit; readonly release?: undefined } | { readonly limit?: undefined; readonly release: () => void };
+
+/** @internal Admission-only Root resource; no bind or finish authority is published. */
+export const commandExecutionAdmissionToken = createToken<AdmissionReader>('zhin.command.execution-admission');
+
+/** @internal Held only by Core's actual leased operation. */
+export interface CommandOperationController {
+  bind(view: object, owner: PluginId): void;
+  /** Core registers actual started delivery promises, never a caller-supplied completion callback. */
+  trackSend(send: Promise<unknown>): void;
+  /** Stop pending feedback and drain already-started feedback before the final reply. */
+  stopProgress(): Promise<void>;
+  /** Called only by the real outer operation's finally, after all final sends settle. */
+  finish(): Promise<void>;
+}
+
+interface Entry { active: number; cooldownUntil: number }
+interface Operation {
+  snapshot?: RuntimeSnapshot;
+  key?: readonly string[];
+  active: boolean;
+  progressStopped: boolean;
+  admitted: boolean;
+  signal: AbortSignal;
+  reply?: (owner: PluginId, text: string) => Promise<unknown>;
+  readonly releases: (() => void)[];
+  readonly timers: Set<ReturnType<typeof setTimeout>>;
+  readonly feedback: Promise<void>[];
+  readonly accepted: Set<string>;
+  readonly sends: Set<Promise<void>>;
+}
+
+/** @internal Root-instance-owned state shared by projections and draining retired generations. */
+export class CommandExecutionBudget {
+  readonly #entries = new Map<string, Entry>();
+  readonly #views = new WeakMap<object, { operation: Operation; owner: PluginId }>();
+  readonly #clock: () => number;
+  readonly #capacity: number;
+  readonly admission: AdmissionReader;
+
+  constructor(options: { readonly clock?: () => number; readonly capacity?: number } = {}) {
+    this.#clock = options.clock ?? (() => performance.now());
+    this.#capacity = options.capacity ?? 10_000;
+    if (!Number.isSafeInteger(this.#capacity) || this.#capacity < 1) throw new TypeError('Invalid command budget capacity');
+    this.admission = Object.freeze<AdmissionReader>({ admit: (source, capability, owner, policy, snapshot) => this.#admit(source, capability, owner, policy, snapshot),
+      admitDirect: (capability, policy) => this.#admitDirect(capability, policy) });
+  }
+
+  openOperation(input: {
+    readonly snapshot: RuntimeSnapshot;
+    readonly conversation: ConversationIdentity;
+    readonly senderId?: string;
+    readonly retirementSignal: AbortSignal;
+    readonly reply: (owner: PluginId, text: string) => Promise<unknown>;
+  }): CommandOperationController {
+    const c = input.conversation;
+    const values = [c.endpoint.adapter, c.endpoint.id, c.kind, c.id, c.parent?.kind ?? '', c.parent?.id ?? '', c.threadId ?? '', input.senderId ?? ''];
+    const valid = values.slice(0, 4).every(nonempty) && ['private', 'group', 'channel'].includes(c.kind) && nonempty(input.senderId)
+      && (c.parent === undefined || (nonempty(c.parent.kind) && nonempty(c.parent.id)))
+      && (c.threadId === undefined || nonempty(c.threadId)) && values.every(value => value.length <= 1024);
+    const operation: Operation = {
+      snapshot: input.snapshot, key: valid ? Object.freeze(values) : undefined,
+      active: true, progressStopped: false, admitted: false, signal: input.retirementSignal,
+      reply: input.reply, releases: [], timers: new Set(), feedback: [], accepted: new Set(), sends: new Set(),
+    };
+    const stop = () => {
+      operation.progressStopped = true;
+      for (const timer of operation.timers) clearTimeout(timer);
+      operation.timers.clear();
+    };
+    input.retirementSignal.addEventListener('abort', stop, { once: true });
+    return Object.freeze({
+      bind: (view: object, owner: PluginId) => { if (operation.active) this.#views.set(view, { operation, owner }); },
+      trackSend: (send: Promise<unknown>) => {
+        if (!operation.active) return;
+        const settled = send.then(() => { operation.sends.delete(settled); }, () => { operation.sends.delete(settled); });
+        operation.sends.add(settled);
+      },
+      stopProgress: async () => { stop(); await Promise.all(operation.feedback); },
+      finish: async () => {
+        stop();
+        await Promise.all(operation.feedback);
+        // New sends may start while an earlier send is draining. Do not release from an initial snapshot alone.
+        if (operation.admitted) while (operation.sends.size > 0) await Promise.all(operation.sends);
+        if (!operation.active) return;
+        operation.active = false;
+        operation.signal.removeEventListener('abort', stop);
+        for (const release of operation.releases) release();
+        operation.releases.length = 0;
+        operation.feedback.length = 0;
+        operation.accepted.clear();
+        operation.sends.clear();
+        operation.reply = undefined;
+        operation.snapshot = undefined;
+        operation.key = undefined;
+      },
+    });
+  }
+
+  #admitDirect(capability: string, policy: CommandExecutionPolicy): DirectAdmission {
+    return this.#acquire(JSON.stringify([capability, 'direct']), policy);
+  }
+
+  /** Shared entry accounting: concurrency, cooldown and capacity. Returns a one-shot release on success. */
+  #acquire(key: string, policy: CommandExecutionPolicy): DirectAdmission {
+    const now = this.#clock();
+    let entry = this.#entries.get(key);
+    if (entry && policy.maxConcurrent !== undefined && entry.active >= policy.maxConcurrent) return { limit: limited('busy') };
+    if (entry && entry.cooldownUntil > now) return { limit: Object.freeze({ reason: 'cooldown', retryAfterMs: Math.ceil(entry.cooldownUntil - now) }) };
+    if (!entry) {
+      if (this.#entries.size >= this.#capacity) {
+        for (const [oldKey, old] of this.#entries) if (old.active === 0 && old.cooldownUntil <= now) this.#entries.delete(oldKey);
+        if (this.#entries.size >= this.#capacity) {
+          // Still full of cooling identities: drop the oldest idle one. Forgetting a cooldown is acceptable;
+          // refusing every new identity is not. Only entries with running operations are never evicted.
+          for (const [oldKey, old] of this.#entries) if (old.active === 0) { this.#entries.delete(oldKey); break; }
+        }
+        if (this.#entries.size >= this.#capacity) return { limit: limited('capacity') };
+      }
+      entry = { active: 0, cooldownUntil: 0 };
+      this.#entries.set(key, entry);
+    }
+    entry.active++;
+    entry.cooldownUntil = now + (policy.cooldownMs ?? 0);
+    const acceptedEntry = entry;
+    let released = false;
+    return {
+      release: () => {
+        if (released) return;
+        released = true;
+        acceptedEntry.active--;
+        if (acceptedEntry.active === 0 && acceptedEntry.cooldownUntil <= this.#clock()) this.#entries.delete(key);
+      },
+    };
+  }
+
+  #admit(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined {
+    const binding = source !== null && typeof source === 'object' ? this.#views.get(source) : undefined;
+    const operation = binding?.operation;
+    if (!operation?.active || operation.snapshot !== snapshot || binding?.owner !== owner || operation.signal.aborted) return limited('operation_unavailable');
+    if (!operation.key) return limited('identity_unavailable');
+    const key = JSON.stringify([capability, ...operation.key]);
+    // Re-entering the same capability is a second attempt, rather than a second free execution.
+    const acquired = this.#acquire(key, policy);
+    if (acquired.limit) return acquired.limit;
+    operation.admitted = true;
+    operation.releases.push(acquired.release);
+    if (policy.progressAfterMs !== undefined && !operation.progressStopped && !operation.accepted.has(capability)) {
+      const timer = setTimeout(() => {
+        operation.timers.delete(timer);
+        if (!operation.active || operation.progressStopped || operation.signal.aborted || !operation.reply) return;
+        // Observe failure once. Never retry uncertain delivery and never expose the exception.
+        let send: Promise<void>;
+        try { send = Promise.resolve(operation.reply(owner, '正在处理中，请稍候。')).then(() => {}, () => {}); }
+        catch { send = Promise.resolve(); }
+        operation.feedback.push(send);
+      }, policy.progressAfterMs);
+      operation.timers.add(timer);
+    }
+    operation.accepted.add(capability);
+    return undefined;
+  }
+}
+
+function nonempty(value: unknown): value is string { return typeof value === 'string' && value.length > 0; }
+function limited(reason: CommandExecutionLimit['reason']): CommandExecutionLimit { return Object.freeze({ reason }); }
+
+/** @internal Projection reads the Root resource; ordinary authoring values cannot bind an operation. */
+export function admitCommandExecution(source: unknown, capability: string, owner: PluginId, policy: CommandExecutionPolicy | undefined, snapshot: RuntimeSnapshot): CommandExecutionLimit | undefined {
+  if (!policy) return undefined;
+  const reader = snapshot.resources.get(snapshot.root)?.get(commandExecutionAdmissionToken.id) as AdmissionReader | undefined;
+  return reader ? reader.admit(source, capability, owner, policy, snapshot) : limited('service_unavailable');
+}
+
+/** @internal Programmatic (source-less) admission: keyed by command only, never refused for lacking a source. */
+export function admitDirectCommandExecution(capability: string, policy: CommandExecutionPolicy | undefined, snapshot: RuntimeSnapshot): DirectAdmission {
+  if (!policy) return { release: () => {} };
+  const reader = snapshot.resources.get(snapshot.root)?.get(commandExecutionAdmissionToken.id) as AdmissionReader | undefined;
+  return reader ? reader.admitDirect(capability, policy) : { limit: limited('service_unavailable') };
+}

package/src/index.ts

@@ -6,7 +6,10 @@
 export * from './command-index.js';
 /** @public Command authoring contract and `defineCommand`. */
 export * from './definition.js';
+export * from './permission-explanation.js';
 export {
+  CONVERSATION_MANAGER_PERMIT,
+  canManageConversation,
   assertBuiltinPermits,
   checkBuiltinPermit,
   checkBuiltinPermitList,
@@ -17,8 +20,10 @@ export {
   type PermitKind,
 } from './permit.js';
 export {
+  bindCommandSource,
   CommandPathSyntaxError,
   commandFeatureId,
+  type BoundCommandSource,
   default as commandFeature,
 } from './provider.js';
 export { default } from './provider.js';

package/src/permission-explanation.ts

@@ -0,0 +1,58 @@
+import { operationClientAdapter } from '@zhin.js/feature-kit';
+import { explainPermitRules, toPermissionSubject, type PermissionSubject, type PermissionConditionExplanation } from '@zhin.js/permission';
+import { resolveCommandSender, resolveCommandSession, type CommandMessage } from './definition.js';
+import type { CommandDescriptor } from './command-index.js';
+
+/** The exact subject projection used by the real command permit gate. No factories or checkers run. */
+export function toCommandPermissionSubject(source: unknown): PermissionSubject {
+  const projected = toPermissionSubject(source);
+  const session = resolveCommandSession(source);
+  return { ...projected, ...session, ...(session.sender ? { sender: { ...projected.sender, ...session.sender } } : {}) };
+}
+
+/** Exact authoring adapter restriction, distinct from builtin adapter(...) matching. */
+export function commandAdapterMatches(command: Readonly<{ adapter?: string }>, source: unknown): boolean {
+  return !command.adapter || operationClientAdapter(source) === command.adapter;
+}
+
+export type CommandPermissionHostStatus = 'present' | 'missing' | 'unverified';
+
+/** Read-only hypothetical conditions. A match is not permission to execute the command. */
+export function explainCommandPermissions(
+  command: Pick<CommandDescriptor, 'adapter' | 'permit'>,
+  options: Readonly<{ source?: unknown; rolesKnown?: boolean; permissionHost: CommandPermissionHostStatus }>,
+) {
+  const projected = toCommandPermissionSubject(options.source);
+  const inputSender = options.source && typeof options.source === 'object'
+    ? (options.source as Pick<CommandMessage, 'sender'>).sender : undefined;
+  const structuredRoles = inputSender && typeof inputSender === 'object'
+    && Array.isArray((inputSender as { readonly role?: unknown }).role);
+  // A sender-only assumption has no synthetic conversation. Apply the real canonical
+  // sender defaults without inventing an Endpoint or treating unknown roles as known.
+  const senderOnly = options.source && typeof options.source === 'object' && !('conversation' in options.source) && !structuredRoles
+    ? resolveCommandSender(options.source as Pick<CommandMessage, 'sender'>, undefined) : undefined;
+  const subject = senderOnly ? { ...projected, sender: senderOnly } : projected;
+  const defaultedRoles = options.rolesKnown && Array.isArray(inputSender?.roles) && inputSender.roles.length === 0
+    && subject.sender?.role.length === 1 && subject.sender.role[0] === 'user';
+  const actualAdapter = operationClientAdapter(options.source);
+  const adapter: PermissionConditionExplanation = !command.adapter
+    ? { outcome: 'not_evaluated', reason: '命令未声明 adapter 约束' }
+    : !actualAdapter ? { outcome: 'unknown', reason: '未选择当前 Endpoint，无法判断命令的精确 adapter 约束' }
+      : { outcome: commandAdapterMatches(command, options.source) ? 'match' : 'mismatch', reason: '命令 adapter 与当前 Endpoint 声明的原生适配器精确比较；未探测在线状态' };
+  const rules = explainPermitRules(command.permit ?? [], subject, { rolesKnown: options.rolesKnown });
+  const conditions = [...(command.adapter ? [adapter] : []), ...rules];
+  let summary: PermissionConditionExplanation;
+  if (conditions.some(item => item.outcome === 'mismatch')) summary = { outcome: 'mismatch', reason: '至少一个声明条件与假设输入不符；这不是实际准入检查' };
+  else if ((rules.length > 0 && options.permissionHost !== 'present') || conditions.some(item => item.outcome === 'unknown')) {
+    summary = { outcome: 'unknown', reason: rules.length > 0 && options.permissionHost !== 'present'
+      ? 'PermissionHost 缺失或无法确认；不能推断命令可执行' : '存在缺少依据的条件，不能推断命令可执行' };
+  } else if (rules.length === 0) summary = { outcome: 'not_evaluated', reason: '命令未声明 permit 限制；这不表示已获得执行权限' };
+  else if (conditions.some(item => item.outcome === 'not_evaluated')) summary = { outcome: 'not_evaluated', reason: '存在未执行的平台或自定义条件，不能推断命令可执行' };
+  else summary = { outcome: 'match', reason: '已解释的 builtin 条件与假设输入匹配；不代表真实授权或命令可执行' };
+  return Object.freeze({ permissionHost: options.permissionHost, adapter: Object.freeze(adapter), rules, summary: Object.freeze(summary),
+    unconstrained: Object.freeze(['已解释的 builtin 规则不检查具体 Endpoint、parent 或 thread；保留完整目标不等于这些维度受规则限制']),
+    assumptions: Object.freeze(['身份与角色仅用于模拟，未向平台核实', '未执行命令、动态默认值、平台或自定义 checker',
+      ...(defaultedRoles
+        ? ['canonical 输入未附角色时按命令运行时默认 user 解释；这不是已核验的平台角色'] : [])]),
+  });
+}

package/src/permit.ts

@@ -2,6 +2,20 @@
  * Re-export permit 解析/校验 from @zhin.js/permission (SSOT)。
  * 保留 CommandSession 兼容签名供 command-index 过渡使用。
  */
+import { checkBuiltinPermit, type PermissionSubject } from '@zhin.js/permission';
+
+/** 会话管理者：群主 / 群管理员 / 机器人主人（适配器投影的规范角色名）。 */
+export const CONVERSATION_MANAGER_PERMIT = 'role(owner,admin,master)';
+
+/**
+ * 「私聊，或 owner / admin / master」。`permit` 列表只支持 AND，
+ * 订阅类命令需要这个 OR 规则时用它，并以命令会话的 `scene` / `sender.role` 为输入。
+ */
+export function canManageConversation(subject: PermissionSubject): boolean {
+  return checkBuiltinPermit('private()', subject)
+    || checkBuiltinPermit(CONVERSATION_MANAGER_PERMIT, subject);
+}
+
 export {
   type PermitKind,
   type ParsedPermit,

package/src/provider.ts

@@ -1,4 +1,4 @@
-import { basename, dirname, join, sep } from 'node:path';
+import { basename, dirname, join, relative, sep } from 'node:path';
 import { featureId, isCapabilityLocalSegment } from '@zhin.js/plugin-runtime';
 import {
   defineFeatureProvider,
@@ -6,7 +6,7 @@ import {
   type DiscoveredSource,
   type SourceConvention,
 } from '@zhin.js/feature-kit';
-import { CommandIndex } from './command-index.js';
+import { CommandIndex, assertParameterSegment } from './command-index.js';
 import {
   bindCommandParameter,
   parseCommandDefinition,
@@ -32,6 +32,8 @@ const commandFiles: SourceConvention = {
   async load(source, context) {
     const module = await context.host.loadModule<{ default?: unknown }>(source.source);
     const definition = parseCommandDefinition(module.default);
+    const commandDirectories = commandDirectoriesOf(context.packageRoot, source.source);
+    assertSingleTrailingParameterDirectory(commandDirectories, source.source);
     const file = parseCommandDirectory(basename(dirname(source.source)));
     return bindCommandParameter(definition, resolveParameter(definition, file, source.source));
   },
@@ -109,6 +111,76 @@ function parseCommandDirectory(value: string): ParsedCommandFile | undefined {
   return undefined;
 }
 
+/** Directory segments between `commands/` and the command's `index.*` file. */
+function commandDirectoriesOf(packageRoot: string, source: string): string[] {
+  const commandsRoot = join(packageRoot, 'commands');
+  const commandDirectory = dirname(source);
+  return relative(commandsRoot, commandDirectory)
+    .split(sep)
+    .filter((segment) => segment !== '');
+}
+
+interface ParameterDirectory {
+  readonly position: number;
+  readonly directory: string;
+  readonly hint: CommandParameterHint;
+}
+
+/**
+ * A command path may contain at most one parameter directory, and it must be the
+ * last directory before `index.*`. Further arguments belong in `defineCommand({ params })`.
+ */
+function assertSingleTrailingParameterDirectory(directories: readonly string[], source: string): void {
+  const parameterDirectories: ParameterDirectory[] = [];
+  directories.forEach((directory, position) => {
+    const hint = parseCommandDirectory(directory)?.parameter;
+    if (hint) parameterDirectories.push({ position, directory, hint });
+  });
+  const [keptDirectory, ...movedDirectories] = parameterDirectories;
+  if (!keptDirectory) return;
+  const lastPosition = directories.length - 1;
+  if (movedDirectories.length === 0 && keptDirectory.position === lastPosition) return;
+  throw new CommandPathSyntaxError(
+    source,
+    describeParameterDirectoryRule(directories, keptDirectory, movedDirectories),
+  );
+}
+
+function describeParameterDirectoryRule(
+  directories: readonly string[],
+  keptDirectory: ParameterDirectory,
+  movedDirectories: readonly ParameterDirectory[],
+): string {
+  const parameterDirectories = [keptDirectory, ...movedDirectories];
+  const currentPath = `commands/${directories.join('/')}/index.ts`;
+  const foundDirectories = parameterDirectories.map((entry) => entry.directory).join(', ');
+  const staticDirectories = directories.filter((_directory, position) =>
+    !parameterDirectories.some((entry) => entry.position === position));
+  const suggestedPath = `commands/${[...staticDirectories, keptDirectory.directory].join('/')}/index.ts`;
+  const suggestedParams = parameterDirectories
+    .map((entry) => describeParamDeclaration(entry.hint))
+    .join(', ');
+  const movedNote = movedDirectories.length > 0
+    ? `move ${movedDirectories.map((entry) => entry.directory).join(', ')} into defineCommand({ params })`
+    : 'move the parameter directory to the end of the path';
+  return `only the last directory of a command path may be a parameter directory `
+    + `([name], [[name]], [...name] or [[...name]]), and a command may have at most one; `
+    + `found ${foundDirectories} in ${currentPath}. `
+    + `Fix: ${movedNote}, e.g. ${suggestedPath} with `
+    + `defineCommand({ params: { ${suggestedParams} } }) `
+    + `(the directory parameter must be listed first). `
+    + 'See https://zhin.js.org/authoring/commands#目录参数规则';
+}
+
+function describeParamDeclaration(hint: CommandParameterHint): string {
+  const type = hint.rest ? 'text' : 'string';
+  const flags: string[] = [];
+  if (hint.optional) flags.push('optional: true');
+  if (hint.rest) flags.push('rest: true');
+  const flagText = flags.map((flag) => `, ${flag}`).join('');
+  return `${hint.name}: { type: '${type}'${flagText} }`;
+}
+
 /** 把文件名形态与 `definition.params` 合并成完整参数定义。 */
 function resolveParameter(
   definition: CommandDefinition,
@@ -124,8 +196,16 @@ function resolveParameter(
       `missing params.${hint.name} declaration in defineCommand({ params })`,
     );
   }
-  if (Object.keys(definition.params ?? {})[0] !== hint.name) {
-    throw new CommandPathSyntaxError(source, `params.${hint.name} must be the first parameter declaration`);
+  const declaredNames = Object.keys(definition.params ?? {});
+  if (declaredNames[0] !== hint.name) {
+    const reorderedNames = [hint.name, ...declaredNames.filter((name) => name !== hint.name)];
+    throw new CommandPathSyntaxError(
+      source,
+      `params.${hint.name} must be the first parameter declaration: the parameter directory `
+        + `binds the first argument after the command name, so it has to come first in `
+        + `defineCommand({ params }). Current order: { ${declaredNames.join(', ')} }; `
+        + `reorder to { ${reorderedNames.join(', ')} }`,
+    );
   }
   if (schema.rest !== undefined && schema.rest !== hint.rest
     || schema.optional !== undefined && schema.optional !== hint.optional) {
@@ -166,6 +246,46 @@ function preferredCommandIndex(
       - commandFilePriority(right.name, preferJavaScript))[0]?.name;
 }
 
+export interface BoundCommandSource<TDefinition> {
+  /** Plugin-local name the runtime registers, e.g. `term/$word`. */
+  readonly localName: string;
+  /** The definition with `$parameter` bound from the directory shape, as the runtime loads it. */
+  readonly definition: TDefinition;
+}
+
+/**
+ * Apply the runtime's convention-path rules to one command module: directory syntax
+ * (`[name]`, `[[name]]`, `[...name]`, `[[...name]]`), the `params` declaration the directory
+ * implies, and the route shape (one dynamic segment, last). `source` is the command's `index`
+ * file or its directory; everything after the last `commands` directory is the command path.
+ * Throws the same errors discovery, loading and the command index throw.
+ */
+export function bindCommandSource<TDefinition extends CommandDefinition>(
+  value: TDefinition,
+  source: string,
+): BoundCommandSource<TDefinition>;
+export function bindCommandSource(value: unknown, source: string): BoundCommandSource<CommandDefinition>;
+export function bindCommandSource(value: unknown, source: string): BoundCommandSource<CommandDefinition> {
+  const directory = /^index\.(?:tsx?|[cm]?js)$/u.test(basename(source)) ? dirname(source) : source;
+  const parts = directory.split(/[\\/]/u).filter(Boolean);
+  const commandsAt = parts.lastIndexOf('commands');
+  if (commandsAt < 0 || commandsAt === parts.length - 1) {
+    throw new CommandPathSyntaxError(source, 'expected a path under commands/, e.g. commands/foo/index.ts');
+  }
+  const segments = parts.slice(commandsAt + 1).map((name) => {
+    const segment = parseCommandDirectory(name);
+    if (!segment) {
+      throw new CommandPathSyntaxError(source, `"${name}" is not a command directory name, so the runtime does not discover it`);
+    }
+    return segment;
+  });
+  const definition = parseCommandDefinition(value);
+  const bound = bindCommandParameter(definition, resolveParameter(definition, segments.at(-1), source));
+  const localName = segments.map((segment) => segment.localSegment).join('/');
+  assertParameterSegment(localName.split('/'), bound.$parameter, source);
+  return Object.freeze({ localName, definition: bound });
+}
+
 export class CommandPathSyntaxError extends TypeError {
   constructor(
     file: string,