@namewta/speculo 0.3.2 → 0.3.4

package/template/skills/typescript-engineering-standards/references/04-typescript-type-system.md

@@ -0,0 +1,150 @@
+# TypeScript 类型系统规范
+
+## 严格模式
+
+新项目必须启用 `strict`。建议逐步启用：
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "useUnknownInCatchVariables": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "forceConsistentCasingInFileNames": true
+  }
+}
+```
+
+具体选项需与编译器版本、模块系统和构建工具兼容。
+
+## 禁止传播 `any`
+
+外部或未知值使用 `unknown`，在边界收窄：
+
+```ts
+function parsePayload(input: unknown): ParsedPayload {
+  return payloadSchema.parse(input)
+}
+```
+
+`any` 只允许存在于极小的兼容层，例如第三方类型错误或遗留迁移，并必须：
+
+- 限定最小作用域。
+- 写明原因与退出条件。
+- 经过运行时验证后再向内部传递。
+- 不进入公共 API。
+
+## 外部输入必须验证
+
+以下数据默认不可信：
+
+- HTTP、RPC、WebSocket、IPC 消息。
+- CLI 参数和环境变量。
+- JSON、数据库反序列化、本地存储。
+- 第三方 SDK 返回值。
+- 浏览器消息和插件输入。
+
+类型断言不是验证：
+
+```ts
+// 错误
+const config = JSON.parse(raw) as AppConfig
+
+// 正确
+const config = appConfigSchema.parse(JSON.parse(raw))
+```
+
+## 可辨识联合
+
+使用单一判别字段表达互斥状态：
+
+```ts
+type ConnectionState =
+  | { kind: 'idle' }
+  | { kind: 'connecting'; startedAtMs: number }
+  | { kind: 'connected'; connectionId: string }
+  | { kind: 'failed'; error: Error }
+```
+
+避免多个可能互相矛盾的布尔字段。对状态分支执行穷尽检查；需要 `default` 时使用 `never` 断言。
+
+## `type` 与 `interface`
+
+默认策略可选择其一并保持一致。推荐默认使用 `type`，以下场景使用 `interface`：
+
+- 需要声明合并。
+- 公共库希望消费者扩展契约。
+- 面向对象体系明确使用 `implements`。
+- 框架生态已有强约定。
+
+不要在同一领域无理由混用。
+
+## 显式类型和推断
+
+必须显式标注：
+
+- 导出函数返回类型。
+- 跨模块公共 API。
+- 插件、回调和扩展点。
+- 递归函数。
+- 权限、金额、状态转换等高风险函数。
+
+局部明显变量和短小私有函数可依赖推断。
+
+## 类型断言
+
+优先顺序：
+
+1. 控制流收窄。
+2. 类型守卫。
+3. 运行时 Schema 验证。
+4. `satisfies`。
+5. 最后才使用 `as`。
+
+禁止无理由双重断言：
+
+```ts
+value as unknown as UserSession
+```
+
+`@ts-ignore` 默认禁止。必须压制已知编译错误时，优先使用带原因的 `@ts-expect-error`，使错误消失后检查能够失败。
+
+## 空值语义
+
+明确区分：
+
+- `property?: T`：属性可能不存在。
+- `property: T | null`：属性存在，但值可以为空。
+- `T | undefined`：查找可能没有结果。
+- `Result<T, E>` 或异常：操作可能失败。
+
+除非外部协议明确区分，不要写 `property?: T | null | undefined`。
+
+## `.d.ts`
+
+`.d.ts` 仅用于：
+
+- 运行时已有但 TypeScript 不可见的全局声明。
+- 无类型第三方模块声明。
+- 框架或库声明扩展。
+- 发布库生成的公共声明。
+
+普通业务类型放在 `.ts` 中，通过正常模块导入。
+
+## 枚举
+
+默认优先字符串联合或 `as const` 对象。`enum` 主要用于外部协议、位标记、既有 API 或团队明确统一的运行时枚举需求。
+
+## 不可变性
+
+- 输入参数尽量使用只读结构。
+- 对外返回 `ReadonlyArray<T>` 或只读对象。
+- 不修改调用方传入对象。
+- 需要排序或变更时先复制。
+- 常量对象使用 `as const` 或 `satisfies`。

package/template/skills/typescript-engineering-standards/references/05-functions-async-errors-and-resources.md

@@ -0,0 +1,142 @@
+# 函数、异步、错误与资源生命周期
+
+## 函数职责
+
+函数应只处理一个可命名职责和一个抽象层级。软性目标：
+
+- 普通函数尽量不超过约 40 行。
+- 编排函数尽量不超过约 60 行。
+- 嵌套通常不超过三层。
+- 参数超过三个时考虑参数对象。
+
+这些数字用于触发审查，不是机械拆分标准。
+
+## 提前返回
+
+使用 Guard Clause 减少嵌套：
+
+```ts
+function processSession(session: Session | undefined): Result {
+  if (!session) {
+    return emptyResult
+  }
+
+  if (!session.isActive || !session.userId) {
+    return emptyResult
+  }
+
+  return createResult(session)
+}
+```
+
+## 参数对象
+
+长参数列表或布尔参数应改为具名选项：
+
+```ts
+type CreateSessionOptions = {
+  userId: string
+  timeoutMs: number
+  persistence: 'memory' | 'disk'
+  logger: Logger
+}
+```
+
+避免 `createSession(id, true, false)`。
+
+## 纯逻辑和副作用分离
+
+建议分离：
+
+- 解析。
+- 验证。
+- 领域决策。
+- 数据持久化。
+- 流程编排。
+
+纯逻辑不读取隐藏全局状态、不修改输入、不直接访问网络、磁盘、时钟或随机源。将这些依赖作为参数或端口注入。
+
+## Promise 必须有归宿
+
+所有 Promise 必须被 `await`、`return`、显式收集，或用 `void` 明确表示有意脱离当前流程，并自行处理错误：
+
+```ts
+void refreshCache().catch((error: unknown) => {
+  logger.error('Failed to refresh cache', { error })
+})
+```
+
+## 并发
+
+只有相互独立的任务才使用 `Promise.all`。有顺序、共享副作用、速率限制或资源约束时，使用顺序执行、队列或并发限制器。
+
+不要无界并发处理大型输入集合。
+
+## 取消与超时
+
+网络、子进程、文件监听、Worker 和长任务应考虑：
+
+- `AbortSignal`。
+- 明确超时。
+- 清理路径。
+- 可识别的取消错误。
+- 超时后底层资源是否真正停止。
+
+## 重试
+
+重试策略必须定义：
+
+- 最大次数。
+- 退避和抖动。
+- 可重试错误范围。
+- 幂等性。
+- 最终失败的记录与反馈。
+
+不能对所有错误无限重试。
+
+## 错误处理
+
+不得吞掉异常。允许忽略时必须说明这是最佳努力操作，并保留必要诊断信息。
+
+错误应包含上下文并保留 `cause`：
+
+```ts
+throw new Error(`Failed to load workspace config: ${configPath}`, {
+  cause: error
+})
+```
+
+需要调用方分支处理的错误使用：
+
+- 具名错误类。
+- 带 `code` 的结构化错误。
+- `Result<T, E>`。
+- 可辨识联合。
+
+不要通过匹配错误消息字符串控制流程。
+
+## `catch` 值
+
+将 `catch` 值视为 `unknown`，先通过 `instanceof`、错误守卫或标准化函数收窄。
+
+## 资源清理
+
+以下资源必须有明确生命周期：
+
+- 事件监听器。
+- Timer 和 Interval。
+- 文件句柄。
+- Socket、数据库连接。
+- Worker 和子进程。
+- `AbortController`。
+- React Effect 订阅。
+
+推荐返回清理函数或实现统一 `dispose()`：
+
+```ts
+type Disposable = {
+  dispose(): void
+}
+```
+
+创建资源的模块通常也应负责定义或暴露其清理方式。

package/template/skills/typescript-engineering-standards/references/06-comments-jsdoc-and-documentation.md

@@ -0,0 +1,104 @@
+# 注释、JSDoc 与文档
+
+## 注释解释原因
+
+注释用于解释代码本身无法清楚表达的：
+
+- 为什么必须采用此顺序。
+- 为什么不能删除看似多余的逻辑。
+- 平台、协议、性能或安全约束。
+- 第三方缺陷和规避方案。
+- 竞态条件和资源生命周期。
+- 非直观产品规则。
+
+不应逐行翻译代码。
+
+```ts
+// 不推荐：Increment retry count.
+retryCount += 1
+
+// 推荐：Provider replication can briefly return 409 after a successful write.
+retryCount += 1
+```
+
+## 注释风格
+
+- 优先一行或一个短段落。
+- 靠近被解释的逻辑。
+- 使用完整、可验证的原因。
+- 修改实现时同步更新。
+- 能用命名和拆分表达时，不靠注释补救。
+
+## 应写注释的场景
+
+- 跨平台差异。
+- 第三方类型或运行时缺陷。
+- 兼容旧协议的临时分支。
+- 性能关键路径的非直观优化。
+- 安全检查顺序。
+- 并发和竞态约束。
+- 清理顺序。
+- 特殊算法或领域公式。
+
+## 不应写的注释
+
+- 复述变量名或控制流。
+- 注释掉的旧代码。
+- 无跟踪信息的“以后优化”。
+- 与实现重复的大篇教程。
+- 无法验证的猜测。
+
+历史实现由版本控制保存，不应长期留在源码中。
+
+## JSDoc 使用范围
+
+JSDoc 主要用于：
+
+- 公共库 API。
+- 插件和扩展点。
+- 跨团队或跨进程契约。
+- 参数具有单位、边界或特殊格式。
+- 函数有重要副作用、取消、异常或线程安全语义。
+
+```ts
+/**
+ * Resolves a workspace path without following symbolic links.
+ *
+ * @throws {WorkspacePathError} When the path escapes the configured root.
+ */
+export function resolveWorkspacePath(
+  rootPath: string,
+  candidatePath: string
+): string {
+  // ...
+}
+```
+
+内部显而易见的函数不需要机械补全 JSDoc。
+
+## TODO
+
+TODO 必须包含负责人约定或可追踪编号，并说明删除条件：
+
+```ts
+// TODO(PROJ-1423): Remove after all clients send protocol v3.
+```
+
+禁止：
+
+```ts
+// TODO: fix later
+```
+
+## 设计文档
+
+以下内容更适合放入 `docs/` 或 ADR，而非源码注释：
+
+- 多方案权衡。
+- 跨服务架构。
+- 数据迁移计划。
+- 兼容性策略。
+- 长期安全模型。
+- 复杂协议说明。
+
+源码注释可以引用相应 ADR 或问题编号，但应保留理解当前代码所需的最小上下文。

package/template/skills/typescript-engineering-standards/references/07-testing-strategy.md

@@ -0,0 +1,84 @@
+# 测试策略
+
+## 测试分层
+
+| 类型 | 目标 | 默认位置 |
+|---|---|---|
+| 单元测试 | 函数、策略、解析器、状态转换 | 与源码同目录 |
+| 集成测试 | 多个真实模块协作 | `tests/integration/` |
+| 契约测试 | API、IPC、插件、适配器契约 | 源码旁或 `tests/contracts/` |
+| E2E | 用户关键路径 | `tests/e2e/` |
+| 基准测试 | 性能关键路径 | `*.bench.ts` |
+
+## 测试命名
+
+测试名描述可观察行为，而不是实现方法：
+
+```ts
+describe('quoteShellArgument', () => {
+  it('preserves an empty argument as an explicit empty string', () => {
+    // ...
+  })
+})
+```
+
+避免 `it('works')`、`describe('utils')`。
+
+## 覆盖范围
+
+关键模块应考虑：
+
+- 正常路径。
+- 边界值和空输入。
+- 无效输入。
+- 错误传播。
+- 取消和超时。
+- 并发或重复调用。
+- 资源清理。
+- 已修复缺陷的回归场景。
+
+覆盖率数字不能替代风险导向的场景设计。
+
+## 缺陷修复流程
+
+1. 添加可稳定复现问题的失败测试。
+2. 确认测试在修复前失败。
+3. 实施最小修复。
+4. 确认回归测试和相关测试通过。
+5. 必要时增加跨平台或集成测试。
+
+## 确定性
+
+测试不应依赖：
+
+- 真实当前时间。
+- 外部不稳定网络。
+- 测试执行顺序。
+- 共享可变全局状态。
+- 本机特定路径或环境配置。
+- 无种子的随机数据。
+
+通过注入时钟、随机源、文件系统和网络端口，或使用临时目录与隔离夹具保持确定性。
+
+## Mock 原则
+
+- 优先测试真实纯函数。
+- Mock 系统边界，不 Mock 被测模块内部每个调用。
+- 测试行为与输出，不锁死实现步骤。
+- 不因 Mock 方便而跳过关键集成测试。
+- 使用小而可读的夹具。
+
+## 快照
+
+快照适合结构稳定、人工审查有价值的输出。避免巨型快照、频繁无脑更新和对动态数据的快照。
+
+## 测试代码质量
+
+测试也是生产资产：
+
+- 命名清晰。
+- 无隐藏共享状态。
+- 失败信息可诊断。
+- 夹具具有领域含义。
+- 清理临时资源。
+- 不复制大量生产实现来计算期望值。

package/template/skills/typescript-engineering-standards/references/08-react-and-frontend.md

@@ -0,0 +1,91 @@
+# React 与前端规范
+
+## 组件职责
+
+组件输入由 Props 明确表达，渲染尽量纯粹。复杂功能按需拆分：
+
+- 数据获取与缓存。
+- 业务状态编排。
+- 领域交互。
+- 视觉展示。
+
+组件名称使用具体领域语义：
+
+- `WorkspaceReconnectDialog`
+- `TerminalPermissionBanner`
+- `PaymentMethodPanel`
+
+避免 `DataComponent`、`CommonModal`、`GenericPanel`。
+
+## Props
+
+```ts
+type WorkspaceCardProps = {
+  workspace: WorkspaceSummary
+  isSelected: boolean
+  onSelect(workspaceId: string): void
+}
+```
+
+要求：
+
+- 使用 `XxxProps`。
+- 布尔 Props 使用 `is`、`has`、`can`、`should`。
+- 事件 Props 使用 `onXxx`。
+- 避免大型万能对象和多个隐式控制模式的布尔值。
+- 复杂互斥状态使用联合类型。
+- 是否使用 `React.FC` 按仓库统一规则，不混用。
+
+## Hook
+
+- 自定义 Hook 以 `use` 开头。
+- 一个 Hook 处理一个可命名职责。
+- Effect 依赖完整，不通过关闭规则规避。
+- Effect 创建资源时返回清理函数。
+- 返回多个独立值时优先具名对象；稳定二元关系可用元组。
+- 避免把普通纯函数包装成 Hook。
+
+## 状态管理
+
+- 状态尽量靠近使用位置。
+- 只有多个远距离调用方共享时才提升。
+- Store 按领域切片，不创建单一巨型 Store。
+- Selector 尽量窄，避免组件订阅整个状态树。
+- 派生数据优先计算，不重复存储。
+- 服务端状态与本地 UI 状态分开管理。
+
+## Effect
+
+Effect 用于与外部系统同步，不用于替代普通计算。检查：
+
+- 是否可在渲染时直接派生。
+- 是否需要取消旧请求。
+- 是否存在竞态和过期响应。
+- 是否清理监听器、Timer 和订阅。
+- 是否因对象引用变化导致无意义重复执行。
+
+## 性能
+
+- 不因为“可能更快”滥用 `memo`、`useMemo`、`useCallback`。
+- 优化针对已识别瓶颈。
+- 长列表使用虚拟化。
+- 高频事件使用调度、批处理、节流或防抖。
+- 避免在热渲染路径创建昂贵对象。
+- 关键优化应有测试、测量或简短原因说明。
+
+## 可访问性
+
+- 优先语义化 HTML。
+- 交互元素支持键盘。
+- 图标按钮有可访问名称。
+- 表单控件有 Label 和错误关联。
+- 焦点管理可预测。
+- 不用颜色作为唯一状态表达。
+- 弹窗、菜单和提示遵守相应 ARIA 交互模式。
+
+## 浏览器边界
+
+- 验证 URL、消息、Storage 和第三方脚本输入。
+- 避免不安全原始 HTML。
+- 不把秘密放入前端 Bundle。
+- 浏览器代码不导入 Node 专属模块，除非平台明确提供安全桥接。

package/template/skills/typescript-engineering-standards/references/09-node-cli-and-cross-platform.md

@@ -0,0 +1,92 @@
+# Node.js、CLI 与跨平台规范
+
+## Node 内置模块
+
+使用 `node:` 前缀：
+
+```ts
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+```
+
+## 路径
+
+使用 `node:path` 组合和归一化路径，不手工拼接分隔符：
+
+```ts
+const configPath = path.join(rootPath, 'config', 'app.json')
+```
+
+涉及安全或相等判断时考虑：
+
+- Windows 盘符和分隔符。
+- UNC 路径。
+- 大小写敏感差异。
+- 符号链接。
+- 相对路径和路径遍历。
+- 规范化前后的边界检查顺序。
+
+## CLI 分层
+
+推荐拆分：
+
+- `parse-cli-arguments.ts`
+- `validate-cli-options.ts`
+- `run-export-command.ts`
+- `render-cli-error.ts`
+
+要求：
+
+- 参数解析与业务执行分离。
+- 正常机器输出写 `stdout`，错误写 `stderr`。
+- 明确定义退出码。
+- 支持 `--help` 和 `--version`。
+- 底层领域代码不直接调用 `process.exit()`。
+- 信号处理和资源清理集中管理。
+
+## 环境变量
+
+在启动边界一次解析、验证和标准化：
+
+```ts
+type AppEnvironment = {
+  port: number
+  logLevel: LogLevel
+}
+
+export function loadEnvironment(
+  source: NodeJS.ProcessEnv
+): AppEnvironment {
+  // ...
+}
+```
+
+业务代码不应在各处直接读取 `process.env`。
+
+## 子进程
+
+- 优先使用参数数组，不拼接 Shell 字符串。
+- 必须拼接时按目标 Shell 正确转义。
+- 处理超时、取消、退出码、信号和输出上限。
+- 避免将不可信输入直接作为命令或参数。
+- 明确清理孤儿进程。
+
+## 文件和流
+
+- 大文件优先流式处理。
+- 关闭文件句柄和流。
+- 处理背压。
+- 临时文件使用隔离目录并在失败路径清理。
+- 写关键文件时考虑原子替换和崩溃恢复。
+
+## 跨平台
+
+跨平台逻辑应集中在适配器中。测试至少覆盖：
+
+- 路径和换行符。
+- Shell 参数引用。
+- 文件权限和可执行位。
+- 信号差异。
+- 大小写和文件锁行为。
+
+不要把平台判断散落在整个业务代码中。