#别名配置

#类型定义

// 别名对象类型
type AliasObject = {
  $cmd?: string;
  $cwd?: string;
  $interactive?: boolean;
  $description?: string;
  [key: string]: string | AliasObject | boolean | undefined;
}

// JSON 文件格式类型
type AliasFileJSON = {
  $priority?: number;      // 优先级，默认本地=10 全局=0
  $cwd?: string;           // 文件级 / 分组级工作目录，子别名自动继承
  $interactive?: boolean;   // 文件级 / 分组级交互模式，子别名自动继承
  $paths?: string[];        // 文件级 PATH 目录列表，子别名自动继承
  [key: string]: string | AliasObject | number | boolean | undefined;
};

#别名对象类型

#Key 命名规则

#普通字段

• key 不能包含 @ 或 .，违规则被忽略
• 支持中文 key 名
• key 支持嵌套分组（dict），通过 . 分隔符访问

#前缀系统字段

通过 $ 前缀系统字段配置别名：

#工作目录 cwd

支持三级继承：文件级 → 分组级 → 别名级，优先级逐级递增（别名自己的 $cwd 覆盖分组级，分组级覆盖文件级）。

{
  "install": {
    "$cmd": "npm i",
    "$cwd": "/project/web"
  }
}

{
  "services": {
    "$cwd": "/project",
    "install": "npm i",
    "web": {
      "$cwd": "/project/web",
      "dev": "pnpm dev",
      "build": "pnpm build"
    }
  }
}

{
  "$cwd": "/project/web",
  "install": "npm i",
  "start": {
    "$cmd": "pnpm dev",
    "$cwd": "/project/web/frontend"
  }
}

#交互模式

交互模式适合需要逐步确认参数或执行危险命令的场景。开启后逐项提示输入占位符值，最后确认执行。

$interactive 同样支持三级继承：文件级 → 分组级 → 别名级。

{
  "deploy": {
    "$cmd": "deploy --env {env} --tag {version}",
    "$interactive": true
  }
}

byk deploy
# ~ deploy --env {env} --tag {version}
#   env: staging
#   version: v2.0
# ~ deploy --env staging --tag v2.0     ← 绿色粗体
#    Press Enter to execute...

{
  "danger": {
    "$interactive": true,
    "delete": "rm -rf {path}",
    "migrate": {
      "$cmd": "db migrate --env {env}",
      "$interactive": false
    }
  }
}

{
  "$interactive": true,
  "deploy": "deploy --env {env}",
  "build": {
    "$cmd": "pnpm build",
    "$interactive": false
  }
}

#描述文本

$description 用于在帮助页中显示描述文本，替代默认的命令映射显示。适合命令本身不够直观的场景。

不可继承 — 仅对当前别名生效，不会从文件级或分组级继承。

{
  "更新版本号": {
    "$interactive": true,
    "$cmd": "cz bump {version}",
    "$description": "交互式更新版本号"
  }
}

帮助页显示效果：

Aliases:
  发布.更新版本号    交互式更新版本号

未设置 $description 时，帮助页默认显示命令映射：

Aliases:
  发布.更新版本号    cz bump {version}

#PATH 目录

$paths 用于在执行别名前将指定目录前置到 PATH 环境变量，使别名可以访问这些目录下的可执行文件。

仅支持文件级设置，所有子别名自动继承。

{
  "$paths": ["./scripts", "~/tools/bin"],
  "deploy": "deploy.sh",
  "check": "lint.sh"
}

执行 byk deploy 时，./scripts 和 ~/tools/bin 会被前置到 PATH，因此可以直接调用 deploy.sh 而无需指定完整路径。

#调用示例

{
  "dev": "vite",

  "install": {
    "$cmd": "npm i",
    "$cwd": "/Users/coke/project/web"
  },

  "deploy": {
    "$cmd": "deploy --env {env}",
    "$interactive": true
  }
}

byk install    
# 等价于在/Users/coke/project/web 运行 npm i

{
  "开发": {
    "测试": "pytest -q",
    "构建": {
      "$cmd": "pnpm run build",
      "后端": "python -m build"
    }
  },
  "清理": "find . -type d ..."
}

byk 开发.测试           # 运行 pytest -q
byk 开发.构建           # 运行 pnpm run build
byk 开发.构建.前端       # 运行pnpm run build
byk 清理               # find . -type d ...

#别名文件

byk 扫描当前目录和全局目录下所有 *.byk.json 文件，自动合并为一个统一的别名空间。

#文件命名规范

#目录结构

本地目录（当前工作目录，不递归扫描子目录）：

全局目录：

#优先级

所有文件合并为一个统一的 key 空间，高优先级文件的同名 key 覆盖低优先级。

#默认优先级

同优先级文件按文件名字母序加载，后者覆盖前者，行为确定。

#自定义优先级

通过 $priority 字段声明，可打破默认规则：

{
  "$priority": 20,
  "build": "vite build",
  "dev": "vite"
}

#精确执行语法

日常使用直接 byk <key>。当需要精确指定执行哪个文件中的别名时：

约定：

• @ 语法只做文件路由，不做任何 fallback
• 文件不存在 → 报错，不自动查找其他位置
• 文件存在但 key 不存在 → 报错
• Key 名不能包含 @，违反则静默跳过

# 本地文件不存在
byk @release.build
# Error: local file "release.byk.json" not found

# 全局文件不存在
byk @@work.deploy
# Error: global file "work.byk.json" not found

# key 不存在
byk @release.cleanup
# Error: alias "cleanup" not found in release.byk.json