colyn-cli 3.1.4

package/dist/types/plugin.d.ts

@@ -0,0 +1,200 @@
+/**
+ * 工具链插件类型定义
+ */
+/**
+ * repairSettings 的上下文对象
+ *
+ * 在 colyn init / colyn repair 时传入各插件的 repairSettings 方法。
+ */
+export interface RepairSettingsContext {
+    /** 项目根目录（.colyn 的父目录） */
+    projectRoot: string;
+    /** 主分支目录路径（包含项目代码文件） */
+    worktreePath: string;
+    /** 当前已保存的工具链专属配置（来自 settings.toolchain.settings 或 projects[i].toolchain.settings） */
+    currentSettings: Record<string, unknown>;
+    /** 是否处于非交互式模式（如 CI 环境，不能弹出交互提问） */
+    nonInteractive: boolean;
+}
+/**
+ * 插件命令执行失败时抛出的异常
+ *
+ * lint / build / install / publish / init 失败时插件必须抛出此类型，
+ * 以便 PluginManager 在 verbose 模式下将命令输出展示给用户。
+ */
+export declare class PluginCommandError extends Error {
+    /** 失败命令的完整输出（stdout + stderr） */
+    readonly output: string;
+    constructor(message: string, output: string);
+}
+/**
+ * 端口分配配置
+ * null 表示该工具链不需要端口（如库项目、CLI 工具）
+ */
+export interface PortConfig {
+    /** 配置文件中的键名，如 "PORT"、"server.port" */
+    key: string;
+    /** 默认端口号 */
+    defaultPort: number;
+}
+/**
+ * 工具链插件接口
+ *
+ * 所有方法均为可选，插件只需实现其关心的扩展点。
+ * 未实现的扩展点由 colyn 核心跳过或使用默认行为。
+ */
+export interface ToolchainPlugin {
+    /** 插件唯一标识符，如 'npm' | 'maven' | 'gradle' | 'pip' */
+    name: string;
+    /** 用于界面展示的名称，如 'Node.js (npm)' */
+    displayName: string;
+    /**
+     * 检测项目是否使用此工具链
+     *
+     * 通常通过扫描项目特定文件（package.json / pom.xml 等）判断。
+     *
+     * @param worktreePath 执行检测的目录路径
+     * @returns true 表示匹配，false 表示不匹配
+     */
+    detect(worktreePath: string): boolean | Promise<boolean>;
+    /**
+     * 返回端口分配配置
+     *
+     * 返回 null 表示该工具链不需要端口（如库项目）。
+     * colyn 根据返回值决定是否为该插件分配 worktree 端口。
+     */
+    portConfig?(): PortConfig | null;
+    /**
+     * 读取配置文件，返回统一键值对
+     *
+     * 执行策略：按插件注册顺序依次尝试，第一个返回非 null 的结果生效。
+     * 插件自行决定从 worktreePath 下的哪个文件读取（如 .env.local）。
+     *
+     * @param worktreePath worktree 目录路径
+     * @returns 键值对，或 null 表示读取失败（文件不存在或格式不支持）
+     */
+    readRuntimeConfig?(worktreePath: string): Promise<Record<string, string> | null>;
+    /**
+     * 将键值对写入配置文件（支持原生格式）
+     *
+     * @param worktreePath worktree 目录路径（由插件自行决定写入哪个配置文件）
+     * @param config 要写入的键值对
+     */
+    writeRuntimeConfig?(worktreePath: string, config: Record<string, string>): Promise<void>;
+    /**
+     * 返回 dev server 启动命令
+     *
+     * 供 terminal session 插件调用，以便在终端中自动启动 dev server。
+     * 工具链插件只负责返回命令，不负责执行。
+     *
+     * @param worktreePath 执行命令检测的目录路径
+     * @returns 命令数组（如 ['npm', 'run', 'dev']），或 null 表示无 dev server
+     */
+    devServerCommand?(worktreePath: string): string[] | null | Promise<string[] | null>;
+    /**
+     * 返回运行时配置文件名
+     *
+     * colyn 会确保该文件名被添加到 .gitignore。
+     * 返回 null 表示该工具链无运行时配置文件需要忽略。
+     *
+     * @returns 文件名（如 '.env.local'、'application-local.properties'），或 null
+     */
+    getRuntimeConfigFileName?(): string | null;
+    /**
+     * 检查并修复插件专属项目配置
+     *
+     * 在 `colyn init` 和 `colyn repair` 时调用。
+     * 插件应扫描项目结构，识别必要的配置项（如 Xcode 的 scheme / destination）。
+     * 如果无法自动确定，可通过交互式提问让用户填写。
+     * 结果由 colyn 保存到 `.colyn/settings.json` 的 `toolchain.settings` 或 `projects[i].toolchain.settings` 字段。
+     *
+     * **典型用途**：Xcode 插件通过此方法询问用户 scheme 和 destination，
+     * 供后续 `build` 命令使用。
+     *
+     * @param context 包含 worktreePath、当前已保存工具链配置、非交互模式标志
+     * @returns 工具链专属配置键值对（将完整覆盖对应 toolchain.settings）
+     */
+    repairSettings?(context: RepairSettingsContext): Promise<Record<string, unknown>>;
+    /**
+     * 安装项目依赖
+     *
+     * 触发场景：
+     * - `colyn add` 后：在新建 worktree 目录下安装依赖
+     * - `colyn release` 前：在主分支目录下安装依赖，确保依赖最新
+     *
+     * @param worktreePath 执行安装的目录路径（worktree 或主分支目录）
+     * @throws {PluginCommandError} 安装失败时，output 包含命令输出
+     */
+    install?(worktreePath: string): Promise<void>;
+    /**
+     * 执行代码质量检查
+     *
+     * 触发时机：`colyn merge` 前（预检）和 `colyn release` 前
+     *
+     * **缺失处理**：如果工具链没有 lint 脚本，插件应**静默跳过**（不抛出异常）。
+     *
+     * @param worktreePath 执行检查的目录路径
+     * @throws {PluginCommandError} lint 失败时，output 包含命令输出
+     */
+    lint?(worktreePath: string): Promise<void>;
+    /**
+     * 构建项目
+     *
+     * 在 `colyn release` 时调用。不实现则跳过。
+     *
+     * **缺失处理**：如果工具链没有 build 脚本，插件应**静默跳过**（不抛出异常）。
+     *
+     * @param worktreePath 执行构建的目录路径
+     * @throws {PluginCommandError} build 失败时，output 包含命令输出
+     */
+    build?(worktreePath: string): Promise<void>;
+    /**
+     * 读取项目当前版本号
+     *
+     * 在 `colyn release` 时调用，用于确定基础版本以计算 major/minor/patch 增量。
+     * 未实现则视为版本不可读（用户需提供完整版本号）。
+     *
+     * @param worktreePath 执行读取的目录路径
+     * @returns 版本号字符串（如 "1.2.0"），或 null 表示无法读取
+     */
+    readVersion?(worktreePath: string): Promise<string | null>;
+    /**
+     * 更新项目版本号
+     *
+     * 在 `colyn release` 时调用。
+     *
+     * **缺失处理**：已激活插件若未实现此方法，PluginManager 报错终止 release。
+     *
+     * @param worktreePath 执行版本更新的目录路径
+     * @param version 新版本号（如 "1.2.0"）
+     */
+    bumpVersion?(worktreePath: string, version: string): Promise<void>;
+    /**
+     * 发布到包管理服务
+     *
+     * 在 `colyn release` 完成 push 后调用。
+     * 由各插件执行对应的发布命令：
+     * - npm: publish 到 npmjs.com
+     * - maven/gradle: publish 到配置的仓库
+     * - pip: publish 到配置的 Python 包仓库
+     * - xcode: 视项目类型执行对应发布动作（或静默跳过）
+     *
+     * **缺失处理**：未实现则跳过。
+     *
+     * @param worktreePath 执行发布的目录路径
+     * @throws {PluginCommandError} 发布失败时，output 包含命令输出
+     */
+    publish?(worktreePath: string): Promise<void>;
+    /**
+     * 检查当前项目是否满足发布条件
+     *
+     * 在 `colyn release` 的发布阶段前调用。
+     * 返回 false 表示当前工具链在该目录下不应执行发布（例如 npm private 包）。
+     *
+     * **缺失处理**：未实现时，默认视为可发布。
+     *
+     * @param worktreePath 执行检查的目录路径
+     */
+    checkPublishable?(worktreePath: string): Promise<boolean>;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/types/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,mCAAmC;IACnC,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAK9B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IAEb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IAMpB;;;;;;;OAOG;IACH,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAMzD;;;;;OAKG;IACH,UAAU,CAAC,IAAI,UAAU,GAAG,IAAI,CAAC;IAEjC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IAEjF;;;;;OAKG;IACH,kBAAkB,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAMzF;;;;;;;;OAQG;IACH,gBAAgB,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAMpF;;;;;;;OAOG;IACH,wBAAwB,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC;IAE3C;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAMlF;;;;;;;;;OASG;IACH,OAAO,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;;;;;;;OASG;IACH,IAAI,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3C;;;;;;;;;OASG;IACH,KAAK,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C;;;;;;;;OAQG;IACH,WAAW,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAE3D;;;;;;;;;OASG;IACH,WAAW,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;;;;;;;;OASG;IACH,gBAAgB,CAAC,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D"}

package/dist/types/plugin.js

@@ -0,0 +1,19 @@
+/**
+ * 工具链插件类型定义
+ */
+/**
+ * 插件命令执行失败时抛出的异常
+ *
+ * lint / build / install / publish / init 失败时插件必须抛出此类型，
+ * 以便 PluginManager 在 verbose 模式下将命令输出展示给用户。
+ */
+export class PluginCommandError extends Error {
+    /** 失败命令的完整输出（stdout + stderr） */
+    output;
+    constructor(message, output) {
+        super(message);
+        this.name = 'PluginCommandError';
+        this.output = output;
+    }
+}
+//# sourceMappingURL=plugin.js.map

package/dist/types/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkBH;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,iCAAiC;IACxB,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,MAAc;QACzC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,42 @@
+import { CommandResult } from '../types/index.js';
+/**
+ * 输出到 stderr（彩色，给用户看）
+ */
+export declare function output(message: string): void;
+/**
+ * 输出空行到 stderr
+ */
+export declare function outputLine(): void;
+/**
+ * 输出成功信息到 stderr
+ */
+export declare function outputSuccess(message: string): void;
+/**
+ * 输出错误信息到 stderr
+ */
+export declare function outputError(message: string): void;
+/**
+ * 输出警告信息到 stderr
+ */
+export declare function outputWarning(message: string): void;
+/**
+ * 输出普通信息到 stderr
+ */
+export declare function outputInfo(message: string): void;
+/**
+ * 输出高亮信息到 stderr
+ */
+export declare function outputBold(message: string): void;
+/**
+ * 输出提示步骤到 stderr
+ */
+export declare function outputStep(message: string): void;
+/**
+ * 输出命令结果到 stdout（JSON 格式，给 bash 解析）
+ */
+export declare function outputResult(result: CommandResult): void;
+/**
+ * 格式化并显示错误到 stderr
+ */
+export declare function formatError(error: unknown): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG9D;;GAEG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEnD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAOxD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAWhD"}

package/dist/utils/logger.js

@@ -0,0 +1,80 @@
+import chalk from 'chalk';
+import { ColynError } from '../types/index.js';
+import { t } from '../i18n/index.js';
+/**
+ * 输出到 stderr（彩色，给用户看）
+ */
+export function output(message) {
+    process.stderr.write(message + '\n');
+}
+/**
+ * 输出空行到 stderr
+ */
+export function outputLine() {
+    process.stderr.write('\n');
+}
+/**
+ * 输出成功信息到 stderr
+ */
+export function outputSuccess(message) {
+    output(chalk.green(`✓ ${message}`));
+}
+/**
+ * 输出错误信息到 stderr
+ */
+export function outputError(message) {
+    output(chalk.red(`✗ ${message}`));
+}
+/**
+ * 输出警告信息到 stderr
+ */
+export function outputWarning(message) {
+    output(chalk.yellow(`⚠ ${message}`));
+}
+/**
+ * 输出普通信息到 stderr
+ */
+export function outputInfo(message) {
+    output(chalk.gray(message));
+}
+/**
+ * 输出高亮信息到 stderr
+ */
+export function outputBold(message) {
+    output(chalk.bold(message));
+}
+/**
+ * 输出提示步骤到 stderr
+ */
+export function outputStep(message) {
+    output(chalk.cyan(message));
+}
+/**
+ * 输出命令结果到 stdout（JSON 格式，给 bash 解析）
+ */
+export function outputResult(result) {
+    // 默认不输出机器结果，避免污染人类可读的终端输出。
+    // 仅 shell 包装器在需要时设置 COLYN_OUTPUT_JSON=1。
+    if (process.env.COLYN_OUTPUT_JSON !== '1') {
+        return;
+    }
+    console.log(JSON.stringify(result));
+}
+/**
+ * 格式化并显示错误到 stderr
+ */
+export function formatError(error) {
+    if (error instanceof ColynError) {
+        output(chalk.red(`\n✗ ${error.message}`));
+        if (error.hint) {
+            output(chalk.yellow(`  ${t('logger.hintPrefix')} ${error.hint}\n`));
+        }
+    }
+    else if (error instanceof Error) {
+        output(chalk.red(`\n✗ ${t('logger.errorPrefix')} ${error.message}\n`));
+    }
+    else {
+        output(chalk.red(`\n✗ ${t('common.unknownError')}\n`));
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAiB,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAC;AAErC;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,OAAe;IACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,2BAA2B;IAC3B,yCAAyC;IACzC,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,GAAG,EAAE,CAAC;QAC1C,OAAO;IACT,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC1C,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,mBAAmB,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;SAAM,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,oBAAoB,CAAC,IAAI,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;IACzE,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC;IACzD,CAAC;AACH,CAAC"}

package/docs/en/manual/04-command-reference/README.md

@@ -0,0 +1,58 @@
+# Command Reference
+
+This section provides detailed reference documentation for all Colyn commands.
+
+---
+
+## Table of Contents
+
+- [Global Options](01-worktree.md#global-options)
+
+### Worktree Management
+
+- [colyn init](01-worktree.md#colyn-init) — Initialize Worktree management structure
+- [colyn add](01-worktree.md#colyn-add) — Create a new Worktree
+- [colyn list](01-worktree.md#colyn-list) — List all Worktrees
+- [colyn list-project](01-worktree.md#colyn-list-project) — List Worktrees across all projects
+- [colyn merge](01-worktree.md#colyn-merge) — Merge Worktree into main branch
+- [colyn remove](01-worktree.md#colyn-remove) — Remove a Worktree
+
+### Branch & Status
+
+- [colyn checkout](02-branch-status.md#colyn-checkout) — Switch branches in a Worktree
+- [colyn info](02-branch-status.md#colyn-info) — Show project info for current directory
+- [colyn status](02-branch-status.md#colyn-status) — Query or set workflow status
+
+### System & Configuration
+
+- [colyn repair](03-system-config.md#colyn-repair) — Check and repair project configuration
+- [colyn config](03-system-config.md#colyn-config) — Manage Colyn configuration
+- [colyn completion](03-system-config.md#colyn-completion) — Generate shell auto-completion script
+- [colyn setup](03-system-config.md#colyn-setup) — Configure shell integration
+
+### Workflow Tools
+
+- [colyn release](04-workflow.md#colyn-release) — Publish a new version
+- [colyn todo](04-workflow.md#colyn-todo) — Manage project Todo task list
+
+---
+
+## Quick Reference
+
+| Command | Alias | Purpose |
+|---------|-------|---------|
+| `colyn init` | - | Initialize project |
+| `colyn add` | - | Create Worktree |
+| `colyn list` | - | List Worktrees |
+| `colyn list-project` | `lsp` | List all projects |
+| `colyn merge` | - | Merge branch |
+| `colyn remove` | - | Remove Worktree |
+| `colyn checkout` | `co` | Switch branch |
+| `colyn info` | - | View location info |
+| `colyn status` | `st` | Query/set workflow status |
+| `colyn repair` | - | Repair configuration |
+| `colyn config` | - | Manage configuration |
+| `colyn completion` | - | Generate completion script |
+| `colyn setup` | - | Configure shell integration |
+| `colyn release` | - | Publish version |
+| `colyn todo` | - | Manage todo tasks |

package/docs/en/manual/README.md

@@ -0,0 +1,108 @@
+# Colyn User Manual
+
+**Version**: 2.5.5
+**Last Updated**: 2026-02-10
+
+---
+
+## Welcome to Colyn
+
+Colyn is a powerful Git Worktree management tool designed for developers who need to work on multiple features in parallel. It simplifies the creation and management of Git worktrees, handles port allocation automatically, supports tmux integration, and makes multi-branch parallel development effortless.
+
+### Core Features
+
+- **Simplified Worktree Management**: Create and manage git worktrees with a single command, no complex commands required
+- **Automatic Port Allocation**: Intelligently assigns dev server ports to avoid conflicts
+- **Automatic Directory Switching**: Automatically switches to the target directory after command execution
+- **Smart Branch Handling**: Automatically identifies local branches, remote branches, or creates new ones
+- **Auto-completion**: Supports Bash/Zsh Tab key completion for commands, options, and arguments
+- **tmux Integration**: Efficient worktree management and switching within tmux
+- **Cross-platform Support**: Full support for macOS, Linux, and Windows
+
+### Use Cases
+
+Colyn is especially well-suited for the following scenarios:
+
+- **Parallel Feature Development**: Develop multiple features simultaneously without frequently switching branches
+- **Multi-version Testing**: Run dev servers on different branches simultaneously for comparison testing
+- **Bug Fixes**: Maintain your current development state while quickly switching to a bugfix branch
+- **Code Review**: Review others' branch code in an isolated environment
+- **AI-assisted Development**: Use AI tools like Claude Code to achieve "Parallel Vibe Coding"
+
+---
+
+## Manual Structure
+
+This user manual contains the following chapters:
+
+0. **[User Story: From Solo Developer to an AI Team](00-user-story.md)** - See what Colyn can do through a complete real-world scenario
+1. **[Quick Start](01-quick-start.md)** - Get up and running in 5 minutes
+2. **[Installation Guide](02-installation.md)** - Detailed installation instructions
+3. **[Core Concepts](03-core-concepts.md)** - Understanding how Colyn works
+4. **[Command Reference](04-command-reference/README.md)** - Detailed documentation for all commands (organized by category)
+5. **[Advanced Usage](05-advanced-usage.md)** - Advanced features and techniques
+6. **[tmux Integration](06-tmux-integration.md)** - Efficient workflows in a tmux environment
+7. **[Best Practices](07-best-practices.md)** - Recommended workflows and tips
+8. **[Troubleshooting](08-troubleshooting.md)** - Common issues and solutions
+9. **[Glossary](09-glossary.md)** - Quick reference for terms and concepts
+10. **[Configuration System](10-configuration.md)** - Complete configuration file guide
+11. **[Plugin System](11-plugin-system.md)** - Multi-language toolchain support (npm / Maven / Gradle / pip)
+
+---
+
+## Quick Navigation
+
+### New Users
+
+If this is your first time using Colyn:
+
+1. Read [User Story](00-user-story.md) to quickly understand what problem Colyn solves
+2. Read [Quick Start](01-quick-start.md) to learn the basics
+3. Check [Core Concepts](03-core-concepts.md) to understand how it works
+4. Refer to [Command Reference](04-command-reference/README.md) to learn specific commands
+
+### Existing Users
+
+If you are already using Colyn:
+
+- Need help with a specific command → [Command Reference](04-command-reference/README.md)
+- Configuration file setup → [Configuration System](10-configuration.md)
+- Having an issue → [Troubleshooting](08-troubleshooting.md)
+- Looking up a term → [Glossary](09-glossary.md)
+- Learning advanced techniques → [Advanced Usage](05-advanced-usage.md)
+
+### tmux Users
+
+If you use tmux:
+
+- Complete tmux integration guide → [tmux Integration](06-tmux-integration.md)
+- Shortcuts and workflows → [Best Practices](07-best-practices.md)
+
+---
+
+## Getting Help
+
+### Command-line Help
+
+View help at any time from the command line:
+
+```bash
+# View all commands
+colyn --help
+
+# View help for a specific command
+colyn init --help
+colyn add --help
+```
+
+### Project Information
+
+- **GitHub Repository**: [github.com/colinhan/colyn](https://github.com/colinhan/colyn)
+- **Issue Tracker**: [GitHub Issues](https://github.com/colinhan/colyn/issues)
+- **Version History**: [CHANGELOG.md](../CHANGELOG.md)
+
+---
+
+## Get Started
+
+Ready? Begin your Colyn journey with [Quick Start](01-quick-start.md)!

package/docs/zh-CN/manual/04-command-reference/README.md

@@ -0,0 +1,58 @@
+# 命令参考手册
+
+本章节提供 Colyn 所有命令的详细参考文档。
+
+---
+
+## 目录
+
+- [全局选项](01-worktree.md#全局选项)
+
+### Worktree 管理
+
+- [colyn init](01-worktree.md#colyn-init) — 初始化 Worktree 管理结构
+- [colyn add](01-worktree.md#colyn-add) — 创建新 Worktree
+- [colyn list](01-worktree.md#colyn-list) — 列出所有 Worktree
+- [colyn list-project](01-worktree.md#colyn-list-project) — 列出所有项目的 Worktree
+- [colyn merge](01-worktree.md#colyn-merge) — 合并 Worktree 到主分支
+- [colyn remove](01-worktree.md#colyn-remove) — 删除 Worktree
+
+### 分支与状态
+
+- [colyn checkout](02-branch-status.md#colyn-checkout) — 在 Worktree 中切换分支
+- [colyn info](02-branch-status.md#colyn-info) — 显示当前目录的项目信息
+- [colyn status](02-branch-status.md#colyn-status) — 查询或设置工作流状态
+
+### 系统与配置
+
+- [colyn repair](03-system-config.md#colyn-repair) — 检查并修复项目配置
+- [colyn config](03-system-config.md#colyn-config) — 管理 Colyn 配置
+- [colyn completion](03-system-config.md#colyn-completion) — 生成 shell 自动补全脚本
+- [colyn setup](03-system-config.md#colyn-setup) — 配置 shell 集成
+
+### 工作流工具
+
+- [colyn release](04-workflow.md#colyn-release) — 发布新版本
+- [colyn todo](04-workflow.md#colyn-todo) — 管理项目 Todo 任务列表
+
+---
+
+## 快速查阅
+
+| 命令 | 别名 | 用途 |
+|------|------|------|
+| `colyn init` | - | 初始化项目 |
+| `colyn add` | - | 创建 Worktree |
+| `colyn list` | - | 列出 Worktree |
+| `colyn list-project` | `lsp` | 列出所有项目 |
+| `colyn merge` | - | 合并分支 |
+| `colyn remove` | - | 删除 Worktree |
+| `colyn checkout` | `co` | 切换分支 |
+| `colyn info` | - | 查看位置信息 |
+| `colyn status` | `st` | 查询/设置工作流状态 |
+| `colyn repair` | - | 修复配置 |
+| `colyn config` | - | 管理配置 |
+| `colyn completion` | - | 生成补全脚本 |
+| `colyn setup` | - | 配置 shell 集成 |
+| `colyn release` | - | 发布版本 |
+| `colyn todo` | - | 管理待办任务 |