@tulip-systems/core 0.8.3 → 0.10.0

package/src/modules/commands/hooks/{use-command-mutation.client.tsx → use-command-mutation.client.ts}

@@ -3,12 +3,7 @@
 import type { DefaultError, MutationFunction, MutationOptions } from "@tanstack/react-query";
 import { useRouter } from "next/navigation";
 import { useAction } from "@/lib/hooks/use-action";
-import { useCommand } from "./context.client";
-
-export type CommandActionResult = Promise<unknown>;
-
-export type CommandAction<TInput = void> = (input: TInput) => CommandActionResult;
-export type BulkCommandAction = (params: { ids: string[] }) => CommandActionResult;
+import { useCommand } from "./use-command.client";
 
 export type CommandMutationMeta = {
   router: ReturnType<typeof useRouter>;
@@ -23,43 +18,31 @@ export function useCommandMutation<
   const router = useRouter();
   const commandContext = useCommand();
 
-  const mutation = useAction({
+  return useAction({
     ...options,
     mutationFn: options?.mutationFn as MutationFunction<TData, TVariables>,
     onMutate: async (...params) => {
       const result = options?.onMutate?.(...params);
-
       commandContext.setStatus("pending");
-
       return (await result) as TOnMutateResult;
     },
     onSuccess: async (...params) => {
       const result = options?.onSuccess?.(...params);
-
       commandContext.setStatus("success");
-      await commandContext.onSuccess?.();
-
       return await result;
     },
     onError: async (...params) => {
       const result = options?.onError?.(...params);
-
       commandContext.setStatus("error");
-      await commandContext.onError?.();
-
       return await result;
     },
     onSettled: async (...params) => {
       const result = options?.onSettled?.(...params);
-
       commandContext.setStatus("idle");
-
       return await result;
     },
     meta: {
       router,
     } satisfies CommandMutationMeta,
   });
-
-  return mutation;
 }

package/src/modules/commands/hooks/use-command.client.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import {
+  createContext,
+  type Dispatch,
+  type PropsWithChildren,
+  type SetStateAction,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import type { CommandStatus, CommandUI } from "../lib/builder";
+
+type CommandContextValue = {
+  ui: CommandUI;
+  status: CommandStatus;
+  disabled: boolean;
+  setStatus: Dispatch<SetStateAction<CommandStatus>>;
+};
+
+const CommandContext = createContext<CommandContextValue | null>(null);
+
+export function useCommand() {
+  const context = useContext(CommandContext);
+  if (!context) {
+    throw new Error("useCommand must be used within CommandContextProvider");
+  }
+
+  return context;
+}
+
+export type CommandContextLifecycle = {
+  onSuccess?: () => Promise<void> | void;
+  onError?: () => Promise<void> | void;
+  onSettled?: () => Promise<void> | void;
+};
+
+type CommandContextProviderProps = PropsWithChildren<
+  CommandContextLifecycle & {
+    ui: CommandUI;
+    disabled?: boolean;
+  }
+>;
+
+export function CommandContextProvider({
+  children,
+  ui,
+  disabled = false,
+  onSuccess,
+  onError,
+  onSettled,
+}: CommandContextProviderProps) {
+  const [status, setStatus] = useState<CommandStatus>("idle");
+  const previousStatusRef = useRef<CommandStatus>("idle");
+
+  useEffect(() => {
+    if (status === previousStatusRef.current) return;
+
+    if (status === "success") {
+      void onSuccess?.();
+      void onSettled?.();
+    }
+
+    if (status === "error") {
+      void onError?.();
+      void onSettled?.();
+    }
+
+    previousStatusRef.current = status;
+  }, [status, onSuccess, onError, onSettled]);
+
+  return (
+    <CommandContext.Provider value={{ ui, status, disabled, setStatus }}>
+      {children}
+    </CommandContext.Provider>
+  );
+}

package/src/modules/commands/lib/builder.ts

@@ -0,0 +1,271 @@
+import type { Permission } from "@/modules/auth/lib/permissions";
+
+/**
+ * The different UI contexts in which a command can be rendered.
+ */
+export type CommandUI = "dropdown" | "context" | "table" | "inline" | "custom";
+
+/**
+ * The status of a command, which can be used to style the command's UI appropriately.
+ */
+export type CommandStatus = "idle" | "pending" | "success" | "error";
+
+/**
+ * A string tag that can be added to a command for organizational and filtering purposes.
+ */
+export type CommandTag = string;
+
+/**
+ * Represents a command definition with its associated types and properties.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: intentional — holds heterogeneous command data/meta/tag types.
+export type AnyCommandDef = CommandDef<any, any, any, any>;
+
+/**
+ * Condition function that determines whether a command is visible or disabled based on the provided data and meta.
+ */
+export type CommandCondition<TData, TMeta> = (params: {
+  data: TData;
+  meta: TMeta;
+}) => boolean | boolean[];
+
+/**
+ * Render function that defines how a command should be rendered based on the provided data, meta, and UI context.
+ */
+export type CommandRender<TData, TMeta> = (params: {
+  data: TData;
+  meta: TMeta;
+  ui: CommandUI;
+}) => React.ReactNode;
+
+/**
+ * Final command definition (without name).
+ * Name is derived from the object key in `defineCommands`.
+ *
+ * @typeParam TData  - The type `visibleWhen`, `disabledWhen`, and `render` receive.
+ *                    When `.transform()` is used this is the post-transform type.
+ * @typeParam TMeta  - Shared contextual metadata passed alongside data.
+ * @typeParam TTags  - Literal tuple of tag strings preserved from the builder's
+ *                    `.tags()` call. Enables compile-time tag filtering in the
+ *                    registry. Defaults to `string[]` when not provided.
+ * @typeParam TInput - The type that menus must pass as `data`. Equals `TData`
+ *                    when no `.transform()` is used. When `.transform(fn)` is
+ *                    called, `TInput` captures the pre-transform type so menus
+ *                    remain correctly typed while `render` sees the transformed type.
+ *                    Structurally expressed as the parameter of `transform`.
+ */
+export type CommandDef<
+  TData = unknown,
+  TMeta = object,
+  TTags extends readonly string[] = string[],
+  TInput = TData,
+> = {
+  id?: string;
+  tags: TTags;
+  transform?: (data: TInput) => TData;
+  permission?: Permission;
+  visibleWhen?: CommandCondition<TData, TMeta>;
+  disabledWhen?: CommandCondition<TData, TMeta>;
+  render: CommandRender<TData, TMeta>;
+};
+
+/**
+ * Command typed by accepted input data.
+ *
+ * Useful for APIs that only care about what can be passed in (e.g. table
+ * providers that always pass selected rows), not the command's normalized
+ * render-time shape.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: hides non-input generics for call-site ergonomics.
+export type CommandFor<TInput, TMeta = object> = CommandDef<any, TMeta, any, TInput>;
+
+/**
+ * Extracts the **input** data type of a command — what menus must pass as `data`.
+ *
+ * - When `.transform()` is used, this is the pre-transform type (e.g. `Template | Template[]`).
+ * - Otherwise it equals the render-time type.
+ *
+ * The type is read from the `transform` field's parameter when present, and
+ * falls back to the `render` parameter when there is no transformer.
+ */
+export type ExtractCommandData<TCommand extends AnyCommandDef> = [
+  NonNullable<TCommand["transform"]>,
+] extends [never]
+  ? TCommand extends { render: (params: { data: infer TData; meta: any; ui: any }) => any }
+    ? TData
+    : never
+  : NonNullable<TCommand["transform"]> extends (data: infer TInput) => any
+    ? TInput
+    : never;
+
+// ─── Builder interfaces ────────────────────────────────────────────────────────
+
+/**
+ * Builder state after `.$type<TData>()` has been called (or at initial state
+ * with `TData = unknown`).
+ *
+ * @typeParam TData  - Current render-time data type (post-transform if used).
+ * @typeParam TTags  - Literal tag tuple, carried through every method so that
+ *                    the final `CommandDef` retains the literal type.
+ * @typeParam TInput - Input data type for menus. Starts equal to `TData`.
+ *                    Freezes to the value of `TData` at the moment `.transform()`
+ *                    is called, while `TData` changes to the transformer's output.
+ */
+type ReadyCommandBuilder<
+  TData,
+  TMeta,
+  TTags extends readonly string[] = string[],
+  TInput = TData,
+> = {
+  /** Override the data (and optionally meta) type. Resets `TInput` to the new `TData`. */
+  $type<TNewData, TNewMeta = TMeta>(): ReadyCommandBuilder<TNewData, TNewMeta, TTags, TNewData>;
+  /**
+   * Set the command's tags as a literal tuple. The `const` modifier infers
+   * string arguments as literals, enabling compile-time tag narrowing in the registry.
+   */
+  tags<const TNewTags extends string[]>(
+    ...tags: TNewTags
+  ): ReadyCommandBuilder<TData, TMeta, TNewTags, TInput>;
+  permission(permission: Permission): ReadyCommandBuilder<TData, TMeta, TTags, TInput>;
+  /**
+   * Declares a lightweight transformer that runs once per render — before `visibleWhen`,
+   * `disabledWhen`, and `render` — collapsing the input type into a single usable shape.
+   *
+   * Freezes `TInput` to the current `TData` (the pre-transform type) and advances
+   * `TData` to `TNewData` (the transformer's return type). This ensures:
+   * - Menus are typed against the union input (e.g. `Template | Template[]`)
+   * - `visibleWhen` and `render` work with the clean transformed type (e.g. `Template[]`)
+   *
+   * @example
+   * commandBuilder
+   *   .$type<Template | Template[]>()
+   *   .transform((data) => (Array.isArray(data) ? data : [data]))
+   *   .visibleWhen(({ data }) => data.length > 0)  // data: Template[]
+   *   .render(({ data }) => <ArchiveCommand ids={data.map(i => i.id)} />)
+   */
+  transform<TNewData>(
+    fn: (data: TData) => TNewData,
+  ): ReadyCommandBuilder<TNewData, TMeta, TTags, TData>;
+  visibleWhen(
+    condition: CommandCondition<TData, TMeta>,
+  ): ReadyCommandBuilder<TData, TMeta, TTags, TInput>;
+  disabledWhen(
+    condition: CommandCondition<TData, TMeta>,
+  ): ReadyCommandBuilder<TData, TMeta, TTags, TInput>;
+  /** Terminal — produces the final `CommandDef`. */
+  render(render: CommandRender<TData, TMeta>): CommandDef<TData, TMeta, TTags, TInput>;
+};
+
+/**
+ * The initial builder returned by `commandBuilder` / `createCommandBuilder()`.
+ * Before `.$type<>()` is called, `TData` is `unknown`.
+ */
+type InitialCommandBuilder<TMeta> = ReadyCommandBuilder<unknown, TMeta, string[], unknown> & {
+  $type<TNewData, TNewMeta = TMeta>(): ReadyCommandBuilder<TNewData, TNewMeta, string[], TNewData>;
+  tags<const TNewTags extends string[]>(
+    ...tags: TNewTags
+  ): ReadyCommandBuilder<unknown, TMeta, TNewTags, unknown>;
+};
+
+// ─── Internal builder state ────────────────────────────────────────────────────
+
+type StartState<TMeta> = {
+  tags?: readonly string[];
+  permission?: Permission;
+  meta?: TMeta;
+};
+
+type ReadyState<TData, TMeta, TTags extends readonly string[]> = {
+  tags: TTags;
+  permission?: Permission;
+  // Erased to (data: unknown) => unknown at storage level; CommandDef.transform is typed as
+  // CommandNormalize<TInput, TData> and restored via cast in the render() terminal.
+  transform?: (data: unknown) => unknown;
+  visibleWhen?: CommandCondition<TData, TMeta>;
+  disabledWhen?: CommandCondition<TData, TMeta>;
+};
+
+// ─── Builder factory functions ─────────────────────────────────────────────────
+
+function createInitialBuilder<TMeta>(state: StartState<TMeta>): InitialCommandBuilder<TMeta> {
+  const readyBuilder = createReadyBuilder<unknown, TMeta, string[]>({
+    tags: (state.tags as string[]) ?? [],
+    permission: state.permission,
+  });
+
+  return {
+    ...readyBuilder,
+    tags<const TNewTags extends string[]>(...tags: TNewTags) {
+      return createReadyBuilder<unknown, TMeta, TNewTags>({
+        tags,
+        permission: state.permission,
+      });
+    },
+    $type<TNewData, TNewMeta = TMeta>() {
+      return createReadyBuilder<TNewData, TNewMeta, string[]>({
+        tags: (state.tags as string[]) ?? [],
+        permission: state.permission,
+      });
+    },
+  } as InitialCommandBuilder<TMeta>;
+}
+
+function createReadyBuilder<TData, TMeta, TTags extends readonly string[]>(
+  state: ReadyState<TData, TMeta, TTags>,
+): ReadyCommandBuilder<TData, TMeta, TTags, TData> {
+  return {
+    $type<TNewData, TNewMeta = TMeta>() {
+      return createReadyBuilder<TNewData, TNewMeta, TTags>({
+        tags: state.tags,
+        permission: state.permission,
+      });
+    },
+    tags<const TNewTags extends string[]>(...tags: TNewTags) {
+      return createReadyBuilder<TData, TMeta, TNewTags>({
+        tags,
+        permission: state.permission,
+        transform: state.transform,
+        visibleWhen: state.visibleWhen as CommandCondition<TData, TMeta> | undefined,
+        disabledWhen: state.disabledWhen as CommandCondition<TData, TMeta> | undefined,
+      });
+    },
+    permission(permission: Permission) {
+      return createReadyBuilder<TData, TMeta, TTags>({ ...state, permission });
+    },
+    transform<TNewData>(fn: (data: TData) => TNewData) {
+      // TInput freezes to the current TData; TData advances to TNewData.
+      // The returned builder is typed ReadyCommandBuilder<TNewData, TMeta, TTags, TData>
+      // but createReadyBuilder only tracks TData (output); TInput is enforced via the cast.
+      return createReadyBuilder<TNewData, TMeta, TTags>({
+        tags: state.tags,
+        permission: state.permission,
+        transform: fn as (data: unknown) => unknown,
+      }) as unknown as ReadyCommandBuilder<TNewData, TMeta, TTags, TData>;
+    },
+    visibleWhen(condition: CommandCondition<TData, TMeta>) {
+      return createReadyBuilder<TData, TMeta, TTags>({ ...state, visibleWhen: condition });
+    },
+    disabledWhen(condition: CommandCondition<TData, TMeta>) {
+      return createReadyBuilder<TData, TMeta, TTags>({ ...state, disabledWhen: condition });
+    },
+    render(render: CommandRender<TData, TMeta>) {
+      // The transform field is stored as (data: unknown) => unknown in ReadyState but
+      // CommandDef.transform is typed as (data: TInput) => TData. The cast bridges the gap;
+      // runtime correctness is guaranteed by the builder's type constraints.
+      return {
+        tags: state.tags,
+        transform: state.transform,
+        permission: state.permission,
+        visibleWhen: state.visibleWhen,
+        disabledWhen: state.disabledWhen,
+        render,
+      } as unknown as CommandDef<TData, TMeta, TTags, TData>;
+    },
+  } as ReadyCommandBuilder<TData, TMeta, TTags, TData>;
+}
+
+export function createCommandBuilder<TMeta = object>(): InitialCommandBuilder<TMeta> {
+  return createInitialBuilder<TMeta>({});
+}
+
+export const commandBuilder = createCommandBuilder();

package/src/modules/commands/lib/registery.ts

@@ -0,0 +1,279 @@
+import type { AnyCommandDef } from "./builder";
+
+/**
+ * Command map type defining the shape of command definitions.
+ */
+export type CommandMap = Record<string, AnyCommandDef>;
+
+/** Union of all values in a command map. */
+type ValueOf<TCommands extends CommandMap> = TCommands[keyof TCommands];
+
+// ─── Tag filter type helpers ───────────────────────────────────────────────────
+// Each helper checks ONLY the `tags` field to avoid function-type variance issues.
+// Commands with non-literal `string[]` tags are always kept (conservative fallback).
+
+/** Keep commands that have **every** of `TFilterTags`. */
+type FilterAllTags<
+  TCommand extends AnyCommandDef,
+  TFilterTags extends readonly string[],
+> = TCommand extends { tags: infer CmdTags extends readonly string[] }
+  ? TFilterTags[number] extends CmdTags[number]
+    ? TCommand
+    : never
+  : TCommand;
+
+/** Keep commands that have **some** of `TFilterTags`. */
+type FilterAnyTags<
+  TCommand extends AnyCommandDef,
+  TFilterTags extends readonly string[],
+> = TCommand extends { tags: infer CmdTags extends readonly string[] }
+  ? string[] extends CmdTags
+    ? TCommand
+    : Extract<CmdTags[number], TFilterTags[number]> extends never
+      ? never
+      : TCommand
+  : TCommand;
+
+/** Keep commands whose tag set equals `TFilterTags` (order-insensitive). */
+type FilterExactTags<
+  TCommand extends AnyCommandDef,
+  TFilterTags extends readonly string[],
+> = TCommand extends { tags: infer CmdTags extends readonly string[] }
+  ? string[] extends CmdTags
+    ? TCommand
+    : [CmdTags[number]] extends [TFilterTags[number]]
+      ? [TFilterTags[number]] extends [CmdTags[number]]
+        ? TCommand
+        : never
+      : never
+  : TCommand;
+
+/** Keep commands that have **without** of `TFilterTags`. */
+type FilterWithoutTags<
+  TCommand extends AnyCommandDef,
+  TFilterTags extends readonly string[],
+> = TCommand extends { tags: infer CmdTags extends readonly string[] }
+  ? string[] extends CmdTags
+    ? TCommand
+    : Extract<CmdTags[number], TFilterTags[number]> extends never
+      ? TCommand
+      : never
+  : TCommand;
+
+// ─── Registry type definitions ─────────────────────────────────────────────────
+
+type CommandKey<TCommands extends CommandMap> = Extract<keyof TCommands, string>;
+type CommandFlags<TCommands extends CommandMap> = Partial<Record<CommandKey<TCommands>, boolean>>;
+type CommandInput<TCommands extends CommandMap> =
+  | readonly CommandKey<TCommands>[]
+  | CommandFlags<TCommands>;
+
+type TruthyKeys<T> = { [K in keyof T]-?: T[K] extends true ? K : never }[keyof T];
+
+type PickedCommands<
+  TCommands extends CommandMap,
+  TInput extends CommandInput<TCommands>,
+> = TInput extends readonly CommandKey<TCommands>[]
+  ? Pick<TCommands, TInput[number]>
+  : TInput extends CommandFlags<TCommands>
+    ? Pick<TCommands, Extract<TruthyKeys<TInput>, keyof TCommands>>
+    : never;
+
+type OmittedCommands<
+  TCommands extends CommandMap,
+  TInput extends CommandInput<TCommands>,
+> = TInput extends readonly CommandKey<TCommands>[]
+  ? Omit<TCommands, TInput[number]>
+  : TInput extends CommandFlags<TCommands>
+    ? Omit<TCommands, Extract<TruthyKeys<TInput>, keyof TCommands>>
+    : never;
+
+type ExtendedCommands<TBase extends CommandMap, TExtension extends CommandMap> = Omit<
+  TBase,
+  keyof TExtension
+> &
+  TExtension;
+
+type CommandTagFilterRegistry<TCommand extends AnyCommandDef> = {
+  every<const TTags extends string[]>(
+    ...tags: TTags
+  ): CommandTagFilterRegistry<FilterAllTags<TCommand, TTags>>;
+  some<const TTags extends string[]>(
+    ...tags: TTags
+  ): CommandTagFilterRegistry<FilterAnyTags<TCommand, TTags>>;
+  exact<const TTags extends string[]>(
+    ...tags: TTags
+  ): CommandTagFilterRegistry<FilterExactTags<TCommand, TTags>>;
+  without<const TTags extends string[]>(
+    ...tags: TTags
+  ): CommandTagFilterRegistry<FilterWithoutTags<TCommand, TTags>>;
+  toArray(): TCommand[];
+};
+
+type CommandKeyFilterRegistry<TCommands extends CommandMap> = {
+  pick<const TInput extends CommandInput<TCommands>>(
+    input: TInput,
+  ): CommandKeyFilterRegistry<PickedCommands<TCommands, TInput>>;
+  omit<const TInput extends CommandInput<TCommands>>(
+    input: TInput,
+  ): CommandKeyFilterRegistry<OmittedCommands<TCommands, TInput>>;
+  toArray(): ValueOf<TCommands>[];
+};
+
+type CommandRegistry<TCommands extends CommandMap> = {
+  commands: TCommands;
+  keys: CommandKeyFilterRegistry<TCommands>;
+  tags: CommandTagFilterRegistry<ValueOf<TCommands>>;
+  extend<const TExtension extends CommandMap>(
+    extension: TExtension,
+  ): CommandRegistry<ExtendedCommands<TCommands, TExtension>>;
+  /** @deprecated Use `commands.keys.pick(...)` instead. */
+  pick<const TInput extends CommandInput<TCommands>>(
+    input: TInput,
+  ): CommandRegistry<PickedCommands<TCommands, TInput>>;
+  /** @deprecated Use `commands.keys.omit(...)` instead. */
+  omit<const TInput extends CommandInput<TCommands>>(
+    input: TInput,
+  ): CommandRegistry<OmittedCommands<TCommands, TInput>>;
+  toArray(): ValueOf<TCommands>[];
+};
+
+// ─── Runtime helpers ───────────────────────────────────────────────────────────
+
+function resolveKeys<TCommands extends CommandMap>(
+  input: CommandInput<TCommands>,
+): CommandKey<TCommands>[] {
+  if (Array.isArray(input)) return [...input];
+  return Object.entries(input)
+    .filter(([, enabled]) => enabled === true)
+    .map(([key]) => key as CommandKey<TCommands>);
+}
+
+function dedupe(tags: readonly string[]) {
+  return [...new Set(tags)];
+}
+
+function hasEveryTag(command: AnyCommandDef, tags: readonly string[]) {
+  return tags.every((tag) => command.tags.includes(tag));
+}
+
+function hasSomeTag(command: AnyCommandDef, tags: readonly string[]) {
+  return tags.some((tag) => command.tags.includes(tag));
+}
+
+function hasExactTags(command: AnyCommandDef, tags: readonly string[]) {
+  const ctags = dedupe(command.tags);
+  const ftags = dedupe(tags);
+  return ctags.length === ftags.length && ftags.every((t) => ctags.includes(t));
+}
+
+function injectIds<TCommands extends CommandMap>(commands: TCommands): TCommands {
+  return Object.fromEntries(
+    Object.entries(commands).map(([id, c]) => [id, { ...c, id }]),
+  ) as TCommands;
+}
+
+function pickCommands<TCommands extends CommandMap, TInput extends CommandInput<TCommands>>(
+  commands: TCommands,
+  input: TInput,
+): PickedCommands<TCommands, TInput> {
+  const keys = resolveKeys<TCommands>(input);
+  return Object.fromEntries(
+    keys.filter((k) => k in commands).map((k) => [k, commands[k]]),
+  ) as PickedCommands<TCommands, TInput>;
+}
+
+function omitCommands<TCommands extends CommandMap, TInput extends CommandInput<TCommands>>(
+  commands: TCommands,
+  input: TInput,
+): OmittedCommands<TCommands, TInput> {
+  const keys = new Set(resolveKeys<TCommands>(input));
+  return Object.fromEntries(
+    Object.entries(commands).filter(([k]) => !keys.has(k as CommandKey<TCommands>)),
+  ) as OmittedCommands<TCommands, TInput>;
+}
+
+function createTagFilterRegistry<TCommand extends AnyCommandDef>(
+  commands: TCommand[],
+): CommandTagFilterRegistry<TCommand> {
+  function apply<const TTags extends string[]>(
+    predicate: (cmd: AnyCommandDef, tags: readonly string[]) => boolean,
+  ) {
+    return (...tags: TTags) => {
+      const filtered = commands.filter((c) => predicate(c, tags));
+      return createTagFilterRegistry(filtered) as CommandTagFilterRegistry<any>;
+    };
+  }
+
+  return {
+    every: apply(hasEveryTag) as CommandTagFilterRegistry<TCommand>["every"],
+    some: apply(hasSomeTag) as CommandTagFilterRegistry<TCommand>["some"],
+    exact: apply(hasExactTags) as CommandTagFilterRegistry<TCommand>["exact"],
+    without: apply((c, ts) => !hasSomeTag(c, ts)) as CommandTagFilterRegistry<TCommand>["without"],
+    toArray() {
+      return commands;
+    },
+  };
+}
+
+function createKeyFilterRegistry<TCommands extends CommandMap>(
+  commands: TCommands,
+): CommandKeyFilterRegistry<TCommands> {
+  return {
+    pick<const TInput extends CommandInput<TCommands>>(input: TInput) {
+      return createKeyFilterRegistry(pickCommands(commands, input));
+    },
+    omit<const TInput extends CommandInput<TCommands>>(input: TInput) {
+      return createKeyFilterRegistry(omitCommands(commands, input));
+    },
+    toArray() {
+      return Object.values(commands) as ValueOf<TCommands>[];
+    },
+  };
+}
+
+function createRegistry<TCommands extends CommandMap>(
+  commands: TCommands,
+): CommandRegistry<TCommands> {
+  const withIds = injectIds(commands);
+  const keys = createKeyFilterRegistry(withIds);
+
+  return {
+    commands: withIds,
+    keys,
+    tags: createTagFilterRegistry(Object.values(withIds) as ValueOf<TCommands>[]),
+    extend<const TExtension extends CommandMap>(extension: TExtension) {
+      return createRegistry({ ...withIds, ...extension } as ExtendedCommands<
+        TCommands,
+        TExtension
+      >);
+    },
+    pick(input) {
+      return createRegistry(pickCommands(withIds, input as CommandInput<TCommands>));
+    },
+    omit(input) {
+      return createRegistry(omitCommands(withIds, input as CommandInput<TCommands>));
+    },
+    toArray() {
+      return Object.values(withIds) as ValueOf<TCommands>[];
+    },
+  } as CommandRegistry<TCommands>;
+}
+
+/**
+ * Define commands from a map of name → `CommandDef`.
+ *
+ * Returns a `CommandRegistry` with key-based and tag-based filtering, plus
+ * `extend` for composition. Filter chains are immutable — each call produces
+ * a new registry.
+ *
+ * @example
+ * const registry = defineCommands({ edit, delete, archive });
+ * registry.tags.every("danger", "table").toArray();
+ * registry.keys.omit({ delete: true }).toArray();
+ */
+export function defineCommands<TCommands extends CommandMap>(
+  commands: TCommands,
+): CommandRegistry<TCommands> {
+  return createRegistry(commands);
+}

package/src/modules/commands/lib/utils.ts

@@ -0,0 +1,10 @@
+/**
+ * Normalizes command data into an array.
+ *
+ * Use this as a command transform when the same command should support both
+ * single-item and bulk contexts. After `.transform(ensureArray)`, command
+ * callbacks can safely use array helpers like `.map` and `.every`.
+ */
+export function ensureArray<T>(data: T | T[]) {
+  return Array.isArray(data) ? data : [data];
+}