magic-spec 1.4.77 → 1.5.48
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.
- package/CHANGELOG.md +213 -152
- package/README.md +29 -15
- package/installers/config.json +18 -21
- package/installers/node/index.js +97 -29
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,152 +1,213 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to this project will be documented in this file.
|
|
4
|
-
|
|
5
|
-
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
-
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
-
|
|
8
|
-
## [1.
|
|
9
|
-
|
|
10
|
-
### Added
|
|
11
|
-
|
|
12
|
-
- **
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- **
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
- **
|
|
28
|
-
- **
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
- **
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
- **
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
- **
|
|
89
|
-
- **
|
|
90
|
-
|
|
91
|
-
###
|
|
92
|
-
|
|
93
|
-
-
|
|
94
|
-
|
|
95
|
-
## [1.
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
- **
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
- **
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
- **
|
|
137
|
-
- **
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
- **
|
|
149
|
-
- **
|
|
150
|
-
- **
|
|
151
|
-
|
|
152
|
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [1.5.48] - 2026-03-24
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **Publish Workflow**: Restored `.agents/workflows/publish.md` for engine maintenance and registry publishing.
|
|
13
|
+
- **History Tracking**: Initialized history for `magic.analyze` and `magic.dev.simulate` wrappers to ensure full auditability.
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
|
|
17
|
+
- **Version Synchronization**: Unified project version to `1.5.47` across all manifests (`package.json`, `pyproject.toml`, `__init__.py`) and the `.magic/.version` engine core.
|
|
18
|
+
- **Instruction Density**: Refined `.magic/simulate.md` (Context Bleed Warning) to remove vague qualifiers ("high-confidence" -> "strictly unbiased"), reaching a density score of 10/10.
|
|
19
|
+
- **Engine Integrity**: Optimized `generate-checksums.js` to exclude the `.checksums` file from its own mapping, preventing confusion and unstable hash values.
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
- **Testing Logic**: Corrected `run_tests.py` to properly set `PYTHONPATH` for Python installer subprocesses and fixed an `os.environ` access bug.
|
|
24
|
+
- **Sandbox Cleanup**: Removed dev-only `simulate.md` from installer test sandbox.
|
|
25
|
+
- **RULES Template**: Added missing conventions C18-C23 to `init.js` RULES.md generator.
|
|
26
|
+
- **Python Installer**: Fixed `_resolve_package_version()` to read actual package version.
|
|
27
|
+
- **Engine Scripts**: Deduplicated `workspace.json` reads in `executor.js`.
|
|
28
|
+
- **History Cleanup**: Removed legacy `audit.md` and `docs.md` files from `.magic/history/`.
|
|
29
|
+
|
|
30
|
+
## [1.5.30] - 2026-03-24
|
|
31
|
+
|
|
32
|
+
### Fixed
|
|
33
|
+
|
|
34
|
+
- **Version Synchronization**: Unified project version across `package.json` (was 1.5.0), `pyproject.toml` (was 1.4.162), and `__init__.py` (was 1.4.162) to a single `1.5.30`. Previously 5 different versions existed across 5 sources.
|
|
35
|
+
- **CONTEXT.md**: Regenerated stale context file (was 9 days old).
|
|
36
|
+
|
|
37
|
+
## [1.5.29] - 2026-03-16
|
|
38
|
+
|
|
39
|
+
### Added
|
|
40
|
+
|
|
41
|
+
- **Argument Routing (A–D)** for `task.md` and `run.md`: Both workflows now accept optional arguments — workspace name, directive text, or both. Consistent with `analyze.md` pattern. Includes Workspace Fallback, Disambiguation, and Handoff Propagation rules.
|
|
42
|
+
- **T4 Inline Guards** in `spec.md`: When spec workflow captures a standing rule via T4 trigger ("remember that..."), it now applies Tier Routing (global vs workspace RULES.md), Duplication Check (across both tiers), and Constitutional Guard (§1–6 protection) — matching `rule.md` safety guarantees without breaking T4's "Apply Immediately" semantics.
|
|
43
|
+
- **Regression Tests (T153–T161)**: 9 new scenarios covering argument routing (scoped planning, workspace fallback, disambiguation, targeted task/phase execution, cross-workflow handoff propagation) and T4 inline guards (tier routing, duplication detection, constitutional block).
|
|
44
|
+
|
|
45
|
+
### Changed
|
|
46
|
+
|
|
47
|
+
- **AGENTS.md**: Clarified C14 Enforcement scope — explicitly covers all `.magic/` content (workflows, scripts, templates, tests, config), not just workflow files. Added description of what `update-engine-meta` does (bumps `.version`, regenerates `.checksums`).
|
|
48
|
+
- **`run.md` Argument Routing**: Detection column harmonized with `analyze.md` — accepts both quoted text and non-workspace tokens (e.g., unquoted `T-1A01` or `phase-2`).
|
|
49
|
+
|
|
50
|
+
## [1.4.162] - 2026-03-12
|
|
51
|
+
|
|
52
|
+
### Added
|
|
53
|
+
|
|
54
|
+
- **Session Isolation Rule (C17)**: Formalized the requirement for "New Chat" sessions between major workflow transitions (Spec → Task → Run) to prevent context bleed-over and hallucinations.
|
|
55
|
+
- **Multi-Workspace Support (C22)**: Enhanced `check-prerequisites.js` and `init.js` to support nested workspaces with inherited root rules.
|
|
56
|
+
- **Model-Aware History**: Updated engine history schema to include AI Model information, improving auditability of generated code.
|
|
57
|
+
|
|
58
|
+
### Changed
|
|
59
|
+
|
|
60
|
+
- **Task Checklist Logic**: Consolidated implementation checklists into `TASKS.md` for better execution tracking and status reporting.
|
|
61
|
+
- **Gitignore Resilience**: Improved installers to automatically manage `.gitignore` entries for `.magic/` and `.agents/` directories with idempotent updates.
|
|
62
|
+
- **Onboarding Safety**: Added production data collision guards to `onboard.md` to prevent accidental overwrites of existing project plans.
|
|
63
|
+
|
|
64
|
+
### Fixed
|
|
65
|
+
|
|
66
|
+
- **Error Reporting**: Enhanced `check-prerequisites.js` with structured, actionable JSON error suggestions.
|
|
67
|
+
- **Path Handling**: Fixed Windows-specific path issues in installer scripts.
|
|
68
|
+
|
|
69
|
+
## [1.4.162] - 2026-03-03
|
|
70
|
+
|
|
71
|
+
### Added
|
|
72
|
+
|
|
73
|
+
- **Regression Test T85**: Verifies mandatory engine integrity HALT when `.magic/` files are tampered (C1 enforcement).
|
|
74
|
+
|
|
75
|
+
### Changed
|
|
76
|
+
|
|
77
|
+
- **Engine Integrity Halt**: Upgraded `check-prerequisites.js` to set `ok: false` on checksum mismatches, ensuring a hard HALT during pre-flight checks.
|
|
78
|
+
- **History Auto-Heal**: Enhanced `executor.js` to automatically recreate the `.magic/history/` directory and missing history files if deleted.
|
|
79
|
+
|
|
80
|
+
### Fixed
|
|
81
|
+
|
|
82
|
+
- **Resilient Logic**: Improved `check-prerequisites.js` to distinguish between critical engine integrity (HALT) and project data drift (WARNING), preserving self-healing capabilities.
|
|
83
|
+
|
|
84
|
+
## [1.4.162] - 2026-03-02
|
|
85
|
+
|
|
86
|
+
### Changed
|
|
87
|
+
|
|
88
|
+
- **Executor Refactor**: Improved `executor.js` structure by replacing global `return` with an `else` block for better readability and standard Node.js practices.
|
|
89
|
+
- **Test Suite Cleanup**: Removed duplicate T54 "Spec Rename History Immutability" scenario from `suite.md`.
|
|
90
|
+
|
|
91
|
+
### Meta
|
|
92
|
+
|
|
93
|
+
- **Automated Update**: Sequential patch bump, history update, and checksum regeneration via `update-engine-meta`.
|
|
94
|
+
|
|
95
|
+
## [1.4.5] - 2026-03-01
|
|
96
|
+
|
|
97
|
+
### Added
|
|
98
|
+
|
|
99
|
+
- **Engine Versioning Protocol (C14)**: Established a mandatory convention requiring a patch version bump in `.magic/.version` whenever core engine files are modified. Integrated checkpoints into all primary workflows (`run.md`, `spec.md`, `rule.md`).
|
|
100
|
+
- **History Refactoring**: Extracted "Document History" from core workflow markdown files into a dedicated `.magic/history/` directory. This significantly reduces token consumption during agentic operations while preserving audit trials.
|
|
101
|
+
- **Node.js Script Transition**: Fully replaced legacy `.sh` and `.ps1` initialization and utility scripts with cross-platform Node.js implementations (`init.js`, `generate-context.js`, etc.).
|
|
102
|
+
|
|
103
|
+
### Changed
|
|
104
|
+
|
|
105
|
+
- **Installer Configuration**: Optimized `installers/config.json` to exclude history files from distribution and prioritize Node.js scripts.
|
|
106
|
+
- **Engine Security**: `generate-checksums.js` and `executor.js` now explicitly skip history files to prevent non-functional changes from triggering integrity warnings.
|
|
107
|
+
- **Template System**: `init.js` now automatically injects the new C14 protocol into target project constitution files (`RULES.md`).
|
|
108
|
+
|
|
109
|
+
### Fixed
|
|
110
|
+
|
|
111
|
+
- **Syntax Hygiene**: Cleaned up redundant markdown artifacts (terminal backticks) in core workflow files.
|
|
112
|
+
- **Workflow Integrity**: Fixed accidental history duplication in `spec.md`.
|
|
113
|
+
|
|
114
|
+
## [1.4.3] - 2026-03-01
|
|
115
|
+
|
|
116
|
+
### Added
|
|
117
|
+
|
|
118
|
+
- **Smart Adapter Updates**: Both Python and Node.js installers now seamlessly verify and update adapter `.mdc`/`.toml` wrapper files during `--update`.
|
|
119
|
+
- **Smart Update Conflict Resolution**: When users manually modify `.cursor/rules/*` wrapper files in their project, the `--update` command now detects the modifications. Users can intelligently choose to skip updates for specific conflicting adapter files, preserving their changes while updating the core `.magic` engine logic.
|
|
120
|
+
|
|
121
|
+
### Fixed
|
|
122
|
+
|
|
123
|
+
- **Updater Integrity**: Modified files that are bypassed during an update via `[s] Skip modified files` now persist their original hashes so they don't get silently overwritten in subsequent updates.
|
|
124
|
+
- **Testing Logic**: Fixed an issue in the `run_tests.py` exhaustive test suite section where failures during adapter testing cycles were mistakenly swallowed, reporting a false "All tests completed successfully".
|
|
125
|
+
|
|
126
|
+
## [1.4.1] - 2026-03-01
|
|
127
|
+
|
|
128
|
+
### Fixed
|
|
129
|
+
|
|
130
|
+
- **Localization**: Translated remaining Russian text in `README.md` Mermaid diagrams to English.
|
|
131
|
+
|
|
132
|
+
## [1.4.0] - 2026-03-01
|
|
133
|
+
|
|
134
|
+
### Added
|
|
135
|
+
|
|
136
|
+
- **Smart Sync Optimization (AOP)** in `analyze.md`: Automated detection of manual renames during project re-analysis. If an orphaned specification matches a new uncovered directory (>80% similarity or title match), it triggers a `[RESCUE]` action instead of delete/create cycle.
|
|
137
|
+
- **Manual Rename Rescue** in `spec.md`: Protocol to globally update references (INDEX, PLAN, TASKS) when a specification file is moved/renamed, preserving task progress.
|
|
138
|
+
- **Regression Tests (T48–T51)**: Added coverage for Engine Integrity guards, Analysis Depth Control, and Smart Sync mechanisms.
|
|
139
|
+
|
|
140
|
+
### Changed
|
|
141
|
+
|
|
142
|
+
- **Test Suite Synchronization**: The `suite.md` version is now synchronized with the core engine version to prevent metadata confusion.
|
|
143
|
+
|
|
144
|
+
## [1.3.2] - 2026-02-28
|
|
145
|
+
|
|
146
|
+
### Added
|
|
147
|
+
|
|
148
|
+
- **Project Analysis Workflow** (`.magic/analyze.md`): Powerful reverse-engineering tool. Delegated automatically from `spec.md` or directly via `/magic.analyze`. Supports scanning existing source code to generate structured proposals with paired Layer 1 (Concept) and Layer 2 (Implementation) specifications. Features Depth Control for massive codebases.
|
|
149
|
+
- **Bootstrapping Exemption**: Special rules added to bypass standard Draft/RFC phases and create "Stable" specs directly when adopting existing working code into the SDD system.
|
|
150
|
+
- **Improv Mode (Live Simulation)** in `simulate.md`: Added ability for the simulation workflow to synthesize "crisis scenarios" (e.g., INDEX.md desync) and perform full SDK lifecycle stress tests end-to-end on its own, functioning as a fallback if the static test suite is missing.
|
|
151
|
+
|
|
152
|
+
### Changed
|
|
153
|
+
|
|
154
|
+
- Expanded Test Suite (`.magic/tests/suite.md`) from 28 to 34 scenarios (+6), fully covering Analyze gap detection, L1/L2 generation asserts, depth control limits, and the missing test suite fallback.
|
|
155
|
+
|
|
156
|
+
## [1.3.1] - 2026-02-27### Added
|
|
157
|
+
|
|
158
|
+
- **Workflow Test Suite** (`.magic/tests/suite.md`): 16 predefined regression test scenarios covering all 8 engine workflows. Run via `/magic.dev.simulate test`.
|
|
159
|
+
- **Test Suite mode** in `simulate.md`: reads `suite.md` and reports PASS/FAIL for each scenario.
|
|
160
|
+
- **Template directory** (`.magic/templates/`): extracted inline templates from core workflow files:
|
|
161
|
+
- `specification.md` — Specification Template (from `spec.md`)
|
|
162
|
+
- `plan.md` — PLAN.md Template (from `task.md`)
|
|
163
|
+
- `tasks.md` — TASKS.md + phase-{n}.md Templates (from `task.md`)
|
|
164
|
+
- `retrospective.md` — RETROSPECTIVE.md Template (from `retrospective.md`)
|
|
165
|
+
|
|
166
|
+
### Changed
|
|
167
|
+
|
|
168
|
+
- **AOP Optimization**: Compressed verbose prose in `spec.md` (Post-Update Review, Audit/Consistency Reports). ~17% token reduction across core workflows.
|
|
169
|
+
- **Stress-test hardening** across all workflows:
|
|
170
|
+
- `spec.md`: Intra-input self-contradiction guard, Deprecation Cascade (scan Related Specs for stale refs)
|
|
171
|
+
- `task.md`: Circular Dependency Guard, Phantom Done-task preservation (Archive not Cancel), Deprecated Done-task preservation, Convention Sync wording fix
|
|
172
|
+
- `run.md`: Mode Guard — HALT if execution mode not in RULES.md §7
|
|
173
|
+
- `rule.md`: Duplication Guard, convention-not-found handler, Workflow Dependency Check in Remove Impact Analysis
|
|
174
|
+
- `simulate.md`: Checksums mismatch upgraded to HALT, Checksum Rule (generate after approval only)
|
|
175
|
+
- `onboard.md`: Production collision HALT with backup/cancel, re-entry checks production PLAN.md
|
|
176
|
+
- `init.md`: Expanded post-init verification to all 5 artifacts, Maintainer Note for hardcoded RULES.md sync
|
|
177
|
+
|
|
178
|
+
### Fixed
|
|
179
|
+
|
|
180
|
+
- Template references now explicitly point to `.magic/templates/*.md` in creation steps of `spec.md`, `task.md`, `retrospective.md`, and `onboard.md`.
|
|
181
|
+
|
|
182
|
+
## [1.3.0] - 2026-02-25
|
|
183
|
+
|
|
184
|
+
### Added
|
|
185
|
+
|
|
186
|
+
- **Full support for abstract environment templates** with automatic resolution (`{ARGUMENTS}`) across all CLIs.
|
|
187
|
+
- **Introduced `.magicrc`** for persistence of selected environments and their auto-detection.
|
|
188
|
+
- **Two-level automatic Changelog generation** (by accumulating `Changes` blocks within tasks).
|
|
189
|
+
- **Added new CLI commands:** `info`, `--check`, `--list-envs`, and `--eject`.
|
|
190
|
+
- **Introduced core version tracking** within the project via the `.magic/.version` file.
|
|
191
|
+
|
|
192
|
+
### Changed
|
|
193
|
+
|
|
194
|
+
- **Architecture:** Restructured the repository into a two-level model (root = source of truth + installers), and removed the `core/` folder to eliminate duplication.
|
|
195
|
+
- **Node Installer:** Completely overhauled the installation mechanism (it now uses compiled files from NPM instead of downloading them from GitHub, eliminating Path Traversal vulnerabilities).
|
|
196
|
+
- **Python Installer:** Implemented an isolated package based on `hatchling` (via shared-data) without external dependencies on GitHub.
|
|
197
|
+
- **Documentation:** Separated `README.md` strategies (different focuses for GitHub, NPM package, and PyPI package).
|
|
198
|
+
- **Update Logic:** Improved `.magic` update logic to be safer (old folders are now moved to `.magic/archives/` rather than simply deleted).
|
|
199
|
+
|
|
200
|
+
## [1.3.0] - 2026-02-23
|
|
201
|
+
|
|
202
|
+
### Added
|
|
203
|
+
|
|
204
|
+
- **Handoff integrations** (`magic.*.md`): Introduced explicit handoff blocks across all agent workflow wrappers to guide next-steps effortlessly.
|
|
205
|
+
- **Task Engine Enhancement:** Integrated User Stories generation parsing into `.magic/task.md` and suppressed user priority prompts using `RULES.md C4`.
|
|
206
|
+
- **System Automation Hooks:** Added `generate-context` script hooks into `task.md` and `run.md` post-write triggers.
|
|
207
|
+
- **Context Automation Script:** Created `generate-context.sh` and `generate-context.ps1` to assemble `CONTEXT.md` from PLAN, workspace trees, and changelogs.
|
|
208
|
+
- **Spec Engine Protections:** Added strict Explore Mode Safety rules and Delta Editing constraints for spec updates over 200 lines to `.magic/spec.md`.
|
|
209
|
+
- **Explore Hints:** Updated `.agents/workflows/magic.spec.md` UI wrapper with tips to use Delta Constraints and strict read-only explore mode.
|
|
210
|
+
- **CLI Doctor Command (Node/Python):** Implemented `--doctor` and `--check` parsing in installers, executing the prerequisite script and outputting a formatted terminal validation report.
|
|
211
|
+
- **Interactive Onboarding Script:** Created `.magic/onboard.md` to guide new developers through building a toy "console logger" specification.
|
|
212
|
+
- **Onboarding Wrapper:** Added `.agents/workflows/magic.onboard.md` to trigger the interactive onboarding tutorial seamlessly.
|
|
213
|
+
- **Prerequisite Validation:** Created `check-prerequisites.sh` and `check-prerequisites.ps1` parsing `INDEX.md` and returning valid JSON results.
|
package/README.md
CHANGED
|
@@ -36,15 +36,14 @@ After running the installer, your project directory will be augmented with the f
|
|
|
36
36
|
|
|
37
37
|
```plaintext
|
|
38
38
|
root-project/
|
|
39
|
-
├── .
|
|
39
|
+
├── .agents/workflows/ # Slash commands wrapper (e.g., magic.spec, magic.task)
|
|
40
40
|
├── .magic/ # The SDD Engine (workflow logic and scripts - read-only)
|
|
41
41
|
└── .design/ # Your Project Design Workspace (INDEX.md, RULES.md, PLAN.md)
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
1. **`.magic/`**: Deploys the core SDD engine.
|
|
45
|
-
2. **`.
|
|
45
|
+
2. **`.agents/`**: Sets up workflows for your AI.
|
|
46
46
|
3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
|
|
47
|
-
4. **Onboarding**: An interactive tutorial (`magic.onboard`) helps you and your AI get started smoothly.
|
|
48
47
|
|
|
49
48
|
> [!TIP]
|
|
50
49
|
> **Magic Workspaces**: Magic Spec supports multiple, isolated design environments within a single repository (e.g., `.design/engine/`, `.design/installers/`). This allows you to manage fundamentally different project domains without specification overlap, while sharing a single core engine. See [workspaces.md](./workspaces.md) for details.
|
|
@@ -55,16 +54,23 @@ root-project/
|
|
|
55
54
|
|
|
56
55
|
Magic Spec is built around a single conviction: **AI agents write better code when they are forced to think before they act.** Left unconstrained, they jump straight to implementation — producing code that is fragile, misaligned, and expensive to refactor. Magic Spec installs a structured pipeline that makes this impossible.
|
|
57
56
|
|
|
58
|
-
### Human-Minimal Engineering
|
|
57
|
+
### Human-Minimal Engineering (Autonomous Partner)
|
|
59
58
|
|
|
60
|
-
The core design goal is to **keep humans out of the loop as much as possible** — without sacrificing control over what actually matters.
|
|
59
|
+
The core design goal is to **keep humans out of the loop as much as possible** — without sacrificing control over what actually matters. Magic Spec moves from manual "Status Gates" to an **Autonomous Partner** model.
|
|
60
|
+
|
|
61
|
+
#### Trust Mode: Encapsulated Logic
|
|
61
62
|
|
|
62
63
|
Once you describe what you want, the engine takes over:
|
|
63
64
|
|
|
64
|
-
-
|
|
65
|
-
-
|
|
66
|
-
|
|
67
|
-
|
|
65
|
+
- **Type A — "AI Trust"**: You provide intent, the agent handles the rest (`Draft -> RFC -> Stable -> Plan -> Run`). The internal SDD ceremony is **encapsulated** — you only see the result and a final "Go" gate.
|
|
66
|
+
- **Type B — "Expert Audit"**: You maintain full control. Inspect `.design/` at any time to review specifications and plans. The rigor is there for when you need it.
|
|
67
|
+
|
|
68
|
+
#### Silent Orchestration
|
|
69
|
+
|
|
70
|
+
- **Auto-Stabilization**: Specifications are drafted, reviewed, and promoted to `Stable` automatically if the logic is clear.
|
|
71
|
+
- **Zero-Prompt Planning**: Tasks are decomposed, prioritized, and scheduled without interrupting your flow.
|
|
72
|
+
- **Silent Operations**: Phases execute end-to-end: retrospectives, changelogs, and context regeneration happen silently.
|
|
73
|
+
- **Single Execution Gate**: The only mandatory prompt is the final sign-off before implementation begins.
|
|
68
74
|
|
|
69
75
|
Everything else is automated. The agent does the engineering. You approve the direction.
|
|
70
76
|
|
|
@@ -87,6 +93,7 @@ This separation prevents a common failure mode in AI-assisted development: mixin
|
|
|
87
93
|
The engine actively protects specification integrity throughout the project lifecycle:
|
|
88
94
|
|
|
89
95
|
- **Quarantine Cascade**: If a Layer 1 spec is destabilized (demoted from `Stable`), all dependent Layer 2 specs are automatically flagged and their tasks are blocked. The plan cannot proceed on a broken foundation.
|
|
96
|
+
- **Session Isolation (Phase Gates)**: To prevent AI "hallucinations" and context bleed-over, major workflow transitions enforce a **Hard Stop** (e.g., from Specification to Planning). You are required to physically open a "New Chat" in your IDE to proceed. Simply telling the AI to "forget" does not clear its context window reliably.
|
|
90
97
|
- **Registry Parity**: Every spec that exists on disk must be registered in `INDEX.md`. Every registered spec must appear in the implementation plan or the backlog. Orphaned specs are treated as critical blockers.
|
|
91
98
|
- **Rules Parity**: If project conventions change (`RULES.md`), any existing task plan is flagged as stale. The agent will not execute tasks generated under outdated rules without an explicit sync.
|
|
92
99
|
- **Engine Integrity**: Core engine files are checksummed. Any untracked modification halts all workflows until the engine state is reconciled.
|
|
@@ -164,7 +171,7 @@ Works perfectly with **any project** — Rust, Go, Python, JavaScript, C++, or a
|
|
|
164
171
|
**Stable Release:**
|
|
165
172
|
|
|
166
173
|
```bash
|
|
167
|
-
# Basic installation (defaults to .
|
|
174
|
+
# Basic installation (defaults to .agents/ folder)
|
|
168
175
|
npx magic-spec@latest
|
|
169
176
|
|
|
170
177
|
# Targeted installation for Cursor
|
|
@@ -214,7 +221,7 @@ npx magic-spec@latest --cursor --copilot --windsurf
|
|
|
214
221
|
If automated installers do not fit your environment:
|
|
215
222
|
|
|
216
223
|
1. **Engine**: Download the `.magic/` folder from the [GitHub repository](https://github.com/teratron/magic-spec).
|
|
217
|
-
2. **Workflows**: Download command wrappers from [
|
|
224
|
+
2. **Workflows**: Download command wrappers from [`workflows/`](https://github.com/teratron/magic-spec/tree/main/workflows).
|
|
218
225
|
3. **Deploy**: Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
|
|
219
226
|
|
|
220
227
|
## 🔄 Updating
|
|
@@ -230,13 +237,21 @@ npx magic-spec@latest --update
|
|
|
230
237
|
```
|
|
231
238
|
|
|
232
239
|
> [!TIP]
|
|
233
|
-
> The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.
|
|
240
|
+
> The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.agents/` folders. If you have modified core engine files, the installer will detect conflicts and ask for your preference (overwrite, skip, or abort).
|
|
241
|
+
|
|
242
|
+
### Post-Install: `.gitignore`
|
|
243
|
+
|
|
244
|
+
The installer automatically adds `.magic/` and the adapter directory (e.g., `.agents/`, `.cursor/rules/`) to your project's `.gitignore`. These directories are **installed dependencies** — similar to `node_modules/` — and should be reinstalled via `npx magic-spec@latest` rather than committed to version control.
|
|
245
|
+
|
|
246
|
+
> [!TIP]
|
|
247
|
+
> **Vendoring**: If you prefer to commit the engine into your repository (so teammates get it without running the installer), simply remove the `.magic/` and `.agents/` entries from your `.gitignore`.
|
|
234
248
|
|
|
235
249
|
## 💬 Usage
|
|
236
250
|
|
|
237
251
|
Just talk to your AI agent naturally in your prompt interface. No complex commands to learn:
|
|
238
252
|
|
|
239
253
|
- *"Dispatch this thought into specs..."* → Triggers **Specification** workflow.
|
|
254
|
+
- *"Run a project audit"*, *"magic.analyze"* → Triggers **Analyze** (Ventilation) workflow.
|
|
240
255
|
- *"Create an implementation plan"* → Triggers **Task & Plan** workflow.
|
|
241
256
|
- *"Execute the next task"* → Triggers **Run** workflow.
|
|
242
257
|
- *"Add a rule: always use Inter font"* → Triggers **Rule** workflow.
|
|
@@ -273,14 +288,13 @@ You can install support for a specific adapter using the shortcut flag (e.g., `-
|
|
|
273
288
|
|
|
274
289
|
- [**Main Documentation**](./docs/README.md) — Detailed guide on workflows, architecture, and advanced features.
|
|
275
290
|
- [**Installers Guide**](./installers/README.md) — Advanced CLI options and platform specifics.
|
|
276
|
-
- [**Contributing**](./
|
|
291
|
+
- [**Contributing**](./CONTRIBUTING.md) — How to develop, test, and extend the engine.
|
|
277
292
|
|
|
278
293
|
## 🛟 Support
|
|
279
294
|
|
|
280
295
|
If you encounter issues or have questions:
|
|
281
296
|
|
|
282
297
|
- Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
|
|
283
|
-
- Run `magic.onboard` in your agent to restart the interactive tutorial.
|
|
284
298
|
|
|
285
299
|
## 🗺️ Roadmap
|
|
286
300
|
|
|
@@ -293,7 +307,7 @@ If you encounter issues or have questions:
|
|
|
293
307
|
## 🏗️ Contributing
|
|
294
308
|
|
|
295
309
|
We welcome contributions! Whether it's a bug fix, a new adapter, or an improvement to the workflow logic.
|
|
296
|
-
Please see [**Contributing Guide**](./
|
|
310
|
+
Please see [**Contributing Guide**](./CONTRIBUTING.md) for details.
|
|
297
311
|
|
|
298
312
|
## 👥 Authors and Acknowledgments
|
|
299
313
|
|
package/installers/config.json
CHANGED
|
@@ -1,26 +1,27 @@
|
|
|
1
1
|
{
|
|
2
2
|
"githubRepo": "teratron/magic-spec",
|
|
3
3
|
"packageName": "magic-spec",
|
|
4
|
-
"removePrefix": "magic.",
|
|
5
4
|
"engineDir": ".magic",
|
|
6
|
-
"agentDir": ".
|
|
5
|
+
"agentDir": ".agents",
|
|
7
6
|
"workflowsDir": "workflows",
|
|
8
7
|
"defaultExt": ".md",
|
|
8
|
+
"designDir": ".design",
|
|
9
|
+
"versionFile": ".version",
|
|
10
|
+
"checksumsFile": ".checksums",
|
|
11
|
+
"historyDir": "history",
|
|
9
12
|
"workflows": [
|
|
10
|
-
"magic.
|
|
13
|
+
"magic.analyze",
|
|
11
14
|
"magic.rule",
|
|
12
15
|
"magic.run",
|
|
13
|
-
"magic.simulate",
|
|
14
16
|
"magic.spec",
|
|
15
17
|
"magic.task"
|
|
16
18
|
],
|
|
17
19
|
"magicFiles": [
|
|
18
20
|
"analyze.md",
|
|
19
|
-
"
|
|
21
|
+
"init.md",
|
|
20
22
|
"retrospective.md",
|
|
21
23
|
"rule.md",
|
|
22
24
|
"run.md",
|
|
23
|
-
"simulate.md",
|
|
24
25
|
"spec.md",
|
|
25
26
|
"task.md",
|
|
26
27
|
".version",
|
|
@@ -32,40 +33,36 @@
|
|
|
32
33
|
"scripts/init.js",
|
|
33
34
|
"templates/plan.md",
|
|
34
35
|
"templates/retrospective.md",
|
|
35
|
-
"templates/
|
|
36
|
+
"templates/spec.md",
|
|
36
37
|
"templates/tasks.md"
|
|
37
38
|
],
|
|
38
39
|
"download": {
|
|
39
|
-
"timeoutMs":
|
|
40
|
-
"tempPrefix": "magic-spec-"
|
|
40
|
+
"timeoutMs": 10000,
|
|
41
|
+
"tempPrefix": "magic-spec-tmp-"
|
|
41
42
|
},
|
|
42
43
|
"userAgent": {
|
|
43
|
-
"
|
|
44
|
-
"
|
|
44
|
+
"python": "magic-spec-python-installer/1.0",
|
|
45
|
+
"node": "magic-spec-node-installer/1.0"
|
|
45
46
|
},
|
|
46
47
|
"eject": {
|
|
47
48
|
"targets": [
|
|
48
49
|
".magic",
|
|
49
|
-
".
|
|
50
|
-
"
|
|
51
|
-
".agent.bak"
|
|
50
|
+
".agents",
|
|
51
|
+
"installers"
|
|
52
52
|
]
|
|
53
53
|
},
|
|
54
54
|
"publish": {
|
|
55
55
|
"versionFiles": [
|
|
56
|
-
"pyproject.toml",
|
|
57
|
-
"installers/python/magic_spec/__init__.py",
|
|
58
56
|
"package.json",
|
|
59
|
-
".
|
|
57
|
+
"pyproject.toml",
|
|
58
|
+
"installers/python/magic_spec/__init__.py"
|
|
60
59
|
],
|
|
61
60
|
"docsTargets": [
|
|
62
|
-
"README.md",
|
|
63
61
|
"CHANGELOG.md"
|
|
64
|
-
]
|
|
65
|
-
"docsDir": "docs"
|
|
62
|
+
]
|
|
66
63
|
},
|
|
67
64
|
"tests": {
|
|
68
|
-
"sandboxDir": "
|
|
65
|
+
"sandboxDir": "tmp/sandbox",
|
|
69
66
|
"adaptersJson": "installers/adapters.json",
|
|
70
67
|
"pythonInstaller": "installers/python/magic_spec/__main__.py",
|
|
71
68
|
"nodeInstaller": "installers/node/index.js",
|
package/installers/node/index.js
CHANGED
|
@@ -77,6 +77,11 @@ function loadInstallerConfig() {
|
|
|
77
77
|
failConfig("field 'magicFiles' must be an array of strings");
|
|
78
78
|
}
|
|
79
79
|
|
|
80
|
+
const designDir = requireNonEmptyString(parsed.designDir, 'designDir');
|
|
81
|
+
const versionFile = requireNonEmptyString(parsed.versionFile, 'versionFile');
|
|
82
|
+
const checksumsFile = requireNonEmptyString(parsed.checksumsFile, 'checksumsFile');
|
|
83
|
+
const historyDir = requireNonEmptyString(parsed.historyDir, 'historyDir');
|
|
84
|
+
|
|
80
85
|
return {
|
|
81
86
|
githubRepo,
|
|
82
87
|
packageName,
|
|
@@ -84,6 +89,10 @@ function loadInstallerConfig() {
|
|
|
84
89
|
engineDir,
|
|
85
90
|
agentDir,
|
|
86
91
|
workflowsDir,
|
|
92
|
+
designDir,
|
|
93
|
+
versionFile,
|
|
94
|
+
checksumsFile,
|
|
95
|
+
historyDir,
|
|
87
96
|
defaultExt,
|
|
88
97
|
workflows,
|
|
89
98
|
magicFiles,
|
|
@@ -102,6 +111,10 @@ const WORKFLOWS_DIR = INSTALLER_CONFIG.workflowsDir;
|
|
|
102
111
|
const DEFAULT_EXT = INSTALLER_CONFIG.defaultExt;
|
|
103
112
|
const WORKFLOWS = INSTALLER_CONFIG.workflows;
|
|
104
113
|
const MAGIC_FILES = INSTALLER_CONFIG.magicFiles;
|
|
114
|
+
const DESIGN_DIR = INSTALLER_CONFIG.designDir;
|
|
115
|
+
const VERSION_FILE = INSTALLER_CONFIG.versionFile;
|
|
116
|
+
const CHECKSUMS_FILE = INSTALLER_CONFIG.checksumsFile;
|
|
117
|
+
const HISTORY_DIR = INSTALLER_CONFIG.historyDir;
|
|
105
118
|
const DEFAULT_REMOVE_PREFIX = INSTALLER_CONFIG.removePrefix;
|
|
106
119
|
const DOWNLOAD_TIMEOUT_MS = INSTALLER_CONFIG.download.timeoutMs;
|
|
107
120
|
const NODE_USER_AGENT = INSTALLER_CONFIG.userAgent.node;
|
|
@@ -178,6 +191,45 @@ function copyDir(src, dest) {
|
|
|
178
191
|
fs.cpSync(src, dest, { recursive: true, force: true });
|
|
179
192
|
}
|
|
180
193
|
|
|
194
|
+
function appendToGitignore(entries) {
|
|
195
|
+
const gitignoreFile = path.join(cwd, '.gitignore');
|
|
196
|
+
let content = '';
|
|
197
|
+
if (fs.existsSync(gitignoreFile)) {
|
|
198
|
+
content = fs.readFileSync(gitignoreFile, 'utf8');
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
const added = [];
|
|
202
|
+
for (const entry of entries) {
|
|
203
|
+
// Normalize: ensure trailing slash for directories
|
|
204
|
+
const normalized = entry.endsWith('/') ? entry : entry + '/';
|
|
205
|
+
// Check if already present (with or without trailing slash)
|
|
206
|
+
const base = normalized.replace(/\/$/, '');
|
|
207
|
+
const alreadyPresent = content.split(/\r?\n/).some(line => {
|
|
208
|
+
const trimmed = line.trim();
|
|
209
|
+
return trimmed === base || trimmed === normalized;
|
|
210
|
+
});
|
|
211
|
+
if (!alreadyPresent) {
|
|
212
|
+
added.push(normalized);
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
if (added.length === 0) return;
|
|
217
|
+
|
|
218
|
+
// Append under a Magic Spec section header
|
|
219
|
+
const section = '\n# Magic Spec (engine & workflows — installed via npx/uvx)';
|
|
220
|
+
const hasSection = content.includes('# Magic Spec');
|
|
221
|
+
let appendBlock = '';
|
|
222
|
+
if (!hasSection) {
|
|
223
|
+
appendBlock = section + '\n';
|
|
224
|
+
}
|
|
225
|
+
appendBlock += added.join('\n');
|
|
226
|
+
|
|
227
|
+
content = content.trimEnd() + '\n' + appendBlock + '\n';
|
|
228
|
+
fs.writeFileSync(gitignoreFile, content, 'utf8');
|
|
229
|
+
console.log(`📝 Updated .gitignore: added ${added.join(', ')}`);
|
|
230
|
+
console.log(` 💡 To vendor engine files in your repo, remove these entries.`);
|
|
231
|
+
}
|
|
232
|
+
|
|
181
233
|
function convertToToml(content, description) {
|
|
182
234
|
// Escape quotes and backslashes for TOML triple-quoted strings
|
|
183
235
|
const escapedContent = content
|
|
@@ -245,7 +297,7 @@ function installAdapter(sourceRoot, env, adapters, conflictsToSkip = []) {
|
|
|
245
297
|
installedChecksums[relTarget] = crypto.createHash('sha256').update(finalContent).digest('hex');
|
|
246
298
|
}
|
|
247
299
|
|
|
248
|
-
// Copy other files in .
|
|
300
|
+
// Copy other files in .agents if any
|
|
249
301
|
const srcEng = path.join(sourceRoot, AGENT_DIR);
|
|
250
302
|
if (fs.existsSync(srcEng)) {
|
|
251
303
|
const items = fs.readdirSync(srcEng, { withFileTypes: true });
|
|
@@ -327,7 +379,7 @@ function runDoctor() {
|
|
|
327
379
|
console.log(`✅ ${item.path || name} is present`);
|
|
328
380
|
} else {
|
|
329
381
|
const hint = requiredHint ? ` (Hint: ${requiredHint})` : '';
|
|
330
|
-
console.log(`❌
|
|
382
|
+
console.log(`❌ ${DESIGN_DIR}/${name} is missing${hint}`);
|
|
331
383
|
}
|
|
332
384
|
};
|
|
333
385
|
|
|
@@ -363,12 +415,12 @@ function runInfo() {
|
|
|
363
415
|
console.log('magic-spec installation status');
|
|
364
416
|
console.log('────────────────────────────────');
|
|
365
417
|
|
|
366
|
-
const
|
|
418
|
+
const versionFilePath = path.join(cwd, ENGINE_DIR, VERSION_FILE);
|
|
367
419
|
let installedVersion = 'none';
|
|
368
|
-
if (fs.existsSync(
|
|
369
|
-
installedVersion = fs.readFileSync(
|
|
420
|
+
if (fs.existsSync(versionFilePath)) {
|
|
421
|
+
installedVersion = fs.readFileSync(versionFilePath, 'utf8').trim();
|
|
370
422
|
}
|
|
371
|
-
console.log(`Installed version : ${installedVersion} (
|
|
423
|
+
console.log(`Installed version : ${installedVersion} (${ENGINE_DIR}/${VERSION_FILE})`);
|
|
372
424
|
|
|
373
425
|
const ADAPTERS_PATH = path.join(__dirname, '..', 'adapters.json');
|
|
374
426
|
let activeEnvs = [];
|
|
@@ -387,8 +439,8 @@ function runInfo() {
|
|
|
387
439
|
const enginePresent = fs.existsSync(path.join(cwd, ENGINE_DIR));
|
|
388
440
|
console.log(`Engine : ${ENGINE_DIR}/ ${enginePresent ? '✅ present' : '❌ missing'}`);
|
|
389
441
|
|
|
390
|
-
const designPresent = fs.existsSync(path.join(cwd,
|
|
391
|
-
console.log(`Workspace :
|
|
442
|
+
const designPresent = fs.existsSync(path.join(cwd, DESIGN_DIR));
|
|
443
|
+
console.log(`Workspace : ${DESIGN_DIR}/ ${designPresent ? '✅ present' : '❌ missing'}`);
|
|
392
444
|
|
|
393
445
|
console.log('────────────────────────────────');
|
|
394
446
|
console.log(`Run \`npx ${PACKAGE_NAME}@latest --update\` to refresh engine files.`);
|
|
@@ -396,9 +448,9 @@ function runInfo() {
|
|
|
396
448
|
}
|
|
397
449
|
|
|
398
450
|
function runCheck() {
|
|
399
|
-
const versionFile = path.join(cwd, ENGINE_DIR,
|
|
451
|
+
const versionFile = path.join(cwd, ENGINE_DIR, VERSION_FILE);
|
|
400
452
|
if (!fs.existsSync(versionFile)) {
|
|
401
|
-
console.log(`⚠️ Not installed via magic-spec (no ${ENGINE_DIR}
|
|
453
|
+
console.log(`⚠️ Not installed via magic-spec (no ${ENGINE_DIR}/${VERSION_FILE} file)`);
|
|
402
454
|
process.exit(0);
|
|
403
455
|
}
|
|
404
456
|
|
|
@@ -451,7 +503,7 @@ async function runEject() {
|
|
|
451
503
|
console.log(` - ${ENGINE_DIR}/`);
|
|
452
504
|
console.log(` - ${AGENT_DIR}/ (or active env adapter dir)`);
|
|
453
505
|
console.log(` - ${ENGINE_DIR}.bak/ (if exists)`);
|
|
454
|
-
console.log(
|
|
506
|
+
console.log(`\n Your ${DESIGN_DIR}/ workspace will NOT be affected.`);
|
|
455
507
|
|
|
456
508
|
let shouldRun = autoAccept;
|
|
457
509
|
if (!shouldRun) {
|
|
@@ -500,10 +552,10 @@ function getDirectoryChecksums(dir, baseDir = dir) {
|
|
|
500
552
|
for (const item of items) {
|
|
501
553
|
const fullPath = path.join(dir, item.name);
|
|
502
554
|
if (item.isDirectory()) {
|
|
503
|
-
if (item.name ===
|
|
555
|
+
if (item.name === CHECKSUMS_FILE || item.name === HISTORY_DIR) continue;
|
|
504
556
|
Object.assign(results, getDirectoryChecksums(fullPath, baseDir));
|
|
505
557
|
} else {
|
|
506
|
-
if (item.name ===
|
|
558
|
+
if (item.name === CHECKSUMS_FILE) continue;
|
|
507
559
|
const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
|
|
508
560
|
results[relPath] = getFileChecksum(fullPath);
|
|
509
561
|
}
|
|
@@ -512,22 +564,22 @@ function getDirectoryChecksums(dir, baseDir = dir) {
|
|
|
512
564
|
}
|
|
513
565
|
|
|
514
566
|
async function handleConflicts(cwd) {
|
|
515
|
-
const
|
|
516
|
-
if (!fs.existsSync(
|
|
567
|
+
const checksumsFilePath = path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE);
|
|
568
|
+
if (!fs.existsSync(checksumsFilePath)) return;
|
|
517
569
|
|
|
518
570
|
let storedChecksums = {};
|
|
519
571
|
try {
|
|
520
|
-
storedChecksums = JSON.parse(fs.readFileSync(
|
|
572
|
+
storedChecksums = JSON.parse(fs.readFileSync(checksumsFilePath, 'utf8'));
|
|
521
573
|
} catch (e) {
|
|
522
574
|
return;
|
|
523
575
|
}
|
|
524
576
|
|
|
525
577
|
const conflicts = [];
|
|
526
578
|
for (const [relPath, storedHash] of Object.entries(storedChecksums)) {
|
|
527
|
-
if (relPath ===
|
|
579
|
+
if (relPath === CHECKSUMS_FILE || relPath === VERSION_FILE) continue;
|
|
528
580
|
|
|
529
|
-
// Backward compatibility: try
|
|
530
|
-
let localPath = path.join(cwd,
|
|
581
|
+
// Backward compatibility: try engine dir first, then project root
|
|
582
|
+
let localPath = path.join(cwd, ENGINE_DIR, relPath);
|
|
531
583
|
if (!fs.existsSync(localPath)) {
|
|
532
584
|
localPath = path.join(cwd, relPath);
|
|
533
585
|
}
|
|
@@ -733,6 +785,7 @@ async function main() {
|
|
|
733
785
|
}
|
|
734
786
|
|
|
735
787
|
try {
|
|
788
|
+
let selectedEnvResolved = null;
|
|
736
789
|
if (!isLocal) {
|
|
737
790
|
sourceRoot = await downloadPayload(versionToFetch);
|
|
738
791
|
}
|
|
@@ -840,7 +893,7 @@ async function main() {
|
|
|
840
893
|
}
|
|
841
894
|
}
|
|
842
895
|
|
|
843
|
-
// Copy other files in .
|
|
896
|
+
// Copy other files in .agents if any (not workflows subfolder which we handled selectively)
|
|
844
897
|
if (fs.existsSync(srcEng)) {
|
|
845
898
|
const items = fs.readdirSync(srcEng, { withFileTypes: true });
|
|
846
899
|
for (const item of items) {
|
|
@@ -863,8 +916,8 @@ async function main() {
|
|
|
863
916
|
if (!isUpdate) {
|
|
864
917
|
const isWindows = process.platform === 'win32';
|
|
865
918
|
const initScript = isWindows
|
|
866
|
-
? path.join(cwd,
|
|
867
|
-
: path.join(cwd,
|
|
919
|
+
? path.join(cwd, ENGINE_DIR, 'scripts', 'init.ps1')
|
|
920
|
+
: path.join(cwd, ENGINE_DIR, 'scripts', 'init.sh');
|
|
868
921
|
|
|
869
922
|
if (fs.existsSync(initScript)) {
|
|
870
923
|
let shouldRun = true;
|
|
@@ -901,21 +954,36 @@ async function main() {
|
|
|
901
954
|
console.log(`✅ ${PACKAGE_NAME} updated successfully!`);
|
|
902
955
|
}
|
|
903
956
|
|
|
904
|
-
// 4. Write version file
|
|
957
|
+
// 4. Write version file - [T-2B01]
|
|
905
958
|
try {
|
|
906
|
-
const
|
|
907
|
-
fs.writeFileSync(
|
|
959
|
+
const versionFileDest = path.join(cwd, ENGINE_DIR, VERSION_FILE);
|
|
960
|
+
fs.writeFileSync(versionFileDest, version, 'utf8');
|
|
908
961
|
} catch (vErr) {
|
|
909
|
-
console.warn(`⚠️ Failed to write
|
|
962
|
+
console.warn(`⚠️ Failed to write ${ENGINE_DIR}/${VERSION_FILE}: ${vErr.message}`);
|
|
910
963
|
}
|
|
911
964
|
|
|
965
|
+
// 5. Auto-update .gitignore
|
|
966
|
+
const gitignoreEntries = [ENGINE_DIR];
|
|
967
|
+
if (envValues.length > 0) {
|
|
968
|
+
for (const env of envValues) {
|
|
969
|
+
const adapter = ADAPTERS[env];
|
|
970
|
+
if (adapter && adapter.dest) {
|
|
971
|
+
gitignoreEntries.push(adapter.dest);
|
|
972
|
+
}
|
|
973
|
+
}
|
|
974
|
+
} else if (selectedEnvResolved && ADAPTERS[selectedEnvResolved]) {
|
|
975
|
+
gitignoreEntries.push(ADAPTERS[selectedEnvResolved].dest);
|
|
976
|
+
} else {
|
|
977
|
+
gitignoreEntries.push(AGENT_DIR);
|
|
978
|
+
}
|
|
979
|
+
appendToGitignore(gitignoreEntries);
|
|
912
980
|
|
|
913
981
|
// 6. Save checksums - [T-2C03]
|
|
914
982
|
try {
|
|
915
|
-
const currentChecksums = getDirectoryChecksums(path.join(cwd,
|
|
983
|
+
const currentChecksums = getDirectoryChecksums(path.join(cwd, ENGINE_DIR));
|
|
916
984
|
|
|
917
985
|
if (isUpdate) {
|
|
918
|
-
const checksumsFile = path.join(cwd,
|
|
986
|
+
const checksumsFile = path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE);
|
|
919
987
|
if (fs.existsSync(checksumsFile)) {
|
|
920
988
|
try {
|
|
921
989
|
const oldChecksums = JSON.parse(fs.readFileSync(checksumsFile, 'utf8'));
|
|
@@ -930,7 +998,7 @@ async function main() {
|
|
|
930
998
|
|
|
931
999
|
Object.assign(currentChecksums, adapterChecksums);
|
|
932
1000
|
|
|
933
|
-
fs.writeFileSync(path.join(cwd,
|
|
1001
|
+
fs.writeFileSync(path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE), JSON.stringify(currentChecksums, null, 2), 'utf8');
|
|
934
1002
|
} catch (cErr) {
|
|
935
1003
|
console.warn(`⚠️ Failed to save checksums: ${cErr.message}`);
|
|
936
1004
|
}
|