team-toon-tack 1.0.0

package/README.md

@@ -0,0 +1,187 @@
+# team-toon-tack (ttt)
+
+CLI tool for syncing and managing Linear issues with local TOON format.
+
+## Installation
+
+```bash
+# npm (recommended)
+npm install -g team-toon-tack
+
+# Or with bun
+bun add -g team-toon-tack
+
+# Or use npx/bunx without installing
+npx team-toon-tack <command>
+bunx team-toon-tack <command>
+
+# Short alias after global install
+ttt <command>
+```
+
+## Quick Start
+
+```bash
+# 1. Set your Linear API key
+export LINEAR_API_KEY="lin_api_xxxxx"
+
+# 2. Initialize in your project
+cd your-project
+ttt init
+
+# 3. Sync issues from Linear
+ttt sync
+
+# 4. Start working
+ttt work-on
+```
+
+## Commands
+
+### `ttt init`
+
+Initialize configuration files in current directory.
+
+```bash
+ttt init                           # Interactive mode
+ttt init --user alice@example.com  # Pre-select user
+ttt init --label Frontend          # Set default label
+ttt init --force                   # Overwrite existing config
+ttt init -y                        # Non-interactive mode
+```
+
+### `ttt sync`
+
+Sync current cycle issues from Linear.
+
+```bash
+ttt sync
+```
+
+### `ttt work-on`
+
+Start working on a task.
+
+```bash
+ttt work-on              # Interactive selection
+ttt work-on MP-123       # Specific issue
+ttt work-on next         # Auto-select highest priority
+```
+
+### `ttt done`
+
+Mark task as completed.
+
+```bash
+ttt done                    # Auto-select if only one in-progress
+ttt done MP-123             # Specific issue
+ttt done -m "Fixed the bug" # With completion message
+```
+
+## Configuration
+
+### Directory Structure
+
+After `ttt init`, your project will have:
+
+```
+your-project/
+├── config.toon    # Team configuration (gitignore recommended)
+├── local.toon     # Personal settings (gitignore)
+└── cycle.toon     # Current cycle data (gitignore, auto-generated)
+```
+
+### Custom Config Directory
+
+```bash
+# Use -d flag
+ttt sync -d ./team
+
+# Or set environment variable
+export TOON_DIR=./team
+ttt sync
+```
+
+### config.toon
+
+Team-wide configuration (fetched from Linear):
+
+```toon
+teams:
+  main:
+    id: TEAM_UUID
+    name: Team Name
+
+users:
+  alice:
+    id: USER_UUID
+    email: alice@example.com
+    displayName: Alice
+
+labels:
+  frontend:
+    id: LABEL_UUID
+    name: Frontend
+
+current_cycle:
+  id: CYCLE_UUID
+  name: Cycle #1
+```
+
+### local.toon
+
+Personal settings:
+
+```toon
+current_user: alice
+label: Frontend
+exclude_assignees[1]: bob
+```
+
+| Field | Description |
+|-------|-------------|
+| `current_user` | Your user key from config.toon |
+| `label` | Filter issues by label (optional) |
+| `exclude_assignees` | Hide issues from these users (optional) |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LINEAR_API_KEY` | **Required.** Your Linear API key |
+| `TOON_DIR` | Config directory (default: current directory) |
+
+## Integration Examples
+
+### With Claude Code
+
+```yaml
+# .claude/commands/sync.md
+---
+description: Sync Linear issues
+---
+ttt sync -d team
+```
+
+### As Git Submodule
+
+```bash
+# Add config directory as submodule
+git submodule add https://github.com/your-org/team-config.git team
+cd team && ttt sync
+```
+
+### In package.json
+
+```json
+{
+  "scripts": {
+    "sync": "ttt sync -d team",
+    "work": "ttt work-on -d team"
+  }
+}
+```
+
+## License
+
+MIT

package/bin/cli.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env bun
+import { resolve } from 'node:path';
+
+const COMMANDS = ['init', 'sync', 'work-on', 'done', 'help', 'version'] as const;
+type Command = typeof COMMANDS[number];
+
+function printHelp() {
+  console.log(`
+team-toon-tack (ttt) - Linear task sync & management CLI
+
+USAGE:
+  ttt <command> [options]
+
+COMMANDS:
+  init      Initialize config files in current directory
+  sync      Sync issues from Linear to local cycle.toon
+  work-on   Start working on a task (interactive or by ID)
+  done      Mark current task as completed
+  help      Show this help message
+  version   Show version
+
+GLOBAL OPTIONS:
+  -d, --dir <path>    Config directory (default: current directory)
+                      Can also set via TOON_DIR environment variable
+
+EXAMPLES:
+  ttt init                      # Initialize in current directory
+  ttt init -d ./team            # Initialize in ./team directory
+  ttt sync                      # Sync from Linear
+  ttt work-on                   # Interactive task selection
+  ttt work-on MP-123            # Work on specific issue
+  ttt work-on next              # Auto-select highest priority
+  ttt done                      # Complete current task
+  ttt done -m "Fixed the bug"   # With completion message
+
+ENVIRONMENT:
+  LINEAR_API_KEY    Required. Your Linear API key
+  TOON_DIR          Optional. Default config directory
+
+More info: https://github.com/wayne930242/team-toon-tack
+`);
+}
+
+function printVersion() {
+  console.log('team-toon-tack v1.0.0');
+}
+
+function parseGlobalArgs(args: string[]): { dir: string; commandArgs: string[] } {
+  let dir = process.env.TOON_DIR || process.cwd();
+  const commandArgs: string[] = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-d' || arg === '--dir') {
+      dir = resolve(args[++i] || '.');
+    } else {
+      commandArgs.push(arg);
+    }
+  }
+
+  return { dir, commandArgs };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === 'help' || args[0] === '-h' || args[0] === '--help') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (args[0] === 'version' || args[0] === '-v' || args[0] === '--version') {
+    printVersion();
+    process.exit(0);
+  }
+
+  const command = args[0] as Command;
+  const restArgs = args.slice(1);
+  const { dir, commandArgs } = parseGlobalArgs(restArgs);
+
+  // Set TOON_DIR for scripts to use
+  process.env.TOON_DIR = dir;
+
+  if (!COMMANDS.includes(command)) {
+    console.error(`Unknown command: ${command}`);
+    console.error(`Run 'ttt help' for usage.`);
+    process.exit(1);
+  }
+
+  // Import and run the appropriate script
+  const scriptDir = new URL('../scripts/', import.meta.url).pathname;
+
+  try {
+    switch (command) {
+      case 'init':
+        process.argv = ['bun', 'init.ts', ...commandArgs];
+        await import(`${scriptDir}init.ts`);
+        break;
+      case 'sync':
+        await import(`${scriptDir}sync.ts`);
+        break;
+      case 'work-on':
+        process.argv = ['bun', 'work-on.ts', ...commandArgs];
+        await import(`${scriptDir}work-on.ts`);
+        break;
+      case 'done':
+        process.argv = ['bun', 'done-job.ts', ...commandArgs];
+        await import(`${scriptDir}done-job.ts`);
+        break;
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`Error: ${error.message}`);
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "team-toon-tack",
+  "version": "1.0.0",
+  "description": "Linear task sync & management CLI with TOON format",
+  "type": "module",
+  "bin": {
+    "ttt": "./bin/cli.ts",
+    "team-toon-tack": "./bin/cli.ts"
+  },
+  "exports": {
+    ".": "./scripts/utils.ts",
+    "./utils": "./scripts/utils.ts"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "templates"
+  ],
+  "scripts": {
+    "start": "bun bin/cli.ts",
+    "build": "bun build bin/cli.ts --outdir dist --target node",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@linear/sdk": "^29.0.0",
+    "@toon-format/toon": "^2.0.0",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "@types/prompts": "^2.4.9"
+  },
+  "keywords": [
+    "linear",
+    "task-management",
+    "cli",
+    "toon",
+    "sync",
+    "project-management"
+  ],
+  "author": "wayne930242",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wayne930242/team-toon-tack.git"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "bun": ">=1.0.0"
+  }
+}

package/scripts/done-job.ts

@@ -0,0 +1,242 @@
+import prompts from 'prompts';
+import { execSync } from 'node:child_process';
+import { getLinearClient, loadConfig, loadCycleData, saveCycleData, getTeamId, getDefaultTeamKey } from './utils';
+
+interface CommitInfo {
+  shortHash: string;
+  fullHash: string;
+  message: string;
+  diffStat: string;
+  commitUrl: string | null;
+}
+
+async function getLatestCommit(): Promise<CommitInfo | null> {
+  try {
+    const shortHash = execSync('git rev-parse --short HEAD', { encoding: 'utf-8' }).trim();
+    const fullHash = execSync('git rev-parse HEAD', { encoding: 'utf-8' }).trim();
+    const message = execSync('git log -1 --format=%s', { encoding: 'utf-8' }).trim();
+    const diffStat = execSync('git diff HEAD~1 --stat --stat-width=60', { encoding: 'utf-8' }).trim();
+
+    // Get remote URL and construct commit link
+    let commitUrl: string | null = null;
+    try {
+      const remoteUrl = execSync('git remote get-url origin', { encoding: 'utf-8' }).trim();
+      // Handle SSH or HTTPS URLs
+      // git@gitlab.com:org/repo.git -> https://gitlab.com/org/repo/-/commit/hash
+      // https://gitlab.com/org/repo.git -> https://gitlab.com/org/repo/-/commit/hash
+      if (remoteUrl.includes('gitlab')) {
+        const match = remoteUrl.match(/(?:git@|https:\/\/)([^:\/]+)[:\\/](.+?)(?:\.git)?$/);
+        if (match) {
+          commitUrl = `https://${match[1]}/${match[2]}/-/commit/${fullHash}`;
+        }
+      } else if (remoteUrl.includes('github')) {
+        const match = remoteUrl.match(/(?:git@|https:\/\/)([^:\/]+)[:\\/](.+?)(?:\.git)?$/);
+        if (match) {
+          commitUrl = `https://${match[1]}/${match[2]}/commit/${fullHash}`;
+        }
+      }
+    } catch {
+      // Ignore if can't get remote URL
+    }
+
+    return { shortHash, fullHash, message, diffStat, commitUrl };
+  } catch {
+    return null;
+  }
+}
+
+function parseArgs(args: string[]): { issueId?: string; message?: string } {
+  let issueId: string | undefined;
+  let message: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '-m' || arg === '--message') {
+      message = args[++i];
+    } else if (!arg.startsWith('-')) {
+      issueId = arg;
+    }
+  }
+
+  return { issueId, message };
+}
+
+async function doneJob() {
+  const { issueId: argIssueId, message: argMessage } = parseArgs(process.argv.slice(2));
+  let issueId = argIssueId;
+
+  const config = await loadConfig();
+  const data = await loadCycleData();
+
+  if (!data) {
+    console.error('No cycle data found. Run /sync-linear first.');
+    process.exit(1);
+  }
+
+  // Find in-progress tasks
+  const inProgressTasks = data.tasks.filter(t => t.localStatus === 'in-progress');
+
+  if (inProgressTasks.length === 0) {
+    console.log('沒有進行中的任務');
+    process.exit(0);
+  }
+
+  // Phase 0: Issue Resolution
+  if (!issueId) {
+    if (inProgressTasks.length === 1) {
+      issueId = inProgressTasks[0].id;
+      console.log(`Auto-selected: ${issueId}`);
+    } else if (process.stdin.isTTY) {
+      const choices = inProgressTasks.map(task => ({
+        title: `${task.id}: ${task.title}`,
+        value: task.id,
+        description: task.labels.join(', ')
+      }));
+
+      const response = await prompts({
+        type: 'select',
+        name: 'issueId',
+        message: '選擇要完成的任務:',
+        choices: choices
+      });
+
+      if (!response.issueId) {
+        console.log('已取消');
+        process.exit(0);
+      }
+      issueId = response.issueId;
+    } else {
+      console.error('多個進行中任務，請指定 issue ID:');
+      inProgressTasks.forEach(t => console.log(`  - ${t.id}: ${t.title}`));
+      process.exit(1);
+    }
+  }
+
+  // Phase 1: Find task
+  const task = data.tasks.find(t => t.id === issueId || t.id === `MP-${issueId}`);
+  if (!task) {
+    console.error(`Issue ${issueId} not found in current cycle.`);
+    process.exit(1);
+  }
+
+  if (task.localStatus !== 'in-progress') {
+    console.log(`⚠️ 任務 ${task.id} 不在進行中狀態 (目前: ${task.localStatus})`);
+    process.exit(1);
+  }
+
+  // Get latest commit for comment
+  const commit = await getLatestCommit();
+
+  // Phase 2: Get AI summary message
+  let aiMessage = argMessage || '';
+  if (!aiMessage && process.stdin.isTTY) {
+    const aiMsgResponse = await prompts({
+      type: 'text',
+      name: 'aiMessage',
+      message: 'AI 修復說明 (如何解決此問題):',
+    });
+    aiMessage = aiMsgResponse.aiMessage || '';
+  }
+
+  // Phase 3: Update Linear
+  if (task.linearId && process.env.LINEAR_API_KEY) {
+    try {
+      const client = getLinearClient();
+      const workflowStates = await client.workflowStates({
+        filter: { team: { id: { eq: getTeamId(config) } } }
+      });
+      const doneState = workflowStates.nodes.find(s => s.name === 'Done');
+
+      // Update issue to Done
+      if (doneState) {
+        await client.updateIssue(task.linearId, { stateId: doneState.id });
+        console.log(`Linear: ${task.id} → Done`);
+      }
+
+      // Add comment with commit info and AI summary
+      if (commit) {
+        const commitLink = commit.commitUrl
+          ? `[${commit.shortHash}](${commit.commitUrl})`
+          : `\`${commit.shortHash}\``;
+
+        const commentParts = [
+          '## ✅ 開發完成',
+          '',
+          '### 🤖 AI 修復說明',
+          aiMessage || '_No description provided_',
+          '',
+          '### 📝 Commit Info',
+          `**Commit:** ${commitLink}`,
+          `**Message:** ${commit.message}`,
+          '',
+          '### 📊 Changes',
+          '```',
+          commit.diffStat,
+          '```',
+        ];
+
+        await client.createComment({
+          issueId: task.linearId,
+          body: commentParts.join('\n')
+        });
+        console.log(`Linear: 已新增 commit 留言`);
+      }
+
+      // Update parent to Testing if exists
+      if (task.parentIssueId) {
+        try {
+          // Find parent issue by identifier
+          const searchResult = await client.searchIssues(task.parentIssueId);
+          const parentIssue = searchResult.nodes.find(
+            issue => issue.identifier === task.parentIssueId
+          );
+
+          if (parentIssue) {
+            // Get parent's team workflow states
+            const parentTeam = await parentIssue.team;
+            if (parentTeam) {
+              const parentWorkflowStates = await client.workflowStates({
+                filter: { team: { id: { eq: parentTeam.id } } }
+              });
+              const testingState = parentWorkflowStates.nodes.find(s => s.name === 'Testing');
+
+              if (testingState) {
+                await client.updateIssue(parentIssue.id, { stateId: testingState.id });
+                console.log(`Linear: Parent ${task.parentIssueId} → Testing`);
+              }
+            }
+          }
+        } catch (parentError) {
+          console.error('Failed to update parent issue:', parentError);
+        }
+      }
+    } catch (e) {
+      console.error('Failed to update Linear:', e);
+    }
+  }
+
+  // Phase 4: Update local status
+  task.localStatus = 'completed';
+  await saveCycleData(data);
+  console.log(`Local: ${task.id} → completed`);
+
+  // Phase 5: Summary
+  console.log(`\n${'═'.repeat(50)}`);
+  console.log(`✅ ${task.id}: ${task.title}`);
+  console.log(`${'═'.repeat(50)}`);
+  if (commit) {
+    console.log(`Commit: ${commit.shortHash} - ${commit.message}`);
+    if (commit.commitUrl) {
+      console.log(`URL: ${commit.commitUrl}`);
+    }
+  }
+  if (aiMessage) {
+    console.log(`AI: ${aiMessage}`);
+  }
+  if (task.parentIssueId) {
+    console.log(`Parent: ${task.parentIssueId} → Testing`);
+  }
+  console.log(`\n🎉 任務完成！`);
+}
+
+doneJob().catch(console.error);