@winspan/claude-forge 8.41.0 → 8.51.0

package/tests/unit/web/task-title-contract.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Safety-net + TDD contract tests for normalizeTaskTitle()
+ *
+ * harness/safety-net:task-title-summary
+ *
+ * Root cause: Tasks stored with title = raw <task-notification> XML (sub-agent
+ * completion callbacks). The frontend renders the literal XML string, making
+ * task titles completely unreadable.
+ *
+ * This file locks the contract for the pure helper `normalizeTaskTitle`:
+ *   - written BEFORE the implementation (TDD red phase)
+ *   - no React / DOM dependency — pure function only
+ *   - covers passthrough, fallback, XML extraction, edge cases
+ */
+
+import { describe, it, expect } from 'vitest';
+
+// ── Import under test (will fail until task-title.ts is created) ─────────────
+// Adjust path to match web/src/utils/task-title.ts resolved from project root.
+// Because vitest.config.ts only includes tests/unit/**, we use a relative path
+// from this file up to web/src/utils/.
+import { normalizeTaskTitle } from '../../../web/src/utils/task-title';
+
+// ── Fixtures ──────────────────────────────────────────────────────────────────
+
+const TASK_NOTIFICATION_FULL = `<task-notification>
+<task-id>aefe161c3350644df</task-id>
+<tool-use-id>toolu_01XxXxXxXx</tool-use-id>
+<output-file>/private/tmp/something/xxx.output</output-file>
+<status>completed</status>
+<summary>Agent "Hotfix Tasks 返回丢筛选" completed</summary>
+<result>Task finished successfully</result>
+<usage><total_tokens>57809</total_tokens><tool_uses>37</tool_uses><duration_ms>289676</duration_ms></usage>
+</task-notification>`;
+
+const TASK_NOTIFICATION_NO_SUMMARY = `<task-notification>
+<task-id>deadbeef</task-id>
+<status>completed</status>
+</task-notification>`;
+
+const TASK_NOTIFICATION_EMOJI_SUMMARY = `<task-notification>
+<summary>Agent "修复 Bug 🐛" completed — see /tmp/report.md</summary>
+</task-notification>`;
+
+const TASK_NOTIFICATION_QUOTES_SUMMARY = `<task-notification>
+<summary>Agent "it's a 'test' with "quotes"" done</summary>
+</task-notification>`;
+
+const LONG_SUMMARY_NOTIFICATION = `<task-notification>
+<summary>Agent completed a very long task description that exceeds the maximum allowed display length of eighty characters in the UI widget</summary>
+</task-notification>`;
+
+const INLINE_CLOSING_TAG = `<task-notification>
+<summary>First match</summary><summary>Should not appear</summary>
+</task-notification>`;
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+describe('normalizeTaskTitle — contract (harness/safety-net:task-title-summary)', () => {
+
+  // ── 1. Passthrough ─────────────────────────────────────────────────────────
+  describe('passthrough for regular titles', () => {
+    it('returns a normal title unchanged', () => {
+      expect(normalizeTaskTitle('批准')).toBe('批准');
+    });
+
+    it('returns a regular English title unchanged', () => {
+      expect(normalizeTaskTitle('Fix login crash')).toBe('Fix login crash');
+    });
+
+    it('trims leading and trailing whitespace', () => {
+      expect(normalizeTaskTitle('  hello world  ')).toBe('hello world');
+    });
+  });
+
+  // ── 2. Fallback for empty / null / undefined ────────────────────────────────
+  describe('fallback for empty / null / undefined', () => {
+    it('returns fallback for empty string', () => {
+      expect(normalizeTaskTitle('')).toBe('(无标题)');
+    });
+
+    it('returns fallback for whitespace-only string', () => {
+      expect(normalizeTaskTitle('   ')).toBe('(无标题)');
+    });
+
+    it('returns fallback for null', () => {
+      expect(normalizeTaskTitle(null)).toBe('(无标题)');
+    });
+
+    it('returns fallback for undefined', () => {
+      expect(normalizeTaskTitle(undefined)).toBe('(无标题)');
+    });
+  });
+
+  // ── 3. task-notification XML extraction ────────────────────────────────────
+  describe('<task-notification> XML extraction', () => {
+    it('extracts <summary> content from a full notification blob', () => {
+      expect(normalizeTaskTitle(TASK_NOTIFICATION_FULL)).toBe(
+        'Agent "Hotfix Tasks 返回丢筛选" completed'
+      );
+    });
+
+    it('returns "(子任务回调)" when <summary> tag is absent', () => {
+      expect(normalizeTaskTitle(TASK_NOTIFICATION_NO_SUMMARY)).toBe('(子任务回调)');
+    });
+
+    it('returns "(子任务回调)" for bare <task-notification> tag alone', () => {
+      expect(normalizeTaskTitle('<task-notification>')).toBe('(子任务回调)');
+    });
+
+    it('preserves emoji and Chinese characters in summary', () => {
+      expect(normalizeTaskTitle(TASK_NOTIFICATION_EMOJI_SUMMARY)).toBe(
+        'Agent "修复 Bug 🐛" completed — see /tmp/report.md'
+      );
+    });
+
+    it('preserves single quotes and double quotes inside summary', () => {
+      expect(normalizeTaskTitle(TASK_NOTIFICATION_QUOTES_SUMMARY)).toBe(
+        `Agent "it's a 'test' with "quotes"" done`
+      );
+    });
+
+    it('takes the first <summary> match when multiple are present (defensive)', () => {
+      expect(normalizeTaskTitle(INLINE_CLOSING_TAG)).toBe('First match');
+    });
+  });
+
+  // ── 4. Truncation ──────────────────────────────────────────────────────────
+  describe('truncation at 80 characters', () => {
+    it('truncates a summary longer than 80 chars and appends ellipsis', () => {
+      const result = normalizeTaskTitle(LONG_SUMMARY_NOTIFICATION);
+      expect(result.endsWith('…')).toBe(true);
+      // The visible text portion is exactly 80 chars (before the ellipsis)
+      expect(result.slice(0, -1).length).toBe(80);
+    });
+
+    it('does not truncate a summary of exactly 80 chars', () => {
+      const exactly80 = 'A'.repeat(80);
+      const notification = `<task-notification><summary>${exactly80}</summary></task-notification>`;
+      const result = normalizeTaskTitle(notification);
+      expect(result).toBe(exactly80);
+      expect(result.endsWith('…')).toBe(false);
+    });
+
+    it('truncates a plain title longer than 80 chars', () => {
+      const long = 'B'.repeat(90);
+      const result = normalizeTaskTitle(long);
+      expect(result.endsWith('…')).toBe(true);
+      expect(result.slice(0, -1).length).toBe(80);
+    });
+
+    it('does not truncate a plain title of exactly 80 chars', () => {
+      const exactly80 = 'C'.repeat(80);
+      expect(normalizeTaskTitle(exactly80)).toBe(exactly80);
+    });
+  });
+
+  // ── 5. Summary whitespace trimming ────────────────────────────────────────
+  describe('summary whitespace trimming', () => {
+    it('trims whitespace inside <summary> tags', () => {
+      const withPad = `<task-notification><summary>  trimmed  </summary></task-notification>`;
+      expect(normalizeTaskTitle(withPad)).toBe('trimmed');
+    });
+
+    it('falls back to "(子任务回调)" when summary is whitespace-only', () => {
+      const whitespaceSummary = `<task-notification><summary>   </summary></task-notification>`;
+      expect(normalizeTaskTitle(whitespaceSummary)).toBe('(子任务回调)');
+    });
+  });
+
+  // ── 6. safety-net:task-title-summary-real — dual-param with firstPrompt ──
+  // These tests will be RED until normalizeTaskTitle is updated to accept a
+  // second parameter (firstPrompt). Phase 2 fix turns them GREEN.
+  describe('dual-param: title=<task-notification> (19 chars) + firstPrompt', () => {
+    const BARE_NOTIFICATION = '<task-notification>';
+
+    it('extracts summary from firstPrompt when title is bare 19-char token', () => {
+      const firstPrompt = '<task-notification>\n<summary>Fix the login bug</summary>\n</task-notification>';
+      expect(normalizeTaskTitle(BARE_NOTIFICATION, firstPrompt)).toBe('Fix the login bug');
+    });
+
+    it('shows head of firstPrompt when it has no summary tag', () => {
+      const firstPrompt = 'Please investigate the database performance issue and report findings.';
+      const result = normalizeTaskTitle(BARE_NOTIFICATION, firstPrompt);
+      expect(result).toMatch(/^\(子任务回调\) — /);
+      expect(result).toContain('Please investigate');
+    });
+
+    it('falls back to "(子任务回调)" when firstPrompt is null', () => {
+      expect(normalizeTaskTitle(BARE_NOTIFICATION, null)).toBe('(子任务回调)');
+    });
+
+    it('falls back to "(子任务回调)" when firstPrompt is undefined', () => {
+      expect(normalizeTaskTitle(BARE_NOTIFICATION, undefined)).toBe('(子任务回调)');
+    });
+
+    it('plain title ignores firstPrompt entirely (no contamination)', () => {
+      const fp = '<task-notification><summary>Should be ignored</summary></task-notification>';
+      expect(normalizeTaskTitle('Fix login crash', fp)).toBe('Fix login crash');
+    });
+
+    it('truncates a long summary from firstPrompt at 80 chars with ellipsis', () => {
+      const longSummary = 'A'.repeat(90);
+      const fp = `<task-notification><summary>${longSummary}</summary></task-notification>`;
+      const result = normalizeTaskTitle(BARE_NOTIFICATION, fp);
+      expect(result.endsWith('…')).toBe(true);
+      expect(result.slice(0, -1).length).toBe(80);
+    });
+  });
+});

package/tests/unit/web/tasks-component-contract.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Safety-net: Tasks component API contract test
+ *
+ * harness/safety-net:tasks-page-white-screen
+ *
+ * Root cause: Tasks.tsx called GET /api/tasks and treated the response as
+ * Task[] (bare array), but the API returns { items: Task[], total, has_more }.
+ * Iterating a plain object as an array caused a runtime error → white screen.
+ *
+ * This test locks the correct API contract so a regression is immediately
+ * visible. It also validates the TypeScript-level interface that Tasks.tsx
+ * must use when consuming the /api/tasks endpoint.
+ */
+
+import { describe, it, expect } from 'vitest';
+
+// ── Types mirroring the API contract ────────────────────────────────────────
+
+interface TaskRecord {
+  id: string;
+  session_id: string;
+  title: string;
+  status: 'active' | 'completed' | 'abandoned';
+  start_time: string;
+  end_time?: string;
+  event_count: number;
+  project_path?: string;
+}
+
+interface TaskPage {
+  items: TaskRecord[];
+  total: number;
+  has_more: boolean;
+}
+
+// ── Simulated fetch helpers (pure functions, no DOM needed) ──────────────────
+
+/**
+ * BROKEN: simulates what the old Tasks.tsx code did — treated the entire
+ * response body as a Task[] and tried to .filter() on it.
+ * This is the defect we are safety-netting.
+ */
+function consumeTasksResponseBROKEN(responseBody: unknown): TaskRecord[] {
+  // Old code: `return res.json()` then `tasks.filter(...)` — treats body as array
+  return responseBody as TaskRecord[];
+}
+
+/**
+ * CORRECT: extracts items from the paginated wrapper that /api/tasks returns.
+ */
+function consumeTasksResponseCORRECT(responseBody: TaskPage): TaskRecord[] {
+  return responseBody.items;
+}
+
+// ── Test fixtures ─────────────────────────────────────────────────────────────
+
+const TASK_RECORD: TaskRecord = {
+  id: 'abc-123',
+  session_id: 'sess-001',
+  title: 'Test task',
+  status: 'active',
+  start_time: '2026-05-18T00:00:00.000Z',
+  event_count: 5,
+  project_path: '/home/user/project',
+};
+
+const API_RESPONSE: TaskPage = {
+  items: [TASK_RECORD],
+  total: 1,
+  has_more: false,
+};
+
+// ── Contract: /api/tasks must return { items, total, has_more } ───────────────
+
+describe('Tasks API contract (safety-net: tasks-page-white-screen)', () => {
+  describe('API response shape', () => {
+    it('response body is an object with items array, not a bare array', () => {
+      expect(Array.isArray(API_RESPONSE)).toBe(false);
+      expect(typeof API_RESPONSE).toBe('object');
+    });
+
+    it('response.items is the array of task records', () => {
+      expect(Array.isArray(API_RESPONSE.items)).toBe(true);
+      expect(API_RESPONSE.items).toHaveLength(1);
+    });
+
+    it('response.total is a number >= 0', () => {
+      expect(typeof API_RESPONSE.total).toBe('number');
+      expect(API_RESPONSE.total).toBeGreaterThanOrEqual(0);
+    });
+
+    it('response.has_more is a boolean', () => {
+      expect(typeof API_RESPONSE.has_more).toBe('boolean');
+    });
+
+    it('each item has required fields: id, session_id, title, status, start_time, event_count', () => {
+      const item = API_RESPONSE.items[0];
+      expect(item).toHaveProperty('id');
+      expect(item).toHaveProperty('session_id');
+      expect(item).toHaveProperty('title');
+      expect(item).toHaveProperty('status');
+      expect(item).toHaveProperty('start_time');
+      expect(item).toHaveProperty('event_count');
+    });
+  });
+
+  describe('[CHAR] broken consumer — documents the white-screen defect', () => {
+    it('treating response body as Task[] gives an object not an array (this was the bug)', () => {
+      // consumeTasksResponseBROKEN returns the whole { items, total, has_more } object
+      // as if it were Task[]. Calling array methods on it would throw.
+      const result = consumeTasksResponseBROKEN(API_RESPONSE);
+      // The broken code returns an object where an array is expected
+      expect(Array.isArray(result)).toBe(false);
+      // Accessing .filter would succeed (it's on Object.prototype? No — it would
+      // return undefined because plain objects don't have .filter)
+      expect(typeof (result as unknown as { filter?: unknown }).filter).toBe('undefined');
+    });
+
+    it('[CHAR] calling .map on the broken result throws or returns undefined', () => {
+      const result = consumeTasksResponseBROKEN(API_RESPONSE) as unknown;
+      // When Tasks.tsx does tasks.filter(...), tasks is { items, total, has_more }
+      // which has no .filter → calling it throws TypeError
+      expect(() => {
+        (result as TaskRecord[]).filter(() => true);
+      }).toThrow(TypeError);
+    });
+  });
+
+  describe('correct consumer — contract the fix must satisfy', () => {
+    it('correct consumer returns an actual array', () => {
+      const result = consumeTasksResponseCORRECT(API_RESPONSE);
+      expect(Array.isArray(result)).toBe(true);
+    });
+
+    it('correct consumer exposes task fields for rendering', () => {
+      const result = consumeTasksResponseCORRECT(API_RESPONSE);
+      expect(result[0].id).toBe('abc-123');
+      expect(result[0].title).toBe('Test task');
+      expect(result[0].status).toBe('active');
+    });
+
+    it('total is preserved from response for pagination display', () => {
+      expect(API_RESPONSE.total).toBe(1);
+    });
+
+    it('has_more drives next-page button state', () => {
+      expect(API_RESPONSE.has_more).toBe(false);
+    });
+
+    it('empty page shape is valid', () => {
+      const empty: TaskPage = { items: [], total: 0, has_more: false };
+      const result = consumeTasksResponseCORRECT(empty);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('pagination parameters', () => {
+    it('default limit is 50', () => {
+      // The API uses Zod default(50) — component should default to 50 items/page
+      const defaultLimit = 50;
+      expect(defaultLimit).toBeGreaterThan(0);
+    });
+
+    it('supported page sizes are 20, 50, 100', () => {
+      const PAGE_SIZES = [20, 50, 100];
+      PAGE_SIZES.forEach(size => {
+        expect(size).toBeGreaterThan(0);
+        expect(size).toBeLessThanOrEqual(200); // API max is 200
+      });
+    });
+
+    it('offset is computed as (page - 1) * pageSize', () => {
+      const page = 3;
+      const pageSize = 50;
+      const offset = (page - 1) * pageSize;
+      expect(offset).toBe(100);
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "moduleResolution": "nodenext",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/unit/**/*.test.ts', 'tests/integration/**/*.test.ts'],
+    exclude: ['tests-old/**', 'src-old/**', 'node_modules/**'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: ['node_modules/', 'dist/', 'tests/', 'tests-old/', 'src-old/']
+    }
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src')
+    }
+  }
+});

package/vitest.integration.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vitest/config';
+import path from 'path';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/unit/**/*.test.ts', 'tests/integration/**/*.test.ts'],
+    exclude: ['tests-old/**', 'src-old/**', 'node_modules/**'],
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src')
+    }
+  }
+});

package/web/CLAUDE.md

@@ -0,0 +1,20 @@
+
+
+<!-- forge:resume-begin:4be8b345-7ddc-4d5f-819a-ebb586eb0ec7 -->
+```forge-resume-body
+## 上次工作续接
+
+⚠️ **IMPORTANT: 在开始新任务前，请先检查以下上下文**
+
+**上次在做**:
+- <task-notification>
+
+**上次活跃**: 刚刚
+
+**会话行为**: 工具调用 4934 次 | Agent 委托 106 次 (Explore, coder, feature-developer) | Skill 调用 9 次
+
+_生成时间: 2026-05-15T04:39:12.196Z_
+```
+
+_生成时间: 2026-05-15T04:39:12.272Z_
+<!-- forge:resume-end:4be8b345-7ddc-4d5f-819a-ebb586eb0ec7 -->

package/web/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Claude Forge 管理后台</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>