clawt 2.18.0 → 2.19.0

package/docs/spec.md

@@ -29,6 +29,7 @@
   - [5.15 命令别名管理](#515-命令别名管理)
   - [5.16 Shell 自动补全](#516-clawt-completion-命令)
   - [5.17 自动更新检查](#517-自动更新检查)
+  - [5.18 跨项目 Worktree 概览](#518-跨项目-worktree-概览)
 - [6. 错误处理规范](#6-错误处理规范)
 - [7. 非功能性需求](#7-非功能性需求)
   - [7.1 性能](#71-性能)
@@ -188,6 +189,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 | `clawt status`        | 显示项目全局状态总览（支持 `--json` 格式输出）          | 5.14     |
 | `clawt alias`         | 管理命令别名（列出 / 设置 / 移除）                       | 5.15     |
 | `clawt completion`    | 为终端提供 shell 自动补全功能（bash/zsh）              | 5.16     |
+| `clawt projects`      | 展示所有项目的 worktree 概览，或查看指定项目的 worktree 详情 | 5.17     |
 
 **全局选项：**
 
@@ -1655,6 +1657,9 @@ clawt status [--json]
 - `formatRelativeTime()` 是新增的格式化函数（在 `src/utils/formatter.ts`），将 ISO 8601 日期字符串转换为中文相对时间描述（如"3 天前"、"2 小时前"、"刚刚"），无效日期时返回 null
 - `getCommitCountBehind()` 是新增的工具函数（在 `src/utils/git.ts`），通过 `git rev-list --count <branch>..HEAD` 计算落后提交数
 - `getProjectSnapshotBranches()` 是新增的工具函数（在 `src/utils/validate-snapshot.ts`），通过扫描快照目录下的 `.tree` 文件提取分支名列表
+- `formatDiskSize()` 是新增的格式化函数（在 `src/utils/formatter.ts`），将字节数格式化为带单位的磁盘大小字符串（如 `"1.5 GB"`、`"256.0 MB"`、`"10.2 KB"`、`"512 B"`）
+- `formatLocalISOString()` 是新增的格式化函数（在 `src/utils/formatter.ts`），将 Date 对象格式化为本机时区的 ISO 8601 字符串（输出格式: `YYYY-MM-DDTHH:mm:ss.sss+HH:MM`），替代 `Date.toISOString()` 的 UTC 时区输出
+- `calculateDirSize()` 是新增的文件系统工具函数（在 `src/utils/fs.ts`），递归计算目录占用的磁盘大小（字节），遇到无法访问的文件或目录时静默跳过
 
 ---
 
@@ -1916,6 +1921,142 @@ CLI 在每次命令执行完毕后，根据配置项 `autoUpdate` 决定是否
 
 ---
 
+### 5.18 跨项目 Worktree 概览
+
+**命令：**
+
+```bash
+clawt projects [name] [--json]
+```
+
+**参数：**
+
+| 参数     | 必填 | 说明                                           |
+| -------- | ---- | ---------------------------------------------- |
+| `[name]` | 否   | 指定项目名，查看该项目的 worktree 详情           |
+| `--json` | 否   | 以 JSON 格式输出完整数据                        |
+
+**使用场景：**
+
+当使用 clawt 管理多个不同项目时，快速了解所有项目的 worktree 数量、磁盘占用和最近活跃时间。也可以指定项目名查看该项目下每个 worktree 的分支、路径、最后修改时间和磁盘占用。
+
+**注意：** `projects` 命令不需要在主 worktree 中执行（与其他命令不同），它直接扫描 `~/.clawt/worktrees/` 目录。
+
+**运行流程：**
+
+#### 无参数模式（项目概览）
+
+1. 扫描 `~/.clawt/worktrees/` 目录，列出所有项目子目录
+2. 对每个项目收集以下信息：
+   - **项目名**（目录名即项目名）
+   - **worktree 数量**（项目目录下的子目录数）
+   - **最近活跃时间**（取项目目录自身和所有 worktree 目录 mtime 的最大值，通过 `formatLocalISOString()` 格式化为本机时区的 ISO 8601 字符串）
+   - **磁盘占用**（通过 `calculateDirSize()` 递归计算整个项目目录的总大小）
+3. 按最近活跃时间降序排序
+4. 输出概览信息（文本或 JSON）
+
+#### 指定项目模式（worktree 详情）
+
+1. 检查 `~/.clawt/worktrees/<name>/` 是否存在，不存在则报错退出
+2. 扫描项目目录，对每个 worktree 子目录收集：
+   - **分支名**（目录名即分支名）
+   - **worktree 路径**
+   - **最后修改时间**（目录 mtime，通过 `formatLocalISOString()` 格式化）
+   - **磁盘占用**（通过 `calculateDirSize()` 递归计算）
+3. 按最后修改时间降序排序
+4. 输出详情信息（文本或 JSON）
+
+**文本输出格式（概览模式）：**
+
+```
+════════════════════════════════════════
+  项目概览
+════════════════════════════════════════
+
+  ● my-project
+    3 个 worktree   最近活跃: 2 小时前   磁盘占用: 1.5 GB
+
+  ● another-project
+    1 个 worktree   最近活跃: 3 天前   磁盘占用: 256.0 MB
+
+────────────────────────────────────────
+
+  共 2 个项目   总占用: 1.8 GB
+
+════════════════════════════════════════
+```
+
+**文本输出格式（详情模式）：**
+
+```
+════════════════════════════════════════
+  项目详情: my-project
+════════════════════════════════════════
+
+  ◆ 路径: ~/.clawt/worktrees/my-project
+    总占用: 1.5 GB
+
+────────────────────────────────────────
+
+  ● feature-login
+    ~/.clawt/worktrees/my-project/feature-login
+    最后修改: 2 小时前   磁盘占用: 800.0 MB
+
+  ● feature-signup
+    ~/.clawt/worktrees/my-project/feature-signup
+    最后修改: 1 天前   磁盘占用: 700.0 MB
+
+════════════════════════════════════════
+```
+
+**JSON 输出格式（概览模式，`--json`）：**
+
+```json
+{
+  "projects": [
+    {
+      "name": "my-project",
+      "worktreeCount": 3,
+      "lastActiveTime": "2025-06-15T18:30:00.000+08:00",
+      "diskUsage": 1610612736
+    }
+  ],
+  "totalProjects": 1,
+  "totalDiskUsage": 1610612736
+}
+```
+
+**JSON 输出格式（详情模式，`--json`）：**
+
+```json
+{
+  "name": "my-project",
+  "projectDir": "~/.clawt/worktrees/my-project",
+  "worktrees": [
+    {
+      "branch": "feature-login",
+      "path": "~/.clawt/worktrees/my-project/feature-login",
+      "lastModifiedTime": "2025-06-15T18:30:00.000+08:00",
+      "diskUsage": 838860800
+    }
+  ],
+  "totalDiskUsage": 838860800
+}
+```
+
+**实现要点：**
+
+- 命令注册函数：`registerProjectsCommand()`（在 `src/commands/projects.ts`）
+- 类型定义在 `src/types/project.ts`：`ProjectOverview`、`ProjectWorktreeDetail`、`ProjectDetailResult`、`ProjectsOverviewResult`
+- 命令选项类型：`ProjectsOptions`（在 `src/types/command.ts`）
+- 消息常量在 `PROJECTS_MESSAGES`（在 `src/constants/messages/projects.ts`）
+- 时间格式化使用 `formatLocalISOString()`（在 `src/utils/formatter.ts`），输出本机时区的 ISO 8601 字符串（替代 `Date.toISOString()` 的 UTC 输出）
+- 磁盘大小展示使用 `formatDiskSize()`（在 `src/utils/formatter.ts`），将字节数格式化为带单位的可读字符串
+- 目录大小计算使用 `calculateDirSize()`（在 `src/utils/fs.ts`），递归遍历目录计算总字节数
+- 时间的相对展示使用 `formatRelativeTime()`（在 `src/utils/formatter.ts`），将 ISO 8601 日期转换为中文相对时间（如"2 小时前"）
+
+---
+
 ## 6. 错误处理规范
 
 ### 6.1 通用错误处理

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/projects.ts

@@ -0,0 +1,324 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import chalk from 'chalk';
+import { MESSAGES, WORKTREES_DIR } from '../constants/index.js';
+import { logger } from '../logger/index.js';
+import type {
+  ProjectsOptions,
+  ProjectOverview,
+  ProjectWorktreeDetail,
+  ProjectDetailResult,
+  ProjectsOverviewResult,
+} from '../types/index.js';
+import {
+  formatRelativeTime,
+  formatDiskSize,
+  formatLocalISOString,
+  calculateDirSize,
+  printInfo,
+  printDoubleSeparator,
+  printSeparator,
+  printError,
+} from '../utils/index.js';
+
+/**
+ * 注册 projects 命令：统一管理多个项目的 worktree 状态
+ * @param {Command} program - Commander 实例
+ */
+export function registerProjectsCommand(program: Command): void {
+  program
+    .command('projects [name]')
+    .description('展示所有项目的 worktree 概览，或查看指定项目的 worktree 详情')
+    .option('--json', '以 JSON 格式输出')
+    .action((name: string | undefined, options: { json?: boolean }) => {
+      handleProjects({ name, json: options.json });
+    });
+}
+
+/**
+ * 执行 projects 命令的核心逻辑
+ * @param {ProjectsOptions} options - 命令选项
+ */
+function handleProjects(options: ProjectsOptions): void {
+  if (options.name) {
+    handleProjectDetail(options.name, options.json);
+  } else {
+    handleProjectsOverview(options.json);
+  }
+}
+
+/**
+ * 处理项目概览展示：列出所有项目
+ * @param {boolean} [json] - 是否以 JSON 格式输出
+ */
+function handleProjectsOverview(json?: boolean): void {
+  const result = collectProjectsOverview();
+
+  logger.info(`projects 命令执行，共 ${result.totalProjects} 个项目`);
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  printProjectsOverviewAsText(result);
+}
+
+/**
+ * 处理指定项目的 worktree 详情展示
+ * @param {string} name - 项目名
+ * @param {boolean} [json] - 是否以 JSON 格式输出
+ */
+function handleProjectDetail(name: string, json?: boolean): void {
+  const projectDir = join(WORKTREES_DIR, name);
+
+  if (!existsSync(projectDir)) {
+    printError(MESSAGES.PROJECTS_NOT_FOUND(name));
+    process.exit(1);
+  }
+
+  const result = collectProjectDetail(name, projectDir);
+
+  logger.info(`projects 命令执行，项目: ${name}，共 ${result.worktrees.length} 个 worktree`);
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  printProjectDetailAsText(result);
+}
+
+// ─── 数据收集函数 ─────────────────────────────────
+
+/**
+ * 收集所有项目的概览信息
+ * @returns {ProjectsOverviewResult} 所有项目概览结果
+ */
+function collectProjectsOverview(): ProjectsOverviewResult {
+  if (!existsSync(WORKTREES_DIR)) {
+    return { projects: [], totalProjects: 0, totalDiskUsage: 0 };
+  }
+
+  const entries = readdirSync(WORKTREES_DIR, { withFileTypes: true });
+  const projects: ProjectOverview[] = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const projectDir = join(WORKTREES_DIR, entry.name);
+    const overview = collectSingleProjectOverview(entry.name, projectDir);
+    projects.push(overview);
+  }
+
+  // 按最近活跃时间降序排序
+  sortByLastActiveTimeDesc(projects);
+
+  const totalDiskUsage = projects.reduce((sum, p) => sum + p.diskUsage, 0);
+
+  return {
+    projects,
+    totalProjects: projects.length,
+    totalDiskUsage,
+  };
+}
+
+/**
+ * 收集单个项目的概览信息
+ * @param {string} name - 项目名
+ * @param {string} projectDir - 项目目录路径
+ * @returns {ProjectOverview} 项目概览
+ */
+function collectSingleProjectOverview(name: string, projectDir: string): ProjectOverview {
+  const subEntries = readdirSync(projectDir, { withFileTypes: true });
+  const worktreeDirs = subEntries.filter((e) => e.isDirectory());
+
+  const worktreeCount = worktreeDirs.length;
+  const diskUsage = calculateDirSize(projectDir);
+  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join(projectDir, e.name)));
+
+  return {
+    name,
+    worktreeCount,
+    lastActiveTime,
+    diskUsage,
+  };
+}
+
+/**
+ * 收集指定项目的 worktree 详情
+ * @param {string} name - 项目名
+ * @param {string} projectDir - 项目目录路径
+ * @returns {ProjectDetailResult} 项目详情结果
+ */
+function collectProjectDetail(name: string, projectDir: string): ProjectDetailResult {
+  const subEntries = readdirSync(projectDir, { withFileTypes: true });
+  const worktrees: ProjectWorktreeDetail[] = [];
+
+  for (const entry of subEntries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const wtPath = join(projectDir, entry.name);
+    const detail = collectSingleWorktreeDetail(entry.name, wtPath);
+    worktrees.push(detail);
+  }
+
+  // 按最近修改时间降序排序
+  worktrees.sort((a, b) => new Date(b.lastModifiedTime).getTime() - new Date(a.lastModifiedTime).getTime());
+
+  const totalDiskUsage = worktrees.reduce((sum, wt) => sum + wt.diskUsage, 0);
+
+  return {
+    name,
+    projectDir,
+    worktrees,
+    totalDiskUsage,
+  };
+}
+
+/**
+ * 收集单个 worktree 的详情信息
+ * @param {string} branch - 分支名（目录名即分支名）
+ * @param {string} wtPath - worktree 路径
+ * @returns {ProjectWorktreeDetail} worktree 详情
+ */
+function collectSingleWorktreeDetail(branch: string, wtPath: string): ProjectWorktreeDetail {
+  const stat = statSync(wtPath);
+  const diskUsage = calculateDirSize(wtPath);
+
+  return {
+    branch,
+    path: wtPath,
+    lastModifiedTime: formatLocalISOString(stat.mtime),
+    diskUsage,
+  };
+}
+
+// ─── 工具函数 ─────────────────────────────────────
+
+/**
+ * 确定项目的最近活跃时间
+ * 取项目目录自身和所有子 worktree 目录修改时间的最大值
+ * @param {string} projectDir - 项目目录路径
+ * @param {string[]} worktreePaths - worktree 路径列表
+ * @returns {string} ISO 8601 格式的最近活跃时间
+ */
+function resolveProjectLastActiveTime(projectDir: string, worktreePaths: string[]): string {
+  let latestTime = statSync(projectDir).mtime;
+
+  for (const wtPath of worktreePaths) {
+    try {
+      const wtStat = statSync(wtPath);
+      if (wtStat.mtime > latestTime) {
+        latestTime = wtStat.mtime;
+      }
+    } catch {
+      // 忽略无法访问的目录
+    }
+  }
+
+  return formatLocalISOString(latestTime);
+}
+
+/**
+ * 按最近活跃时间降序排序项目概览列表（原地排序）
+ * @param {ProjectOverview[]} projects - 项目概览列表
+ */
+function sortByLastActiveTimeDesc(projects: ProjectOverview[]): void {
+  projects.sort((a, b) => new Date(b.lastActiveTime).getTime() - new Date(a.lastActiveTime).getTime());
+}
+
+// ─── 文本输出函数 ─────────────────────────────────
+
+/**
+ * 以文本格式输出所有项目概览
+ * @param {ProjectsOverviewResult} result - 项目概览结果
+ */
+function printProjectsOverviewAsText(result: ProjectsOverviewResult): void {
+  printDoubleSeparator();
+  printInfo(`  ${chalk.bold.cyan(MESSAGES.PROJECTS_OVERVIEW_TITLE)}`);
+  printDoubleSeparator();
+  printInfo('');
+
+  if (result.projects.length === 0) {
+    printInfo(`  ${MESSAGES.PROJECTS_NO_PROJECTS}`);
+    printInfo('');
+    printDoubleSeparator();
+    return;
+  }
+
+  for (const project of result.projects) {
+    printProjectOverviewItem(project);
+  }
+
+  printSeparator();
+  printInfo('');
+  printInfo(`  共 ${chalk.bold(String(result.totalProjects))} 个项目   ${chalk.gray(MESSAGES.PROJECTS_TOTAL_DISK_USAGE(formatDiskSize(result.totalDiskUsage)))}`);
+  printInfo('');
+  printDoubleSeparator();
+}
+
+/**
+ * 输出单个项目概览项
+ * @param {ProjectOverview} project - 项目概览
+ */
+function printProjectOverviewItem(project: ProjectOverview): void {
+  const relativeTime = formatRelativeTime(project.lastActiveTime);
+  const activeLabel = relativeTime ? MESSAGES.PROJECTS_LAST_ACTIVE(relativeTime) : '';
+  const diskLabel = MESSAGES.PROJECTS_DISK_USAGE(formatDiskSize(project.diskUsage));
+
+  printInfo(`  ${chalk.bold('●')} ${chalk.bold(project.name)}`);
+  printInfo(`    ${MESSAGES.PROJECTS_WORKTREE_COUNT(project.worktreeCount)}   ${chalk.gray(activeLabel)}   ${chalk.gray(diskLabel)}`);
+  printInfo('');
+}
+
+/**
+ * 以文本格式输出指定项目的 worktree 详情
+ * @param {ProjectDetailResult} result - 项目详情结果
+ */
+function printProjectDetailAsText(result: ProjectDetailResult): void {
+  printDoubleSeparator();
+  printInfo(`  ${chalk.bold.cyan(MESSAGES.PROJECTS_DETAIL_TITLE(result.name))}`);
+  printDoubleSeparator();
+  printInfo('');
+
+  printInfo(`  ${chalk.bold('◆')} ${chalk.bold(MESSAGES.PROJECTS_PATH(result.projectDir))}`);
+  printInfo(`    ${MESSAGES.PROJECTS_TOTAL_DISK_USAGE(formatDiskSize(result.totalDiskUsage))}`);
+  printInfo('');
+
+  printSeparator();
+  printInfo('');
+
+  if (result.worktrees.length === 0) {
+    printInfo(`  ${MESSAGES.PROJECTS_DETAIL_NO_WORKTREES}`);
+    printInfo('');
+    printDoubleSeparator();
+    return;
+  }
+
+  for (const wt of result.worktrees) {
+    printWorktreeDetailItem(wt);
+  }
+
+  printDoubleSeparator();
+}
+
+/**
+ * 输出单个 worktree 详情项
+ * @param {ProjectWorktreeDetail} wt - worktree 详情
+ */
+function printWorktreeDetailItem(wt: ProjectWorktreeDetail): void {
+  const relativeTime = formatRelativeTime(wt.lastModifiedTime);
+  const modifiedLabel = relativeTime ? MESSAGES.PROJECTS_LAST_MODIFIED(relativeTime) : '';
+  const diskLabel = MESSAGES.PROJECTS_DISK_USAGE(formatDiskSize(wt.diskUsage));
+
+  printInfo(`  ${chalk.bold('●')} ${chalk.bold(wt.branch)}`);
+  printInfo(`    ${wt.path}`);
+  printInfo(`    ${chalk.gray(modifiedLabel)}   ${chalk.gray(diskLabel)}`);
+  printInfo('');
+}

package/src/constants/messages/index.ts

@@ -10,6 +10,7 @@ import { RESET_MESSAGES } from './reset.js';
 import { CONFIG_CMD_MESSAGES, CONFIG_ALIAS_DISABLED_HINT } from './config.js';
 import { STATUS_MESSAGES } from './status.js';
 import { ALIAS_MESSAGES } from './alias.js';
+import { PROJECTS_MESSAGES } from './projects.js';
 import { COMPLETION_MESSAGES } from './completion.js';
 import { UPDATE_MESSAGES, UPDATE_COMMANDS } from './update.js';
 
@@ -33,5 +34,6 @@ export const MESSAGES = {
   ...CONFIG_CMD_MESSAGES,
   ...STATUS_MESSAGES,
   ...ALIAS_MESSAGES,
+  ...PROJECTS_MESSAGES,
   ...COMPLETION_MESSAGES,
 } as const;

package/src/constants/messages/projects.ts

@@ -0,0 +1,25 @@
+/** projects 命令专属提示消息 */
+export const PROJECTS_MESSAGES = {
+  /** projects 命令全局概览标题 */
+  PROJECTS_OVERVIEW_TITLE: '项目概览',
+  /** projects 命令指定项目详情标题 */
+  PROJECTS_DETAIL_TITLE: (projectName: string) => `项目详情: ${projectName}`,
+  /** 无项目提示 */
+  PROJECTS_NO_PROJECTS: '(暂无项目，worktrees 目录为空)',
+  /** 项目不存在提示 */
+  PROJECTS_NOT_FOUND: (name: string) => `项目 ${name} 不存在`,
+  /** worktree 数量标签 */
+  PROJECTS_WORKTREE_COUNT: (count: number) => `${count} 个 worktree`,
+  /** 最近活跃时间标签 */
+  PROJECTS_LAST_ACTIVE: (relativeTime: string) => `最近活跃: ${relativeTime}`,
+  /** 磁盘占用标签 */
+  PROJECTS_DISK_USAGE: (size: string) => `磁盘占用: ${size}`,
+  /** 总磁盘占用标签 */
+  PROJECTS_TOTAL_DISK_USAGE: (size: string) => `总占用: ${size}`,
+  /** projects 详情无 worktree */
+  PROJECTS_DETAIL_NO_WORKTREES: '(该项目下无 worktree)',
+  /** 路径标签 */
+  PROJECTS_PATH: (path: string) => `路径: ${path}`,
+  /** 最后修改时间标签 */
+  PROJECTS_LAST_MODIFIED: (relativeTime: string) => `最后修改: ${relativeTime}`,
+} as const;

package/src/index.ts

@@ -16,6 +16,7 @@ import { registerSyncCommand } from './commands/sync.js';
 import { registerResetCommand } from './commands/reset.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerAliasCommand } from './commands/alias.js';
+import { registerProjectsCommand } from './commands/projects.js';
 import { registerCompletionCommand } from './commands/completion.js';
 
 // 从 package.json 读取版本号，避免硬编码
@@ -53,6 +54,7 @@ registerSyncCommand(program);
 registerResetCommand(program);
 registerStatusCommand(program);
 registerAliasCommand(program);
+registerProjectsCommand(program);
 registerCompletionCommand(program);
 
 // 加载配置并应用命令别名

package/src/types/command.ts

@@ -69,3 +69,11 @@ export interface StatusOptions {
   /** 以 JSON 格式输出 */
   json?: boolean;
 }
+
+/** projects 命令选项 */
+export interface ProjectsOptions {
+  /** 指定项目名（可选，不传则展示所有项目概览） */
+  name?: string;
+  /** 以 JSON 格式输出 */
+  json?: boolean;
+}

package/src/types/index.ts

@@ -1,7 +1,8 @@
 export type { ClawtConfig, ConfigItemDefinition, ConfigDefinitions } from './config.js';
-export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions, StatusOptions } from './command.js';
+export type { CreateOptions, RunOptions, ValidateOptions, MergeOptions, RemoveOptions, ResumeOptions, SyncOptions, ListOptions, StatusOptions, ProjectsOptions } from './command.js';
 export type { WorktreeInfo, WorktreeStatus } from './worktree.js';
 export type { ClaudeCodeResult } from './claudeCode.js';
 export type { TaskResult, TaskSummary } from './taskResult.js';
 export type { WorktreeDetailedStatus, MainWorktreeStatus, SnapshotInfo, SnapshotSummary, StatusResult } from './status.js';
 export type { TaskFileEntry, ParseTaskFileOptions } from './taskFile.js';
+export type { ProjectOverview, ProjectWorktreeDetail, ProjectDetailResult, ProjectsOverviewResult } from './project.js';

package/src/types/project.ts

@@ -0,0 +1,45 @@
+/** 单个项目的概览信息 */
+export interface ProjectOverview {
+  /** 项目名称 */
+  name: string;
+  /** worktree 数量 */
+  worktreeCount: number;
+  /** 最近活跃时间（ISO 8601 格式），无 worktree 时为目录修改时间 */
+  lastActiveTime: string;
+  /** 磁盘占用（字节） */
+  diskUsage: number;
+}
+
+/** 单个项目的 worktree 详情 */
+export interface ProjectWorktreeDetail {
+  /** 分支名 */
+  branch: string;
+  /** worktree 路径 */
+  path: string;
+  /** 最后修改时间（ISO 8601 格式） */
+  lastModifiedTime: string;
+  /** 磁盘占用（字节） */
+  diskUsage: number;
+}
+
+/** projects 命令展示指定项目时的完整结果 */
+export interface ProjectDetailResult {
+  /** 项目名称 */
+  name: string;
+  /** 项目 worktree 根目录 */
+  projectDir: string;
+  /** worktree 详情列表（按最近活跃时间排序） */
+  worktrees: ProjectWorktreeDetail[];
+  /** 总磁盘占用（字节） */
+  totalDiskUsage: number;
+}
+
+/** projects 命令展示所有项目概览时的完整结果 */
+export interface ProjectsOverviewResult {
+  /** 所有项目概览列表（按最近活跃时间排序） */
+  projects: ProjectOverview[];
+  /** 项目总数 */
+  totalProjects: number;
+  /** 总磁盘占用（字节） */
+  totalDiskUsage: number;
+}

package/src/utils/formatter.ts

@@ -184,3 +184,49 @@ export function formatRelativeTime(isoDateString: string): string | null {
   const years = Math.floor(diffDays / 365);
   return `${years} 年前`;
 }
+
+/**
+ * 将字节数格式化为带单位的磁盘大小字符串
+ * @param {number} bytes - 字节数
+ * @returns {string} 格式化后的大小字符串，如 "1.5 GB"、"256.0 MB"、"10.2 KB"
+ */
+export function formatDiskSize(bytes: number): string {
+  /** 1 KB 的字节数 */
+  const KB = 1024;
+  /** 1 MB 的字节数 */
+  const MB = KB * 1024;
+  /** 1 GB 的字节数 */
+  const GB = MB * 1024;
+
+  if (bytes >= GB) {
+    return `${(bytes / GB).toFixed(1)} GB`;
+  }
+  if (bytes >= MB) {
+    return `${(bytes / MB).toFixed(1)} MB`;
+  }
+  if (bytes >= KB) {
+    return `${(bytes / KB).toFixed(1)} KB`;
+  }
+  return `${bytes} B`;
+}
+
+/**
+ * 将 Date 对象格式化为本机时区的 ISO 8601 字符串
+ * 输出格式: YYYY-MM-DDTHH:mm:ss.sss+HH:MM
+ * @param {Date} date - 日期对象
+ * @returns {string} 本机时区的 ISO 8601 格式字符串
+ */
+export function formatLocalISOString(date: Date): string {
+  const tzOffsetMs = date.getTimezoneOffset() * 60 * 1000;
+  const localDate = new Date(date.getTime() - tzOffsetMs);
+  const iso = localDate.toISOString().slice(0, -1);
+
+  // 拼接时区偏移量
+  const totalMinutes = -date.getTimezoneOffset();
+  const sign = totalMinutes >= 0 ? '+' : '-';
+  const absMinutes = Math.abs(totalMinutes);
+  const hours = String(Math.floor(absMinutes / 60)).padStart(2, '0');
+  const minutes = String(absMinutes % 60).padStart(2, '0');
+
+  return `${iso}${sign}${hours}:${minutes}`;
+}