prizmkit 1.1.190 → 1.1.192

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 (189) hide show
  1. package/bin/create-prizmkit.js +4 -4
  2. package/bundled/VERSION.json +3 -3
  3. package/bundled/adapters/antigravity/assets/prizmkit-hook.cjs +150 -0
  4. package/bundled/adapters/antigravity/hooks-adapter.js +195 -0
  5. package/bundled/adapters/antigravity/paths.js +14 -0
  6. package/bundled/adapters/antigravity/rules-adapter.js +54 -0
  7. package/bundled/adapters/antigravity/skill-adapter.js +38 -0
  8. package/bundled/adapters/codex/skill-adapter.js +28 -8
  9. package/bundled/adapters/cursor/skill-adapter.js +13 -4
  10. package/bundled/adapters/pi/skill-adapter.js +28 -7
  11. package/bundled/dev-pipeline/.env.example +4 -12
  12. package/bundled/dev-pipeline/README.md +21 -15
  13. package/bundled/dev-pipeline/assets/skill-subagent-integration.md +3 -6
  14. package/bundled/dev-pipeline/prizmkit_runtime/atomic_io.py +48 -0
  15. package/bundled/dev-pipeline/prizmkit_runtime/checkpoint_state.py +66 -23
  16. package/bundled/dev-pipeline/prizmkit_runtime/cli.py +10 -7
  17. package/bundled/dev-pipeline/prizmkit_runtime/commands.py +2 -21
  18. package/bundled/dev-pipeline/prizmkit_runtime/config.py +29 -70
  19. package/bundled/dev-pipeline/prizmkit_runtime/daemon.py +125 -67
  20. package/bundled/dev-pipeline/prizmkit_runtime/gitops.py +89 -442
  21. package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py +93 -49
  22. package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py +1 -3
  23. package/bundled/dev-pipeline/prizmkit_runtime/paths.py +0 -6
  24. package/bundled/dev-pipeline/prizmkit_runtime/platform_detection.py +49 -18
  25. package/bundled/dev-pipeline/prizmkit_runtime/processes.py +206 -151
  26. package/bundled/dev-pipeline/prizmkit_runtime/reset.py +2 -23
  27. package/bundled/dev-pipeline/prizmkit_runtime/reset_preserve.py +15 -134
  28. package/bundled/dev-pipeline/prizmkit_runtime/results.py +25 -0
  29. package/bundled/dev-pipeline/prizmkit_runtime/runner_bookkeeping.py +68 -83
  30. package/bundled/dev-pipeline/prizmkit_runtime/runner_classification.py +15 -5
  31. package/bundled/dev-pipeline/prizmkit_runtime/runner_models.py +1 -29
  32. package/bundled/dev-pipeline/prizmkit_runtime/runner_prompts.py +0 -2
  33. package/bundled/dev-pipeline/prizmkit_runtime/runner_status.py +7 -2
  34. package/bundled/dev-pipeline/prizmkit_runtime/runners.py +282 -217
  35. package/bundled/dev-pipeline/prizmkit_runtime/runtime_commit.py +124 -122
  36. package/bundled/dev-pipeline/prizmkit_runtime/runtime_helper.py +90 -9
  37. package/bundled/dev-pipeline/prizmkit_runtime/sessions.py +369 -154
  38. package/bundled/dev-pipeline/prizmkit_runtime/status.py +3 -3
  39. package/bundled/dev-pipeline/prizmkit_runtime/stream_progress.py +2780 -0
  40. package/bundled/dev-pipeline/prizmkit_runtime/task_checkout.py +27 -101
  41. package/bundled/dev-pipeline/prizmkit_runtime/test_result.py +58 -4
  42. package/bundled/dev-pipeline/scripts/check-session-status.py +43 -19
  43. package/bundled/dev-pipeline/scripts/continuation.py +6 -4
  44. package/bundled/dev-pipeline/scripts/detect-stuck.py +28 -28
  45. package/bundled/dev-pipeline/scripts/generate-bootstrap-prompt.py +7 -2
  46. package/bundled/dev-pipeline/scripts/generate-bugfix-prompt.py +7 -2
  47. package/bundled/dev-pipeline/scripts/init-bugfix-pipeline.py +10 -7
  48. package/bundled/dev-pipeline/scripts/init-change-artifact.py +8 -2
  49. package/bundled/dev-pipeline/scripts/init-pipeline.py +14 -69
  50. package/bundled/dev-pipeline/scripts/parse-stream-progress.py +31 -2328
  51. package/bundled/dev-pipeline/scripts/patch-completion-notes.py +4 -24
  52. package/bundled/dev-pipeline/scripts/prompt_framework.py +56 -9
  53. package/bundled/dev-pipeline/scripts/status_common.py +591 -0
  54. package/bundled/dev-pipeline/scripts/update-bug-status.py +85 -463
  55. package/bundled/dev-pipeline/scripts/update-checkpoint.py +227 -65
  56. package/bundled/dev-pipeline/scripts/update-feature-status.py +76 -509
  57. package/bundled/dev-pipeline/scripts/utils.py +10 -15
  58. package/bundled/dev-pipeline/templates/bootstrap-tier3.md +4 -4
  59. package/bundled/dev-pipeline/templates/bug-fix-list-schema.json +7 -0
  60. package/bundled/dev-pipeline/templates/bugfix-bootstrap-prompt.md +1 -1
  61. package/bundled/dev-pipeline/templates/sections/artifact-manifest.md +1 -1
  62. package/bundled/dev-pipeline/templates/sections/bugfix-phase-manual-verification.md +1 -1
  63. package/bundled/dev-pipeline/templates/sections/bugfix-phase-review.md +1 -1
  64. package/bundled/dev-pipeline/templates/sections/bugfix-phase-test.md +2 -1
  65. package/bundled/dev-pipeline/templates/sections/checkpoint-system.md +1 -1
  66. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-auto.md +1 -1
  67. package/bundled/dev-pipeline/templates/sections/phase-browser-verification-opencli.md +2 -2
  68. package/bundled/dev-pipeline/templates/sections/phase-browser-verification.md +2 -2
  69. package/bundled/dev-pipeline/templates/sections/phase-prizmkit-test.md +2 -1
  70. package/bundled/dev-pipeline/templates/sections/phase-review-full.md +1 -1
  71. package/bundled/dev-pipeline/templates/sections/phase-specify-plan-full.md +3 -6
  72. package/bundled/dev-pipeline/templates/session-status-schema.json +2 -5
  73. package/bundled/dev-pipeline/tests/_helpers.py +418 -0
  74. package/bundled/dev-pipeline/tests/conftest.py +45 -1
  75. package/bundled/dev-pipeline/tests/live_ai_cli_log_smoke.py +1 -0
  76. package/bundled/dev-pipeline/tests/test_auto_skip.py +4 -69
  77. package/bundled/dev-pipeline/tests/test_checkpoint_state.py +126 -1
  78. package/bundled/dev-pipeline/tests/test_daemon_and_scripts.py +257 -0
  79. package/bundled/dev-pipeline/tests/test_e2e_pipeline_run.py +500 -0
  80. package/bundled/dev-pipeline/tests/test_generate_bootstrap_prompt.py +59 -117
  81. package/bundled/dev-pipeline/tests/test_generate_bugfix_prompt.py +12 -10
  82. package/bundled/dev-pipeline/tests/test_python_runner_parity.py +561 -3094
  83. package/bundled/dev-pipeline/tests/test_recovery_workflow.py +7 -8
  84. package/bundled/dev-pipeline/tests/test_repository_bootstrap.py +0 -1
  85. package/bundled/dev-pipeline/tests/test_reset_modes.py +15 -27
  86. package/bundled/dev-pipeline/tests/test_reset_preserve.py +54 -139
  87. package/bundled/dev-pipeline/tests/test_runner_bookkeeping.py +766 -0
  88. package/bundled/dev-pipeline/tests/test_runner_lifecycle.py +1257 -0
  89. package/bundled/dev-pipeline/tests/test_runtime_helper.py +97 -20
  90. package/bundled/dev-pipeline/tests/test_session_launch.py +1101 -0
  91. package/bundled/dev-pipeline/tests/test_stream_progress.py +585 -0
  92. package/bundled/dev-pipeline/tests/test_unified_cli.py +490 -2006
  93. package/bundled/dev-pipeline/tests/test_utils.py +3 -3
  94. package/bundled/rules/USAGE.md +1 -0
  95. package/bundled/skills/_metadata.json +9 -63
  96. package/bundled/skills/app-planner/SKILL.md +32 -303
  97. package/bundled/skills/app-planner/references/app-design-guide.md +0 -4
  98. package/bundled/skills/app-planner/references/generated-plan-review.md +2 -1
  99. package/bundled/skills/app-planner/references/project-brief-guide.md +14 -0
  100. package/bundled/skills/app-planner/references/project-conventions-discovery.md +4 -6
  101. package/bundled/skills/app-planner/references/project-state-detection.md +2 -3
  102. package/bundled/skills/bug-fix-workflow/SKILL.md +1 -2
  103. package/bundled/skills/bug-fix-workflow/references/bug-diagnosis.md +4 -7
  104. package/bundled/skills/bug-planner/SKILL.md +54 -435
  105. package/bundled/skills/bug-planner/references/generated-plan-review.md +3 -2
  106. package/bundled/skills/bug-planner/references/input-formats.md +32 -0
  107. package/bundled/skills/bugfix-pipeline-launcher/SKILL.md +4 -6
  108. package/bundled/skills/bugfix-pipeline-launcher/references/configuration.md +4 -28
  109. package/bundled/skills/feature-pipeline-launcher/SKILL.md +4 -6
  110. package/bundled/skills/feature-pipeline-launcher/references/configuration.md +4 -28
  111. package/bundled/skills/feature-planner/SKILL.md +60 -439
  112. package/bundled/skills/feature-planner/assets/planning-guide.md +1 -1
  113. package/bundled/skills/feature-planner/references/completeness-review.md +34 -0
  114. package/bundled/skills/feature-planner/references/decomposition-patterns.md +2 -2
  115. package/bundled/skills/feature-planner/references/error-recovery.md +1 -1
  116. package/bundled/skills/feature-planner/references/generated-plan-review.md +3 -2
  117. package/bundled/skills/feature-planner/references/incremental-feature-planning.md +3 -1
  118. package/bundled/skills/feature-workflow/SKILL.md +1 -2
  119. package/bundled/skills/prizmkit/SKILL.md +7 -1
  120. package/bundled/skills/prizmkit-code-review/SKILL.md +14 -6
  121. package/bundled/skills/prizmkit-code-review/references/independent-code-review.md +7 -4
  122. package/bundled/skills/prizmkit-code-review/references/review-report-template.md +16 -0
  123. package/bundled/skills/prizmkit-code-review/scripts/render_review_report.py +58 -20
  124. package/bundled/skills/prizmkit-implement/SKILL.md +1 -1
  125. package/bundled/skills/prizmkit-init/SKILL.md +25 -128
  126. package/bundled/skills/prizmkit-init/assets/project-brief-template.md +3 -3
  127. package/bundled/skills/prizmkit-init/references/config-schema.md +2 -2
  128. package/bundled/skills/prizmkit-plan/SKILL.md +6 -8
  129. package/bundled/skills/prizmkit-plan/references/clarify-guide.md +1 -1
  130. package/bundled/skills/prizmkit-plan/references/independent-plan-review.md +5 -2
  131. package/bundled/skills/prizmkit-plan/references/review-plan-spec-loop.md +6 -5
  132. package/bundled/skills/prizmkit-prizm-docs/SKILL.md +1 -13
  133. package/bundled/skills/prizmkit-prizm-docs/assets/prizm-docs-format.md +1 -1
  134. package/bundled/skills/prizmkit-prizm-docs/references/op-init.md +1 -1
  135. package/bundled/skills/prizmkit-prizm-docs/references/op-update.md +1 -1
  136. package/bundled/skills/prizmkit-retrospective/SKILL.md +6 -4
  137. package/bundled/skills/prizmkit-test/SKILL.md +25 -133
  138. package/bundled/skills/prizmkit-test/references/independent-test-review.md +5 -2
  139. package/bundled/skills/prizmkit-test/references/test-coverage-model.md +6 -0
  140. package/bundled/skills/prizmkit-workflow/SKILL.md +2 -3
  141. package/bundled/skills/prizmkit-workflow/references/workflow-state-protocol.md +4 -3
  142. package/bundled/skills/recovery-workflow/SKILL.md +7 -7
  143. package/bundled/skills/recovery-workflow/evals/evals.json +1 -1
  144. package/bundled/skills/recovery-workflow/references/detection.md +1 -3
  145. package/bundled/skills/recovery-workflow/scripts/detect-recovery-state.py +0 -6
  146. package/bundled/templates/project-memory-template.md +1 -2
  147. package/package.json +1 -1
  148. package/src/ai-cli-launch.js +1 -1
  149. package/src/clean.js +40 -4
  150. package/src/config.js +64 -4
  151. package/src/detect-platform.js +10 -6
  152. package/src/external-skills.js +2 -2
  153. package/src/index.js +1 -0
  154. package/src/manifest.js +1 -1
  155. package/src/platforms.js +6 -2
  156. package/src/prompts.js +11 -3
  157. package/src/scaffold.js +87 -11
  158. package/src/upgrade.js +9 -3
  159. package/bundled/dev-pipeline/SCHEMA_ANALYSIS.md +0 -53
  160. package/bundled/dev-pipeline/scripts/generate-refactor-prompt.py +0 -649
  161. package/bundled/dev-pipeline/scripts/init-refactor-pipeline.py +0 -463
  162. package/bundled/dev-pipeline/scripts/update-refactor-status.py +0 -1512
  163. package/bundled/dev-pipeline/templates/refactor-bootstrap-prompt.md +0 -240
  164. package/bundled/dev-pipeline/templates/refactor-list-schema.json +0 -266
  165. package/bundled/dev-pipeline/templates/sections/refactor-critical-paths.md +0 -15
  166. package/bundled/dev-pipeline/templates/sections/refactor-mission.md +0 -9
  167. package/bundled/dev-pipeline/templates/sections/refactor-phase-commit-report.md +0 -24
  168. package/bundled/dev-pipeline/templates/sections/refactor-phase-implement.md +0 -16
  169. package/bundled/dev-pipeline/templates/sections/refactor-phase-init.md +0 -9
  170. package/bundled/dev-pipeline/templates/sections/refactor-phase-plan.md +0 -22
  171. package/bundled/dev-pipeline/templates/sections/refactor-phase-review.md +0 -19
  172. package/bundled/dev-pipeline/templates/sections/refactor-phase-test.md +0 -24
  173. package/bundled/dev-pipeline/templates/sections/refactor-reminders.md +0 -12
  174. package/bundled/dev-pipeline/templates/sections/refactor-session-context.md +0 -6
  175. package/bundled/dev-pipeline/templates/sections/refactor-task-contract.md +0 -52
  176. package/bundled/dev-pipeline/tests/test_generate_refactor_prompt.py +0 -478
  177. package/bundled/skills/feature-planner/assets/evaluation-guide.md +0 -44
  178. package/bundled/skills/refactor-pipeline-launcher/SKILL.md +0 -219
  179. package/bundled/skills/refactor-pipeline-launcher/references/configuration.md +0 -78
  180. package/bundled/skills/refactor-planner/SKILL.md +0 -467
  181. package/bundled/skills/refactor-planner/assets/planning-guide.md +0 -291
  182. package/bundled/skills/refactor-planner/references/behavior-preservation.md +0 -187
  183. package/bundled/skills/refactor-planner/references/error-recovery.md +0 -45
  184. package/bundled/skills/refactor-planner/references/fast-path.md +0 -59
  185. package/bundled/skills/refactor-planner/references/generated-plan-review.md +0 -107
  186. package/bundled/skills/refactor-planner/references/planning-phases.md +0 -172
  187. package/bundled/skills/refactor-planner/references/refactor-scoping-guide.md +0 -230
  188. package/bundled/skills/refactor-planner/scripts/validate-and-generate-refactor.py +0 -1120
  189. package/bundled/skills/refactor-workflow/SKILL.md +0 -205
@@ -1,1120 +0,0 @@
1
- #!/usr/bin/env python3
2
- """
3
- validate-and-generate-refactor.py - Validate and generate refactor-list.json files
4
- for the dev-pipeline system.
5
-
6
- Commands:
7
- validate Validate an existing .prizmkit/plans/refactor-list.json
8
- template Generate a blank template .prizmkit/plans/refactor-list.json
9
- context Print bounded project context plus the five most recent refactors
10
- show Print one explicitly requested refactor
11
- append Merge an additions-only draft into an existing validated list
12
- generate Validate a draft JSON and generate final refactor-list.json with defaults
13
- summary Print a summary table of refactors from a .prizmkit/plans/refactor-list.json
14
-
15
- Usage:
16
- python3 validate-and-generate-refactor.py validate --input .prizmkit/plans/refactor-list.json [--output validated.json]
17
- python3 validate-and-generate-refactor.py template --output .prizmkit/plans/refactor-list.json
18
- python3 validate-and-generate-refactor.py context --input .prizmkit/plans/refactor-list.json
19
- python3 validate-and-generate-refactor.py show --input .prizmkit/plans/refactor-list.json --id R-001
20
- python3 validate-and-generate-refactor.py append --input additions.json --output .prizmkit/plans/refactor-list.json
21
- python3 validate-and-generate-refactor.py append --input additions.json --output .prizmkit/plans/refactor-list.json --dry-run
22
- python3 validate-and-generate-refactor.py generate --input draft.json --output .prizmkit/plans/refactor-list.json
23
- python3 validate-and-generate-refactor.py summary --input .prizmkit/plans/refactor-list.json [--format markdown|json]
24
-
25
- Python 3.6+ required. No external dependencies.
26
- """
27
-
28
- import argparse
29
- import collections
30
- import copy
31
- import json
32
- import os
33
- import re
34
- import sys
35
- import tempfile
36
- from datetime import datetime, timezone
37
-
38
- # ---------------------------------------------------------------------------
39
- # Constants
40
- # ---------------------------------------------------------------------------
41
-
42
- SCHEMA_VERSION = "dev-pipeline-refactor-list-v1"
43
-
44
- VALID_STATUSES = {"pending", "in_progress", "completed", "failed", "skipped", "auto_skipped"}
45
- VALID_TYPES = {"extract", "rename", "restructure", "simplify", "decouple", "migrate"}
46
- VALID_PRIORITIES = {"critical", "high", "medium", "low"}
47
- VALID_COMPLEXITIES = {"low", "medium", "high"}
48
- VALID_PRESERVATION_STRATEGIES = {"test-gate", "snapshot", "manual"}
49
- ALLOWED_LIST_FIELDS = {
50
- "$schema", "project_name", "project_description", "created_at",
51
- "created_by", "refactors", "global_context",
52
- }
53
- ALLOWED_GLOBAL_CONTEXT_FIELDS = {
54
- "tech_stack", "language", "runtime", "frontend_framework",
55
- "frontend_styling", "backend_framework", "database", "orm",
56
- "testing_strategy", "bundler", "project_type", "ci_pipeline",
57
- }
58
- ALLOWED_REFACTOR_FIELDS = {
59
- "id", "title", "description", "scope", "type", "priority", "complexity",
60
- "estimated_lines", "behavior_preservation", "dependencies",
61
- "acceptance_criteria", "status", "completion_notes", "user_context",
62
- "browser_interaction", "model",
63
- }
64
-
65
- REFACTOR_ID_RE = re.compile(r"^R-\d{3}$")
66
-
67
- # ---------------------------------------------------------------------------
68
- # Helpers
69
- # ---------------------------------------------------------------------------
70
-
71
-
72
- def _err(msg):
73
- """Print an error message to stderr."""
74
- print("ERROR: {}".format(msg), file=sys.stderr)
75
-
76
-
77
- def _warn(msg):
78
- """Print a warning message to stderr."""
79
- print("WARNING: {}".format(msg), file=sys.stderr)
80
-
81
-
82
- def _info(msg):
83
- """Print an informational message to stderr."""
84
- print("INFO: {}".format(msg), file=sys.stderr)
85
-
86
-
87
- def _load_json(path):
88
- """Load and return parsed JSON from *path*.
89
-
90
- Returns (data, error_message). On success error_message is None.
91
- """
92
- if not os.path.isfile(path):
93
- return None, "File not found: {}".format(path)
94
- try:
95
- with open(path, "r", encoding="utf-8") as fh:
96
- data = json.load(fh)
97
- return data, None
98
- except json.JSONDecodeError as exc:
99
- return None, "JSON parse error in {}: {}".format(path, exc)
100
- except Exception as exc:
101
- return None, "Failed to read {}: {}".format(path, exc)
102
-
103
-
104
- def _write_json(path, data):
105
- """Write *data* as pretty-printed JSON to *path*."""
106
- parent = os.path.dirname(path)
107
- if parent and not os.path.isdir(parent):
108
- os.makedirs(parent, exist_ok=True)
109
- with open(path, "w", encoding="utf-8") as fh:
110
- json.dump(data, fh, indent=2, ensure_ascii=False)
111
- fh.write("\n")
112
-
113
-
114
- def _write_json_atomic(path, data):
115
- """Atomically replace *path* with pretty-printed JSON data."""
116
- parent = os.path.dirname(os.path.abspath(path))
117
- if parent and not os.path.isdir(parent):
118
- os.makedirs(parent, exist_ok=True)
119
- fd, temp_path = tempfile.mkstemp(prefix=".refactor-list-", suffix=".tmp", dir=parent)
120
- try:
121
- with os.fdopen(fd, "w", encoding="utf-8") as fh:
122
- json.dump(data, fh, indent=2, ensure_ascii=False)
123
- fh.write("\n")
124
- os.replace(temp_path, path)
125
- except Exception:
126
- try:
127
- os.unlink(temp_path)
128
- except OSError:
129
- pass
130
- raise
131
-
132
-
133
- # ---------------------------------------------------------------------------
134
- # Cycle detection (Kahn's algorithm)
135
- # ---------------------------------------------------------------------------
136
-
137
-
138
- def _detect_cycles(refactors):
139
- """Return (has_cycles: bool, max_depth: int) using Kahn's topological sort.
140
-
141
- *refactors* is the list of refactor dicts. We build a graph from the
142
- ``dependencies`` field and run Kahn's algorithm.
143
-
144
- Returns a tuple ``(has_cycles, max_depth)`` where *max_depth* is the
145
- longest path in the DAG (0 if there are cycles or a single node).
146
- """
147
- id_set = {r["id"] for r in refactors}
148
- # Build adjacency list and in-degree map.
149
- adj = {rid: [] for rid in id_set} # dependency -> [dependent]
150
- in_degree = {rid: 0 for rid in id_set}
151
-
152
- for refactor in refactors:
153
- rid = refactor["id"]
154
- for dep in refactor.get("dependencies", []):
155
- if dep in id_set:
156
- adj[dep].append(rid)
157
- in_degree[rid] += 1
158
-
159
- # Kahn's algorithm
160
- queue = collections.deque()
161
- for rid, deg in in_degree.items():
162
- if deg == 0:
163
- queue.append(rid)
164
-
165
- sorted_order = []
166
- # Track depth for each node to compute max dependency depth.
167
- depth = {rid: 0 for rid in id_set}
168
-
169
- while queue:
170
- node = queue.popleft()
171
- sorted_order.append(node)
172
- for neighbour in adj[node]:
173
- in_degree[neighbour] -= 1
174
- new_depth = depth[node] + 1
175
- if new_depth > depth[neighbour]:
176
- depth[neighbour] = new_depth
177
- if in_degree[neighbour] == 0:
178
- queue.append(neighbour)
179
-
180
- has_cycles = len(sorted_order) != len(id_set)
181
- max_depth = max(depth.values()) if depth else 0
182
- return has_cycles, max_depth
183
-
184
-
185
- # ---------------------------------------------------------------------------
186
- # Validation
187
- # ---------------------------------------------------------------------------
188
-
189
-
190
- def validate_refactor_list(data):
191
- """Validate a parsed refactor-list data structure.
192
-
193
- Returns a dict with keys ``valid``, ``errors``, ``warnings``, ``stats``.
194
- """
195
- errors = []
196
- warnings = []
197
-
198
- # ------------------------------------------------------------------
199
- # 1. Top-level schema validation
200
- # ------------------------------------------------------------------
201
- unknown_root = set(data) - ALLOWED_LIST_FIELDS
202
- if unknown_root:
203
- errors.append("refactor list has unknown fields: {}".format(
204
- ", ".join(sorted(unknown_root))
205
- ))
206
-
207
- schema = data.get("$schema")
208
- if schema != SCHEMA_VERSION:
209
- errors.append(
210
- "$schema must be '{}', got '{}'".format(SCHEMA_VERSION, schema)
211
- )
212
-
213
- project_name = data.get("project_name")
214
- if not isinstance(project_name, str) or not project_name.strip():
215
- errors.append("project_name must be a non-empty string")
216
-
217
- global_context = data.get("global_context")
218
- if global_context is not None:
219
- if not isinstance(global_context, dict):
220
- errors.append("global_context must be an object")
221
- else:
222
- unknown_context = set(global_context) - ALLOWED_GLOBAL_CONTEXT_FIELDS
223
- if unknown_context:
224
- errors.append("global_context has unknown fields: {}".format(
225
- ", ".join(sorted(unknown_context))
226
- ))
227
-
228
- refactors = data.get("refactors")
229
- if not isinstance(refactors, list) or len(refactors) == 0:
230
- errors.append("refactors must be a non-empty array")
231
- # Early-out: nothing else to validate if refactors are missing.
232
- return {
233
- "valid": False,
234
- "errors": errors,
235
- "warnings": warnings,
236
- "stats": {
237
- "total_refactors": 0,
238
- "type_distribution": {},
239
- "complexity_distribution": {},
240
- "max_dependency_depth": 0,
241
- "has_cycles": False,
242
- },
243
- }
244
-
245
- # ------------------------------------------------------------------
246
- # 2. Per-refactor validation
247
- # ------------------------------------------------------------------
248
- required_keys = {
249
- "id", "title", "description", "scope", "type", "priority",
250
- "complexity", "behavior_preservation", "acceptance_criteria",
251
- "dependencies", "status",
252
- }
253
-
254
- seen_ids = set()
255
- type_dist = {t: 0 for t in VALID_TYPES}
256
- complexity_dist = {"low": 0, "medium": 0, "high": 0}
257
-
258
- for idx, refactor in enumerate(refactors):
259
- label = "refactors[{}]".format(idx)
260
-
261
- # -- Required keys --
262
- if not isinstance(refactor, dict):
263
- errors.append("{} is not an object".format(label))
264
- continue
265
-
266
- missing = required_keys - set(refactor.keys())
267
- if missing:
268
- errors.append("{} missing required keys: {}".format(
269
- label, ", ".join(sorted(missing))
270
- ))
271
-
272
- unknown = set(refactor.keys()) - ALLOWED_REFACTOR_FIELDS
273
- if unknown:
274
- errors.append("{} has unknown fields: {}".format(
275
- label, ", ".join(sorted(unknown))
276
- ))
277
-
278
- # -- ID format & uniqueness --
279
- rid = refactor.get("id", "")
280
- if not REFACTOR_ID_RE.match(str(rid)):
281
- errors.append(
282
- "{}: id '{}' does not match pattern R-NNN".format(label, rid)
283
- )
284
- if rid in seen_ids:
285
- errors.append("{}: duplicate id '{}'".format(label, rid))
286
- seen_ids.add(rid)
287
-
288
- # -- Title --
289
- title = refactor.get("title")
290
- if not isinstance(title, str) or not title.strip():
291
- errors.append("{}: title must be a non-empty string".format(label))
292
-
293
- # -- Description depth check --
294
- desc = refactor.get("description", "")
295
- if not isinstance(desc, str) or not desc.strip():
296
- errors.append("{}: description must be a non-empty string".format(label))
297
- elif isinstance(desc, str) and desc.strip():
298
- word_count = len(desc.split())
299
- complexity = refactor.get("complexity", "medium")
300
- min_words = {"low": 30, "medium": 50, "high": 80}.get(complexity, 50)
301
- if word_count < 15:
302
- errors.append(
303
- "{}: description too short ({} words, minimum 15). "
304
- "Include: what to refactor, why, affected components, "
305
- "and expected outcome.".format(label, word_count)
306
- )
307
- elif word_count < min_words:
308
- warnings.append(
309
- "{}: description only {} words (recommend {}+ for {} complexity). "
310
- "Richer descriptions produce better pipeline results.".format(
311
- label, word_count, min_words, complexity
312
- )
313
- )
314
-
315
- # -- Scope --
316
- scope = refactor.get("scope")
317
- if isinstance(scope, dict):
318
- scope_files = scope.get("files")
319
- if not isinstance(scope_files, list):
320
- errors.append("{}: scope.files must be an array of strings".format(label))
321
- elif not all(isinstance(f, str) for f in scope_files):
322
- errors.append("{}: scope.files must contain only strings".format(label))
323
-
324
- scope_modules = scope.get("modules")
325
- if not isinstance(scope_modules, list):
326
- errors.append("{}: scope.modules must be an array of strings".format(label))
327
- elif not all(isinstance(m, str) for m in scope_modules):
328
- errors.append("{}: scope.modules must contain only strings".format(label))
329
- else:
330
- errors.append("{}: scope must be an object with 'files' and 'modules'".format(label))
331
-
332
- # -- Type --
333
- rtype = refactor.get("type")
334
- if isinstance(rtype, str) and rtype in VALID_TYPES:
335
- type_dist[rtype] += 1
336
- else:
337
- errors.append(
338
- "{}: type must be one of {}, got {}".format(
339
- label, ", ".join(sorted(VALID_TYPES)), repr(rtype)
340
- )
341
- )
342
-
343
- # -- Priority --
344
- priority = refactor.get("priority")
345
- if not isinstance(priority, str) or priority not in VALID_PRIORITIES:
346
- errors.append(
347
- "{}: priority must be one of {}, got {}".format(
348
- label, ", ".join(sorted(VALID_PRIORITIES)), repr(priority)
349
- )
350
- )
351
-
352
- # -- Complexity --
353
- complexity = refactor.get("complexity")
354
- if isinstance(complexity, str) and complexity in VALID_COMPLEXITIES:
355
- complexity_dist[complexity] += 1
356
- else:
357
- errors.append(
358
- "{}: complexity must be one of {}, got {}".format(
359
- label, ", ".join(sorted(VALID_COMPLEXITIES)), repr(complexity)
360
- )
361
- )
362
-
363
- # -- Behavior preservation --
364
- bp = refactor.get("behavior_preservation")
365
- if isinstance(bp, dict):
366
- strategy = bp.get("strategy")
367
- if not isinstance(strategy, str) or strategy not in VALID_PRESERVATION_STRATEGIES:
368
- errors.append(
369
- "{}: behavior_preservation.strategy must be one of {}, got {}".format(
370
- label,
371
- ", ".join(sorted(VALID_PRESERVATION_STRATEGIES)),
372
- repr(strategy),
373
- )
374
- )
375
-
376
- # Optional fields validation
377
- existing_tests = bp.get("existing_tests")
378
- if existing_tests is not None and not isinstance(existing_tests, bool):
379
- errors.append(
380
- "{}: behavior_preservation.existing_tests must be a boolean, got {}".format(
381
- label, type(existing_tests).__name__
382
- )
383
- )
384
-
385
- new_tests = bp.get("new_tests_needed")
386
- if new_tests is not None:
387
- if not isinstance(new_tests, list):
388
- errors.append(
389
- "{}: behavior_preservation.new_tests_needed must be an array of strings".format(label)
390
- )
391
- elif not all(isinstance(t, str) for t in new_tests):
392
- errors.append(
393
- "{}: behavior_preservation.new_tests_needed must contain only strings".format(label)
394
- )
395
- else:
396
- errors.append(
397
- "{}: behavior_preservation must be an object with 'strategy'".format(label)
398
- )
399
-
400
- # -- Acceptance criteria --
401
- criteria = refactor.get("acceptance_criteria")
402
- if isinstance(criteria, list):
403
- if len(criteria) < 1:
404
- errors.append("{}: must have at least 1 acceptance criterion".format(label))
405
- elif len(criteria) < 3:
406
- warnings.append(
407
- "{}: only {} acceptance criteria (recommend at least 3)".format(
408
- label, len(criteria)
409
- )
410
- )
411
- for ci, c in enumerate(criteria):
412
- if not isinstance(c, str) or not c.strip():
413
- errors.append(
414
- "{}: acceptance_criteria[{}] must be a non-empty string".format(label, ci)
415
- )
416
- else:
417
- errors.append("{}: acceptance_criteria must be an array".format(label))
418
-
419
- # -- Dependencies (list of strings matching R-NNN) --
420
- deps = refactor.get("dependencies")
421
- if isinstance(deps, list):
422
- for dep in deps:
423
- if not isinstance(dep, str) or not REFACTOR_ID_RE.match(dep):
424
- errors.append(
425
- "{}: dependency '{}' does not match R-NNN pattern".format(label, dep)
426
- )
427
- else:
428
- errors.append("{}: dependencies must be an array".format(label))
429
-
430
- # -- Status --
431
- status = refactor.get("status")
432
- if status not in VALID_STATUSES:
433
- errors.append(
434
- "{}: status '{}' invalid, must be one of: {}".format(
435
- label, status, ", ".join(sorted(VALID_STATUSES))
436
- )
437
- )
438
-
439
- # ------------------------------------------------------------------
440
- # 3. Dependency validation
441
- # ------------------------------------------------------------------
442
- all_ids = {r.get("id") for r in refactors}
443
- for idx, refactor in enumerate(refactors):
444
- label = "refactors[{}]".format(idx)
445
- deps = refactor.get("dependencies", [])
446
- if isinstance(deps, list):
447
- for dep in deps:
448
- if isinstance(dep, str) and REFACTOR_ID_RE.match(dep) and dep not in all_ids:
449
- errors.append(
450
- "{}: dependency '{}' does not exist in refactor list".format(label, dep)
451
- )
452
-
453
- # -- Cycle detection --
454
- has_cycles, max_depth = _detect_cycles(refactors)
455
- if has_cycles:
456
- errors.append("Dependency graph contains cycles (not a valid DAG)")
457
-
458
- # ------------------------------------------------------------------
459
- # 4. Build result
460
- # ------------------------------------------------------------------
461
- is_valid = len(errors) == 0
462
-
463
- return {
464
- "valid": is_valid,
465
- "errors": errors,
466
- "warnings": warnings,
467
- "stats": {
468
- "total_refactors": len(refactors),
469
- "type_distribution": type_dist,
470
- "complexity_distribution": complexity_dist,
471
- "max_dependency_depth": max_depth,
472
- "has_cycles": has_cycles,
473
- },
474
- }
475
-
476
-
477
- # ---------------------------------------------------------------------------
478
- # Template generation
479
- # ---------------------------------------------------------------------------
480
-
481
-
482
- def generate_template():
483
- """Return a template refactor-list dict with placeholder values."""
484
- return {
485
- "$schema": SCHEMA_VERSION,
486
- "project_name": "YOUR_PROJECT_NAME",
487
- "refactors": [
488
- {
489
- "id": "R-001",
490
- "title": "Extract authentication module",
491
- "description": (
492
- "Extract authentication logic from the monolithic user service "
493
- "into a dedicated auth module. This will improve separation of "
494
- "concerns, make the auth logic independently testable, and reduce "
495
- "coupling between user management and authentication flows."
496
- ),
497
- "scope": {
498
- "files": [
499
- "src/services/user-service.js",
500
- "src/middleware/auth.js",
501
- ],
502
- "modules": ["user-service", "auth"],
503
- },
504
- "type": "extract",
505
- "priority": "high",
506
- "complexity": "medium",
507
- "behavior_preservation": {
508
- "strategy": "test-gate",
509
- "existing_tests": True,
510
- "new_tests_needed": [
511
- "Auth module unit tests",
512
- "Integration test for login flow",
513
- ],
514
- },
515
- "acceptance_criteria": [
516
- "Auth logic moved to dedicated module",
517
- "All existing auth tests pass without modification",
518
- "No changes to public API surface",
519
- ],
520
- "dependencies": [],
521
- "status": "pending",
522
- }
523
- ],
524
- }
525
-
526
-
527
- # ---------------------------------------------------------------------------
528
- # Summary
529
- # ---------------------------------------------------------------------------
530
-
531
-
532
- def _build_dependency_graph_text(refactors):
533
- """Build a human-readable text representation of the dependency graph.
534
-
535
- Returns a list of lines.
536
- """
537
- all_ids = [r["id"] for r in refactors]
538
-
539
- # Build adjacency: dependency -> list of dependents (forward edges)
540
- dependents = {rid: [] for rid in all_ids}
541
- has_parent = set()
542
- for refactor in refactors:
543
- for dep in refactor.get("dependencies", []):
544
- if dep in dependents:
545
- dependents[dep].append(refactor["id"])
546
- has_parent.add(refactor["id"])
547
-
548
- # Sort children for deterministic output
549
- for rid in dependents:
550
- dependents[rid] = sorted(set(dependents[rid]))
551
-
552
- # Roots: refactors with no incoming dependencies
553
- roots = [rid for rid in all_ids if rid not in has_parent]
554
- if not roots:
555
- return ["(cycle detected - no root nodes)"]
556
- if not any(dependents[r] for r in all_ids):
557
- return ["(no dependencies)"]
558
-
559
- result_lines = []
560
-
561
- def _render(node, prefix, is_continuation):
562
- """Render a node and its dependents recursively."""
563
- children = dependents.get(node, [])
564
- if not children:
565
- return
566
-
567
- for i, child in enumerate(children):
568
- if i == 0:
569
- result_lines[-1] += " -> {}".format(child)
570
- _render(child, prefix + " " * (len(node) + 4), True)
571
- else:
572
- line = "{}-> {}".format(prefix, child)
573
- result_lines.append(line)
574
- child_prefix = prefix + " " * (len(child) + 4)
575
- _render(child, child_prefix, True)
576
-
577
- for root in sorted(roots):
578
- result_lines.append(root)
579
- _render(root, " " * len(root), False)
580
-
581
- return result_lines
582
-
583
-
584
- def generate_summary_markdown(data):
585
- """Generate a markdown summary of the refactor list."""
586
- project_name = data.get("project_name", "Unknown")
587
- refactors = data.get("refactors", [])
588
-
589
- lines = []
590
- lines.append("# Refactor Summary: {}".format(project_name))
591
- lines.append("")
592
-
593
- # Table header
594
- lines.append("| ID | Title | Type | Complexity | Priority | Dependencies | Criteria | Strategy |")
595
- lines.append("|----|-------|------|------------|----------|--------------|----------|----------|")
596
-
597
- for refactor in refactors:
598
- rid = refactor.get("id", "?")
599
- title = refactor.get("title", "?")
600
- rtype = refactor.get("type", "-")
601
- complexity = refactor.get("complexity", "-")
602
- priority = refactor.get("priority", "?")
603
- deps = refactor.get("dependencies", [])
604
- deps_str = ", ".join(deps) if deps else "-"
605
- criteria_count = len(refactor.get("acceptance_criteria", []))
606
- bp = refactor.get("behavior_preservation", {})
607
- strategy = bp.get("strategy", "-") if isinstance(bp, dict) else "-"
608
-
609
- lines.append("| {} | {} | {} | {} | {} | {} | {} | {} |".format(
610
- rid, title, rtype, complexity, priority, deps_str, criteria_count, strategy
611
- ))
612
-
613
- lines.append("")
614
-
615
- # Dependency graph
616
- lines.append("## Dependency Graph")
617
- graph_lines = _build_dependency_graph_text(refactors)
618
- for gl in graph_lines:
619
- lines.append(gl)
620
- lines.append("")
621
-
622
- # Statistics
623
- type_dist = {t: 0 for t in VALID_TYPES}
624
- complexity_dist = {"low": 0, "medium": 0, "high": 0}
625
- for refactor in refactors:
626
- t = refactor.get("type")
627
- if t in type_dist:
628
- type_dist[t] += 1
629
- c = refactor.get("complexity")
630
- if c in complexity_dist:
631
- complexity_dist[c] += 1
632
-
633
- _, max_depth = _detect_cycles(refactors)
634
-
635
- lines.append("## Statistics")
636
- lines.append("- Total refactors: {}".format(len(refactors)))
637
- lines.append("- Complexity: {} low, {} medium, {} high".format(
638
- complexity_dist["low"], complexity_dist["medium"], complexity_dist["high"]
639
- ))
640
- type_parts = ["{} {}".format(v, k) for k, v in sorted(type_dist.items()) if v > 0]
641
- if type_parts:
642
- lines.append("- Types: {}".format(", ".join(type_parts)))
643
- lines.append("- Max dependency depth: {}".format(max_depth))
644
-
645
- return "\n".join(lines)
646
-
647
-
648
- def generate_summary_json(data):
649
- """Generate a JSON summary of the refactor list."""
650
- refactors = data.get("refactors", [])
651
-
652
- type_dist = {t: 0 for t in VALID_TYPES}
653
- complexity_dist = {"low": 0, "medium": 0, "high": 0}
654
- for refactor in refactors:
655
- t = refactor.get("type")
656
- if t in type_dist:
657
- type_dist[t] += 1
658
- c = refactor.get("complexity")
659
- if c in complexity_dist:
660
- complexity_dist[c] += 1
661
-
662
- has_cycles, max_depth = _detect_cycles(refactors)
663
-
664
- refactor_summaries = []
665
- for refactor in refactors:
666
- bp = refactor.get("behavior_preservation", {})
667
- refactor_summaries.append({
668
- "id": refactor.get("id"),
669
- "title": refactor.get("title"),
670
- "type": refactor.get("type"),
671
- "priority": refactor.get("priority"),
672
- "complexity": refactor.get("complexity"),
673
- "dependencies": refactor.get("dependencies", []),
674
- "acceptance_criteria_count": len(refactor.get("acceptance_criteria", [])),
675
- "preservation_strategy": bp.get("strategy") if isinstance(bp, dict) else None,
676
- "status": refactor.get("status"),
677
- })
678
-
679
- return {
680
- "project_name": data.get("project_name", ""),
681
- "refactors": refactor_summaries,
682
- "stats": {
683
- "total_refactors": len(refactors),
684
- "type_distribution": type_dist,
685
- "complexity_distribution": complexity_dist,
686
- "max_dependency_depth": max_depth,
687
- "has_cycles": has_cycles,
688
- },
689
- }
690
-
691
-
692
- # ---------------------------------------------------------------------------
693
- # CLI
694
- # ---------------------------------------------------------------------------
695
-
696
-
697
- def cmd_validate(args):
698
- """Handle the 'validate' command."""
699
- if not args.input:
700
- _err("--input is required for the validate command")
701
- return 2
702
-
703
- data, load_err = _load_json(args.input)
704
- if load_err:
705
- _err(load_err)
706
- result = {
707
- "valid": False,
708
- "errors": [load_err],
709
- "warnings": [],
710
- "stats": {
711
- "total_refactors": 0,
712
- "type_distribution": {},
713
- "complexity_distribution": {},
714
- "max_dependency_depth": 0,
715
- "has_cycles": False,
716
- },
717
- }
718
- print(json.dumps(result, indent=2, ensure_ascii=False))
719
- return 2
720
-
721
- result = validate_refactor_list(data)
722
-
723
- # Print results to stdout
724
- print(json.dumps(result, indent=2, ensure_ascii=False))
725
-
726
- # Log to stderr for humans
727
- if result["valid"]:
728
- _info("Validation passed with {} warning(s)".format(len(result["warnings"])))
729
- else:
730
- _err("Validation failed with {} error(s) and {} warning(s)".format(
731
- len(result["errors"]), len(result["warnings"])
732
- ))
733
-
734
- for e in result["errors"]:
735
- _err(" " + e)
736
- for w in result["warnings"]:
737
- _warn(" " + w)
738
-
739
- # Optionally write validated/cleaned output
740
- if args.output and result["valid"]:
741
- _write_json(args.output, data)
742
- _info("Validated output written to {}".format(args.output))
743
-
744
- return 0 if result["valid"] else 1
745
-
746
-
747
- def cmd_template(args):
748
- """Handle the 'template' command."""
749
- if not args.output:
750
- _err("--output is required for the template command")
751
- return 2
752
-
753
- template = generate_template()
754
- _write_json(args.output, template)
755
- _info("Template written to {}".format(args.output))
756
- return 0
757
-
758
-
759
- def _load_valid_existing(path):
760
- """Load and validate one existing refactor list."""
761
- data, load_err = _load_json(path)
762
- if load_err:
763
- _err(load_err)
764
- return None, None, 2
765
- if not isinstance(data, dict):
766
- _err("Refactor list root must be an object")
767
- return None, None, 1
768
-
769
- result = validate_refactor_list(data)
770
- if not result["valid"]:
771
- _err("Existing refactor list is invalid")
772
- for error in result["errors"]:
773
- _err(" " + error)
774
- return None, result, 1
775
- return data, result, 0
776
-
777
-
778
- def _next_top_level_id(refactors):
779
- """Return the next R-NNN ID, or None when numeric capacity is exhausted."""
780
- numbers = []
781
- for refactor in refactors:
782
- match = REFACTOR_ID_RE.match(str(refactor.get("id", "")))
783
- if match:
784
- numbers.append(int(str(refactor["id"])[2:]))
785
- next_number = max(numbers, default=0) + 1
786
- if next_number > 999:
787
- return None
788
- return "R-{:03d}".format(next_number)
789
-
790
-
791
- def cmd_context(args):
792
- """Print bounded existing-list context for incremental planning."""
793
- data, _, exit_code = _load_valid_existing(args.input)
794
- if exit_code:
795
- return exit_code
796
-
797
- refactors = data["refactors"]
798
- next_id = _next_top_level_id(refactors)
799
- if next_id is None:
800
- _err("Refactor ID capacity exhausted at R-999")
801
- return 1
802
-
803
- context = {
804
- "project_name": data.get("project_name"),
805
- "project_description": data.get("project_description"),
806
- "global_context": data.get("global_context") or {},
807
- "task_count": len(refactors),
808
- "next_id": next_id,
809
- "recent_tasks": [
810
- {"id": refactor.get("id"), "description": refactor.get("description")}
811
- for refactor in refactors[-5:]
812
- ],
813
- }
814
- print(json.dumps(context, indent=2, ensure_ascii=False))
815
- return 0
816
-
817
-
818
- def cmd_show(args):
819
- """Print one explicitly requested top-level refactor."""
820
- data, _, exit_code = _load_valid_existing(args.input)
821
- if exit_code:
822
- return exit_code
823
- if not REFACTOR_ID_RE.match(str(args.id)):
824
- _err("Refactor ID '{}' must match R-NNN".format(args.id))
825
- return 1
826
-
827
- for refactor in data["refactors"]:
828
- if refactor.get("id") == args.id:
829
- print(json.dumps(refactor, indent=2, ensure_ascii=False))
830
- return 0
831
- _err("Refactor '{}' not found".format(args.id))
832
- return 1
833
-
834
-
835
- def cmd_append(args):
836
- """Append a collection-only draft to an existing validated refactor list."""
837
- base, _, exit_code = _load_valid_existing(args.output)
838
- if exit_code:
839
- return exit_code
840
-
841
- draft, load_err = _load_json(args.input)
842
- if load_err:
843
- _err(load_err)
844
- return 2
845
- if not isinstance(draft, dict) or set(draft.keys()) != {"refactors"}:
846
- _err("Additions draft must be an object containing only 'refactors'")
847
- return 1
848
- additions = draft.get("refactors")
849
- if not isinstance(additions, list) or not additions:
850
- _err("Additions draft 'refactors' must be a non-empty array")
851
- return 1
852
- if not all(isinstance(refactor, dict) for refactor in additions):
853
- _err("Every refactor addition must be an object")
854
- return 1
855
-
856
- merge_base = copy.deepcopy(base)
857
- if args.replace_tail:
858
- addition_ids = [refactor.get("id") for refactor in additions]
859
- tail_ids = [refactor.get("id") for refactor in base["refactors"][-len(additions):]]
860
- if len(base["refactors"]) < len(additions) or tail_ids != addition_ids:
861
- _err("--replace-tail requires additions IDs to match the existing final-list suffix exactly")
862
- return 1
863
- merge_base["refactors"] = merge_base["refactors"][:-len(additions)]
864
-
865
- next_id = _next_top_level_id(merge_base["refactors"])
866
- if next_id is None:
867
- _err("Refactor ID capacity exhausted at R-999")
868
- return 1
869
- start_number = int(next_id[2:])
870
- prepared = copy.deepcopy(additions)
871
- for offset, refactor in enumerate(prepared):
872
- expected_id = "R-{:03d}".format(start_number + offset)
873
- if start_number + offset > 999:
874
- _err("Refactor ID capacity exhausted at R-999")
875
- return 1
876
- if refactor.get("id") != expected_id:
877
- _err("Refactor addition {} must use next sequential ID '{}'".format(offset, expected_id))
878
- return 1
879
- refactor.setdefault("status", "pending")
880
-
881
- merged = copy.deepcopy(merge_base)
882
- merged["refactors"].extend(prepared)
883
- result = validate_refactor_list(merged)
884
- result["appended_ids"] = [refactor["id"] for refactor in prepared]
885
- print(json.dumps(result, indent=2, ensure_ascii=False))
886
- if not result["valid"]:
887
- _err("Merged refactor list validation failed")
888
- for error in result["errors"]:
889
- _err(" " + error)
890
- return 1
891
-
892
- if getattr(args, "dry_run", False):
893
- _info("Dry run: {} refactor(s) would be appended to {}".format(
894
- len(prepared), args.output))
895
- return 0
896
-
897
- try:
898
- _write_json_atomic(args.output, merged)
899
- except Exception as exc:
900
- _err("Failed to write merged refactor list: {}".format(exc))
901
- return 2
902
- _info("Appended {} refactor(s) to {}".format(len(prepared), args.output))
903
- return 0
904
-
905
-
906
- def cmd_generate(args):
907
- """Handle the 'generate' command.
908
-
909
- Loads a draft JSON (produced by AI), fills in defaults, validates,
910
- and writes the final refactor-list.json.
911
- """
912
- if not args.input:
913
- _err("--input is required for the generate command")
914
- return 2
915
- if not args.output:
916
- _err("--output is required for the generate command")
917
- return 2
918
-
919
- # Load draft (supports stdin via '-')
920
- if args.input == "-":
921
- try:
922
- data = json.load(sys.stdin)
923
- except json.JSONDecodeError as exc:
924
- _err("Invalid JSON from stdin: {}".format(exc))
925
- return 2
926
- else:
927
- data, load_err = _load_json(args.input)
928
- if load_err:
929
- _err(load_err)
930
- return 2
931
-
932
- # Fill in defaults
933
- now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
934
- data.setdefault("$schema", SCHEMA_VERSION)
935
- data.setdefault("created_at", now)
936
- data.setdefault("created_by", "refactor-planner")
937
-
938
- # Set default status for refactors without one
939
- for refactor in data.get("refactors", []):
940
- refactor.setdefault("status", "pending")
941
-
942
- # Validate
943
- result = validate_refactor_list(data)
944
-
945
- # Output validation result
946
- print(json.dumps(result, indent=2, ensure_ascii=False))
947
-
948
- if result["valid"]:
949
- _write_json(args.output, data)
950
- _info("Generated refactor-list written to {}".format(args.output))
951
- return 0
952
- else:
953
- _err("Validation failed with {} error(s)".format(len(result["errors"])))
954
- for e in result["errors"]:
955
- _err(" " + e)
956
- for w in result.get("warnings", []):
957
- _warn(" " + w)
958
- return 1
959
-
960
-
961
- def cmd_summary(args):
962
- """Handle the 'summary' command."""
963
- if not args.input:
964
- _err("--input is required for the summary command")
965
- return 2
966
-
967
- data, load_err = _load_json(args.input)
968
- if load_err:
969
- _err(load_err)
970
- return 2
971
-
972
- output_format = getattr(args, "format", "markdown") or "markdown"
973
-
974
- if output_format == "json":
975
- summary = generate_summary_json(data)
976
- print(json.dumps(summary, indent=2, ensure_ascii=False))
977
- else:
978
- summary = generate_summary_markdown(data)
979
- print(summary)
980
-
981
- return 0
982
-
983
-
984
- def main():
985
- parser = argparse.ArgumentParser(
986
- description="Validate and generate .prizmkit/plans/refactor-list.json files for the dev-pipeline system.",
987
- formatter_class=argparse.RawDescriptionHelpFormatter,
988
- epilog=(
989
- "Examples:\n"
990
- " %(prog)s validate --input .prizmkit/plans/refactor-list.json\n"
991
- " %(prog)s validate --input .prizmkit/plans/refactor-list.json --output validated.json\n"
992
- " %(prog)s template --output .prizmkit/plans/refactor-list.json\n"
993
- " %(prog)s context --input .prizmkit/plans/refactor-list.json\n"
994
- " %(prog)s show --input .prizmkit/plans/refactor-list.json --id R-001\n"
995
- " %(prog)s append --input additions.json --output .prizmkit/plans/refactor-list.json\n"
996
- " %(prog)s generate --input draft.json --output .prizmkit/plans/refactor-list.json\n"
997
- " %(prog)s summary --input .prizmkit/plans/refactor-list.json\n"
998
- " %(prog)s summary --input .prizmkit/plans/refactor-list.json --format json\n"
999
- ),
1000
- )
1001
-
1002
- subparsers = parser.add_subparsers(dest="command", help="Command to execute")
1003
-
1004
- # -- validate --
1005
- p_validate = subparsers.add_parser(
1006
- "validate",
1007
- help="Validate an existing .prizmkit/plans/refactor-list.json",
1008
- )
1009
- p_validate.add_argument(
1010
- "--input", required=True, help="Path to input .prizmkit/plans/refactor-list.json"
1011
- )
1012
- p_validate.add_argument(
1013
- "--output", help="Path to write validated output (optional)"
1014
- )
1015
-
1016
- # -- template --
1017
- p_template = subparsers.add_parser(
1018
- "template",
1019
- help="Generate a blank template .prizmkit/plans/refactor-list.json",
1020
- )
1021
- p_template.add_argument(
1022
- "--output", required=True, help="Path to write template file"
1023
- )
1024
-
1025
- # -- context --
1026
- p_context = subparsers.add_parser(
1027
- "context",
1028
- help="Print root context and the five most recent refactor id/description pairs",
1029
- )
1030
- p_context.add_argument(
1031
- "--input", required=True, help="Path to existing .prizmkit/plans/refactor-list.json"
1032
- )
1033
-
1034
- # -- show --
1035
- p_show = subparsers.add_parser(
1036
- "show",
1037
- help="Print one explicitly requested top-level refactor",
1038
- )
1039
- p_show.add_argument(
1040
- "--input", required=True, help="Path to existing .prizmkit/plans/refactor-list.json"
1041
- )
1042
- p_show.add_argument(
1043
- "--id", required=True, help="Exact top-level refactor ID"
1044
- )
1045
-
1046
- # -- append --
1047
- p_append = subparsers.add_parser(
1048
- "append",
1049
- help="Append a refactors-only draft to an existing validated refactor list",
1050
- )
1051
- p_append.add_argument(
1052
- "--input", required=True, help="Path to additions-only draft JSON"
1053
- )
1054
- p_append.add_argument(
1055
- "--output", required=True, help="Path to existing final refactor-list.json"
1056
- )
1057
- p_append.add_argument(
1058
- "--replace-tail",
1059
- action="store_true",
1060
- help="Replace the exact existing suffix with the same IDs after local review",
1061
- )
1062
- p_append.add_argument(
1063
- "--dry-run",
1064
- action="store_true",
1065
- help="Validate the would-be merged list without writing it",
1066
- )
1067
-
1068
- # -- generate --
1069
- p_generate = subparsers.add_parser(
1070
- "generate",
1071
- help="Validate a draft and generate final refactor-list.json with defaults",
1072
- )
1073
- p_generate.add_argument(
1074
- "--input", required=True, help="Path to draft JSON (or '-' for stdin)"
1075
- )
1076
- p_generate.add_argument(
1077
- "--output", required=True, help="Path to write final refactor-list.json"
1078
- )
1079
-
1080
- # -- summary --
1081
- p_summary = subparsers.add_parser(
1082
- "summary",
1083
- help="Print a summary table of refactors from a .prizmkit/plans/refactor-list.json",
1084
- )
1085
- p_summary.add_argument(
1086
- "--input", required=True, help="Path to input .prizmkit/plans/refactor-list.json"
1087
- )
1088
- p_summary.add_argument(
1089
- "--format",
1090
- choices=["json", "markdown"],
1091
- default="markdown",
1092
- help="Output format (default: markdown)",
1093
- )
1094
-
1095
- args = parser.parse_args()
1096
-
1097
- if not args.command:
1098
- parser.print_help(sys.stderr)
1099
- return 2
1100
-
1101
- dispatch = {
1102
- "validate": cmd_validate,
1103
- "template": cmd_template,
1104
- "context": cmd_context,
1105
- "show": cmd_show,
1106
- "append": cmd_append,
1107
- "generate": cmd_generate,
1108
- "summary": cmd_summary,
1109
- }
1110
-
1111
- handler = dispatch.get(args.command)
1112
- if handler is None:
1113
- _err("Unknown command: {}".format(args.command))
1114
- return 2
1115
-
1116
- return handler(args)
1117
-
1118
-
1119
- if __name__ == "__main__":
1120
- sys.exit(main())