akanjs 0.0.1 → 2.0.0-beta.1

package/devkit/commandDecorators/command.ts

@@ -0,0 +1,314 @@
+import { confirm, input, select } from "@inquirer/prompts";
+import { Logger } from "akanjs/common";
+import chalk from "chalk";
+import { type Command, program } from "commander";
+
+import { FileSys, getDirname, type PackageJson } from "..";
+import { AppExecutor, Executor, LibExecutor, ModuleExecutor, PkgExecutor, WorkspaceExecutor } from "../executors";
+import { type ArgMeta, getArgMetas, type InternalArgMeta } from "./argMeta";
+import { CommandContainer } from "./dependencyBuilder";
+import { formatCommandHelp, formatHelp } from "./helpFormatter";
+import { type CommandCls, getTargetMetas } from "./targetMeta";
+
+const camelToKebabCase = (str: string) => str.replace(/([A-Z])/g, "-$1").toLowerCase();
+
+const handleOption = (programCommand: Command, argMeta: ArgMeta) => {
+  const {
+    type,
+    flag = argMeta.name.slice(0, 1).toLowerCase(),
+    desc = argMeta.name,
+    example,
+    enum: enumChoices,
+    ask,
+  } = argMeta.argsOption;
+  const kebabName = camelToKebabCase(argMeta.name);
+  const choices = enumChoices?.map((choice: string | number | { label: string; value: string | number | boolean }) =>
+    typeof choice === "object"
+      ? { value: choice.value, name: choice.label }
+      : { value: choice, name: choice.toString() },
+  );
+  programCommand.option(
+    `-${flag}, --${kebabName}${type === "boolean" ? " [boolean]" : ` <${kebabName}>`}`,
+    `${desc}${ask ? ` (${ask})` : ""}${example ? ` (example: ${example})` : ""}${choices ? ` (choices: ${choices.map((choice) => choice.name).join(", ")})` : ""}`,
+  );
+  return programCommand;
+};
+const handleArgument = (programCommand: Command, argMeta: ArgMeta) => {
+  const kebabName = camelToKebabCase(argMeta.name);
+  programCommand.argument(
+    `[${kebabName}]`,
+    `${argMeta.argsOption.desc}${argMeta.argsOption.example ? ` (example: ${argMeta.argsOption.example})` : ""}`,
+  );
+  return programCommand;
+};
+
+const convertArgValue = (value: string | boolean, type: "string" | "number" | "boolean") => {
+  if (type === "string") return value as string;
+  else if (type === "number") return Number(value);
+  else return value === true || value === "true";
+};
+
+const getOptionValue = async (argMeta: ArgMeta, opt: Record<string, unknown>) => {
+  const {
+    name,
+    argsOption: { enum: enumChoices, default: defaultValue, type, desc, nullable, example, ask },
+  } = argMeta;
+  if (opt[argMeta.name] !== undefined) return convertArgValue(opt[argMeta.name] as string, type ?? "string");
+  else if (defaultValue !== undefined) return defaultValue;
+  else if (nullable) return null;
+
+  if (enumChoices) {
+    const choices = enumChoices.map((choice: string | number | { label: string; value: string | number | boolean }) =>
+      typeof choice === "object"
+        ? { value: choice.value, name: choice.label }
+        : { value: choice, name: choice.toString() },
+    );
+    const choice = await select({ message: ask ?? desc ?? `Select the ${name} value`, choices });
+    return choice;
+  } else if (type === "boolean") {
+    const message = ask ?? desc ?? `Do you want to set ${name}? ${desc ? ` (${desc})` : ""}: `;
+    return await confirm({ message });
+  } else {
+    const message = ask
+      ? `${ask}: `
+      : desc
+        ? `${desc}: `
+        : `Enter the ${name} value${example ? ` (example: ${example})` : ""}: `;
+    if (argMeta.argsOption.nullable) return await input({ message });
+    else return convertArgValue(await input({ message }), type ?? "string");
+  }
+};
+
+const getArgumentValue = async (argMeta: ArgMeta, value: string | undefined) => {
+  const {
+    name,
+    argsOption: { default: defaultValue, type, desc, nullable, example, ask },
+  } = argMeta;
+  if (value !== undefined) return convertArgValue(value, type ?? "string");
+  else if (defaultValue !== undefined) return defaultValue;
+  else if (nullable) return null;
+
+  const message = ask
+    ? `${ask}: `
+    : desc
+      ? `${desc}: `
+      : `Enter the ${name} value${example ? ` (example: ${example})` : ""}: `;
+  return convertArgValue(await input({ message }), type ?? "string");
+};
+
+const assertCurrentDirectoryIsWorkspaceRoot = async () => {
+  const cwd = process.cwd();
+  const [hasPackageJson, hasTsConfig, hasEnv] = await Promise.all([
+    FileSys.fileExists(`${cwd}/package.json`),
+    FileSys.fileExists(`${cwd}/tsconfig.json`),
+    FileSys.fileExists(`${cwd}/.env`),
+  ]);
+  if (hasPackageJson && hasTsConfig && hasEnv) return;
+
+  throw new Error(
+    [
+      "Akan CLI commands must be run from the workspace root.",
+      `Current directory: ${cwd}`,
+      "Move to the directory that contains package.json, tsconfig.json, and .env, then run the command again.",
+    ].join("\n"),
+  );
+};
+
+const getInternalArgumentValue = async (
+  argMeta: InternalArgMeta,
+  value: string | undefined,
+  workspace: WorkspaceExecutor,
+) => {
+  if (argMeta.type === "Workspace") return workspace;
+  const sysType = argMeta.type.toLowerCase();
+  const [appNames, libNames, pkgNames] = await workspace.getExecs();
+  if (sysType === "sys") {
+    if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
+    else if (value && libNames.includes(value)) return LibExecutor.from(workspace, value);
+    else {
+      const sysName = await select<string>({
+        message: `Select the App or Lib name`,
+        choices: [...appNames, ...libNames],
+      });
+      if (appNames.includes(sysName)) return AppExecutor.from(workspace, sysName);
+      else if (libNames.includes(sysName)) return LibExecutor.from(workspace, sysName);
+      else throw new Error(`Invalid system name: ${sysName}`);
+    }
+  } else if (sysType === "exec") {
+    if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
+    else if (value && libNames.includes(value)) return LibExecutor.from(workspace, value);
+    else if (value && pkgNames.includes(value)) return PkgExecutor.from(workspace, value);
+    else {
+      const execName = await select<string>({
+        message: `Select the App or Lib or Pkg name`,
+        choices: [...appNames, ...libNames, ...pkgNames],
+      });
+      if (appNames.includes(execName)) return AppExecutor.from(workspace, execName);
+      else if (libNames.includes(execName)) return LibExecutor.from(workspace, execName);
+      else if (pkgNames.includes(execName)) return PkgExecutor.from(workspace, execName);
+      else throw new Error(`Invalid system name: ${execName}`);
+    }
+  } else if (sysType === "app") {
+    if (value && appNames.includes(value)) return AppExecutor.from(workspace, value);
+    const appName = await select<string>({ message: `Select the ${sysType} name`, choices: appNames });
+    return AppExecutor.from(workspace, appName);
+  } else if (sysType === "lib") {
+    if (value && libNames.includes(value)) return LibExecutor.from(workspace, value);
+    const libName = await select<string>({ message: `Select the ${sysType} name`, choices: libNames });
+    return LibExecutor.from(workspace, libName);
+  } else if (sysType === "pkg") {
+    const pkgs = await workspace.getPkgs();
+    if (value && pkgs.includes(value)) return PkgExecutor.from(workspace, value);
+    const pkgName = await select<string>({ message: `Select the ${sysType} name`, choices: pkgs });
+    return PkgExecutor.from(workspace, pkgName);
+  } else if (sysType === "module") {
+    if (value) {
+      const [sysName, moduleName] = value.split(":");
+      if (!sysName || !moduleName) throw new Error(`Invalid module name: ${value}`);
+      if (appNames.includes(sysName)) {
+        const app = AppExecutor.from(workspace, sysName);
+        const modules = await app.getModules();
+        if (modules.includes(moduleName)) return ModuleExecutor.from(app, moduleName);
+        else throw new Error(`Invalid module name: ${moduleName}`);
+      } else if (libNames.includes(sysName)) {
+        const lib = LibExecutor.from(workspace, sysName);
+        const modules = await lib.getModules();
+        if (modules.includes(moduleName)) return ModuleExecutor.from(lib, moduleName);
+      } else throw new Error(`Invalid system name: ${sysName}`);
+    }
+    const { type, name } = await select<{ type: "app" | "lib"; name: string }>({
+      message: `select the App or Lib name`,
+      choices: [
+        ...appNames.map((name) => ({ name, value: { type: "app" as const, name } })),
+        ...libNames.map((name) => ({ name, value: { type: "lib" as const, name } })),
+      ],
+    });
+    const executor = type === "app" ? AppExecutor.from(workspace, name) : LibExecutor.from(workspace, name);
+    const modules = await executor.getModules();
+    const moduleName = await select<string>({
+      message: `Select the module name`,
+      choices: modules.map((name) => ({ name: `${executor.name}:${name}`, value: name })),
+    });
+    return ModuleExecutor.from(executor, moduleName);
+  } else throw new Error(`Invalid system type: ${argMeta.type}`);
+};
+
+export const runCommands = async (...commands: CommandCls[]) => {
+  process.on("unhandledRejection", (error) => {
+    process.exit(1);
+  });
+  const __dirname = getDirname(import.meta.url);
+  const hasPackageJson = await FileSys.fileExists(`${__dirname}/../package.json`);
+  process.env.AKAN_VERSION = hasPackageJson
+    ? (await FileSys.readJson<PackageJson>(`${__dirname}/../package.json`)).version
+    : "0.0.1";
+
+  const hasHelpFlag = process.argv.includes("--help") || process.argv.includes("-h");
+  const hasCommand = process.argv.length > 2 && !process.argv[2]?.startsWith("-");
+
+  if (hasHelpFlag || !hasCommand) {
+    if (process.argv.length === 2 || (process.argv.length === 3 && hasHelpFlag)) {
+      
+      Logger.rawLog(formatHelp(commands, process.env.AKAN_VERSION));
+      process.exit(0);
+    }
+  }
+
+  program.version(process.env.AKAN_VERSION).description("Akan CLI").configureHelp({
+    helpWidth: 100,
+  });
+  const installedAkanPackageJson = (await FileSys.fileExists("./node_modules/akanjs/package.json"))
+    ? await FileSys.readJson<PackageJson>("./node_modules/akanjs/package.json")
+    : null;
+  if (installedAkanPackageJson && installedAkanPackageJson.version !== process.env.AKAN_VERSION) {
+    Logger.rawLog(
+      chalk.yellow(
+        `
+Akan CLI version is mismatch with installed package. ${process.env.AKAN_VERSION} (global) vs ${installedAkanPackageJson.version} (akanjs)
+It may cause unexpected behavior. Run \`akan update\` to update latest akanjs.`,
+      ),
+    );
+  }
+
+  for (const command of commands) {
+    const targetMetas = getTargetMetas(command);
+    for (const targetMeta of targetMetas) {
+      const kebabKey = camelToKebabCase(targetMeta.key);
+      const commandNames =
+        targetMeta.targetOption.short === true
+          ? [
+              kebabKey,
+              typeof targetMeta.targetOption.short === "string"
+                ? targetMeta.targetOption.short
+                : kebabKey
+                    .split("-")
+                    .map((s) => s.slice(0, 1))
+                    .join(""),
+            ]
+          : [kebabKey];
+      for (const commandName of commandNames) {
+        let programCommand = program.command(commandName, {
+          hidden: targetMeta.targetOption.devOnly,
+        });
+        const [allArgMetas] = getArgMetas(command, targetMeta.key);
+        for (const argMeta of allArgMetas) {
+          if (argMeta.type === "Option") programCommand = handleOption(programCommand, argMeta);
+          else if (argMeta.type === "Argument") programCommand = handleArgument(programCommand, argMeta);
+          else if (argMeta.type === "Workspace") continue;
+          else if (argMeta.type === "Module") {
+            programCommand = programCommand.argument(
+              `[sys-name:module-name]`,
+              `${argMeta.type} in this workspace (apps|libs)/<sys-name>/lib/<module-name>`,
+            );
+          } else {
+            const sysType = argMeta.type.toLowerCase();
+            programCommand = programCommand.argument(
+              `[${sysType}]`,
+              `${sysType} in this workspace ${sysType}s/<${sysType}Name>`,
+            );
+          }
+        }
+        programCommand = programCommand.option(`-v, --verbose [boolean]`, `verbose output`);
+
+        programCommand.helpInformation = () => {
+          return formatCommandHelp(command, targetMeta.key);
+        };
+
+        programCommand.action(async (...args: unknown[]) => {
+          Logger.rawLog();
+          const cmdArgs = args.slice(0, args.length - 2);
+          const opt = args[args.length - 2] as Record<string, unknown>;
+          const commandArgs = [] as unknown[];
+          if (targetMeta.targetOption.runsOnWorkspaceRoot) await assertCurrentDirectoryIsWorkspaceRoot();
+          const workspace = WorkspaceExecutor.fromRoot();
+          for (const argMeta of allArgMetas) {
+            if (argMeta.type === "Option") commandArgs[argMeta.idx] = await getOptionValue(argMeta, opt);
+            else if (argMeta.type === "Argument")
+              commandArgs[argMeta.idx] = await getArgumentValue(argMeta, cmdArgs[argMeta.idx] as string);
+            else
+              commandArgs[argMeta.idx] = await getInternalArgumentValue(
+                argMeta as InternalArgMeta,
+                cmdArgs[argMeta.idx] as string,
+                workspace,
+              );
+            
+            if (commandArgs[argMeta.idx] instanceof AppExecutor)
+              process.env.AKAN_PUBLIC_APP_NAME = (commandArgs[argMeta.idx] as AppExecutor).name;
+            if ((opt as { verbose?: boolean }).verbose) Executor.setVerbose(true);
+          }
+          const cmd = CommandContainer.get(command);
+
+          try {
+            await targetMeta.handler.call(cmd, ...commandArgs);
+            Logger.rawLog();
+          } catch (e) {
+            const errMsg = e instanceof Error ? e.message : typeof e === "string" ? e : JSON.stringify(e);
+            Logger.rawLog(`\n${chalk.red(errMsg)}`);
+            throw e;
+          }
+        });
+      }
+    }
+  }
+  await program.parseAsync(process.argv);
+};

package/devkit/commandDecorators/commandBuilder.ts

@@ -0,0 +1,188 @@
+import type { ArgMeta, ArgsOption, InternalArgMeta, InternalArgToken, PrimitiveArgType } from "./argMeta";
+import { normalizePrimitiveArgType } from "./argMeta";
+import { assertUniqueDependencies, type DependencyInstanceMap, injectDependencies } from "./dependencyBuilder";
+import { COMMAND_META, type CommandCls, type TargetMeta, type TargetOption } from "./targetMeta";
+import type { DependencyCls, DependencyKey } from "./types";
+
+type PrimitiveValue<T extends PrimitiveArgType> = T extends StringConstructor
+  ? string
+  : T extends NumberConstructor
+    ? number
+    : boolean;
+type ArgsOptionInput = Record<string, never> | ArgsOption;
+type MaybeNullable<Value, Option extends ArgsOptionInput> = Option extends { nullable: true } ? Value | null : Value;
+type AddArg<Params extends unknown[], Type extends PrimitiveArgType, Option extends ArgsOptionInput> = [
+  ...Params,
+  MaybeNullable<PrimitiveValue<Type>, Option>,
+];
+type AddInternalArg<Params extends unknown[], Token extends InternalArgToken> = [...Params, Token["_value"]];
+type AddInternalArgs<Params extends unknown[], Tokens extends readonly InternalArgToken[]> = Tokens extends readonly [
+  infer Head extends InternalArgToken,
+  ...infer Rest extends InternalArgToken[],
+]
+  ? AddInternalArgs<AddInternalArg<Params, Head>, Rest>
+  : Params;
+type CommandHandler<Deps extends readonly DependencyCls[], Params extends unknown[]> = (
+  this: DependencyInstanceMap<Deps>,
+  ...args: Params
+) => unknown | Promise<unknown>;
+
+class TargetBuilder<Deps extends readonly DependencyCls[], Params extends unknown[] = []> {
+  readonly #args: (ArgMeta | InternalArgMeta)[];
+
+  constructor(
+    private readonly targetOption: TargetOption,
+    args: (ArgMeta | InternalArgMeta)[] = [],
+  ) {
+    this.#args = args;
+  }
+
+  arg<Type extends PrimitiveArgType, Option extends ArgsOptionInput = Record<string, never>>(
+    name: string,
+    type: Type,
+    argsOption: Option = {} as Option,
+  ): TargetBuilder<Deps, AddArg<Params, Type, Option>> {
+    return new TargetBuilder(this.targetOption, [
+      ...this.#args,
+      {
+        name,
+        argsOption: { ...argsOption, type: normalizePrimitiveArgType(type) },
+        key: "",
+        idx: this.#args.length,
+        type: "Argument",
+      },
+    ]);
+  }
+
+  option<Type extends PrimitiveArgType, Option extends ArgsOptionInput = Record<string, never>>(
+    name: string,
+    type: Type,
+    argsOption: Option = {} as Option,
+  ): TargetBuilder<Deps, AddArg<Params, Type, Option>> {
+    return new TargetBuilder(this.targetOption, [
+      ...this.#args,
+      {
+        name,
+        argsOption: { ...argsOption, type: normalizePrimitiveArgType(type) },
+        key: "",
+        idx: this.#args.length,
+        type: "Option",
+      },
+    ]);
+  }
+
+  with<Tokens extends readonly InternalArgToken[]>(
+    ...tokens: Tokens
+  ): TargetBuilder<Deps, AddInternalArgs<Params, Tokens>> {
+    return new TargetBuilder(this.targetOption, [
+      ...this.#args,
+      ...tokens.map(
+        (token, offset) =>
+          ({
+            key: "",
+            idx: this.#args.length + offset,
+            type: token.type,
+          }) satisfies InternalArgMeta,
+      ),
+    ]);
+  }
+
+  exec(handler: CommandHandler<Deps, Params>) {
+    return {
+      args: this.#args,
+      handler: handler as TargetMeta["handler"],
+      targetOption: this.targetOption,
+    };
+  }
+}
+
+type TargetDefinition = ReturnType<TargetBuilder<readonly DependencyCls[], unknown[]>["exec"]>;
+type CommandBuilderContext<Deps extends readonly DependencyCls[]> = {
+  public: (targetOption?: Omit<TargetOption, "type">) => TargetBuilder<Deps>;
+  cloud: (targetOption?: Omit<TargetOption, "type">) => TargetBuilder<Deps>;
+  dev: (targetOption?: Omit<TargetOption, "type">) => TargetBuilder<Deps>;
+  arg: <Type extends PrimitiveArgType, Option extends ArgsOptionInput = Record<string, never>>(
+    name: string,
+    type: Type,
+    argsOption?: Option,
+  ) => ArgMeta;
+  option: <Type extends PrimitiveArgType, Option extends ArgsOptionInput = Record<string, never>>(
+    name: string,
+    type: Type,
+    argsOption?: Option,
+  ) => ArgMeta;
+};
+type CommandBuilder<Deps extends readonly DependencyCls[]> = (
+  context: CommandBuilderContext<Deps>,
+) => Record<string, TargetDefinition>;
+
+const createTarget =
+  <Deps extends readonly DependencyCls[]>(type: TargetOption["type"]) =>
+  (targetOption: Omit<TargetOption, "type"> = {}) =>
+    new TargetBuilder<Deps>({ runsOnWorkspaceRoot: true, ...targetOption, type });
+
+const createContext = <Deps extends readonly DependencyCls[]>(): CommandBuilderContext<Deps> => ({
+  public: createTarget<Deps>("public"),
+  cloud: createTarget<Deps>("cloud"),
+  dev: createTarget<Deps>("dev"),
+  arg: (name, type, argsOption) => ({
+    name,
+    argsOption: { ...(argsOption ?? {}), type: normalizePrimitiveArgType(type) },
+    key: "",
+    idx: -1,
+    type: "Argument",
+  }),
+  option: (name, type, argsOption) => ({
+    name,
+    argsOption: { ...(argsOption ?? {}), type: normalizePrimitiveArgType(type) },
+    key: "",
+    idx: -1,
+    type: "Option",
+  }),
+});
+
+const buildCommandMeta = (definitions: Record<string, TargetDefinition>) => {
+  const commandMeta = new Map<string, TargetMeta>();
+  for (const [key, definition] of Object.entries(definitions)) {
+    commandMeta.set(key, {
+      key,
+      args: definition.args.map((arg) => ({ ...arg, key })),
+      handler: definition.handler,
+      targetOption: definition.targetOption,
+    });
+  }
+  return commandMeta;
+};
+
+export function command<RefName extends string, Deps extends readonly DependencyCls[]>(
+  refName: RefName,
+  deps: Deps,
+  builder: CommandBuilder<Deps>,
+): CommandCls<DependencyInstanceMap<Deps>, DependencyKey<RefName, "command">>;
+export function command<RefName extends string>(
+  refName: RefName,
+  builder: CommandBuilder<[]>,
+): CommandCls<DependencyInstanceMap<[]>, DependencyKey<RefName, "command">>;
+export function command<RefName extends string, Deps extends readonly DependencyCls[]>(
+  refName: RefName,
+  depsOrBuilder: Deps | CommandBuilder<[]>,
+  builder?: CommandBuilder<Deps>,
+) {
+  const deps = (Array.isArray(depsOrBuilder) ? depsOrBuilder : []) as unknown as Deps;
+  const commandBuilder = (Array.isArray(depsOrBuilder) ? builder : depsOrBuilder) as CommandBuilder<Deps>;
+  assertUniqueDependencies(deps);
+  const commandMeta = buildCommandMeta(commandBuilder(createContext<Deps>()));
+
+  class CommandBase {
+    static readonly refName = refName;
+    static readonly dependencyKind = "command";
+    static readonly dependencyKey = `${refName}Command` as const;
+    static readonly [COMMAND_META] = commandMeta;
+
+    constructor() {
+      injectDependencies(this, deps);
+    }
+  }
+
+  return CommandBase as unknown as CommandCls<DependencyInstanceMap<Deps>, DependencyKey<RefName, "command">>;
+}

package/devkit/commandDecorators/commandMeta.ts

@@ -0,0 +1,6 @@
+import type { Cls } from "./types";
+
+export const Commands = () => {
+  return (target: Cls) => {
+  };
+};

package/devkit/commandDecorators/dependencyBuilder.ts

@@ -0,0 +1,100 @@
+import type { DependencyCls, DependencyKey, DependencyKind } from "./types";
+
+type UnionToIntersection<Union> = (Union extends unknown ? (value: Union) => void : never) extends (
+  value: infer Intersection,
+) => void
+  ? Intersection
+  : never;
+
+type DependencyToField<Dep> = Dep extends DependencyCls<infer Instance, infer Key> ? { [K in Key]: Instance } : never;
+
+export type DependencyInstanceMap<Deps extends readonly DependencyCls[]> = [Deps[number]] extends [never]
+  ? Record<PropertyKey, never>
+  : UnionToIntersection<DependencyToField<Deps[number]>>;
+
+const capitalize = (value: string) => value.slice(0, 1).toUpperCase() + value.slice(1);
+
+const createDependencyKey = <RefName extends string, Kind extends DependencyKind>(
+  refName: RefName,
+  kind: Kind,
+): DependencyKey<RefName, Kind> => `${refName}${capitalize(kind)}` as DependencyKey<RefName, Kind>;
+
+export class CommandContainer {
+  static #instances = new Map<DependencyCls, unknown>();
+  static #resolving = new Set<DependencyCls>();
+
+  static get<T>(dep: DependencyCls<T>): T {
+    const instance = CommandContainer.#instances.get(dep);
+    if (instance) return instance as T;
+    if (CommandContainer.#resolving.has(dep)) throw new Error(`Circular command dependency: ${dep.name}`);
+    CommandContainer.#resolving.add(dep);
+    try {
+      const nextInstance = new dep();
+      CommandContainer.#instances.set(dep, nextInstance);
+      return nextInstance;
+    } finally {
+      CommandContainer.#resolving.delete(dep);
+    }
+  }
+
+  static clear() {
+    CommandContainer.#instances.clear();
+    CommandContainer.#resolving.clear();
+  }
+}
+
+export const getDependencyKey = (dep: DependencyCls) => dep.dependencyKey;
+
+export const assertUniqueDependencies = (deps: readonly DependencyCls[]) => {
+  const keys = new Map<string, DependencyCls>();
+  const classes = new Set<DependencyCls>();
+  for (const dep of deps) {
+    if (classes.has(dep)) throw new Error(`Duplicate command dependency class: ${dep.name}`);
+    classes.add(dep);
+    const key = getDependencyKey(dep);
+    const existing = keys.get(key);
+    if (existing) throw new Error(`Duplicate command dependency key "${key}": ${existing.name}, ${dep.name}`);
+    keys.set(key, dep);
+  }
+};
+
+export const injectDependencies = <Deps extends readonly DependencyCls[]>(target: object, deps: Deps) => {
+  assertUniqueDependencies(deps);
+  for (const dep of deps) {
+    Object.defineProperty(target, getDependencyKey(dep), {
+      configurable: true,
+      enumerable: false,
+      value: CommandContainer.get(dep),
+      writable: false,
+    });
+  }
+  return target as typeof target & DependencyInstanceMap<Deps>;
+};
+
+export const runner = <RefName extends string>(refName: RefName) => {
+  class RunnerBase {
+    static readonly refName = refName;
+    static readonly dependencyKind = "runner";
+    static readonly dependencyKey = createDependencyKey(refName, "runner");
+  }
+
+  return RunnerBase as unknown as DependencyCls<InstanceType<typeof RunnerBase>, DependencyKey<RefName, "runner">>;
+};
+
+export const script = <RefName extends string, Deps extends readonly DependencyCls[]>(
+  refName: RefName,
+  deps: Deps = [] as unknown as Deps,
+) => {
+  assertUniqueDependencies(deps);
+  class ScriptBase {
+    static readonly refName = refName;
+    static readonly dependencyKind = "script";
+    static readonly dependencyKey = createDependencyKey(refName, "script");
+
+    constructor() {
+      injectDependencies(this, deps);
+    }
+  }
+
+  return ScriptBase as unknown as DependencyCls<DependencyInstanceMap<Deps>, DependencyKey<RefName, "script">>;
+};