@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/templates/workflows/personal.js

@@ -0,0 +1,225 @@
+const VOICE = `正文和对话必须是简体中文、白话。先写结论，再写原因。句子要短。
+
+禁止黑话，禁止自创缩略。不要用只有作者懂的二字、三字当动词，例如：写边、选桶、查 bind、物化、对账、抽会话、封尾。键名、类名、路径、协议可以保留，旁边必须用完整中文说明在干什么。缩写第一次出现先写全称。
+
+禁止电报句。不要写「两类可配置；缓存处置；独有优先」这种压缩句。要写清是哪几类、各做什么、谁写入、谁读取。读者不看后文也能懂这一句。
+
+禁止这些词：优化、提升、赋能、闭环、拉通、完善、大概、可能、后续再看。专业词第一次出现，后面补半句人话。
+
+不要把对话过程、试错流水、自我纠正写进正文。
+
+落盘后只报路径和还没拍板的点，不要把全文贴进对话。文件已经存在时，只改走样的地方，不要整篇重写。已经勾选的任务保留。`;
+const PLACE = `变更目录在 \`freespec/<名称>变更/\`。
+
+做完就停。
+
+结束的话固定三样：写到哪个文件、还剩什么没定或没做、请人审阅后再决定下一步。不要替人决定下一步，不要说「接下来写设计」「接下来实现」。
+
+细则在本技能目录的 \`references/\`。
+必须项只写在 \`references/护栏.md\`。护栏挂在动作上：写到哪一步，就查哪一步，不靠回头翻清单。
+\`references/约束.md\` 只写尽量项。做不到就在对话里说一句。`;
+const WRITE = `四份文件都可选，没有先后顺序：\`需求文档.md\`、\`设计文档.md\`、\`任务清单.md\`、\`测试用例.md\`。缺哪份都不必补，也不要因此判失败。
+
+写需求文档时，会改功能点但还没定的，写进需求待定，把文档写完，不要停下来重问。写设计、任务、用例时，读到这种还没定、又会改变做法的，停下来问，不要补。
+
+目录不存在时，先运行 \`freespec new change "<名称>"\`。\`登录改造\` 和 \`登录改造变更\` 都会建成 \`freespec/登录改造变更/\`。名称用中文，可以加数字和连字符。传给命令的名称可以不带「变更」，命令会补上。
+
+需求文档和设计文档按 \`freespec instructions\` 返回的模板章节写。需求文档只用模板里的四个标题。设计文档只写这次涉及的章，没用到的整章删掉。正文模板只看这次命令返回的那一份。`;
+const CODE = `实现时的语言规范只在「写Java」和「审Java」。本仓库里已经有的写法，优先于技能里的默认约定。`;
+function skill(name, description, instructions) {
+    return {
+        name,
+        description,
+        instructions,
+        compatibility: '需要 freespec CLI。',
+        metadata: { author: 'freespec', version: '1.0' },
+    };
+}
+function command(name, description, content) {
+    return {
+        name,
+        description,
+        category: 'Workflow',
+        tags: ['freespec'],
+        content,
+    };
+}
+export function getNewSkillTemplate() {
+    return skill('新建', '创建 freespec 下的中文变更目录。用户要新建变更、开一个需求文件夹时使用。', `只创建变更目录，不写四份文档。
+
+${PLACE}
+
+先读 \`references/交接.md\`、\`references/约束.md\`。
+
+1. 从用户的话得出中文名称。拿不准就用一句话问。名称可以不带「变更」，命令会补上。
+2. 运行 \`freespec new change "<名称>"\`。目录已经存在就按交接问，不要另建。
+3. 读 \`references/护栏.md\`。过了再用一两句中文说明目录路径，然后停下。`);
+}
+export function getNewCommandTemplate() {
+    return command('新建', '创建变更目录', getNewSkillTemplate().instructions);
+}
+export function getAskSkillTemplate() {
+    return skill('深思', '从用户的问题出发，把漏洞补上，把答案写全。用户说深思、想透、深度思考时使用。', `从用户的问题出发，往深处想，也往旁边想。把问题里的漏洞补上，把答案写全。
+
+能从用户原话、已有材料和仓库补上的，直接写进答案。只有会改答案、又不能代用户定的，才拿去点选。点选方式写在 \`references/点选提问.md\`。一次把这一批题交出，让人点选。
+
+这次只把答案和登记写进该变更目录的 \`深思/\`。
+
+${PLACE}
+
+${VOICE}
+
+先读 \`references/怎么想.md\`、\`references/三方核对.md\`、\`references/点选提问.md\`、\`references/登记.md\`、\`references/例子.md\`、\`references/约束.md\`。
+
+\`config/prompts.yaml\` 是往深处和旁边想时要看的漏洞。能补上的写进答案。补不上、而且会改答案的，才做成点选项。页面、表、接口不在这份清单里，只按三方核对做。
+
+1. 确定中文变更名。目录不存在就先 \`freespec new change "<名称>"\`。
+2. 用一两句复述用户要回答的问题。复述和用户要的不是一回事，就先点选确认问题，再往下想。
+3. 按 \`references/怎么想.md\` 把漏洞找出来。点了名的页面、表、接口，按 \`references/三方核对.md\` 对实物。对得上的写进答案。对不上的收成点选题。
+4. 能补上的漏洞写进答案，并写依据。不要再拿去问人。
+5. 补不上、而且会改答案的，按 \`references/点选提问.md\` 一次点选。人点完就写入答案。工具单次有道数上限时，点完立刻再出下一张。
+6. 答案写到 \`freespec/<名称>变更/深思/记录.md\`，登记写到同目录的 \`registry.json\`。
+7. 读 \`references/护栏.md\`。过了再停下。`);
+}
+export function getAskCommandTemplate() {
+    return command('深思', '把问题想透并写全答案', getAskSkillTemplate().instructions);
+}
+export function getRequirementsSkillTemplate() {
+    return skill('需求', '按四个标题写需求文档.md。用户说写需求、需求文档时使用。', `只写 \`需求文档.md\`。会改功能点但还没定的，写进需求待定，把这份文档写完。不要停下来重问，也不要编一个结果填进功能点。
+
+${PLACE}
+
+${VOICE}
+
+${WRITE}
+
+先读 \`references/文风.md\`、\`references/需求待定.md\`、\`references/深思摄入.md\`、\`references/约束.md\`。
+
+1. 有深思记录就先读。已定的写进背景、描述或功能点。未决写进需求待定。不要重问。
+2. 运行 \`freespec instructions requirements --change "<名称>" --json\`。二级标题按返回的 template，只用那四个，顺序不要换。句子怎么写按文风。返回的说明和文风不一致时，以文风和需求待定为准。
+3. 读 \`references/护栏.md\`。用本技能目录的 \`scripts/check-requirements.mjs\` 检查刚写的需求文档。退出码不是 0 就按缺项改文件，再跑，直到通过。
+4. 通过后只报路径和需求待定里还要人拍板的条目。停下，不要写设计。`);
+}
+export function getRequirementsCommandTemplate() {
+    return command('需求', '写需求文档', getRequirementsSkillTemplate().instructions);
+}
+export function getDesignSkillTemplate() {
+    return skill('设计', '按涉及范围选用章节写设计文档.md。用户说写设计、设计文档时使用。', `只写 \`设计文档.md\`。没有需求文档也可以写。
+
+${PLACE}
+
+${VOICE}
+
+${WRITE}
+
+先读 \`references/准备.md\`、\`references/类型.md\`、\`references/文风.md\`、\`references/约束.md\`。有页面再读 \`references/界面.md\`。
+
+1. 先判断涉及范围：纯前端、前后端、纯后端、仅数据或配置。拿不准就问一句。
+2. 运行 \`freespec instructions design --change "<名称>" --json\`。章名、节名、表头按返回的 template 写。用到的章才写，从第一章连续编号。
+3. 写数据、页面、接口、服务之前，先按护栏把改动清单里的引用追溯写完。追不全就不要写后面的章。
+4. 读 \`references/护栏.md\`。用本技能目录的 \`scripts/check-design.mjs\` 检查刚写的设计文档。退出码不是 0 就按缺项改文件，再跑，直到通过。
+5. 通过后再停下。`);
+}
+export function getDesignCommandTemplate() {
+    return command('设计', '写设计文档', getDesignSkillTemplate().instructions);
+}
+export function getTasksSkillTemplate() {
+    return skill('任务', '按设计章节写可勾选的任务清单.md。用户说写任务、任务清单时使用。', `只写 \`任务清单.md\`。没有需求文档或设计文档也可以写。
+
+${PLACE}
+
+${VOICE}
+
+${WRITE}
+
+先读 \`references/粒度.md\`、\`references/约束.md\`。
+
+1. 运行 \`freespec instructions tasks --change "<名称>" --json\`，按返回的 template 写。
+2. 读 \`references/护栏.md\`。用本技能目录的 \`scripts/check-tasks.mjs\` 检查刚写的任务清单。退出码不是 0 就按缺项改文件，再跑，直到通过。
+3. 通过后再停下。`);
+}
+export function getTasksCommandTemplate() {
+    return command('任务', '写任务清单', getTasksSkillTemplate().instructions);
+}
+export function getCasesSkillTemplate() {
+    return skill('用例', '写测试用例.md，只描述输入、操作和期望。用户说写用例、测试用例时使用。', `只写 \`测试用例.md\`。每条写输入、操作和期望。
+
+${PLACE}
+
+${VOICE}
+
+${WRITE}
+
+先读 \`references/怎么写.md\`、\`references/约束.md\`。
+
+1. 先写核算表：每条功能点对上哪条用例、还缺什么。列不出不写正文。
+2. 运行 \`freespec instructions cases --change "<名称>" --json\`，按返回的 template 写。
+3. 读 \`references/护栏.md\`。用本技能目录的 \`scripts/check-cases.mjs\` 检查刚写的用例。退出码不是 0 就按缺项改文件，再跑，直到通过。
+4. 通过后再停下。`);
+}
+export function getCasesCommandTemplate() {
+    return command('用例', '写用例说明', getCasesSkillTemplate().instructions);
+}
+export function getReviewDocsSkillTemplate() {
+    return skill('审文档', '只读评审已经存在的需求、设计、任务和用例。用户说审文档时使用。', `只读。
+
+${PLACE}
+
+${VOICE}
+
+先读 \`references/维度.md\`、\`references/踩坑.md\`、\`references/约束.md\`。
+
+读 \`references/护栏.md\` 后再给结论。结论用：通过、有条件通过、不通过。然后停下。`);
+}
+export function getReviewDocsCommandTemplate() {
+    return command('审文档', '评审已有文档', getReviewDocsSkillTemplate().instructions);
+}
+export function getCheckSkillTemplate() {
+    return skill('验收', '对照已有文档、测试和代码，看这件事做完没有。用户说验收、核对实现时使用。', `只读。
+
+${PLACE}
+
+${VOICE}
+
+先读 \`references/核对.md\`、\`references/约束.md\`。写完读 \`references/护栏.md\`。结论用：通过、有条件通过、不通过。过了再停下。`);
+}
+export function getCheckCommandTemplate() {
+    return command('验收', '核对实现', getCheckSkillTemplate().instructions);
+}
+export function getJavaImplSkillTemplate() {
+    return skill('写Java', '用 Java 实现当前变更。用户说写Java、实现 Java 时使用。', `只写 Java。不改需求、设计、任务、用例的正文，除非用户明确要求改文档。
+
+${PLACE}
+
+${VOICE}
+
+${CODE}
+
+先读 \`references/Java规范.md\`、\`references/踩坑.md\`、\`references/危险写法.md\`、\`references/完成对照.md\`、\`references/约束.md\`。
+
+1. 读这个变更目录里已经有的文件。缺的不用补。
+2. 有 \`测试用例.md\` 时，先写成会失败的 Java 测试并运行，说明现在是失败的，再写实现，直到这些测试通过。
+3. 有 \`任务清单.md\` 时，一次做一条，对照一条，再改成 \`- [x]\`。没有测试用例就按任务写。
+4. 两份都没有时，按对话里已经说清的内容实现，并写明假设。
+5. 读 \`references/护栏.md\`。过了再停下。`);
+}
+export function getJavaImplCommandTemplate() {
+    return command('写Java', '用 Java 实现', getJavaImplSkillTemplate().instructions);
+}
+export function getJavaReviewSkillTemplate() {
+    return skill('审Java', '只读评审 Java 改动。用户说审Java、看 Java 代码时使用。', `只评 Java 改动。
+
+${PLACE}
+
+${VOICE}
+
+${CODE}
+
+先读 \`references/规则.md\`、\`references/示例.md\`、\`references/约束.md\`。diff 沾到 SQL、事务、循环、并发时再读 \`references/领域检项.md\`。
+
+读 \`references/护栏.md\` 后再给结论。结论用：通过、有条件通过、不通过。然后停下。`);
+}
+export function getJavaReviewCommandTemplate() {
+    return command('审Java', '评审 Java 代码', getJavaReviewSkillTemplate().instructions);
+}
+//# sourceMappingURL=personal.js.map

package/dist/core/update-plan.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Update Plan
+ *
+ * The write seam `update` uses for every file it generates or removes.
+ *
+ * A real run forwards to the filesystem. A dry run records what the same call
+ * would have done and writes nothing, so the preview and the real update come
+ * from one code path instead of two descriptions of it.
+ */
+import type { FileView } from './file-view.js';
+export type UpdatePlanAction = 'add' | 'update' | 'delete';
+export interface UpdatePlanChange {
+    /** Project-relative POSIX path, or an absolute path (home collapsed to `~`) for files outside the project. */
+    path: string;
+    action: UpdatePlanAction;
+    /**
+     * Tool the file belongs to, as configured (e.g. `claude`), or `freespec`
+     * for FreeSpec's own files: the global config and legacy-artifact cleanup.
+     */
+    tool: string;
+}
+/**
+ * What the plan cannot settle by itself: a step a terminal user is asked
+ * about, which the plan lists as a non-interactive run makes it. Stable
+ * identifiers, for a caller that branches on them.
+ */
+export type UpdatePlanNoteCode = 'legacy-tool-directories' | 'legacy-artifacts';
+export interface UpdatePlanNote {
+    code: UpdatePlanNoteCode;
+    message: string;
+}
+export interface UpdatePlanFailure {
+    tool: string;
+    error: string;
+}
+export interface UpdatePlan {
+    changes: UpdatePlanChange[];
+    /**
+     * Steps a terminal user would be asked about. `changes` lists them as a
+     * non-interactive run makes them. Empty for an ordinary refresh.
+     */
+    notes: UpdatePlanNote[];
+    /**
+     * Tools the real update would fail on. Reported rather than thrown: one
+     * broken tool must not cost the caller the rest of the plan.
+     */
+    failures: UpdatePlanFailure[];
+}
+/** Every filesystem mutation `update` makes while generating artifacts. */
+export interface UpdateFileOps {
+    writeFile(filePath: string, content: string, tool: string): Promise<void>;
+    removeFile(filePath: string, tool: string): Promise<void>;
+    removeDirectory(dirPath: string, tool: string): Promise<void>;
+    /** Removes a directory already known to be empty. */
+    removeEmptyDirectory(dirPath: string): Promise<void>;
+}
+export declare const realFileOps: UpdateFileOps;
+export declare class UpdatePlanRecorder implements UpdateFileOps {
+    private readonly projectPath;
+    private readonly notes;
+    private readonly failures;
+    /**
+     * The tree as the real update would have it so far: absolute path to planned
+     * content, a moved directory, or null once planned away (a removed directory
+     * takes everything under it). Steps that read what an earlier step left
+     * behind read this through `view`.
+     */
+    private readonly staged;
+    /** Every file path the plan has touched, with the tool that touched it last. */
+    private readonly touched;
+    constructor(projectPath: string);
+    writeFile(filePath: string, content: string, tool: string): Promise<void>;
+    removeFile(filePath: string, tool: string): Promise<void>;
+    removeEmptyDirectory(dirPath: string): Promise<void>;
+    removeDirectory(dirPath: string, tool: string): Promise<void>;
+    /**
+     * A rename, as the legacy-root migration makes it: whatever the entry is
+     * moves, a directory with everything in it.
+     */
+    moveFile(source: string, destination: string, tool: string): Promise<void>;
+    /**
+     * The tree with every planned write, move and removal applied. A path the
+     * plan has not touched answers exactly as the disk does.
+     */
+    readonly view: FileView;
+    addNote(code: UpdatePlanNoteCode, message: string): void;
+    addFailure(tool: string, error: string): void;
+    /**
+     * Each touched path, compared as it is on disk now with how the plan leaves
+     * it. A file written and then removed, or rewritten with the bytes it
+     * already had, is no change at all.
+     */
+    getPlan(): UpdatePlan;
+    private stage;
+    /**
+     * What the plan has put at a path: content, a moved directory, null once
+     * planned away, or undefined when the plan has not touched it.
+     */
+    private stagedEntry;
+    /** Whether the plan has put any file or directory below `directory`. */
+    private hasStagedDescendant;
+    /** Files under a directory in the tree as planned: those on disk, and those the plan added. */
+    private filesUnder;
+    /**
+     * What is at a path in the tree as planned, and whether that is what is on
+     * disk (so its permissions are real).
+     */
+    private entryKind;
+    /**
+     * Fails the way the real write would, without writing: a directory where the
+     * file belongs, a file where one of its directories belongs, or no
+     * permission. Recording the write instead would plan past the point where
+     * the real update stops for this tool, listing files it never writes.
+     */
+    private probeWrite;
+    /** Fails the way unlinking the file would. */
+    private probeRemove;
+    /**
+     * The nearest existing ancestor has to be a directory the update can create
+     * entries in; anything it would create below that starts out empty.
+     */
+    private probeCreatableIn;
+    private toDisplayPath;
+}
+/** Human-readable rendering of a dry-run plan. */
+export declare function formatUpdatePlan(plan: UpdatePlan): string;
+//# sourceMappingURL=update-plan.d.ts.map