feat(timer): 碼錶移出領取，等工作樹建成之後才起

原本的順序是「放行 → 設 assignee 與標籤 → 起錶 → 處理分支」，而工作樹建立
失敗會中止整個領取——錶已經起了才失敗，使用者會被計一段什麼都沒做的時間，
而工時要準正是工時報表的立足點。

claim 只留領取鎖的兩件事（assignee 與標籤），起錶交給新的 timer.js，由流程
正本排在 branch-prep 之後。timer 已經跑在這顆議題上時什麼都不做：中斷後重跑
是它最常見的處境，重新起錶會把已經累積的時間切成兩段；跑在別顆上則照舊擋下，
不代勞停錶。

三支腳本讀碼錶的那段各留一份，趁這次收進 lib。

議題 #40

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

scripts/claim.js

@@ -1,10 +1,13 @@
 #!/usr/bin/env node
 /**
- * 領取一顆工作包：上鎖、貼標籤、起錶。
+ * 領取一顆工作包：上鎖、貼標籤。
  *
  * 鎖用 assignee 加標籤，不用碼錶——Gitea 只讓人讀自己的碼錶（`/user/stopwatches`），
  * 看不到別人的錶，拿它當鎖會漏判。碼錶在這裡只有一個用途：發現自己忘了停掉上一顆。
  *
+ * **錶不在這一步起**。它等工作樹建好之後才由 timer.js 起動（見 branch-prep.js）：
+ * 工作樹建立失敗會中止整個領取，錶要是先起了，使用者就被計了一段什麼都沒做的時間。
+ *
  * 四種狀態的處置：
  *   - 他人已認領                → 擋。不會兩個人做同一件事。
  *   - 自己的錶跑在本議題        → 擋。這顆你已經在做了，別重複起錶。
@@ -24,12 +27,14 @@ import {
   fetchIssue,
   giteaRequest,
   listLabels,
+  listStopwatches,
   main,
   parseFlags,
   parseIndex,
   parseRepo,
   preflight,
   resolveLogin,
+  stopwatchOnIssue,
 } from './lib.js';
 
 /** 領取鎖的另一半。本 plugin 不自動建立標籤，這個名字要在 repo 上先存在。 */
@@ -84,9 +89,6 @@ main(async () => {
     });
     labels.push(IN_PROGRESS);
   }
-  // 錶最後才起：前面任一步失敗時，不該留下一顆還在跑的碼錶
-  planned.push({ method: 'POST', path: `${issuePath}/stopwatch/start`, body: {} });
-
   if (dryRun) {
     return { dryRun: true, repo, index, title: issue.title, requests: planned, 已認領過 };
   }
@@ -102,7 +104,8 @@ main(async () => {
     url: issue.html_url,
     assignee: me,
     labels,
-    碼錶中: true,
+    // 鎖上好了，錶還沒起：它等工作樹建好之後才由 timer.js 起動
+    碼錶中: false,
     已認領過,
   };
 });
@@ -128,14 +131,10 @@ function checkClaimable(assignees, me, index) {
  * 跑在別的議題是「你忘了停掉那一顆」。
  */
 async function checkNoStopwatch(login, repo, index) {
-  const path = '/user/stopwatches';
+  const watches = await listStopwatches(login);
-  const watches = expectOk(await giteaRequest(login, 'GET', path), `GET ${path}`) ?? [];
   if (watches.length === 0) return;
 
-  const here = watches.find(
+  if (stopwatchOnIssue(watches, repo, index)) {
-    (watch) => `${watch.repo_owner_name}/${watch.repo_name}` === repo && watch.issue_index === index,
-  );
-  if (here) {
     throw new ScriptError(
       'STOPWATCH_ON_THIS_ISSUE',
       `你的碼錶已經跑在議題 #${index} 上，這顆你正在做；` +

scripts/timer.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * 起錶。
+ *
+ * 錶與領取鎖是兩件事：鎖用 assignee 加標籤（見 claim.js），錶只管工時。分開的理由是
+ * 時機不同——鎖要在開工之前就上好，錶則要等到**工作樹真的建好之後**才起。工作樹建立
+ * 失敗會中止整個領取，錶要是先起了，使用者就被計了一段什麼都沒做的時間，
+ * 而工時要準正是工時報表的立足點。
+ *
+ * 自己的錶跑在別顆議題上時擋下，不代勞停錶：那一段時間該記在哪顆議題上只有人知道，
+ * 腳本自作主張會把工時記錯地方。錶已經跑在本議題上則什麼都不做——重新起錶會把已經
+ * 累積的時間切成兩段，而中斷後重跑正是這支腳本最常見的處境。
+ *
+ * 用法：
+ *   node scripts/timer.js --repo owner/name --index 40 [--host <網址>] [--dry-run]
+ */
+import {
+  ScriptError,
+  expectOk,
+  fetchIssue,
+  giteaRequest,
+  listStopwatches,
+  main,
+  parseFlags,
+  parseIndex,
+  parseRepo,
+  preflight,
+  resolveLogin,
+  stopwatchOnIssue,
+} from './lib.js';
+
+main(async () => {
+  const flags = parseFlags(process.argv.slice(2), {
+    required: ['repo', 'index'],
+    optional: ['host'],
+    booleans: ['dry-run'],
+  });
+  const repo = parseRepo(flags.repo);
+  const index = parseIndex(flags.index);
+  const issuePath = `/repos/${repo}/issues/${index}`;
+  const dryRun = flags['dry-run'] === true;
+
+  const login = resolveLogin({ host: flags.host });
+  // 試跑照樣讀現況：手寫一份固定的清單會跟實作走鐘，也說不出「這顆已經在計時了」
+  if (!dryRun) await preflight(login, repo);
+  const issue = await fetchIssue(login, repo, index);
+
+  const watches = await listStopwatches(login);
+  const 已在計時 = stopwatchOnIssue(watches, repo, index) !== null;
+  if (!已在計時 && watches.length > 0) {
+    const elsewhere = watches[0];
+    throw new ScriptError(
+      'STOPWATCH_ON_OTHER_ISSUE',
+      `你的碼錶正跑在 ${elsewhere.repo_owner_name}/${elsewhere.repo_name} 的議題 ` +
+        `#${elsewhere.issue_index} 上，起錶前請先手動停錶，否則工時會記到那一顆去`,
+    );
+  }
+
+  // 已經在跑就不重起：重新起錶會把已經累積的時間切成兩段
+  const planned = 已在計時 ? [] : [{ method: 'POST', path: `${issuePath}/stopwatch/start`, body: {} }];
+
+  if (dryRun) {
+    return { dryRun: true, repo, index, title: issue.title, requests: planned, 已在計時 };
+  }
+
+  for (const { method, path, body } of planned) {
+    expectOk(await giteaRequest(login, method, path, { body }), `${method} ${path}`);
+  }
+
+  return {
+    repo,
+    index: issue.number,
+    title: issue.title,
+    url: issue.html_url,
+    碼錶中: true,
+    已在計時,
+  };
+});

scripts/wp-extract.js

@@ -14,9 +14,8 @@
 import {
   UNMERGED_COMMENT_NOTE,
   countUnmergedComments,
-  expectOk,
   fetchIssue,
-  giteaRequest,
+  listStopwatches,
   main,
   pages,
   parseFlags,
@@ -24,6 +23,7 @@ import {
   parseRepo,
   preflight,
   resolveLogin,
+  stopwatchOnIssue,
 } from './lib.js';
 import {
   checklistInSection,
@@ -118,10 +118,5 @@ async function fetchLinked(login, path, kind) {
  * ——領取鎖看的是 assignee。
  */
 async function hasRunningStopwatch(login, repo, index) {
-  const path = '/user/stopwatches';
+  return stopwatchOnIssue(await listStopwatches(login), repo, index) !== null;
-  const watches = expectOk(await giteaRequest(login, 'GET', path), `GET ${path}`) ?? [];
-
-  return watches.some(
-    (watch) => `${watch.repo_owner_name}/${watch.repo_name}` === repo && watch.issue_index === index,
-  );
 }

test/claim.test.js

@@ -1,6 +1,10 @@
 /**
  * 領取工作包的鎖。
  *
+ * 錶不在這一支起——它等工作樹建好之後才由 timer.js 起動，所以這裡連帶要驗
+ * 「一發起錶請求都沒有」：領取失敗或工作樹建不起來時，使用者不該被計一段
+ * 什麼都沒做的時間。
+ *
  * 這一支的價值全在「什麼時候擋下來」：放行的路徑只有一條，擋的理由有四種，
  * 而擋錯的代價是兩個人做同一件事、或是工時記到別顆議題上。所以決策表的四種狀態
  * 各有測試，而且每一種都要驗「一個字都沒寫進 Gitea」——擋下來卻已經改了一半，
@@ -68,7 +72,7 @@ const writes = (stub) =>
 
 // ── 決策表：無鎖 ───────────────────────────────────────────────────
 
-test('沒有鎖時放行：設 assignee、貼進行中、起錶', async (t) => {
+test('沒有鎖時放行：設 assignee、貼進行中', async (t) => {
   const stub = await withStub(t, {}, { repoLabels: ['ready-for-agent', '進行中'] });
 
   const { code, json } = await run([], stub);
@@ -76,11 +80,11 @@ test('沒有鎖時放行：設 assignee、貼進行中、起錶', async (t) => {
   assert.equal(code, 0);
   assert.equal(json.data.assignee, ME);
   assert.deepEqual(json.data.labels, ['進行中']);
-  assert.equal(json.data.碼錶中, true);
+  assert.equal(json.data.碼錶中, false, '鎖上好了，錶還沒起');
   assert.equal(json.data.已認領過, false);
 });
 
-test('放行時三個寫入請求都發出，且順序為先上鎖再起錶', async (t) => {
+test('放行時只寫入鎖的那兩件事，一發起錶請求都沒有', async (t) => {
   const stub = await withStub(t, {}, { repoLabels: ['進行中'] });
 
   await run([], stub);
@@ -90,9 +94,8 @@ test('放行時三個寫入請求都發出，且順序為先上鎖再起錶', as
     [
       `PATCH /api/v1/repos/${REPO}/issues/${INDEX}`,
       `POST /api/v1/repos/${REPO}/issues/${INDEX}/labels`,
-      `POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/start`,
     ],
-    '錶要最後才起：前面任一步失敗時，不該留下一顆還在跑的碼錶',
+    '錶等工作樹建好之後才由 timer.js 起動：建不起來就中止，不該已經計了時間',
   );
 });
 
@@ -180,7 +183,7 @@ test('自己已認領但沒有錶時放行，並如實說這顆本來就是自
 
   assert.equal(code, 0);
   assert.equal(json.data.已認領過, true);
-  assert.equal(json.data.碼錶中, true, '錶還是要起，中斷重跑就是為了接上這件事');
+  assert.equal(json.data.碼錶中, false, '重跑時鎖照樣補齊，錶則仍舊留到工作樹建好之後');
 });
 
 test('進行中標籤已經在議題上時不重複貼', async (t) => {
@@ -251,7 +254,6 @@ test('--dry-run 印出將發出的寫入，但一個字都不寫進去', async (
     [
       `PATCH /repos/${REPO}/issues/${INDEX}`,
       `POST /repos/${REPO}/issues/${INDEX}/labels`,
-      `POST /repos/${REPO}/issues/${INDEX}/stopwatch/start`,
     ],
   );
   assert.deepEqual(writes(stub), [], '預覽不得真的寫入');
@@ -270,7 +272,7 @@ test('--dry-run 會先讀現況：預覽出來的是這一顆實際的處境', a
   assert.ok(reads.includes(`/api/v1/repos/${REPO}/labels`));
 });
 
-test('--dry-run 略過已經做好的部分，不謊報將發出的請求', async (t) => {
+test('--dry-run 略過已經做好的部分：鎖都在了就什麼都不必寫', async (t) => {
   const stub = await withStub(t, {}, {
     assignees: [ME],
     labels: ['進行中'],
@@ -280,9 +282,9 @@ test('--dry-run 略過已經做好的部分，不謊報將發出的請求', asyn
   const { json } = await run(['--dry-run'], stub);
 
   assert.deepEqual(
-    json.data.requests.map((r) => `${r.method} ${r.path}`),
+    json.data.requests,
-    [`POST /repos/${REPO}/issues/${INDEX}/stopwatch/start`],
+    [],
-    'assignee 與標籤都已經到位，只差起錶',
+    'assignee 與標籤都已經到位，中斷重跑就是走到這裡；手寫一份固定的清單會謊報',
   );
 });
 

test/timer.test.js

@@ -0,0 +1,144 @@
+/**
+ * 起錶。
+ *
+ * 錶是工時報表的唯一來源，所以這一支的價值全在「什麼時候不該起」：工作樹還沒建好
+ * 不該起（那由流程的順序保證），自己的錶已經跑在別顆議題上更不該起——那會把兩顆
+ * 工作包的時間攪在一起。停錶一律由使用者自己來，這裡不提供。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runScript } from './helpers/run-script.js';
+import { healthyRoutes, stubEnv as envFor, withStubGitea } from './helpers/stub-gitea.js';
+
+const REPO = 'plugins/tea-sdlc';
+const INDEX = 40;
+
+/** 議題上跑著的碼錶長什麼樣 */
+const stopwatchOn = (index, repo = REPO) => ({
+  issue_index: index,
+  repo_owner_name: repo.split('/')[0],
+  repo_name: repo.split('/')[1],
+});
+
+function routes(overrides = {}, { stopwatches = [] } = {}) {
+  return healthyRoutes(REPO, {
+    [`GET /api/v1/repos/${REPO}/issues/${INDEX}`]: {
+      status: 200,
+      body: {
+        number: INDEX,
+        title: '以 worktree 建立工作包分支並備妥隔離環境',
+        html_url: `https://gitea.jsc.idv.tw/${REPO}/issues/${INDEX}`,
+      },
+    },
+    'GET /api/v1/user/stopwatches': { status: 200, body: stopwatches },
+    [`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/start`]: { status: 201, body: {} },
+    ...overrides,
+  });
+}
+
+const withStub = (t, overrides = {}, options) => withStubGitea(t, routes(overrides, options));
+
+const run = (args, stub) =>
+  runScript('timer.js', ['--repo', REPO, '--index', String(INDEX), ...args], { env: envFor(stub) });
+
+/** 會改動 Gitea 的請求；前置檢查打在 issues/0 的探針不算（見 lib 的 checkIssueWrite） */
+const writes = (stub) =>
+  stub.requests.filter((r) => r.method !== 'GET').filter((r) => !r.path.endsWith('/issues/0'));
+
+test('沒有錶在跑時起錶，並回報起在哪一顆上', async (t) => {
+  const stub = await withStub(t);
+
+  const { code, json } = await run([], stub);
+
+  assert.equal(code, 0, json.error?.message);
+  assert.equal(json.data.碼錶中, true);
+  assert.equal(json.data.index, INDEX);
+  assert.deepEqual(
+    writes(stub).map((r) => `${r.method} ${r.path}`),
+    [`POST /api/v1/repos/${REPO}/issues/${INDEX}/stopwatch/start`],
+  );
+});
+
+test('錶已經跑在這顆議題上時什麼都不做，重跑不會把計時打斷', async (t) => {
+  const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] });
+
+  const { code, json } = await run([], stub);
+
+  assert.equal(code, 0, json.error?.message);
+  assert.equal(json.data.碼錶中, true);
+  assert.equal(json.data.已在計時, true, '要如實說這顆本來就在計時，不要假裝是這次起的');
+  assert.deepEqual(writes(stub), [], '重新起錶會把已經累積的時間切成兩段');
+});
+
+test('錶跑在別顆議題上時擋下，並指出是哪一顆', async (t) => {
+  const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(7)] });
+
+  const { code, json } = await run([], stub);
+
+  assert.equal(code, 1);
+  assert.equal(json.error.code, 'STOPWATCH_ON_OTHER_ISSUE');
+  assert.match(json.error.message, /#7/, '忘了停掉的是哪一顆，要指名');
+  assert.deepEqual(writes(stub), [], '擋下來就不該寫進任何東西');
+});
+
+test('別的 repo 上的同號碼錶也算自己有錶在跑', async (t) => {
+  const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX, 'plugins/別的專案')] });
+
+  const { json } = await run([], stub);
+
+  assert.equal(json.error.code, 'STOPWATCH_ON_OTHER_ISSUE');
+  assert.match(json.error.message, /別的專案/);
+});
+
+test('不代替使用者停錶：訊息要說清楚下一步是他自己去停', async (t) => {
+  const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(7)] });
+
+  const { json } = await run([], stub);
+
+  assert.match(json.error.message, /停/);
+});
+
+test('議題不存在時回可區分的錯誤碼', async (t) => {
+  const stub = await withStub(t, {
+    [`GET /api/v1/repos/${REPO}/issues/${INDEX}`]: { status: 404, body: { message: 'not found' } },
+  });
+
+  const { json } = await run([], stub);
+
+  assert.equal(json.error.code, 'ISSUE_NOT_FOUND');
+  assert.deepEqual(writes(stub), []);
+});
+
+test('--index 不是正整數時擋在打 Gitea 之前', async (t) => {
+  const stub = await withStub(t);
+
+  const { json } = await runScript('timer.js', ['--repo', REPO, '--index', '0'], {
+    env: envFor(stub),
+  });
+
+  assert.equal(json.error.code, 'BAD_INDEX');
+  assert.equal(stub.requests.length, 0);
+});
+
+test('--dry-run 印出將發出的寫入，但一個字都不寫進去', async (t) => {
+  const stub = await withStub(t);
+
+  const { code, json } = await run(['--dry-run'], stub);
+
+  assert.equal(code, 0);
+  assert.equal(json.data.dryRun, true);
+  assert.deepEqual(
+    json.data.requests.map((r) => `${r.method} ${r.path}`),
+    [`POST /repos/${REPO}/issues/${INDEX}/stopwatch/start`],
+  );
+  assert.deepEqual(writes(stub), [], '預覽不得真的寫入');
+});
+
+test('--dry-run 會先讀現況：已經在計時時預覽出來就是什麼都不做', async (t) => {
+  const stub = await withStub(t, {}, { stopwatches: [stopwatchOn(INDEX)] });
+
+  const { json } = await run(['--dry-run'], stub);
+
+  assert.deepEqual(json.data.requests, [], '手寫一份固定的清單會跟實作走鐘');
+  assert.equal(json.data.已在計時, true);
+});