@brucewaynedecoy/make-docs 1.0.0-rc.1 → 2.0.3

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 (187) hide show
  1. package/LICENSE +21 -201
  2. package/README.md +31 -67
  3. package/dist/backup-GCM64IPN.js +20 -0
  4. package/dist/backup-GCM64IPN.js.map +1 -0
  5. package/dist/chunk-2HNJCJJE.js +1291 -0
  6. package/dist/chunk-2HNJCJJE.js.map +1 -0
  7. package/dist/chunk-4LLSMDWJ.js +24674 -0
  8. package/dist/chunk-4LLSMDWJ.js.map +1 -0
  9. package/dist/chunk-57GN6ALR.js +204 -0
  10. package/dist/chunk-57GN6ALR.js.map +1 -0
  11. package/dist/chunk-C2IBRVUA.js +4136 -0
  12. package/dist/chunk-C2IBRVUA.js.map +1 -0
  13. package/dist/chunk-D4HDZEJT.js +37 -0
  14. package/dist/chunk-D4HDZEJT.js.map +1 -0
  15. package/dist/chunk-DFQJENNL.js +2340 -0
  16. package/dist/chunk-DFQJENNL.js.map +1 -0
  17. package/dist/chunk-DNDM7DUQ.js +39 -0
  18. package/dist/chunk-DNDM7DUQ.js.map +1 -0
  19. package/dist/chunk-GPVKIBFC.js +875 -0
  20. package/dist/chunk-GPVKIBFC.js.map +1 -0
  21. package/dist/chunk-IHMZ2OCS.js +1575 -0
  22. package/dist/chunk-IHMZ2OCS.js.map +1 -0
  23. package/dist/chunk-O2UZ35PV.js +523 -0
  24. package/dist/chunk-O2UZ35PV.js.map +1 -0
  25. package/dist/chunk-U25GFKNZ.js +13995 -0
  26. package/dist/chunk-U25GFKNZ.js.map +1 -0
  27. package/dist/chunk-Z5K4FHYP.js +922 -0
  28. package/dist/chunk-Z5K4FHYP.js.map +1 -0
  29. package/dist/index.js +3798 -250
  30. package/dist/index.js.map +1 -1
  31. package/dist/self-UHPM4A2U.js +653 -0
  32. package/dist/self-UHPM4A2U.js.map +1 -0
  33. package/dist/server-N7XAAV3X.js +512 -0
  34. package/dist/server-N7XAAV3X.js.map +1 -0
  35. package/dist/setup-system-JUHGDZJW.js +544 -0
  36. package/dist/setup-system-JUHGDZJW.js.map +1 -0
  37. package/dist/{skills-command-3ESCZ75U.js → skills-command-W3SE3OFP.js} +190 -32
  38. package/dist/skills-command-W3SE3OFP.js.map +1 -0
  39. package/dist/uninstall-BGMJ6KCI.js +223 -0
  40. package/dist/uninstall-BGMJ6KCI.js.map +1 -0
  41. package/dist/virtual_make-docs-first-party-skills-VXSUUHTL.js +11 -0
  42. package/dist/virtual_make-docs-first-party-skills-VXSUUHTL.js.map +1 -0
  43. package/package.json +9 -6
  44. package/skill-registry.json +328 -125
  45. package/skill-registry.schema.json +221 -45
  46. package/template/.make-docs/AGENTS.md +18 -0
  47. package/template/.make-docs/CLAUDE.md +18 -0
  48. package/template/.make-docs/archive/AGENTS.md +11 -0
  49. package/template/.make-docs/archive/CLAUDE.md +11 -0
  50. package/template/.make-docs/system/AGENTS.md +12 -0
  51. package/template/.make-docs/system/CLAUDE.md +12 -0
  52. package/template/.make-docs/system/contracts/AGENTS.md +13 -0
  53. package/template/.make-docs/system/contracts/CLAUDE.md +13 -0
  54. package/template/{docs/assets/references → .make-docs/system/contracts}/commit-message-convention.md +4 -4
  55. package/template/.make-docs/system/contracts/coverage-pass-contract.md +198 -0
  56. package/template/.make-docs/system/contracts/deferred-obligation-contract.md +128 -0
  57. package/template/{docs/assets/references → .make-docs/system/contracts}/design-contract.md +7 -2
  58. package/template/{docs/assets/references → .make-docs/system/contracts}/guide-contract.md +21 -19
  59. package/template/{docs/assets/references → .make-docs/system/contracts}/history-record-contract.md +17 -11
  60. package/template/.make-docs/system/contracts/human-experience-contract.md +134 -0
  61. package/template/.make-docs/system/contracts/naive-uat-contract.md +231 -0
  62. package/template/.make-docs/system/contracts/output-contract.md +277 -0
  63. package/template/.make-docs/system/contracts/performance-evidence-governance.md +257 -0
  64. package/template/.make-docs/system/contracts/system-resource-contract.md +93 -0
  65. package/template/.make-docs/system/prompts/AGENTS.md +12 -0
  66. package/template/.make-docs/system/prompts/CLAUDE.md +12 -0
  67. package/template/.make-docs/system/prompts/coverage-pass-maintainer-guide.prompt.md +20 -0
  68. package/template/.make-docs/system/prompts/coverage-pass-prd-reconciliation.prompt.md +18 -0
  69. package/template/.make-docs/system/prompts/coverage-pass-testing-uat.prompt.md +46 -0
  70. package/template/.make-docs/system/prompts/coverage-pass-user-guide.prompt.md +20 -0
  71. package/template/.make-docs/system/prompts/designs-to-plan-change.prompt.md +18 -0
  72. package/template/.make-docs/system/prompts/designs-to-plan.prompt.md +14 -0
  73. package/template/.make-docs/system/prompts/docs-path-hygiene-cleanup.prompt.md +29 -0
  74. package/template/.make-docs/system/prompts/naive-uat-facilitator.prompt.md +28 -0
  75. package/template/.make-docs/system/prompts/naive-uat-tester.prompt.md +20 -0
  76. package/template/.make-docs/system/prompts/performance-coverage.prompt.md +63 -0
  77. package/template/.make-docs/system/prompts/plan-to-prd-change.prompt.md +12 -0
  78. package/template/.make-docs/system/prompts/plan-to-prd-green-field.prompt.md +10 -0
  79. package/template/.make-docs/system/prompts/prd-change-to-work.prompt.md +14 -0
  80. package/template/.make-docs/system/prompts/prd-to-work-full-prd.prompt.md +10 -0
  81. package/template/.make-docs/system/prompts/prd-to-work-prd-feature.prompt.md +10 -0
  82. package/template/.make-docs/system/prompts/request-to-design.prompt.md +20 -0
  83. package/template/.make-docs/system/prompts/session-to-history-record.prompt.md +23 -0
  84. package/template/{docs/assets → .make-docs/system}/prompts/work-to-commit-message.prompt.md +2 -2
  85. package/template/.make-docs/system/prompts/work-to-guides.prompt.md +22 -0
  86. package/template/.make-docs/system/references/AGENTS.md +14 -0
  87. package/template/.make-docs/system/references/CLAUDE.md +14 -0
  88. package/template/{docs/assets → .make-docs/system}/references/design-workflow.md +15 -2
  89. package/template/.make-docs/system/references/execution-workflow.md +189 -0
  90. package/template/.make-docs/system/references/human-experience.md +138 -0
  91. package/template/.make-docs/system/references/lifecycle.md +153 -0
  92. package/template/.make-docs/system/references/naive-uat-validation.md +65 -0
  93. package/template/.make-docs/system/references/naive-uat-workflow.md +64 -0
  94. package/template/.make-docs/system/references/path-and-link-hygiene.md +101 -0
  95. package/template/.make-docs/system/references/performance-evidence.md +114 -0
  96. package/template/.make-docs/system/references/planning-workflow.md +209 -0
  97. package/template/.make-docs/system/references/prd-change-management.md +165 -0
  98. package/template/{docs/assets → .make-docs/system}/references/wave-model.md +10 -8
  99. package/template/.make-docs/system/templates/AGENTS.md +12 -0
  100. package/template/.make-docs/system/templates/CLAUDE.md +12 -0
  101. package/template/.make-docs/system/templates/design.md +79 -0
  102. package/template/{docs/assets/templates/guide-developer.md → .make-docs/system/templates/guide-maintainer.md} +7 -3
  103. package/template/{docs/assets → .make-docs/system}/templates/guide-user.md +6 -2
  104. package/template/{docs/assets → .make-docs/system}/templates/history-record.md +6 -3
  105. package/template/.make-docs/system/templates/naive-uat-scenario.md +91 -0
  106. package/template/.make-docs/system/templates/performance-evidence-profile.md +252 -0
  107. package/template/.make-docs/system/templates/plan-overview.md +76 -0
  108. package/template/.make-docs/system/templates/plan-prd-change.md +155 -0
  109. package/template/{docs/assets → .make-docs/system}/templates/plan-prd-decompose.md +10 -0
  110. package/template/{docs/assets → .make-docs/system}/templates/plan-prd.md +28 -2
  111. package/template/{docs/assets → .make-docs/system}/templates/prd-architecture.md +13 -0
  112. package/template/.make-docs/system/templates/prd-glossary.md +28 -0
  113. package/template/.make-docs/system/templates/prd-index.md +70 -0
  114. package/template/{docs/assets → .make-docs/system}/templates/prd-overview.md +13 -0
  115. package/template/.make-docs/system/templates/prd-reference.md +30 -0
  116. package/template/{docs/assets → .make-docs/system}/templates/prd-risk-register.md +16 -1
  117. package/template/{docs/assets → .make-docs/system}/templates/prd-subsystem.md +15 -0
  118. package/template/.make-docs/system/templates/work-index.md +58 -0
  119. package/template/.make-docs/system/templates/work-phase.md +107 -0
  120. package/template/.make-docs/system-resources.catalog.json +91 -0
  121. package/template/.make-docs/system-resources.schema.json +204 -0
  122. package/template/AGENTS.md +8 -1
  123. package/template/CLAUDE.md +8 -1
  124. package/template/docs/AGENTS.codex-only.md +22 -0
  125. package/template/docs/AGENTS.md +21 -13
  126. package/template/docs/CLAUDE.claude-only.md +22 -0
  127. package/template/docs/CLAUDE.md +21 -13
  128. package/template/docs/assets/AGENTS.md +11 -7
  129. package/template/docs/assets/CLAUDE.md +11 -7
  130. package/template/docs/designs/AGENTS.md +8 -3
  131. package/template/docs/designs/CLAUDE.md +8 -3
  132. package/template/docs/plans/AGENTS.md +10 -3
  133. package/template/docs/plans/CLAUDE.md +10 -3
  134. package/template/docs/prd/AGENTS.md +14 -4
  135. package/template/docs/prd/CLAUDE.md +14 -4
  136. package/template/docs/work/AGENTS.md +10 -3
  137. package/template/docs/work/CLAUDE.md +10 -3
  138. package/dist/chunk-HP3HBG7F.js +0 -626
  139. package/dist/chunk-HP3HBG7F.js.map +0 -1
  140. package/dist/chunk-QRFH4J6H.js +0 -1194
  141. package/dist/chunk-QRFH4J6H.js.map +0 -1
  142. package/dist/chunk-WM3OXYTW.js +0 -2630
  143. package/dist/chunk-WM3OXYTW.js.map +0 -1
  144. package/dist/skills-command-3ESCZ75U.js.map +0 -1
  145. package/dist/uninstall-GQE4SJF2.js +0 -150
  146. package/dist/uninstall-GQE4SJF2.js.map +0 -1
  147. package/template/.make-docs/scripts/check_path_hygiene.py +0 -435
  148. package/template/docs/assets/archive/AGENTS.md +0 -20
  149. package/template/docs/assets/archive/CLAUDE.md +0 -20
  150. package/template/docs/assets/history/AGENTS.md +0 -12
  151. package/template/docs/assets/history/CLAUDE.md +0 -12
  152. package/template/docs/assets/prompts/AGENTS.md +0 -8
  153. package/template/docs/assets/prompts/CLAUDE.md +0 -8
  154. package/template/docs/assets/prompts/designs-to-plan-change.prompt.md +0 -14
  155. package/template/docs/assets/prompts/designs-to-plan.prompt.md +0 -10
  156. package/template/docs/assets/prompts/docs-path-hygiene-cleanup.prompt.md +0 -27
  157. package/template/docs/assets/prompts/plan-to-prd-change.prompt.md +0 -8
  158. package/template/docs/assets/prompts/plan-to-prd-green-field.prompt.md +0 -6
  159. package/template/docs/assets/prompts/prd-change-to-work.prompt.md +0 -10
  160. package/template/docs/assets/prompts/prd-to-work-full-prd.prompt.md +0 -6
  161. package/template/docs/assets/prompts/prd-to-work-prd-feature.prompt.md +0 -6
  162. package/template/docs/assets/prompts/request-to-design.prompt.md +0 -16
  163. package/template/docs/assets/prompts/session-to-history-record.prompt.md +0 -19
  164. package/template/docs/assets/prompts/work-to-guides.prompt.md +0 -18
  165. package/template/docs/assets/references/AGENTS.md +0 -9
  166. package/template/docs/assets/references/CLAUDE.md +0 -9
  167. package/template/docs/assets/references/execution-workflow.md +0 -157
  168. package/template/docs/assets/references/output-contract.md +0 -221
  169. package/template/docs/assets/references/path-and-link-hygiene.md +0 -49
  170. package/template/docs/assets/references/planning-workflow.md +0 -160
  171. package/template/docs/assets/references/prd-change-management.md +0 -129
  172. package/template/docs/assets/templates/AGENTS.md +0 -8
  173. package/template/docs/assets/templates/CLAUDE.md +0 -8
  174. package/template/docs/assets/templates/design.md +0 -30
  175. package/template/docs/assets/templates/plan-overview.md +0 -32
  176. package/template/docs/assets/templates/plan-prd-change.md +0 -99
  177. package/template/docs/assets/templates/prd-change-addition.md +0 -45
  178. package/template/docs/assets/templates/prd-change-revision.md +0 -45
  179. package/template/docs/assets/templates/prd-glossary.md +0 -15
  180. package/template/docs/assets/templates/prd-index.md +0 -45
  181. package/template/docs/assets/templates/prd-reference.md +0 -17
  182. package/template/docs/assets/templates/work-index.md +0 -21
  183. package/template/docs/assets/templates/work-phase.md +0 -34
  184. package/template/docs/guides/AGENTS.md +0 -15
  185. package/template/docs/guides/CLAUDE.md +0 -15
  186. /package/template/{docs/assets → .make-docs/system}/prompts/update-readme-green-field.prompt.md +0 -0
  187. /package/template/{docs/assets → .make-docs/system}/references/harness-capability-matrix.md +0 -0
@@ -1,1194 +0,0 @@
1
- #!/usr/bin/env node
2
- import {
3
- Ct,
4
- Gt,
5
- HARNESSES,
6
- INSTRUCTION_KINDS,
7
- MANIFEST_RELATIVE_PATH,
8
- Rt,
9
- Vt,
10
- Wt,
11
- createAuditPathMetadata,
12
- defaultSelections,
13
- ensureParentDir,
14
- getDesiredAssets,
15
- getDesiredSkillAssets,
16
- getManifestAuditContext,
17
- getManifestPath,
18
- hashText,
19
- loadManifest,
20
- readTextFile,
21
- renderBuildableAsset,
22
- resolveInstallProfile
23
- } from "./chunk-WM3OXYTW.js";
24
-
25
- // src/audit.ts
26
- import { existsSync, readdirSync, statSync } from "fs";
27
- import os from "os";
28
- import path from "path";
29
- var ROOT_INSTRUCTION_SET = new Set(INSTRUCTION_KINDS);
30
- var PROJECT_BACKUP_DIRNAME = ".backup";
31
- var HARNESS_SKILL_DIRS = {
32
- "claude-code": ".claude/skills",
33
- codex: ".agents/skills"
34
- };
35
- async function createAuditReport(options) {
36
- const targetDir = path.resolve(options.targetDir);
37
- const homeDir = path.resolve(options.homeDir ?? os.homedir());
38
- const removableFiles = /* @__PURE__ */ new Map();
39
- const preservedPaths = /* @__PURE__ */ new Map();
40
- const skippedPaths = /* @__PURE__ */ new Map();
41
- if (options.manifest) {
42
- await classifyManifestPresent({
43
- targetDir,
44
- homeDir,
45
- manifest: options.manifest,
46
- removableFiles,
47
- preservedPaths,
48
- skippedPaths
49
- });
50
- } else {
51
- await classifyManifestMissing({
52
- targetDir,
53
- homeDir,
54
- removableFiles,
55
- preservedPaths,
56
- skippedPaths
57
- });
58
- }
59
- const prunableDirectories = classifyPrunableDirectories({
60
- targetDir,
61
- homeDir,
62
- removableFiles: [...removableFiles.values()],
63
- preservedPaths,
64
- skippedPaths
65
- });
66
- return {
67
- mode: options.manifest ? "manifest-present" : "manifest-missing",
68
- targetDir,
69
- manifestPath: getManifestPath(targetDir),
70
- removableFiles: sortAuditEntries([...removableFiles.values()]),
71
- prunableDirectories: sortPrunableDirectories(prunableDirectories),
72
- preservedPaths: sortAuditEntries([...preservedPaths.values()]),
73
- skippedPaths: sortAuditEntries([...skippedPaths.values()])
74
- };
75
- }
76
- async function classifyManifestPresent(options) {
77
- const {
78
- targetDir,
79
- homeDir,
80
- manifest,
81
- removableFiles,
82
- preservedPaths,
83
- skippedPaths
84
- } = options;
85
- const auditContext = getManifestAuditContext(targetDir, manifest, homeDir);
86
- const priorProfile = resolveInstallProfile(auditContext.priorSelections);
87
- const rootInstructionContentByPath = new Map(
88
- INSTRUCTION_KINDS.map((instructionKind) => [
89
- instructionKind,
90
- renderBuildableAsset(instructionKind, priorProfile)
91
- ])
92
- );
93
- const manifestCandidates = /* @__PURE__ */ new Map();
94
- for (const record of auditContext.managedFiles) {
95
- manifestCandidates.set(record.absolutePath, record);
96
- }
97
- for (const record of auditContext.skillFiles) {
98
- manifestCandidates.set(record.absolutePath, manifestCandidates.get(record.absolutePath) ?? record);
99
- }
100
- manifestCandidates.set(
101
- path.resolve(targetDir, MANIFEST_RELATIVE_PATH),
102
- createManagedPathRecord(targetDir, homeDir, MANIFEST_RELATIVE_PATH, "managed-state", {
103
- sourceId: `state:${MANIFEST_RELATIVE_PATH}`
104
- })
105
- );
106
- const manifestSkillContentByPath = await loadCanonicalSkillContentByPath(
107
- targetDir,
108
- homeDir,
109
- auditContext.priorSelections,
110
- [...manifestCandidates.values()].some((record) => record.ownershipSource === "manifest-skill-file")
111
- );
112
- for (const record of sortAuditEntries([...manifestCandidates.values()])) {
113
- classifyManifestRecord({
114
- targetDir,
115
- record,
116
- rootInstructionContentByPath,
117
- manifestSkillContentByPath,
118
- removableFiles,
119
- preservedPaths,
120
- skippedPaths
121
- });
122
- }
123
- }
124
- function classifyManifestRecord(options) {
125
- const {
126
- targetDir,
127
- record,
128
- rootInstructionContentByPath,
129
- manifestSkillContentByPath,
130
- removableFiles,
131
- preservedPaths,
132
- skippedPaths
133
- } = options;
134
- if (isInsideProjectBackupRoot(targetDir, record.absolutePath)) {
135
- addSkipped(
136
- skippedPaths,
137
- record,
138
- "excluded",
139
- createReason(
140
- "inside-backup-root",
141
- "Paths inside the project `.backup/` tree are excluded from removal consideration."
142
- )
143
- );
144
- return;
145
- }
146
- if (record.pathScope === "external") {
147
- addSkipped(
148
- skippedPaths,
149
- record,
150
- "excluded",
151
- createReason(
152
- "outside-supported-roots",
153
- "This path is outside both the target directory and the user home directory and is preserved conservatively."
154
- )
155
- );
156
- return;
157
- }
158
- if (!existsSync(record.absolutePath)) {
159
- addSkipped(
160
- skippedPaths,
161
- record,
162
- "already-absent",
163
- createReason("already-absent", "The managed path is already absent on disk.")
164
- );
165
- return;
166
- }
167
- if (!statSync(record.absolutePath).isFile()) {
168
- addPreserved(
169
- preservedPaths,
170
- record,
171
- createReason(
172
- "managed-file-modified",
173
- "The managed file path is no longer a regular file and will be preserved."
174
- )
175
- );
176
- return;
177
- }
178
- const currentContent = readTextFile(record.absolutePath);
179
- const currentHash = hashText(currentContent);
180
- if (record.ownershipSource === "managed-state") {
181
- addRemovable(
182
- removableFiles,
183
- record,
184
- createReason(
185
- "managed-state-file",
186
- "The make-docs manifest is CLI-managed state and is eligible for removal."
187
- ),
188
- currentHash,
189
- void 0
190
- );
191
- return;
192
- }
193
- if (isRootInstructionPath(record.path)) {
194
- const expectedContent = rootInstructionContentByPath.get(record.path);
195
- if (expectedContent && currentContent === expectedContent) {
196
- addRemovable(
197
- removableFiles,
198
- record,
199
- createReason(
200
- "root-instruction-content-match",
201
- "The root instruction file exactly matches the canonical make-docs content for the recorded selections."
202
- ),
203
- currentHash,
204
- hashText(expectedContent)
205
- );
206
- return;
207
- }
208
- addPreserved(
209
- preservedPaths,
210
- record,
211
- createReason(
212
- "root-instruction-content-mismatch",
213
- "The root instruction file does not exactly match the canonical make-docs content and will be preserved."
214
- )
215
- );
216
- return;
217
- }
218
- if (record.manifestHash && currentHash === record.manifestHash) {
219
- addRemovable(
220
- removableFiles,
221
- record,
222
- createReason(
223
- "managed-file-hash-match",
224
- "The file still matches the manifest-tracked make-docs content."
225
- ),
226
- currentHash,
227
- record.manifestHash
228
- );
229
- return;
230
- }
231
- if (record.ownershipSource === "manifest-skill-file") {
232
- const expectedContent = manifestSkillContentByPath?.get(record.path);
233
- if (!expectedContent) {
234
- addPreserved(
235
- preservedPaths,
236
- record,
237
- createReason(
238
- "manifest-skill-file-without-metadata",
239
- "The skill file is tracked only by the manifest skill list and cannot be proven removable without canonical make-docs content."
240
- )
241
- );
242
- return;
243
- }
244
- if (currentContent === expectedContent) {
245
- addRemovable(
246
- removableFiles,
247
- record,
248
- createReason(
249
- "managed-skill-file-content-match",
250
- "The skill file exactly matches canonical make-docs skill content."
251
- ),
252
- currentHash,
253
- hashText(expectedContent)
254
- );
255
- return;
256
- }
257
- addPreserved(
258
- preservedPaths,
259
- record,
260
- createReason(
261
- "manifest-skill-file-content-mismatch",
262
- "The manifest-tracked skill file does not match canonical make-docs skill content and will be preserved."
263
- )
264
- );
265
- return;
266
- }
267
- addPreserved(
268
- preservedPaths,
269
- record,
270
- createReason(
271
- "managed-file-modified",
272
- "The manifest-tracked file was modified locally and will be preserved."
273
- )
274
- );
275
- }
276
- async function classifyManifestMissing(options) {
277
- const { targetDir, homeDir, removableFiles, preservedPaths, skippedPaths } = options;
278
- const fallbackSelections = defaultSelections();
279
- const fallbackProfile = resolveInstallProfile(fallbackSelections);
280
- const fallbackCandidates = /* @__PURE__ */ new Map();
281
- const canonicalContentByPath = /* @__PURE__ */ new Map();
282
- for (const asset of getDesiredAssets(fallbackProfile)) {
283
- const record = createManagedPathRecord(targetDir, homeDir, asset.relativePath, "fallback", {
284
- sourceId: asset.sourceId
285
- });
286
- fallbackCandidates.set(record.absolutePath, record);
287
- canonicalContentByPath.set(record.path, asset.content);
288
- }
289
- fallbackCandidates.set(
290
- path.resolve(targetDir, MANIFEST_RELATIVE_PATH),
291
- createManagedPathRecord(targetDir, homeDir, MANIFEST_RELATIVE_PATH, "managed-state", {
292
- sourceId: `state:${MANIFEST_RELATIVE_PATH}`
293
- })
294
- );
295
- const knownSkillRoots = getKnownSkillRoots(targetDir, homeDir);
296
- const existingSkillRoots = knownSkillRoots.filter((root) => existsSync(root.absolutePath));
297
- const scopeRootFetchFailures = /* @__PURE__ */ new Set();
298
- if (existingSkillRoots.some((root) => root.pathScope === "project")) {
299
- const skillRecords = await loadFallbackSkillCandidates({
300
- targetDir,
301
- homeDir,
302
- selections: {
303
- ...fallbackSelections,
304
- skillScope: "project"
305
- }
306
- });
307
- if (skillRecords) {
308
- for (const record of skillRecords) {
309
- fallbackCandidates.set(record.record.absolutePath, record.record);
310
- canonicalContentByPath.set(record.record.path, record.content);
311
- }
312
- } else {
313
- scopeRootFetchFailures.add("project");
314
- }
315
- }
316
- if (existingSkillRoots.some((root) => root.pathScope === "home")) {
317
- const skillRecords = await loadFallbackSkillCandidates({
318
- targetDir,
319
- homeDir,
320
- selections: {
321
- ...fallbackSelections,
322
- skillScope: "global"
323
- }
324
- });
325
- if (skillRecords) {
326
- for (const record of skillRecords) {
327
- fallbackCandidates.set(record.record.absolutePath, record.record);
328
- canonicalContentByPath.set(record.record.path, record.content);
329
- }
330
- } else {
331
- scopeRootFetchFailures.add("home");
332
- }
333
- }
334
- const rootFingerprints = new Set(
335
- INSTRUCTION_KINDS.map(
336
- (instructionKind) => hashText(renderBuildableAsset(instructionKind, fallbackProfile))
337
- )
338
- );
339
- for (const record of sortAuditEntries([...fallbackCandidates.values()])) {
340
- classifyFallbackRecord({
341
- targetDir,
342
- record,
343
- canonicalContentByPath,
344
- rootFingerprints,
345
- removableFiles,
346
- preservedPaths,
347
- skippedPaths
348
- });
349
- }
350
- for (const skillRoot of existingSkillRoots) {
351
- const hasExistingManagedCandidateDescendant = [...fallbackCandidates.values()].some(
352
- (record) => existsSync(record.absolutePath) && isWithinRoot(skillRoot.absolutePath, record.absolutePath)
353
- );
354
- if (scopeRootFetchFailures.has(skillRoot.pathScope) || !hasExistingManagedCandidateDescendant) {
355
- addPreserved(
356
- preservedPaths,
357
- skillRoot,
358
- createReason(
359
- "fallback-ambiguous",
360
- "The harness skill root exists, but fallback mode cannot prove which contents are make-docs-managed."
361
- )
362
- );
363
- }
364
- }
365
- }
366
- function classifyFallbackRecord(options) {
367
- const {
368
- targetDir,
369
- record,
370
- canonicalContentByPath,
371
- rootFingerprints,
372
- removableFiles,
373
- preservedPaths,
374
- skippedPaths
375
- } = options;
376
- if (isInsideProjectBackupRoot(targetDir, record.absolutePath)) {
377
- addSkipped(
378
- skippedPaths,
379
- record,
380
- "excluded",
381
- createReason(
382
- "inside-backup-root",
383
- "Paths inside the project `.backup/` tree are excluded from removal consideration."
384
- )
385
- );
386
- return;
387
- }
388
- if (record.pathScope === "external") {
389
- addSkipped(
390
- skippedPaths,
391
- record,
392
- "excluded",
393
- createReason(
394
- "outside-supported-roots",
395
- "This path is outside both the target directory and the user home directory and cannot be removed in fallback mode."
396
- )
397
- );
398
- return;
399
- }
400
- if (!existsSync(record.absolutePath)) {
401
- addSkipped(
402
- skippedPaths,
403
- record,
404
- "already-absent",
405
- createReason("already-absent", "The candidate path is already absent on disk.")
406
- );
407
- return;
408
- }
409
- if (!statSync(record.absolutePath).isFile()) {
410
- addPreserved(
411
- preservedPaths,
412
- record,
413
- createReason(
414
- "fallback-ambiguous",
415
- "Fallback mode found a non-file at an expected make-docs-managed file path and will preserve it."
416
- )
417
- );
418
- return;
419
- }
420
- const currentContent = readTextFile(record.absolutePath);
421
- const currentHash = hashText(currentContent);
422
- if (record.ownershipSource === "managed-state") {
423
- if (looksLikeMakeDocsManifest(record.absolutePath)) {
424
- addRemovable(
425
- removableFiles,
426
- record,
427
- createReason(
428
- "managed-state-file",
429
- "The make-docs manifest matches the generated manifest shape and is eligible for removal."
430
- ),
431
- currentHash,
432
- void 0
433
- );
434
- } else {
435
- addPreserved(
436
- preservedPaths,
437
- record,
438
- createReason(
439
- "fallback-ambiguous",
440
- "Fallback mode found make-docs state at the expected path, but its contents do not match the generated manifest shape."
441
- )
442
- );
443
- }
444
- return;
445
- }
446
- if (isRootInstructionPath(record.path)) {
447
- if (rootFingerprints.has(currentHash)) {
448
- addRemovable(
449
- removableFiles,
450
- record,
451
- createReason(
452
- "fallback-root-fingerprint-match",
453
- "The root instruction file exactly matches a known make-docs-generated fingerprint."
454
- ),
455
- currentHash,
456
- currentHash
457
- );
458
- } else {
459
- addPreserved(
460
- preservedPaths,
461
- record,
462
- createReason(
463
- "fallback-root-fingerprint-mismatch",
464
- "The root instruction file does not match a known make-docs-generated fingerprint and will be preserved."
465
- )
466
- );
467
- }
468
- return;
469
- }
470
- const expectedContent = canonicalContentByPath.get(record.path);
471
- if (typeof expectedContent === "string" && currentContent === expectedContent) {
472
- addRemovable(
473
- removableFiles,
474
- record,
475
- createReason(
476
- "fallback-canonical-content-match",
477
- "The file exactly matches canonical make-docs content in fallback mode."
478
- ),
479
- currentHash,
480
- hashText(expectedContent)
481
- );
482
- return;
483
- }
484
- addPreserved(
485
- preservedPaths,
486
- record,
487
- createReason(
488
- "fallback-ambiguous",
489
- "Fallback mode cannot prove that this existing path is safe to remove."
490
- )
491
- );
492
- }
493
- function classifyPrunableDirectories(options) {
494
- const { targetDir, homeDir, removableFiles, preservedPaths, skippedPaths } = options;
495
- const removableFileSet = new Set(removableFiles.map((entry) => entry.absolutePath));
496
- const prunableDirectories = /* @__PURE__ */ new Map();
497
- const removableDescendantsByDirectory = /* @__PURE__ */ new Map();
498
- for (const removableFile of removableFiles) {
499
- const boundary = removableFile.pathScope === "project" ? targetDir : removableFile.pathScope === "home" ? homeDir : null;
500
- if (!boundary) {
501
- continue;
502
- }
503
- for (const directoryPath of getCandidateParentDirectories(
504
- removableFile.absolutePath,
505
- boundary,
506
- targetDir
507
- )) {
508
- if (!removableDescendantsByDirectory.has(directoryPath)) {
509
- removableDescendantsByDirectory.set(directoryPath, /* @__PURE__ */ new Set());
510
- }
511
- removableDescendantsByDirectory.get(directoryPath)?.add(removableFile.path);
512
- }
513
- }
514
- const sortedDirectoryCandidates = [...removableDescendantsByDirectory.keys()].sort(
515
- (left, right) => createAuditPathMetadata(targetDir, left, "directory", homeDir).ordering.pruneSortKey.localeCompare(
516
- createAuditPathMetadata(targetDir, right, "directory", homeDir).ordering.pruneSortKey
517
- )
518
- );
519
- for (const directoryPath of sortedDirectoryCandidates) {
520
- if (!existsSync(directoryPath)) {
521
- continue;
522
- }
523
- const metadata = createAuditPathMetadata(targetDir, directoryPath, "directory", homeDir);
524
- const remainingEntries = getRemainingDirectoryEntries(
525
- directoryPath,
526
- removableFileSet,
527
- prunableDirectories
528
- );
529
- if (remainingEntries.length === 0) {
530
- const pruneReason = createReason(
531
- "directory-eligible-for-prune",
532
- "The directory becomes empty after removing audited make-docs-managed descendants."
533
- );
534
- prunableDirectories.set(directoryPath, {
535
- ...metadata,
536
- kind: "directory",
537
- reason: pruneReason.message,
538
- reasonCode: pruneReason.code,
539
- removableDescendantPaths: [...removableDescendantsByDirectory.get(directoryPath) ?? []].sort(),
540
- preservedDescendantPaths: []
541
- });
542
- continue;
543
- }
544
- const preservedDescendantPaths = describeBlockingDescendants(
545
- targetDir,
546
- homeDir,
547
- remainingEntries,
548
- preservedPaths,
549
- skippedPaths
550
- );
551
- addPreserved(
552
- preservedPaths,
553
- metadata,
554
- createReason(
555
- preservedDescendantPaths.length > 0 ? "directory-contains-preserved-descendants" : "directory-contains-unmanaged-descendants",
556
- preservedDescendantPaths.length > 0 ? "The directory still contains preserved descendants after subtracting removable make-docs paths." : "The directory still contains unmanaged descendants after subtracting removable make-docs paths."
557
- ),
558
- preservedDescendantPaths
559
- );
560
- }
561
- return [...prunableDirectories.values()];
562
- }
563
- function getRemainingDirectoryEntries(directoryPath, removableFileSet, prunableDirectories) {
564
- return readdirSync(directoryPath).map((entry) => path.join(directoryPath, entry)).filter((entryPath) => !removableFileSet.has(entryPath) && !prunableDirectories.has(entryPath));
565
- }
566
- function describeBlockingDescendants(targetDir, homeDir, entryPaths, preservedPaths, skippedPaths) {
567
- const described = /* @__PURE__ */ new Set();
568
- for (const entryPath of entryPaths) {
569
- const preserved = findRecordedDescendant(entryPath, preservedPaths);
570
- if (preserved) {
571
- described.add(preserved.path);
572
- continue;
573
- }
574
- const skipped = findRecordedDescendant(entryPath, skippedPaths);
575
- if (skipped) {
576
- described.add(skipped.path);
577
- continue;
578
- }
579
- described.add(
580
- createAuditPathMetadata(targetDir, entryPath, getExistingPathKind(entryPath), homeDir).path
581
- );
582
- }
583
- return [...described].sort();
584
- }
585
- function findRecordedDescendant(rootPath, records) {
586
- for (const record of records.values()) {
587
- if (isWithinRoot(rootPath, record.absolutePath)) {
588
- return record;
589
- }
590
- }
591
- return null;
592
- }
593
- function getCandidateParentDirectories(absoluteFilePath, boundary, targetDir) {
594
- const directories = [];
595
- let current = path.dirname(absoluteFilePath);
596
- const normalizedBoundary = path.resolve(boundary);
597
- while (current !== normalizedBoundary && isWithinRoot(normalizedBoundary, current)) {
598
- if (isInsideProjectBackupRoot(targetDir, current)) {
599
- break;
600
- }
601
- directories.push(current);
602
- current = path.dirname(current);
603
- }
604
- return directories;
605
- }
606
- async function loadCanonicalSkillContentByPath(targetDir, homeDir, selections, shouldLoad) {
607
- if (!shouldLoad) {
608
- return /* @__PURE__ */ new Map();
609
- }
610
- try {
611
- const assets = await getDesiredSkillAssets(selections);
612
- return new Map(
613
- assets.map((asset) => {
614
- const record = createManagedPathRecord(
615
- targetDir,
616
- homeDir,
617
- asset.relativePath,
618
- "manifest-skill-file",
619
- { sourceId: asset.sourceId }
620
- );
621
- return [record.path, asset.content];
622
- })
623
- );
624
- } catch {
625
- return null;
626
- }
627
- }
628
- async function loadFallbackSkillCandidates(options) {
629
- try {
630
- const assets = await getDesiredSkillAssets(options.selections);
631
- return assets.map((asset) => ({
632
- record: createManagedPathRecord(
633
- options.targetDir,
634
- options.homeDir,
635
- asset.relativePath,
636
- "fallback",
637
- { sourceId: asset.sourceId }
638
- ),
639
- content: asset.content
640
- }));
641
- } catch {
642
- return null;
643
- }
644
- }
645
- function getKnownSkillRoots(targetDir, homeDir) {
646
- return HARNESSES.flatMap((harness) => [
647
- createCandidatePathRecord(
648
- targetDir,
649
- homeDir,
650
- path.join(targetDir, HARNESS_SKILL_DIRS[harness]),
651
- "directory",
652
- "fallback"
653
- ),
654
- createCandidatePathRecord(
655
- targetDir,
656
- homeDir,
657
- path.join(homeDir, HARNESS_SKILL_DIRS[harness]),
658
- "directory",
659
- "fallback"
660
- )
661
- ]);
662
- }
663
- function createManagedPathRecord(targetDir, homeDir, auditPath, ownershipSource, options) {
664
- return {
665
- ...createAuditPathMetadata(targetDir, auditPath, "file", homeDir),
666
- ownershipSource,
667
- sourceId: options?.sourceId,
668
- manifestHash: options?.manifestHash
669
- };
670
- }
671
- function createCandidatePathRecord(targetDir, homeDir, auditPath, kind, ownershipSource) {
672
- return {
673
- ...createAuditPathMetadata(targetDir, auditPath, kind, homeDir),
674
- ownershipSource
675
- };
676
- }
677
- function addRemovable(removableFiles, record, reason, currentHash, expectedHash) {
678
- removableFiles.set(record.absolutePath, {
679
- ...record,
680
- kind: "file",
681
- reason: reason.message,
682
- reasonCode: reason.code,
683
- currentHash,
684
- expectedHash
685
- });
686
- }
687
- function addPreserved(preservedPaths, record, reason, preservedDescendantPaths) {
688
- preservedPaths.set(record.absolutePath, {
689
- ...record,
690
- reason: reason.message,
691
- reasonCode: reason.code,
692
- preservedDescendantPaths
693
- });
694
- }
695
- function addSkipped(skippedPaths, record, status, reason) {
696
- skippedPaths.set(record.absolutePath, {
697
- ...record,
698
- reason: reason.message,
699
- reasonCode: reason.code,
700
- status
701
- });
702
- }
703
- function createReason(code, message) {
704
- return { code, message };
705
- }
706
- function isRootInstructionPath(auditPath) {
707
- return ROOT_INSTRUCTION_SET.has(auditPath);
708
- }
709
- function isInsideProjectBackupRoot(targetDir, absolutePath) {
710
- return isWithinRoot(path.join(targetDir, PROJECT_BACKUP_DIRNAME), absolutePath);
711
- }
712
- function isWithinRoot(rootPath, candidatePath) {
713
- const relative = path.relative(path.resolve(rootPath), path.resolve(candidatePath));
714
- return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
715
- }
716
- function getExistingPathKind(absolutePath) {
717
- return statSync(absolutePath).isDirectory() ? "directory" : "file";
718
- }
719
- function looksLikeMakeDocsManifest(filePath) {
720
- try {
721
- const raw = JSON.parse(readTextFile(filePath));
722
- return typeof raw.schemaVersion === "number" && typeof raw.packageName === "string" && typeof raw.packageVersion === "string" && typeof raw.profileId === "string" && typeof raw.updatedAt === "string" && typeof raw.selections === "object" && raw.selections !== null && typeof raw.files === "object" && raw.files !== null;
723
- } catch {
724
- return false;
725
- }
726
- }
727
- function sortAuditEntries(entries) {
728
- return [...entries].sort(
729
- (left, right) => left.ordering.sortKey.localeCompare(right.ordering.sortKey)
730
- );
731
- }
732
- function sortPrunableDirectories(entries) {
733
- return [...entries].sort(
734
- (left, right) => left.ordering.pruneSortKey.localeCompare(right.ordering.pruneSortKey)
735
- );
736
- }
737
-
738
- // src/lifecycle-ui.ts
739
- import { stdin as input, stdout as output } from "process";
740
- var lifecycleRenderer = createClackLifecycleRenderer();
741
- function createClackLifecycleRenderer() {
742
- return {
743
- beginWorkflow(title) {
744
- Wt(title);
745
- },
746
- renderBackupAuditSummary(options) {
747
- renderAuditNote({
748
- title: "make-docs backup",
749
- lines: buildBackupAuditSummaryLines(options),
750
- groups: [
751
- formatEntryGroup(
752
- "Files to copy",
753
- options.copyableFiles,
754
- (entry) => `${formatPath(entry)} (${entry.reason})`
755
- ),
756
- formatEntryGroup(
757
- "Directories to materialize",
758
- options.materializableDirectories
759
- ),
760
- formatEntryGroup(
761
- "Retained paths",
762
- options.auditReport.preservedPaths,
763
- (entry) => `${formatPath(entry)} (${entry.reason})`
764
- ),
765
- formatEntryGroup(
766
- "Skipped paths",
767
- options.auditReport.skippedPaths,
768
- (entry) => `${formatPath(entry)} (${entry.reason})`
769
- )
770
- ]
771
- });
772
- },
773
- confirmBackupRun(permissions) {
774
- return confirmLifecycleCheckpoint({
775
- permissions,
776
- message: "Create this backup?",
777
- ttyError: "Backup confirmation requires a TTY. Re-run with `make-docs backup --yes`."
778
- });
779
- },
780
- renderBackupNoopSummary() {
781
- Gt(
782
- "No make-docs-managed files required backup. No backup destination was created."
783
- );
784
- },
785
- renderBackupCancelled() {
786
- Gt("Backup cancelled.");
787
- },
788
- renderBackupCompletionSummary(result) {
789
- if (result.status !== "completed" || !result.destinationDir) {
790
- return;
791
- }
792
- Vt(
793
- [
794
- `Destination: ${result.destinationDir}`,
795
- `Copied files: ${result.copiedFiles.length}`,
796
- `Materialized directories: ${result.materializedDirectories.length}`,
797
- `Retained paths surfaced: ${result.auditReport.preservedPaths.length}`,
798
- `Skipped paths surfaced: ${result.auditReport.skippedPaths.length}`
799
- ].join("\n"),
800
- "Backup complete"
801
- );
802
- },
803
- renderUninstallWarning(options) {
804
- const lines = ["This command removes audited make-docs-managed paths", ""];
805
- if (options.backupDestinationDir) {
806
- lines.push("A backup will be created before removal begins.");
807
- lines.push(`Backup destination: ${options.backupDestinationDir}`);
808
- } else {
809
- lines.push("Safer alternative: make-docs backup");
810
- lines.push("Safer destructive flow: make-docs uninstall --backup");
811
- }
812
- Vt(lines.join("\n"), "WARNING");
813
- },
814
- confirmUninstallWarning(permissions) {
815
- return confirmLifecycleCheckpoint({
816
- permissions,
817
- message: "Continue with uninstall review?",
818
- ttyError: "Uninstall confirmation requires a TTY. Re-run with `make-docs uninstall --yes`."
819
- });
820
- },
821
- renderUninstallAuditSummary(options) {
822
- renderAuditNote({
823
- title: "make-docs uninstall",
824
- lines: buildUninstallAuditSummaryLines(options),
825
- groups: [
826
- formatEntryGroup(
827
- "Files to remove",
828
- options.auditReport.removableFiles,
829
- (entry) => `${formatPath(entry)} (${entry.reason})`
830
- ),
831
- formatEntryGroup(
832
- "Directories to prune",
833
- options.auditReport.prunableDirectories,
834
- (entry) => `${formatPath(entry)} (${entry.reason})`
835
- ),
836
- formatEntryGroup(
837
- "Preserved paths",
838
- options.auditReport.preservedPaths,
839
- (entry) => `${formatPath(entry)} (${entry.reason})`
840
- ),
841
- formatEntryGroup(
842
- "Skipped paths",
843
- options.auditReport.skippedPaths,
844
- (entry) => `${formatPath(entry)} (${entry.reason})`
845
- )
846
- ]
847
- });
848
- },
849
- confirmUninstallRun(options) {
850
- const message = options.backupRequested ? "Create the backup and then remove these audited paths? This action cannot be undone." : "Remove these audited paths? This action cannot be undone.";
851
- return confirmLifecycleCheckpoint({
852
- permissions: options.permissions,
853
- message,
854
- ttyError: "Uninstall confirmation requires a TTY. Re-run with `make-docs uninstall --yes`."
855
- });
856
- },
857
- renderUninstallCancelled() {
858
- Gt("Uninstall cancelled. No files were changed.");
859
- },
860
- renderUninstallCompletionSummary(options) {
861
- Vt(
862
- [
863
- `Files removed: ${options.removedFiles.length}`,
864
- `Directories pruned: ${options.prunedDirectories.length}`,
865
- `Preserved paths: ${options.auditReport.preservedPaths.length}`,
866
- `Skipped paths: ${options.auditReport.skippedPaths.length}`,
867
- `Backup: ${formatBackupStatus(options.backupResult)}`
868
- ].join("\n"),
869
- "Uninstall complete"
870
- );
871
- },
872
- renderUninstallFailureSummary(options) {
873
- Vt(
874
- [
875
- `Files removed before failure: ${options.removedFiles.length}`,
876
- `Directories pruned before failure: ${options.prunedDirectories.length}`,
877
- `Preserved paths: ${options.auditReport.preservedPaths.length}`,
878
- `Skipped paths: ${options.auditReport.skippedPaths.length}`,
879
- `Backup: ${formatBackupStatus(options.backupResult)}`,
880
- `Error: ${options.errorMessage}`
881
- ].join("\n"),
882
- "Uninstall partially completed"
883
- );
884
- }
885
- };
886
- }
887
- function getLifecycleRenderer() {
888
- return lifecycleRenderer;
889
- }
890
- function buildBackupAuditSummaryLines(options) {
891
- const { auditReport, destinationDir } = options;
892
- return [
893
- `Target: ${auditReport.targetDir}`,
894
- `Destination: ${destinationDir ?? "(no backup directory will be created)"}`,
895
- `Files to copy: ${options.copyableFiles.length}`,
896
- `Directories to materialize: ${options.materializableDirectories.length}`,
897
- `Retained: ${auditReport.preservedPaths.length}`,
898
- `Skipped: ${auditReport.skippedPaths.length}`
899
- ];
900
- }
901
- function buildUninstallAuditSummaryLines(options) {
902
- const { auditReport, backupDestinationDir } = options;
903
- return [
904
- `Target: ${auditReport.targetDir}`,
905
- `Backup before removal: ${backupDestinationDir ?? "not requested"}`,
906
- `Files to remove: ${auditReport.removableFiles.length}`,
907
- `Directories to prune: ${auditReport.prunableDirectories.length}`,
908
- `Preserved: ${auditReport.preservedPaths.length}`,
909
- `Skipped: ${auditReport.skippedPaths.length}`
910
- ];
911
- }
912
- function renderAuditNote(options) {
913
- Vt(
914
- [...options.lines, "", ...formatEntryGroups(options.groups)].join("\n"),
915
- options.title
916
- );
917
- }
918
- function formatEntryGroups(groups) {
919
- return groups.flatMap(
920
- (group, index) => index === 0 ? group : ["", ...group]
921
- );
922
- }
923
- function formatEntryGroup(title, entries, formatter = formatPath) {
924
- if (entries.length === 0) {
925
- return [`${title}:`, "- none"];
926
- }
927
- return [`${title}:`, ...entries.map((entry) => `- ${formatter(entry)}`)];
928
- }
929
- function formatPath(entry) {
930
- return entry.path;
931
- }
932
- function formatBackupStatus(result) {
933
- if (!result) {
934
- return "not requested";
935
- }
936
- if (result.status === "completed" && result.destinationDir) {
937
- return `created at ${result.destinationDir}`;
938
- }
939
- if (result.status === "noop") {
940
- return "requested, but no backup files or directories needed to be created";
941
- }
942
- return "requested";
943
- }
944
- async function confirmLifecycleCheckpoint(options) {
945
- if (options.permissions === "allow-all") {
946
- return true;
947
- }
948
- if (!input.isTTY || !output.isTTY) {
949
- throw new Error(options.ttyError);
950
- }
951
- const proceed = await Rt({
952
- message: options.message,
953
- initialValue: true,
954
- active: "Yes",
955
- inactive: "No",
956
- withGuide: true
957
- });
958
- return !(Ct(proceed) || !proceed);
959
- }
960
-
961
- // src/backup.ts
962
- import {
963
- copyFileSync,
964
- existsSync as existsSync2,
965
- mkdirSync,
966
- readdirSync as readdirSync2,
967
- renameSync
968
- } from "fs";
969
- import os2 from "os";
970
- import path2 from "path";
971
- var PROJECT_BACKUP_DIRNAME2 = ".backup";
972
- async function runBackupCommand(options) {
973
- const renderer = getLifecycleRenderer();
974
- renderer.beginWorkflow("make-docs backup");
975
- const preparedBackup = await prepareBackupExecution(options);
976
- renderer.renderBackupAuditSummary({
977
- auditReport: preparedBackup.auditReport,
978
- destinationDir: preparedBackup.destinationPlan?.destinationDir ?? null,
979
- copyableFiles: preparedBackup.copyableFiles,
980
- materializableDirectories: preparedBackup.materializableDirectories
981
- });
982
- if (!hasBackupWork(preparedBackup)) {
983
- renderer.renderBackupNoopSummary();
984
- return createNoopBackupResult(preparedBackup);
985
- }
986
- const shouldProceed = await renderer.confirmBackupRun(options.permissions);
987
- if (!shouldProceed) {
988
- renderer.renderBackupCancelled();
989
- return {
990
- status: "cancelled",
991
- targetDir: preparedBackup.targetDir,
992
- destinationDir: preparedBackup.destinationPlan.destinationDir,
993
- auditReport: preparedBackup.auditReport,
994
- copiedFiles: [],
995
- materializedDirectories: []
996
- };
997
- }
998
- const result = executePreparedBackup(preparedBackup);
999
- renderer.renderBackupCompletionSummary(result);
1000
- return result;
1001
- }
1002
- async function prepareBackupExecution(options) {
1003
- const targetDir = path2.resolve(options.targetDir);
1004
- const homeDir = path2.resolve(options.homeDir ?? os2.homedir());
1005
- const auditReport = options.auditReport ?? await createAuditReport({
1006
- targetDir,
1007
- manifest: loadManifest(targetDir),
1008
- homeDir
1009
- });
1010
- const copyableFiles = auditReport.removableFiles.filter(hasBackupRelativePath);
1011
- const materializableDirectories = auditReport.prunableDirectories.filter(
1012
- hasBackupRelativePath
1013
- );
1014
- const hasCopyableEntries = copyableFiles.length > 0 || materializableDirectories.length > 0;
1015
- const hasProvidedDestinationPlan = Object.hasOwn(options, "destinationPlan");
1016
- const destinationPlan = hasCopyableEntries ? hasProvidedDestinationPlan ? options.destinationPlan ?? null : resolveBackupDestinationPlan(targetDir, options.now ?? /* @__PURE__ */ new Date()) : null;
1017
- if (hasCopyableEntries && !destinationPlan) {
1018
- throw new Error(
1019
- "Backup destination plan is required when audited entries are copyable."
1020
- );
1021
- }
1022
- return {
1023
- targetDir,
1024
- auditReport,
1025
- destinationPlan,
1026
- copyableFiles,
1027
- materializableDirectories
1028
- };
1029
- }
1030
- function executePreparedBackup(preparedBackup) {
1031
- if (!hasBackupWork(preparedBackup)) {
1032
- return createNoopBackupResult(preparedBackup);
1033
- }
1034
- if (!preparedBackup.destinationPlan) {
1035
- throw new Error(
1036
- "Backup destination plan is required before copying audited backup entries."
1037
- );
1038
- }
1039
- ensureBackupDestination(preparedBackup.destinationPlan);
1040
- const copiedFiles = copyAuditedFiles(
1041
- preparedBackup.copyableFiles,
1042
- preparedBackup.destinationPlan.destinationDir
1043
- );
1044
- const materializedDirectories = materializePrunableDirectories(
1045
- preparedBackup.materializableDirectories,
1046
- preparedBackup.destinationPlan.destinationDir
1047
- );
1048
- return {
1049
- status: "completed",
1050
- targetDir: preparedBackup.targetDir,
1051
- destinationDir: preparedBackup.destinationPlan.destinationDir,
1052
- auditReport: preparedBackup.auditReport,
1053
- copiedFiles,
1054
- materializedDirectories
1055
- };
1056
- }
1057
- function resolveBackupDestinationPlan(targetDir, now) {
1058
- const backupRoot = path2.join(targetDir, PROJECT_BACKUP_DIRNAME2);
1059
- const dateStamp = formatDateStamp(now);
1060
- const plainDirectory = path2.join(backupRoot, dateStamp);
1061
- const existingOrdinals = collectExistingOrdinals(backupRoot, dateStamp);
1062
- const hasPlainDirectory = existsSync2(plainDirectory);
1063
- if (!hasPlainDirectory && existingOrdinals.length === 0) {
1064
- return {
1065
- backupRoot,
1066
- dateStamp,
1067
- directoryName: dateStamp,
1068
- destinationDir: plainDirectory
1069
- };
1070
- }
1071
- const usedOrdinals = new Set(existingOrdinals);
1072
- let promotion;
1073
- if (hasPlainDirectory) {
1074
- const promotionOrdinal = findLowestAvailableOrdinal(usedOrdinals);
1075
- const promotedName = `${dateStamp}-${formatOrdinal(promotionOrdinal)}`;
1076
- promotion = {
1077
- from: plainDirectory,
1078
- to: path2.join(backupRoot, promotedName)
1079
- };
1080
- usedOrdinals.add(promotionOrdinal);
1081
- }
1082
- const nextOrdinal = Math.max(...usedOrdinals, 0) + 1;
1083
- const directoryName = `${dateStamp}-${formatOrdinal(nextOrdinal)}`;
1084
- return {
1085
- backupRoot,
1086
- dateStamp,
1087
- directoryName,
1088
- destinationDir: path2.join(backupRoot, directoryName),
1089
- promotion
1090
- };
1091
- }
1092
- function collectExistingOrdinals(backupRoot, dateStamp) {
1093
- if (!existsSync2(backupRoot)) {
1094
- return [];
1095
- }
1096
- const pattern = new RegExp(`^${escapeRegExp(dateStamp)}-(\\d+)$`);
1097
- return readdirSync2(backupRoot).map((entryName) => {
1098
- const match = pattern.exec(entryName);
1099
- if (!match) {
1100
- return null;
1101
- }
1102
- return Number.parseInt(match[1] ?? "", 10);
1103
- }).filter((value) => Number.isInteger(value)).sort((left, right) => left - right);
1104
- }
1105
- function findLowestAvailableOrdinal(usedOrdinals) {
1106
- let ordinal = 1;
1107
- while (usedOrdinals.has(ordinal)) {
1108
- ordinal += 1;
1109
- }
1110
- return ordinal;
1111
- }
1112
- function ensureBackupDestination(plan) {
1113
- mkdirSync(plan.backupRoot, { recursive: true });
1114
- if (plan.promotion) {
1115
- if (existsSync2(plan.promotion.to)) {
1116
- throw new Error(
1117
- `Cannot promote existing backup to ${plan.promotion.to} because that destination already exists.`
1118
- );
1119
- }
1120
- renameSync(plan.promotion.from, plan.promotion.to);
1121
- }
1122
- if (existsSync2(plan.destinationDir)) {
1123
- throw new Error(
1124
- `Backup destination already exists: ${plan.destinationDir}. Re-run the command to resolve a fresh destination.`
1125
- );
1126
- }
1127
- mkdirSync(plan.destinationDir, { recursive: true });
1128
- }
1129
- function copyAuditedFiles(removableFiles, destinationDir) {
1130
- const copiedFiles = [];
1131
- for (const removableFile of removableFiles) {
1132
- if (!removableFile.backupRelativePath) {
1133
- continue;
1134
- }
1135
- const destinationPath = path2.join(
1136
- destinationDir,
1137
- removableFile.backupRelativePath
1138
- );
1139
- ensureParentDir(destinationPath);
1140
- copyFileSync(removableFile.absolutePath, destinationPath);
1141
- copiedFiles.push(removableFile.backupRelativePath);
1142
- }
1143
- return copiedFiles;
1144
- }
1145
- function materializePrunableDirectories(prunableDirectories, destinationDir) {
1146
- const materializedDirectories = /* @__PURE__ */ new Set();
1147
- for (const directory of prunableDirectories) {
1148
- const relativePath = directory.backupRelativePath;
1149
- if (!relativePath || relativePath === ".") {
1150
- continue;
1151
- }
1152
- mkdirSync(path2.join(destinationDir, relativePath), { recursive: true });
1153
- materializedDirectories.add(relativePath);
1154
- }
1155
- return [...materializedDirectories].sort();
1156
- }
1157
- function hasBackupRelativePath(entry) {
1158
- return typeof entry.backupRelativePath === "string";
1159
- }
1160
- function hasBackupWork(preparedBackup) {
1161
- return preparedBackup.copyableFiles.length > 0 || preparedBackup.materializableDirectories.length > 0;
1162
- }
1163
- function createNoopBackupResult(preparedBackup) {
1164
- return {
1165
- status: "noop",
1166
- targetDir: preparedBackup.targetDir,
1167
- destinationDir: null,
1168
- auditReport: preparedBackup.auditReport,
1169
- copiedFiles: [],
1170
- materializedDirectories: []
1171
- };
1172
- }
1173
- function formatDateStamp(now) {
1174
- const year = now.getFullYear();
1175
- const month = String(now.getMonth() + 1).padStart(2, "0");
1176
- const day = String(now.getDate()).padStart(2, "0");
1177
- return `${year}-${month}-${day}`;
1178
- }
1179
- function formatOrdinal(ordinal) {
1180
- return String(ordinal).padStart(2, "0");
1181
- }
1182
- function escapeRegExp(value) {
1183
- return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
1184
- }
1185
-
1186
- export {
1187
- createAuditReport,
1188
- getLifecycleRenderer,
1189
- runBackupCommand,
1190
- prepareBackupExecution,
1191
- executePreparedBackup,
1192
- resolveBackupDestinationPlan
1193
- };
1194
- //# sourceMappingURL=chunk-QRFH4J6H.js.map