@namewta/speculo 0.3.4 → 0.5.0

package/template/skills/typescript-engineering-standards/references/12-security-performance-and-i18n.md

@@ -1,65 +0,0 @@
-# 安全、性能与国际化
-
-## 输入安全
-
-所有外部输入必须验证，包括 API、IPC、消息、配置、文件、URL 和用户输入。
-
-- 路径防止目录穿越。
-- SQL 使用参数化查询。
-- Shell 使用参数数组并正确转义。
-- HTML 默认转义，谨慎使用原始 HTML。
-- URL、重定向和文件类型需要校验。
-- 跨窗口、跨进程消息校验来源和结构。
-
-## 敏感信息
-
-禁止：
-
-- 日志记录密码、Token、Cookie、私钥。
-- 将秘密打包到浏览器代码。
-- 提交 `.env`、证书或生产配置。
-- 向最终用户泄露内部堆栈、路径和未脱敏请求。
-- 把用户输入直接作为命令、查询或文件路径执行。
-
-日志应使用结构化字段并在边界脱敏。
-
-## 权限
-
-- 默认最小权限。
-- 权限判断集中在策略或 Guard 中。
-- UI 隐藏按钮不能替代服务端鉴权。
-- 高风险操作有确认、审计和幂等保护。
-- 不依赖客户端可篡改字段作最终安全决策。
-
-## 性能原则
-
-- 优化以前先测量。
-- 优先改进算法复杂度、I/O 次数和数据复制。
-- 大文件、日志和列表使用流式、分页、窗口化或虚拟化。
-- 避免热路径重复解析配置、创建正则、序列化大型对象或读取磁盘。
-- 定时器、监听器、队列和缓存必须有上限和清理。
-
-## 缓存
-
-缓存需要明确：
-
-- 键和命名空间。
-- 容量上限。
-- 淘汰策略。
-- 过期和主动失效。
-- 一致性要求。
-- 是否缓存错误或空结果。
-
-非直观优化应有基准、回归测试或简短原因说明。
-
-## 国际化
-
-有多语言需求时：
-
-- 用户可见文本不散落为硬编码字符串。
-- 文案键按领域语义命名，不按屏幕位置命名。
-- 插值使用具名参数。
-- 不拼接自然语言句子。
-- 日期、数字、货币和复数使用国际化 API。
-- 用户提示和开发日志分离。
-- CI 检查缺失键、未使用键和占位符不一致。

package/template/skills/typescript-engineering-standards/references/13-git-review-and-delivery.md

@@ -1,79 +0,0 @@
-# Git、代码评审与交付
-
-## 分支命名
-
-推荐：
-
-- `feat/workspace-search`
-- `fix/session-timeout-race`
-- `refactor/terminal-state-split`
-- `perf/large-log-rendering`
-- `test/payment-retry-policy`
-- `docs/typescript-style-guide`
-- `chore/upgrade-vitest`
-
-避免 `update`、`changes`、`fix-stuff` 等无语义名称。
-
-## 提交信息
-
-可采用 Conventional Commits：
-
-```text
-feat(auth): add device authorization flow
-fix(terminal): prevent duplicate process cleanup
-refactor(store): split workspace selectors
-test(cli): cover empty shell argument
-```
-
-提交应：
-
-- 聚焦一个逻辑变化。
-- 不混入无关格式化。
-- 能通过基本检查。
-- 不包含秘密、构建产物和本地配置。
-- 说明改变的目的，而不仅是文件列表。
-
-## Pull Request
-
-PR 应包含：
-
-- 背景和问题。
-- 方案和关键取舍。
-- 风险、兼容性和迁移影响。
-- 验证方式。
-- UI 变化的截图或录屏。
-- 缺陷修复的回归测试。
-- 未完成项和后续工作。
-
-## 审查优先级
-
-1. 正确性、安全、数据完整性。
-2. 类型边界和运行时验证。
-3. 资源生命周期、并发、错误处理。
-4. 架构边界和公共 API。
-5. 测试缺口。
-6. 可维护性与命名。
-7. 风格。
-
-## 审查意见格式
-
-一条有效意见应尽量说明：
-
-- 具体位置。
-- 真实风险。
-- 触发条件。
-- 建议修复方向。
-- 是否阻塞合并。
-
-不要只写“这里不好”“建议重构”。
-
-## 交付检查
-
-- 格式检查通过。
-- Lint 通过。
-- 类型检查通过。
-- 相关测试通过。
-- 构建通过。
-- 文档和配置同步。
-- 没有无关改动。
-- 已评估跨平台、安全、性能和兼容性。

package/template/skills/typescript-engineering-standards/references/14-adoption-exceptions-and-migration.md

@@ -1,84 +0,0 @@
-# 落地、例外与迁移
-
-## 例外原则
-
-规范允许例外，但不允许无记录的例外。例外必须：
-
-1. 有具体技术原因。
-2. 范围尽可能小。
-3. 在代码、配置或 PR 中说明。
-4. 不破坏核心安全与类型边界。
-5. 临时例外有退出条件和跟踪任务。
-6. 经代码评审确认。
-
-## 例外示例
-
-```ts
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-// Why: Vendor callback type is incorrect; remove after SDK-481 is fixed.
-function normalizeVendorPayload(payload: any): NormalizedPayload {
-  return vendorPayloadSchema.parse(payload)
-}
-```
-
-该例外仍在边界进行运行时验证，不让 `any` 传播。
-
-## 遗留项目迁移
-
-不要一次性重写全部代码。推荐阶段：
-
-### 阶段 1：建立事实和门禁
-
-- 固定包管理器和锁文件。
-- 增加稳定的 `format:check`、`lint`、`typecheck`、`test`、`build` 命令。
-- CI 先报告问题，再逐步改为阻塞。
-
-### 阶段 2：阻止新增债务
-
-- 新文件遵守命名和大小规则。
-- 新 API 不使用 `any`。
-- 新外部输入必须验证。
-- 新缺陷修复补回归测试。
-
-### 阶段 3：按触及范围治理
-
-- 修改旧文件时降低复杂度。
-- 拆出纯逻辑并补测试。
-- 清理循环依赖和万能工具文件。
-- 缩小公共 API。
-
-### 阶段 4：专项迁移
-
-- 分模块开启更严格的 TypeScript 选项。
-- 按领域迁移目录。
-- 引入项目引用和依赖边界检查。
-- 清理临时规则禁用和类型断言。
-
-## Ratchet 策略
-
-对无法立即达标的指标采用“只降不升”：
-
-- 文件行数不能继续增长。
-- `any` 数量不能增加。
-- 循环依赖数量不能增加。
-- 被跳过测试数量不能增加。
-- Lint 警告基线只能下降。
-
-## 自动生成代码
-
-生成代码可以豁免部分格式、大小和命名规则，但必须：
-
-- 明确标识生成来源。
-- 不手工修改。
-- 将生成目录排除在不适用检查外。
-- 对生成器本身进行测试和审查。
-
-## 大规模重命名
-
-只有在用户明确要求或迁移收益充分时进行。应：
-
-- 单独 PR。
-- 不混入功能变化。
-- 使用自动化重构工具。
-- 检查大小写敏感文件系统和 Git 重命名。
-- 验证导入、测试、文档和构建。

package/template/skills/typescript-engineering-standards/references/15-orca-derived-observations.md

@@ -1,54 +0,0 @@
-# 从 Orca 项目提炼的工程习惯
-
-本文件记录从 Orca 类型项目实践中抽象出的可迁移经验。它不是要求其他项目复制 Electron 目录，也不是 Orca 上游规范的逐字镜像。
-
-## 1. 运行环境边界优先
-
-Orca 一类 Electron 项目天然包含主进程、预加载、渲染器、共享代码和命令行等不同运行环境。可迁移经验是：
-
-- 运行能力不同的代码应物理隔离。
-- 每个环境使用适合自己的 TypeScript 配置和依赖范围。
-- 跨边界接口显式化，而不是随意互相导入。
-
-## 2. 领域内部局部平铺
-
-Orca 的工程习惯体现出：同一明确职责区域不必为每个实现再加一层目录。可迁移经验是：
-
-- 小型领域优先平铺。
-- 文件名承担定位职责。
-- 只有形成稳定子域后再增加目录。
-
-## 3. 文件名具体
-
-相较 `utils.ts`、`helpers.ts`，具体动作和领域名称更利于搜索、审查和拆分。例如清理、解析、引用、状态选择、平台适配等职责可以直接进入文件名。
-
-## 4. 控制文件体积
-
-对普通 TypeScript、React 文件和测试设置不同的大小预算，可以提前暴露职责混合。数字应视为审查触发器，而非机械规则。
-
-## 5. 注释关注 WHY
-
-简短解释兼容性、性能、安全和平台差异，比逐行描述实现更有价值。注释不能替代清晰命名和模块拆分。
-
-## 6. 工具链形成门禁
-
-Orca 类现代项目通常将格式化、Lint、类型检查、测试和 Git/CI 检查组合起来。可迁移经验是：
-
-- 规范应尽量机器可执行。
-- 命令名保持稳定，底层工具可替换。
-- 不允许通过关闭规则或删除测试绕过门禁。
-
-## 7. 测试靠近实现
-
-单元测试和实现共置，便于发现、移动和维护；集成和 E2E 测试则按跨模块边界集中管理。
-
-## 8. 不机械复制
-
-不应直接复制：
-
-- Electron 专属目录到普通 Node 或 Web 项目。
-- 某个具体格式工具的全部选项。
-- 某个仓库的行数阈值作为绝对标准。
-- 某个框架生成目录的特殊命名。
-
-应复制的是背后的目的：边界清晰、职责具体、类型严格、质量自动化、修改可验证。

package/template/skills/typescript-engineering-standards/references/README.md

@@ -1,45 +0,0 @@
-# Reference Index
-
-本目录保存 TypeScript 工程规范的详细知识模块。`SKILL.md` 是唯一主入口；执行具体任务时只读取必要模块。
-
-## 分类
-
-### 治理与决策
-
-- `00-standard-levels-and-precedence.md`：规则级别、冲突处理、事实优先。
-- `14-adoption-exceptions-and-migration.md`：例外、遗留项目、渐进迁移。
-- `15-orca-derived-observations.md`：从 Orca 工程实践中抽象出的可迁移经验。
-
-### 架构与代码组织
-
-- `01-project-architecture-and-directory-layout.md`
-- `02-file-directory-and-symbol-naming.md`
-- `03-modules-imports-exports-and-dependencies.md`
-
-### 语言与实现
-
-- `04-typescript-type-system.md`
-- `05-functions-async-errors-and-resources.md`
-- `06-comments-jsdoc-and-documentation.md`
-
-### 平台与测试
-
-- `07-testing-strategy.md`
-- `08-react-and-frontend.md`
-- `09-node-cli-and-cross-platform.md`
-
-### 工程化与交付
-
-- `10-formatting-lint-and-complexity.md`
-- `11-configuration-dependencies-and-ci.md`
-- `12-security-performance-and-i18n.md`
-- `13-git-review-and-delivery.md`
-
-## 读取原则
-
-- 单文件命名问题：读取 `02`，通常无需读取其他文件。
-- 类型错误或 API 设计：读取 `04`，涉及异步时再读 `05`。
-- 新领域目录设计：读取 `01`、`02`、`03`。
-- React 组件重构：读取 `08`，并按需补充 `04`、`05`、`07`。
-- 全仓库审计：从 `00` 开始，再按仓库技术栈选择相关模块。
-- 制定团队规范：先读 `00`、`01`、`02`、`04`、`10`、`11`、`13`，其余按技术栈补充。

package/template/skills/typescript-engineering-standards/templates/.editorconfig

@@ -1,12 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = true
-indent_style = space
-indent_size = 2
-trim_trailing_whitespace = true
-
-[*.md]
-trim_trailing_whitespace = false

package/template/skills/typescript-engineering-standards/templates/AGENTS.typescript.md

@@ -1,21 +0,0 @@
-# TypeScript Project Rules
-
-- 先按运行环境和业务领域组织代码，领域内部优先局部平铺。
-- 目录与普通 TypeScript 文件使用 `kebab-case`；组件文件沿用项目统一规则。
-- 文件名必须表达具体领域和职责，避免 `utils`、`helpers`、`common`、`misc`。
-- 一个文件只有一个主要职责；不要为单个普通文件创建目录。
-- 默认使用命名导出；仅在框架约定入口使用默认导出。
-- 禁止无意义全局 Barrel 和循环依赖。
-- TypeScript 必须开启严格模式；禁止无说明的 `any`、双重断言和 `@ts-ignore`。
-- 外部输入先作为 `unknown`，在系统边界运行时验证。
-- 优先使用可辨识联合表达互斥状态，并进行穷尽检查。
-- 导出函数和公共 API 写明确返回类型。
-- 所有 Promise 必须 `await`、`return` 或显式处理。
-- 监听器、Timer、连接、Worker 和进程必须有清理路径。
-- 注释解释 WHY、约束和权衡，不逐行翻译代码。
-- 单元测试与源码共置；集成和 E2E 测试放在根级 `tests/`。
-- 修复缺陷时添加回归测试。
-- 不引入未经要求的新框架或依赖。
-- 不通过关闭核心规则、删除测试或扩大 `any` 来绕过检查。
-- 合并前运行格式检查、Lint、类型检查、测试和构建。
-- 修改现有项目时优先遵守仓库已生效配置，避免无关重命名和格式噪声。

package/template/skills/typescript-engineering-standards/templates/code-review-checklist.md

@@ -1,37 +0,0 @@
-# TypeScript Code Review Checklist
-
-## 正确性与安全
-
-- [ ] 外部输入已验证。
-- [ ] 权限、安全和敏感信息处理正确。
-- [ ] 错误路径不会造成数据损坏或状态不一致。
-
-## 类型与 API
-
-- [ ] 没有无说明的 `any`、双重断言或 `@ts-ignore`。
-- [ ] 公共 API 输入、输出和错误契约明确。
-- [ ] 互斥状态使用可靠模型，分支穷尽。
-- [ ] 空值和可选语义清晰。
-
-## 异步与资源
-
-- [ ] Promise 已等待、返回或显式处理。
-- [ ] 超时、取消和重试策略合理。
-- [ ] 监听器、Timer、连接和进程已清理。
-- [ ] 无明显竞态或过期响应覆盖问题。
-
-## 架构与维护
-
-- [ ] 文件位于正确领域和运行环境。
-- [ ] 文件名具体，职责单一。
-- [ ] 依赖方向正确，无循环依赖。
-- [ ] 没有无意义共享抽象和 Barrel。
-- [ ] 文件、函数和状态复杂度合理。
-
-## 测试与交付
-
-- [ ] 新行为有适当测试。
-- [ ] 缺陷修复有回归测试。
-- [ ] 测试确定、可诊断且不过度 Mock。
-- [ ] 格式、Lint、类型检查、测试和构建通过。
-- [ ] 无无关格式化、重命名或生成文件变化。

package/template/skills/typescript-engineering-standards/templates/package-scripts.json

@@ -1,11 +0,0 @@
-{
-  "scripts": {
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "eslint .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "build": "tsc -b",
-    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build"
-  }
-}

package/template/skills/typescript-engineering-standards/templates/prettier.json

@@ -1,6 +0,0 @@
-{
-  "singleQuote": true,
-  "semi": false,
-  "printWidth": 100,
-  "trailingComma": "none"
-}

package/template/skills/typescript-engineering-standards/templates/pull-request-template.md

@@ -1,37 +0,0 @@
-## 背景
-
-<!-- 这个变更解决什么问题？ -->
-
-## 方案
-
-<!-- 核心实现、边界和主要取舍。 -->
-
-## 影响范围
-
-- [ ] 公共 API
-- [ ] 数据或配置迁移
-- [ ] 跨平台行为
-- [ ] 安全或权限
-- [ ] 性能
-- [ ] UI / 可访问性
-
-## 验证
-
-- [ ] 格式检查
-- [ ] Lint
-- [ ] TypeScript 类型检查
-- [ ] 单元测试
-- [ ] 集成 / E2E 测试
-- [ ] 构建
-
-## 证据
-
-<!-- 截图、录屏、日志、基准或测试结果。 -->
-
-## 风险与回滚
-
-<!-- 已知风险、兼容性和回滚方式。 -->
-
-## 后续工作
-
-<!-- 不属于本 PR 的工作，附任务编号。 -->

package/template/skills/typescript-engineering-standards/templates/tsconfig.base.json

@@ -1,17 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "compilerOptions": {
-    "target": "ES2022",
-    "strict": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
-    "noImplicitOverride": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "useUnknownInCatchVariables": true,
-    "verbatimModuleSyntax": true,
-    "isolatedModules": true,
-    "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true
-  }
-}

package/template/skills/typescript-engineering-standards/templates/tsconfig.project-references.json

@@ -1,8 +0,0 @@
-{
-  "files": [],
-  "references": [
-    { "path": "./tsconfig.node.json" },
-    { "path": "./tsconfig.web.json" },
-    { "path": "./tsconfig.test.json" }
-  ]
-}

package/template/workflows/specdev/I-implement/codebase-design-glossary.md

@@ -1,12 +0,0 @@
-# 代码库设计术语
-
-- **模块**：隐藏复杂度并提供稳定接口的单元，不等于目录或类。
-- **深度**：接口简单度相对于模块内部承载复杂度的杠杆。
-- **接口**：调用者必须知道的全部，包括类型、不变量、顺序、错误和性能语义。
-- **接缝**：可以替换、观察或验证行为的位置。
-- **适配器**：把外部变化隔离在稳定接缝外的实现。
-- **信息隐藏**：设计决定只存在于一个权威位置。
-- **局部性**：完成一个行为所需理解和修改的范围尽可能集中。
-- **时间耦合**：调用必须按隐含顺序发生；应显式化或封装。
-
-检查目标：减少调用者认知，而不是单纯减少行数或文件数。

package/template/workflows/specdev/I-implement/deepening.md

@@ -1,17 +0,0 @@
-# 深化与依赖策略
-
-## 依赖分类
-
-1. 进程内稳定依赖：直接调用通常足够。
-2. 本地可替换依赖：在真实替换/测试需要处建立接缝。
-3. 远程但自有：封装协议、超时、重试、幂等和可观测性。
-4. 真正外部：适配器隔离版本、失败、限流和不可控变化。
-
-不要为了“可测试”给每个类加接口。接缝应服务真实变化轴或高价值验证。
-
-## 深化问题
-
-- 能否让调用者少知道一个状态、顺序或错误分支？
-- 能否把重复策略收进单一模块？
-- 是否把外部 SDK 类型泄漏到领域层？
-- 是否有至少两个真实消费者/适配器证明抽象成立？