specthread 0.1.5 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +171 -66
  2. package/dist/bin/check.js +9 -34
  3. package/dist/bin/cli.js +5 -4
  4. package/dist/bin/generate.js +32 -19
  5. package/dist/bin/open-project.d.ts +5 -0
  6. package/dist/bin/open-project.js +26 -0
  7. package/dist/checks/changelog.js +5 -4
  8. package/dist/checks/headings.d.ts +0 -1
  9. package/dist/checks/headings.js +15 -6
  10. package/dist/checks/links.js +7 -4
  11. package/dist/checks/markers.d.ts +3 -1
  12. package/dist/checks/markers.js +33 -18
  13. package/dist/checks/pending.js +57 -23
  14. package/dist/checks/references.js +2 -2
  15. package/dist/checks/sections.js +3 -6
  16. package/dist/checks/style.d.ts +0 -8
  17. package/dist/checks/style.js +23 -43
  18. package/dist/checks/timestamps.js +5 -5
  19. package/dist/checks/toc.js +4 -6
  20. package/dist/commands/config-template.d.ts +8 -0
  21. package/{scaffold/config.jsonc → dist/commands/config-template.js} +48 -40
  22. package/dist/commands/init.js +121 -47
  23. package/dist/commands/upgrade-prompt.d.ts +12 -0
  24. package/dist/commands/upgrade-prompt.js +147 -0
  25. package/dist/config-loader.d.ts +44 -1
  26. package/dist/config-loader.js +219 -36
  27. package/dist/config.schema.d.ts +16 -35
  28. package/dist/config.schema.js +1 -7
  29. package/dist/constants/docs.d.ts +8 -4
  30. package/dist/constants/docs.js +8 -5
  31. package/dist/constants/exit.d.ts +12 -0
  32. package/dist/constants/exit.js +12 -0
  33. package/dist/constants/paths.d.ts +25 -0
  34. package/dist/constants/paths.js +25 -0
  35. package/dist/constants/patterns.d.ts +13 -6
  36. package/dist/constants/patterns.js +16 -6
  37. package/dist/constants/rules.d.ts +7 -3
  38. package/dist/constants/rules.js +7 -3
  39. package/dist/gen/pending-section.js +20 -16
  40. package/dist/gen/references.js +13 -9
  41. package/dist/gen/summary.d.ts +1 -1
  42. package/dist/gen/summary.js +11 -7
  43. package/dist/gen/toc.js +5 -2
  44. package/dist/run-check.d.ts +5 -0
  45. package/dist/run-check.js +35 -0
  46. package/dist/types.d.ts +6 -4
  47. package/dist/utils/anchor.d.ts +1 -1
  48. package/dist/utils/anchor.js +1 -1
  49. package/dist/utils/ignore.d.ts +2 -8
  50. package/dist/utils/ignore.js +23 -6
  51. package/dist/utils/parse.d.ts +6 -6
  52. package/dist/utils/parse.js +18 -27
  53. package/dist/utils/path-match.d.ts +19 -0
  54. package/dist/utils/path-match.js +27 -0
  55. package/dist/utils/report.d.ts +1 -7
  56. package/dist/utils/report.js +10 -3
  57. package/dist/utils/resolve.d.ts +15 -5
  58. package/dist/utils/resolve.js +63 -25
  59. package/dist/utils/root.d.ts +2 -0
  60. package/dist/utils/root.js +19 -0
  61. package/dist/utils/scan.d.ts +1 -3
  62. package/dist/utils/scan.js +28 -26
  63. package/dist/utils/scope.d.ts +37 -11
  64. package/dist/utils/scope.js +60 -24
  65. package/package.json +3 -3
  66. package/scaffold/AGENTS.md +4 -6
  67. package/scaffold/claude/skills/{check.md → check/SKILL.md} +6 -3
  68. package/scaffold/claude/skills/{gen.md → gen/SKILL.md} +5 -3
  69. package/scaffold/claude/skills/{plan-close.md → plan-close/SKILL.md} +1 -0
  70. package/scaffold/claude/skills/{plan-open.md → plan-open/SKILL.md} +1 -0
  71. package/scaffold/claude/skills/{plan-run.md → plan-run/SKILL.md} +1 -0
  72. package/scaffold/pending.md +1 -1
  73. package/scaffold/project.md +1 -1
  74. package/scaffold/rules.md +28 -27
  75. package/scaffold/templates/plan.md +3 -7
@@ -1,13 +1,19 @@
1
1
  import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
- import { join, dirname } from "node:path";
2
+ import { basename, join, dirname } from "node:path";
3
3
  import { fileURLToPath } from "node:url";
4
+ import { DEFAULT_CONFIG } from "../config.schema.js";
5
+ import { CONFIG_PATH, LOCAL_CONFIG_PATH, PENDING_PATH, PROJECT_PATH, RULES_PATH, SPECTHREAD_DIR, TEMPLATES_DIR, } from "../constants/paths.js";
6
+ import { renderConfig } from "./config-template.js";
7
+ import { renderUpgradePrompt } from "./upgrade-prompt.js";
4
8
  const SPECTHREAD_START = "<!-- specthread:start -->";
5
9
  const SPECTHREAD_END = "<!-- specthread:end -->";
6
10
  const scaffoldDir = () => {
7
11
  const thisFile = dirname(fileURLToPath(import.meta.url));
12
+ // dist/commands, dist, tools/docs/commands (소스에서 실행) 순
8
13
  const candidates = [
9
14
  join(thisFile, "..", "..", "scaffold"),
10
15
  join(thisFile, "..", "scaffold"),
16
+ join(thisFile, "..", "..", "..", "scaffold"),
11
17
  ];
12
18
  for (const dir of candidates) {
13
19
  if (existsSync(dir))
@@ -15,36 +21,60 @@ const scaffoldDir = () => {
15
21
  }
16
22
  throw new Error("scaffold 디렉터리를 찾을 수 없다");
17
23
  };
18
- const copyFile = (src, dest, force) => {
19
- if (existsSync(dest) && !force)
20
- return "skipped";
24
+ const putFile = (dest, content, force, owner) => {
21
25
  const existed = existsSync(dest);
26
+ if (existed && owner === "user")
27
+ return force ? "kept" : "skipped";
28
+ if (existed && !force)
29
+ return "skipped";
30
+ if (existed && readFileSync(dest, "utf8") === content)
31
+ return "unchanged";
22
32
  const dir = dirname(dest);
23
33
  if (!existsSync(dir))
24
34
  mkdirSync(dir, { recursive: true });
25
- writeFileSync(dest, readFileSync(src, "utf8"), "utf8");
35
+ writeFileSync(dest, content, "utf8");
26
36
  return existed ? "overwritten" : "created";
27
37
  };
38
+ const copyFile = (src, dest, force, owner) => putFile(dest, readFileSync(src, "utf8"), force, owner);
39
+ /** 표식으로 감싼 specthread 섹션. 표식 사이만 패키지가 갱신한다 */
40
+ const wrapSection = (section) => `${SPECTHREAD_START}\n${section}\n${SPECTHREAD_END}`;
41
+ /**
42
+ * 표식 없이 만들어진 이전 버전의 AGENTS.md 인지. scaffold 의 제목과 절 이름으로 본다.
43
+ *
44
+ * 섹션을 덧붙이면 같은 내용이 두 번 들어가고, 파일 전체를 바꾸면 사용자가 덧붙인 내용이
45
+ * 사라질 수 있다. 그래서 건드리지 않고 알린다.
46
+ */
47
+ const isLegacyAgents = (content) => /^# specthread\s*$/m.test(content) && /^## 2\. SDD 작업 흐름\s*$/m.test(content);
48
+ /** AGENTS.md 의 specthread 섹션을 맞춘다 */
28
49
  const ensureAgentsMd = (cwd, scaffold) => {
29
50
  const dest = join(cwd, "AGENTS.md");
30
- const src = join(scaffold, "AGENTS.md");
51
+ const section = readFileSync(join(scaffold, "AGENTS.md"), "utf8");
31
52
  if (!existsSync(dest)) {
32
- writeFileSync(dest, readFileSync(src, "utf8"), "utf8");
53
+ writeFileSync(dest, `${wrapSection(section)}\n`, "utf8");
33
54
  console.log(" AGENTS.md 생성");
34
- return;
55
+ return "written";
35
56
  }
36
57
  const content = readFileSync(dest, "utf8");
37
- if (content.includes(SPECTHREAD_START)) {
38
- const before = content.slice(0, content.indexOf(SPECTHREAD_START));
39
- const after = content.slice(content.indexOf(SPECTHREAD_END) + SPECTHREAD_END.length);
40
- const section = readFileSync(src, "utf8");
41
- writeFileSync(dest, `${before}${SPECTHREAD_START}\n${section}\n${SPECTHREAD_END}${after}`, "utf8");
58
+ const start = content.indexOf(SPECTHREAD_START);
59
+ if (start >= 0) {
60
+ const end = content.indexOf(SPECTHREAD_END, start);
61
+ // 끝 표식이 없으면 섹션이 어디서 끝나는지 알 수 없다. 추측해서 바꾸면 사용자 내용을 지운다
62
+ if (end < 0) {
63
+ console.log(` AGENTS.md ${SPECTHREAD_END} 표식 없음. 건드리지 않음`);
64
+ return "broken";
65
+ }
66
+ const after = content.slice(end + SPECTHREAD_END.length);
67
+ writeFileSync(dest, `${content.slice(0, start)}${wrapSection(section)}${after}`, "utf8");
42
68
  console.log(" AGENTS.md specthread 섹션 갱신");
43
- return;
69
+ return "written";
44
70
  }
45
- const section = readFileSync(src, "utf8");
46
- writeFileSync(dest, `${content.trimEnd()}\n\n${SPECTHREAD_START}\n${section}\n${SPECTHREAD_END}\n`, "utf8");
71
+ if (isLegacyAgents(content)) {
72
+ console.log(" AGENTS.md 이전 버전 형식 (구분 표식 없음). 건드리지 않음");
73
+ return "legacy";
74
+ }
75
+ writeFileSync(dest, `${content.trimEnd()}\n\n${wrapSection(section)}\n`, "utf8");
47
76
  console.log(" AGENTS.md specthread 섹션 삽입");
77
+ return "written";
48
78
  };
49
79
  const ensureClaudeMd = (cwd) => {
50
80
  const dest = join(cwd, "CLAUDE.md");
@@ -61,6 +91,26 @@ const ensureClaudeMd = (cwd) => {
61
91
  writeFileSync(dest, `${content.trimEnd()}\n\n@AGENTS.md\n`, "utf8");
62
92
  console.log(" CLAUDE.md @AGENTS.md 추가");
63
93
  };
94
+ /** 개인 설정이 커밋되지 않게 한다. 이미 적혀 있으면 건드리지 않는다 */
95
+ const ensureGitignore = (cwd) => {
96
+ const dest = join(cwd, ".gitignore");
97
+ if (!existsSync(dest)) {
98
+ writeFileSync(dest, `${LOCAL_CONFIG_PATH}\n`, "utf8");
99
+ console.log(" .gitignore 생성");
100
+ return;
101
+ }
102
+ const content = readFileSync(dest, "utf8");
103
+ if (content.split(/\r?\n/).some((l) => l.trim() === LOCAL_CONFIG_PATH)) {
104
+ console.log(` .gitignore 이미 ${LOCAL_CONFIG_PATH} 포함`);
105
+ return;
106
+ }
107
+ writeFileSync(dest, `${content.trimEnd()}\n\n# specthread 개인 설정\n${LOCAL_CONFIG_PATH}\n`, "utf8");
108
+ console.log(` .gitignore ${LOCAL_CONFIG_PATH} 추가`);
109
+ };
110
+ const SKILLS = ["check", "gen", "plan-open", "plan-run", "plan-close"];
111
+ /** 업데이트 프롬프트 구분선. 사용자가 이 사이를 복사해 AI 에 전달한다 */
112
+ const PROMPT_START = "── 업데이트 프롬프트: 아래를 AI 에게 그대로 전달한다 ──────────────";
113
+ const PROMPT_END = "──────────────────────────────────────────────────────────────";
64
114
  const parseTools = (args) => {
65
115
  const idx = args.indexOf("--tools");
66
116
  if (idx === -1 || idx + 1 >= args.length)
@@ -70,7 +120,9 @@ const parseTools = (args) => {
70
120
  const STATUS_LABEL = {
71
121
  created: "생성",
72
122
  overwritten: "덮어씀",
123
+ unchanged: "변경 없음",
73
124
  skipped: "이미 존재. 건너뜀",
125
+ kept: "사용자 파일. 건너뜀",
74
126
  };
75
127
  export const init = (args) => {
76
128
  const cwd = process.cwd();
@@ -81,47 +133,69 @@ export const init = (args) => {
81
133
  console.log("specthread init --force\n");
82
134
  else
83
135
  console.log("specthread init\n");
84
- const stDir = join(cwd, "specthread");
136
+ const stDir = join(cwd, SPECTHREAD_DIR);
85
137
  if (existsSync(stDir)) {
86
- console.log(" specthread/ 이미 존재 - 기존 설정 유지");
138
+ console.log(` ${SPECTHREAD_DIR}/ 이미 존재 - 기존 설정 유지`);
87
139
  }
88
140
  else {
89
141
  mkdirSync(stDir, { recursive: true });
90
- console.log(" specthread/ 생성");
142
+ console.log(` ${SPECTHREAD_DIR}/ 생성`);
91
143
  }
92
- const specthreadFiles = [
93
- "config.jsonc",
94
- "rules.md",
95
- "project.md",
96
- "pending.md",
144
+ const configStatus = putFile(join(cwd, CONFIG_PATH), renderConfig(DEFAULT_CONFIG), force, "user");
145
+ console.log(` ${CONFIG_PATH} ${STATUS_LABEL[configStatus]}`);
146
+ // 내용이 바뀐 패키지 파일. 업데이트 프롬프트가 사용자 수정분 확인을 요청한다
147
+ const overwritten = [];
148
+ const put = ({ src, dest, owner }) => {
149
+ const status = copyFile(src, join(cwd, dest), force, owner);
150
+ if (status === "overwritten")
151
+ overwritten.push(dest);
152
+ console.log(` ${dest} ${STATUS_LABEL[status]}`);
153
+ };
154
+ // scaffold 원본은 고정 경로와 같은 파일 이름을 쓴다
155
+ const docs = [
156
+ [RULES_PATH, "package"],
157
+ [PROJECT_PATH, "user"],
158
+ [PENDING_PATH, "user"],
97
159
  ];
98
- for (const file of specthreadFiles) {
99
- const status = copyFile(join(scaffold, file), join(stDir, file), force);
100
- console.log(` specthread/${file} ${STATUS_LABEL[status]}`);
160
+ for (const [dest, owner] of docs)
161
+ put({ src: join(scaffold, basename(dest)), dest, owner });
162
+ for (const file of ["spec.md", "plan.md"]) {
163
+ put({ src: join(scaffold, "templates", file), dest: `${TEMPLATES_DIR}/${file}`, owner: "package" });
101
164
  }
102
- const templateFiles = ["spec.md", "plan.md"];
103
- const templatesDir = join(stDir, "templates");
104
- for (const file of templateFiles) {
105
- const status = copyFile(join(scaffold, "templates", file), join(templatesDir, file), force);
106
- console.log(` specthread/templates/${file} ${STATUS_LABEL[status]}`);
107
- }
108
- ensureAgentsMd(cwd, scaffold);
165
+ const agents = ensureAgentsMd(cwd, scaffold);
166
+ ensureGitignore(cwd);
167
+ const oldSkills = [];
109
168
  if (tools.has("claude")) {
110
169
  ensureClaudeMd(cwd);
111
- const skillsDir = join(cwd, ".claude", "skills");
112
- if (!existsSync(skillsDir))
113
- mkdirSync(skillsDir, { recursive: true });
114
- const skillFiles = [
115
- "check.md",
116
- "gen.md",
117
- "plan-open.md",
118
- "plan-run.md",
119
- "plan-close.md",
120
- ];
121
- for (const file of skillFiles) {
122
- const status = copyFile(join(scaffold, "claude", "skills", file), join(skillsDir, file), force);
123
- console.log(` .claude/skills/${file} ${STATUS_LABEL[status]}`);
170
+ // Claude Code 는 `<이름>/SKILL.md` 만 스킬로 읽는다. `<이름>.md` 는 이전 버전의 경로다
171
+ for (const name of SKILLS) {
172
+ put({
173
+ src: join(scaffold, "claude", "skills", name, "SKILL.md"),
174
+ dest: `.claude/skills/${name}/SKILL.md`,
175
+ owner: "package",
176
+ });
177
+ if (existsSync(join(cwd, ".claude", "skills", `${name}.md`)))
178
+ oldSkills.push(`.claude/skills/${name}.md`);
179
+ }
180
+ // 사용자가 고쳤을 수 있으므로 지우지 않고 알리기만 한다
181
+ if (oldSkills.length > 0) {
182
+ console.log("\n 이전 형식의 스킬 파일이 남아 있다. Claude Code 가 읽지 않으므로 지워도 된다:");
183
+ for (const path of oldSkills)
184
+ console.log(` ${path}`);
124
185
  }
125
186
  }
187
+ if (force) {
188
+ console.log(`\n--force 는 패키지 파일만 갱신한다. ${CONFIG_PATH}, ${PROJECT_PATH}, ${PENDING_PATH} 는 그대로 둔다.`);
189
+ console.log(`\n${PROMPT_START}`);
190
+ console.log(renderUpgradePrompt({ root: cwd, agents, overwritten, oldSkills }));
191
+ console.log(PROMPT_END);
192
+ return;
193
+ }
194
+ if (agents === "broken") {
195
+ console.log(`\nAGENTS.md 의 specthread 섹션 끝에 ${SPECTHREAD_END} 를 넣고 다시 실행한다.`);
196
+ }
197
+ if (agents === "legacy" || oldSkills.length > 0) {
198
+ console.log("\n이전 버전에서 올린 프로젝트로 보인다. `npx specthread init --force` 로 패키지 파일을 갱신하면 남은 정리를 위한 프롬프트를 출력한다.");
199
+ }
126
200
  console.log("\n완료. npx specthread check 로 문서 정합성을 확인할 수 있다.");
127
201
  };
@@ -0,0 +1,12 @@
1
+ /** AGENTS.md 처리 결과. `legacy`·`broken` 은 파일을 고치지 않은 경우다 */
2
+ export type AgentsStatus = "written" | "legacy" | "broken";
3
+ /** init 이 넘겨주는 상태 */
4
+ export interface UpgradeInput {
5
+ root: string;
6
+ agents: AgentsStatus;
7
+ /** 내용이 바뀐 패키지 파일 */
8
+ overwritten: string[];
9
+ /** `<이름>/SKILL.md` 가 아닌 이전 경로에 남은 스킬 파일 */
10
+ oldSkills: string[];
11
+ }
12
+ export declare const renderUpgradePrompt: (input: UpgradeInput) => string;
@@ -0,0 +1,147 @@
1
+ /**
2
+ * `init --force` 가 마지막에 출력하는 업데이트 프롬프트.
3
+ *
4
+ * 사용자가 AI 에 그대로 붙여 넣는 글이다. init 이 감지한 상태에 해당하는 단계만 넣고,
5
+ * 검사와 생성 단계는 항상 넣는다. 버전을 올리며 정리할 것이 생기면 감지 항목을 더한다.
6
+ */
7
+ import { existsSync, readFileSync } from "node:fs";
8
+ import { join } from "node:path";
9
+ import { readConfig, REMOVED_KEYS } from "../config-loader.js";
10
+ import { DEFAULT_CONFIG } from "../config.schema.js";
11
+ import { CONFIG_PATH, LOCAL_CONFIG_PATH, PENDING_PATH, PROJECT_PATH, SPECTHREAD_DIR, } from "../constants/paths.js";
12
+ import { normalizeConfigPath, underPath } from "../utils/path-match.js";
13
+ /**
14
+ * 사용자 파일은 `--force` 로도 덮어쓰지 않는다. scaffold 의 사용자 파일 문구를 바꾸면
15
+ * 옛 문구를 여기에 더해 업데이트 프롬프트가 고치게 한다.
16
+ */
17
+ const STALE_TEXT = [
18
+ {
19
+ file: PROJECT_PATH,
20
+ before: "`config.jsonc` 에서 경로를 override 할 수 있다.",
21
+ after: "경로는 `specthread/pending.md` 고정이다.",
22
+ },
23
+ {
24
+ file: PENDING_PATH,
25
+ before: "**종류마다 `##` 섹션이 하나씩 생긴다.** 종류 값은 `config.markers.types` 가 정의하며,",
26
+ after: "**종류마다 `##` 섹션을 하나씩 둔다.** 섹션은 사람이 만들고, 종류 값은 `config.markers.types` 에 있어야 한다.",
27
+ },
28
+ ];
29
+ /** 규약 파일 경로를 정하던 키. 값을 적어 썼다면 파일을 `specthread/` 아래로 옮겨야 한다 */
30
+ const PATH_KEYS = new Set(["rules", "pending", "project"]);
31
+ /** 주석 줄에 남은 제거된 키. 기본값을 주석으로 적어 둔 설정 파일에서 나온다 */
32
+ const commentedKeys = (text) => Object.keys(REMOVED_KEYS).filter((key) => {
33
+ const name = key.slice(key.lastIndexOf(".") + 1);
34
+ return new RegExp(`^\\s*//.*"${name}"\\s*:`, "m").test(text);
35
+ });
36
+ const removedKeys = (root, live) => {
37
+ const out = live.map((r) => ({ ...r, commented: false }));
38
+ for (const file of [CONFIG_PATH, LOCAL_CONFIG_PATH]) {
39
+ const abs = join(root, file);
40
+ if (!existsSync(abs))
41
+ continue;
42
+ for (const key of commentedKeys(readFileSync(abs, "utf8"))) {
43
+ if (!out.some((r) => r.file === file && r.key === key))
44
+ out.push({ file, key, commented: true });
45
+ }
46
+ }
47
+ return out;
48
+ };
49
+ const staleText = (root) => STALE_TEXT.filter(({ file, before }) => {
50
+ const abs = join(root, file);
51
+ return existsSync(abs) && readFileSync(abs, "utf8").includes(before);
52
+ });
53
+ /**
54
+ * 기본 스캔 경로 중 설정에서 빠진 것. 그 디렉터리가 있을 때만 본다.
55
+ *
56
+ * `path` 는 기본값과 합치지 않고 통째로 교체하므로 일부 키만 적으면 기본 경로가 빠진다.
57
+ * `specthread/` 의 규약 파일은 `path` 와 관계없이 읽으므로 대상에서 뺀다.
58
+ */
59
+ const uncoveredDefaults = (root, path) => {
60
+ const bases = Object.values(path).flat().map(normalizeConfigPath);
61
+ return Object.values(DEFAULT_CONFIG.path)
62
+ .flat()
63
+ .map(normalizeConfigPath)
64
+ .filter((d) => d !== SPECTHREAD_DIR && existsSync(join(root, d)))
65
+ .filter((d) => !bases.some((b) => underPath(b, d) || underPath(d, b)));
66
+ };
67
+ const bullets = (items) => items.map((item) => `- ${item}`);
68
+ const HEADER = [
69
+ "specthread 패키지 파일을 새 버전으로 갱신했다. 아래를 순서대로 처리해줘.",
70
+ "내가 직접 쓴 내용은 지우지 말고, 판단이 필요하면 멈추고 물어봐.",
71
+ ];
72
+ export const renderUpgradePrompt = (input) => {
73
+ const { config, removed: live } = readConfig(input.root);
74
+ const steps = [];
75
+ if (input.agents === "broken") {
76
+ steps.push([
77
+ "`AGENTS.md` 에 `<!-- specthread:start -->` 는 있고 `<!-- specthread:end -->` 가 없다. " +
78
+ "specthread 섹션이 끝나는 줄 다음에 끝 표식을 넣고 `npx specthread init` 을 다시 실행한다.",
79
+ ]);
80
+ }
81
+ if (input.agents === "legacy") {
82
+ steps.push([
83
+ "`AGENTS.md` 의 specthread 섹션을 `<!-- specthread:start -->` 와 `<!-- specthread:end -->` 로 감싼다. " +
84
+ "섹션은 `# specthread` 제목부터 그 섹션 끝까지이고, 그 밖의 내용은 그대로 둔다.",
85
+ ...bullets([
86
+ "specthread 섹션이 두 번 들어 있으면 뒤의 것을 지운다.",
87
+ "감싼 뒤 `npx specthread init` 을 다시 실행해 섹션을 새 버전으로 바꾼다.",
88
+ ]),
89
+ ]);
90
+ }
91
+ if (input.overwritten.length > 0) {
92
+ steps.push([
93
+ "아래 파일을 새 버전으로 덮어썼다. git diff 로 확인하고, 내가 고쳐 둔 내용이 사라졌으면 알려줘.",
94
+ ...bullets(input.overwritten),
95
+ ]);
96
+ }
97
+ if (input.oldSkills.length > 0) {
98
+ steps.push([
99
+ "아래 옛 스킬 파일을 같은 이름의 `<이름>/SKILL.md` 와 비교한다. 내가 고친 부분이 없으면 지우고, 있으면 알려줘.",
100
+ ...bullets(input.oldSkills),
101
+ ]);
102
+ }
103
+ const removed = removedKeys(input.root, live);
104
+ if (removed.length > 0) {
105
+ const pathKeyInUse = removed.some((r) => !r.commented && PATH_KEYS.has(r.key));
106
+ steps.push([
107
+ "설정 파일에서 제거된 키를 지운다. 주석으로만 남은 것은 그 설명 주석까지 지운다.",
108
+ ...bullets(removed.map((r) => `${r.file}: ${r.key}${r.commented ? " (주석)" : ""}`)),
109
+ ...(pathKeyInUse
110
+ ? [
111
+ "`rules`·`pending`·`project` 에 경로를 적어 쓰고 있었다면 지우지 말고 알려줘. " +
112
+ "경로가 `specthread/` 아래로 고정이라 파일을 옮겨야 한다.",
113
+ ]
114
+ : []),
115
+ ]);
116
+ }
117
+ const stale = staleText(input.root);
118
+ if (stale.length > 0) {
119
+ steps.push([
120
+ "사용자 파일의 옛 문구를 지금 문구로 바꾼다.",
121
+ ...bullets(stale.map((s) => `${s.file}: "${s.before}" → "${s.after}"`)),
122
+ ]);
123
+ }
124
+ const uncovered = uncoveredDefaults(input.root, config.path);
125
+ if (uncovered.length > 0) {
126
+ steps.push([
127
+ "`config.path` 가 아래 경로를 스캔하지 않는다. `path` 는 기본값과 합치지 않고 통째로 교체되므로, " +
128
+ "일부 키만 적으면 기본 경로가 빠진다. 의도한 것인지 물어봐.",
129
+ ...bullets(uncovered.map((d) => `${d}/`)),
130
+ ]);
131
+ }
132
+ steps.push([
133
+ "`npx specthread check` 를 실행하고 지적을 고친다.",
134
+ ...bullets([
135
+ "종료 코드 2 로 끝나면 출력된 설정 파일과 키부터 고친다.",
136
+ "`marker/unknown-type` 이 나오면 쓰고 있는 종류를 `config.markers.types` 에 추가할지 물어봐.",
137
+ "`heading/tail-order` 가 나오면 꼬리 절을 참조 → 미확정 사항 → 변경 이력 순서로 옮긴다.",
138
+ ]),
139
+ ]);
140
+ steps.push(["`npx specthread gen --write` 를 실행한 뒤 `npx specthread check` 가 0 건인지 확인한다."]);
141
+ const body = steps.flatMap(([first, ...rest], i) => [
142
+ `${i + 1}. ${first}`,
143
+ ...rest.map((line) => ` ${line}`),
144
+ "",
145
+ ]);
146
+ return [...HEADER, "", ...body].join("\n").trimEnd();
147
+ };
@@ -1,2 +1,45 @@
1
1
  import type { SpecthreadConfig } from "./config.schema.ts";
2
- export declare const loadConfig: (cwd?: string) => SpecthreadConfig;
2
+ /** 설정을 읽지 못한 이유 하나. 어느 파일 어느 키인지 함께 낸다 */
3
+ export interface ConfigProblem {
4
+ file: string;
5
+ /** 점으로 이은 키 경로. 파일 전체의 문제면 빈 문자열 */
6
+ key: string;
7
+ message: string;
8
+ }
9
+ /**
10
+ * 설정을 쓸 수 없을 때 던진다.
11
+ *
12
+ * 문제를 하나씩 던지면 사용자가 고치고 다시 돌리기를 반복해야 한다. 한 번에 모아 낸다.
13
+ */
14
+ export declare class ConfigError extends Error {
15
+ readonly problems: ConfigProblem[];
16
+ constructor(problems: ConfigProblem[]);
17
+ }
18
+ /** 제거한 키와 그 이유. 기존 config 가 깨지지 않게 오류 대신 경고로 알린다 */
19
+ export declare const REMOVED_KEYS: Record<string, string>;
20
+ /** 설정 파일에 남아 있는 제거된 키 하나 */
21
+ export interface RemovedKey {
22
+ file: string;
23
+ /** 점으로 이은 키 경로 */
24
+ key: string;
25
+ }
26
+ /** 설정을 읽은 결과. 문제가 있어도 쓸 수 있는 값만 병합해 함께 돌려준다 */
27
+ export interface ConfigReport {
28
+ config: SpecthreadConfig;
29
+ problems: ConfigProblem[];
30
+ warnings: string[];
31
+ removed: RemovedKey[];
32
+ }
33
+ /**
34
+ * 기본값 → config.jsonc → config.local.jsonc 순으로 병합한다. 출력도 예외도 없다.
35
+ *
36
+ * 쓸 수 없는 값은 병합에서 빼고 `problems` 에 담는다. 업데이트 프롬프트처럼 설정이 틀려도
37
+ * 중단하지 않아야 하는 기능이 이 결과를 사용한다.
38
+ */
39
+ export declare const readConfig: (root?: string) => ConfigReport;
40
+ /**
41
+ * 기본값 → config.jsonc → config.local.jsonc 순으로 병합한 설정.
42
+ *
43
+ * 쓸 수 없는 값이 하나라도 있으면 `ConfigError` 를 던진다. 경고는 출력만 하고 진행한다.
44
+ */
45
+ export declare const loadConfig: (root?: string) => SpecthreadConfig;