magic-spec 1.4.1 → 1.4.3

package/CHANGELOG.md

@@ -5,7 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.4.1] - 2026-03-01
+## [1.4.3] - 2026-03-01
+
+### Added
+
+- **Smart Adapter Updates**: Both Python and Node.js installers now seamlessly verify and update adapter `.mdc`/`.toml` wrapper files during `--update`.
+- **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.
+
+### Fixed
+
+- **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.
+- **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".
+
+## [1.4.3] - 2026-03-01
 
 ### Fixed
 

package/installers/config.json

@@ -65,5 +65,13 @@
             "CHANGELOG.md"
         ],
         "docsDir": "docs"
+    },
+    "tests": {
+        "sandboxDir": "installers/tests/sandbox",
+        "adaptersJson": "installers/adapters.json",
+        "pythonInstaller": "installers/python/magic_spec/__main__.py",
+        "nodeInstaller": "installers/node/index.js",
+        "testDir": "installers/tests",
+        "testPattern": "test_*.py"
     }
 }

package/installers/node/index.js

@@ -116,6 +116,7 @@ const isInfo = args.includes('info');
 const isListEnvs = args.includes('--list-envs');
 const isEject = args.includes('--eject');
 const isFallbackMain = args.includes('--fallback-main');
+const isLocal = args.includes('--local');
 const autoAccept = args.includes('--yes') || args.includes('-y');
 
 function parseCsvValues(raw) {
@@ -189,14 +190,15 @@ function convertToMdc(content, description) {
     return `---\ndescription: ${description || ''}\nglobs: \n---\n${content}`;
 }
 
-function installAdapter(sourceRoot, env, adapters) {
+function installAdapter(sourceRoot, env, adapters, conflictsToSkip = []) {
+    const installedChecksums = {};
     const adapter = adapters[env];
     if (!adapter) {
         console.warn(`⚠️  Unknown --env value: "${env}".`);
         console.warn(`   Valid values: ${Object.keys(adapters).join(', ')}`);
         console.warn(`   Falling back to default ${AGENT_DIR}/`);
         copyDir(path.join(sourceRoot, AGENT_DIR), path.join(cwd, AGENT_DIR));
-        return;
+        return installedChecksums;
     }
 
     const srcDir = path.join(sourceRoot, AGENT_DIR, WORKFLOWS_DIR);
@@ -204,9 +206,12 @@ function installAdapter(sourceRoot, env, adapters) {
 
     if (!fs.existsSync(srcDir)) {
         console.warn(`⚠️  Source ${AGENT_DIR}/${WORKFLOWS_DIR}/ not found.`);
-        return;
+        return installedChecksums;
     }
 
+    if (adapter.marker) {
+        fs.mkdirSync(path.join(cwd, adapter.marker), { recursive: true });
+    }
     fs.mkdirSync(destDir, { recursive: true });
 
     for (const wfName of WORKFLOWS) {
@@ -221,22 +226,56 @@ function installAdapter(sourceRoot, env, adapters) {
                 destName = destName.slice(removePrefix.length);
             }
         }
+
         const destFile = path.join(destDir, destName);
+        const relTarget = path.relative(cwd, destFile).replace(/\\/g, '/');
+
+        if (conflictsToSkip.includes(relTarget)) continue;
+
+        const content = fs.readFileSync(srcFile, 'utf8');
+        let finalContent = content;
 
         if (adapter.format === 'toml' || adapter.ext === '.toml') {
-            const content = fs.readFileSync(srcFile, 'utf8');
-            const description = `Magic SDD Workflow: ${destName}`;
-            fs.writeFileSync(destFile, convertToToml(content, description), 'utf8');
+            finalContent = convertToToml(content, `Magic SDD Workflow: ${destName}`);
         } else if (adapter.format === 'mdc' || adapter.ext === '.mdc') {
-            const content = fs.readFileSync(srcFile, 'utf8');
-            const description = `Magic SDD Workflow: ${destName}`;
-            fs.writeFileSync(destFile, convertToMdc(content, description), 'utf8');
-        } else {
-            fs.copyFileSync(srcFile, destFile);
+            finalContent = convertToMdc(content, `Magic SDD Workflow: ${destName}`);
+        }
+
+        fs.writeFileSync(destFile, finalContent, 'utf8');
+        installedChecksums[relTarget] = crypto.createHash('sha256').update(finalContent).digest('hex');
+    }
+
+    // Copy other files in .agent if any
+    const srcEng = path.join(sourceRoot, AGENT_DIR);
+    if (fs.existsSync(srcEng)) {
+        const items = fs.readdirSync(srcEng, { withFileTypes: true });
+        for (const item of items) {
+            if (item.name === WORKFLOWS_DIR) continue;
+
+            const srcItem = path.join(srcEng, item.name);
+            const destItem = path.join(cwd, AGENT_DIR, item.name);
+            const relTarget = path.relative(cwd, destItem).replace(/\\/g, '/');
+
+            if (item.isDirectory()) {
+                copyDir(srcItem, destItem);
+                const dirHash = getDirectoryChecksums(destItem, cwd);
+                Object.assign(installedChecksums, dirHash);
+            } else {
+                if (conflictsToSkip.includes(relTarget)) continue;
+                fs.mkdirSync(path.join(cwd, AGENT_DIR), { recursive: true });
+                fs.copyFileSync(srcItem, destItem);
+                installedChecksums[relTarget] = getFileChecksum(destItem);
+            }
         }
     }
 
-    console.log(`✅ Adapter installed: ${env} → ${adapter.dest}/ (${adapter.ext})`);
+    if (conflictsToSkip.length > 0 || isUpdate) {
+        console.log(`✅ Adapter updated: ${env} → ${adapter.dest}/ (${adapter.ext})`);
+    } else {
+        console.log(`✅ Adapter installed: ${env} → ${adapter.dest}/ (${adapter.ext})`);
+    }
+
+    return installedChecksums;
 }
 
 function runDoctor() {
@@ -331,16 +370,20 @@ function runInfo() {
     }
     console.log(`Installed version : ${installedVersion}  (.magic/.version)`);
 
-    const magicrcFile = path.join(cwd, '.magicrc');
-    let activeEnv = 'default (.agent/)';
-    if (fs.existsSync(magicrcFile)) {
+    const ADAPTERS_PATH = path.join(__dirname, '..', 'adapters.json');
+    let activeEnvs = [];
+    if (fs.existsSync(ADAPTERS_PATH)) {
         try {
-            const rc = JSON.parse(fs.readFileSync(magicrcFile, 'utf8'));
-            if (rc.env) activeEnv = rc.env;
+            const adapters = JSON.parse(fs.readFileSync(ADAPTERS_PATH, 'utf8'));
+            activeEnvs = detectEnvironments(adapters);
         } catch (e) { }
     }
-    console.log(`Active env        : ${activeEnv}`);
 
+    if (activeEnvs.length === 0) {
+        console.log(`Active env        : default (${AGENT_DIR}/)`);
+    } else {
+        console.log(`Active envs       : ${activeEnvs.join(', ')}`);
+    }
     const enginePresent = fs.existsSync(path.join(cwd, ENGINE_DIR));
     console.log(`Engine            : ${ENGINE_DIR}/     ${enginePresent ? '✅ present' : '❌ missing'}`);
 
@@ -431,18 +474,17 @@ async function runEject() {
     }
 }
 
-function detectEnvironment(adapters) {
+function detectEnvironments(adapters) {
+    const detected = [];
     for (const env in adapters) {
         const marker = adapters[env].marker;
-        if (marker && fs.existsSync(path.join(cwd, marker))) return env;
+        if (marker && fs.existsSync(path.join(cwd, marker))) {
+            detected.push(env);
+        }
     }
-    return null;
+    return detected;
 }
 
-function saveMagicRc(config) {
-    const magicrcFile = path.join(cwd, '.magicrc');
-    fs.writeFileSync(magicrcFile, JSON.stringify(config, null, 2), 'utf8');
-}
 
 function getFileChecksum(filePath) {
     if (!fs.existsSync(filePath)) return null;
@@ -482,8 +524,15 @@ async function handleConflicts(cwd) {
 
     const conflicts = [];
     for (const [relPath, storedHash] of Object.entries(storedChecksums)) {
-        const localPath = path.join(cwd, '.magic', relPath);
-        if (fs.existsSync(localPath)) {
+        if (relPath === '.checksums' || relPath === '.version') continue;
+
+        // Backward compatibility: try .magic first, then project root
+        let localPath = path.join(cwd, '.magic', relPath);
+        if (!fs.existsSync(localPath)) {
+            localPath = path.join(cwd, relPath);
+        }
+
+        if (fs.existsSync(localPath) && fs.statSync(localPath).isFile()) {
             const currentHash = getFileChecksum(localPath);
             if (currentHash !== storedHash) {
                 conflicts.push(relPath);
@@ -493,7 +542,7 @@ async function handleConflicts(cwd) {
 
     if (conflicts.length === 0) return;
 
-    console.log(`\n⚠️  Local changes detected in ${conflicts.length} file(s) in .magic/:`);
+    console.log(`\n⚠️  Local changes detected in ${conflicts.length} file(s):`);
     conflicts.slice(0, 5).forEach(f => console.log(`   - ${f}`));
     if (conflicts.length > 5) console.log(`   ... and ${conflicts.length - 5} more.`);
 
@@ -661,13 +710,14 @@ async function main() {
         console.log("\nOptions:");
         console.log("  --env <adapter>      Specify environment adapter");
         console.log("  --<adapter>          Shortcut for --env <adapter> (e.g. --cursor)");
-        console.log("  --update             Update engine files only");
+        console.log("  --update             Update engine and adapter files");
+        console.log("  --local              Use local project files instead of GitHub");
         console.log("  --fallback-main      Pull payload from main branch");
         console.log("  --yes, -y            Auto-accept prompts");
         process.exit(0);
     }
 
-    console.log(isUpdate ? '🪄 Updating magic-spec (.magic only)...' : '🪄 Initializing magic-spec...');
+    console.log(isUpdate ? '🪄 Updating magic-spec...' : '🪄 Initializing magic-spec...');
 
     if (isUpdate) {
         createBackup();
@@ -676,18 +726,16 @@ async function main() {
     const versionToFetch = isFallbackMain ? 'main' : version;
     let sourceRoot = null;
 
-    // Load .magicrc
-    let magicrc = {};
-    const magicrcFile = path.join(cwd, '.magicrc');
-    if (fs.existsSync(magicrcFile)) {
-        try {
-            magicrc = JSON.parse(fs.readFileSync(magicrcFile, 'utf8'));
-        } catch (e) { }
+    if (isLocal) {
+        // In local mode, source root is the parent of 'installers' folder
+        sourceRoot = path.resolve(__dirname, '..', '..');
+        console.log(`🏠 Using local project files from: ${sourceRoot}`);
     }
 
     try {
-        sourceRoot = await downloadPayload(versionToFetch);
-
+        if (!isLocal) {
+            sourceRoot = await downloadPayload(versionToFetch);
+        }
         let ADAPTERS = {};
         try {
             ADAPTERS = JSON.parse(fs.readFileSync(path.join(sourceRoot, 'installers', 'adapters.json'), 'utf8'));
@@ -706,25 +754,35 @@ async function main() {
             }
         }
 
-        let selectedEnvResolved = null;
         if (envValues.length > 0) {
             selectedEnvResolved = envValues[0];
-        } else if (magicrc.env && magicrc.env !== 'default') {
-            selectedEnvResolved = magicrc.env;
-        }
-
-        if (!selectedEnvResolved && !isUpdate) {
-            const detected = detectEnvironment(ADAPTERS);
-            if (detected && ADAPTERS[detected] && (!magicrc.env || magicrc.env === 'default')) {
-                const adapterName = ADAPTERS[detected].description || detected;
-                console.log(`\n💡 Detected ${adapterName} (${detected}/ directory found).`);
-                let shouldAdopt = autoAccept;
-                if (!shouldAdopt) {
-                    const answer = await askQuestion(`   Install ${detected} adapter instead of default? (y/N): `);
-                    shouldAdopt = answer.toLowerCase() === 'y';
-                }
-                if (shouldAdopt) {
-                    selectedEnvResolved = detected;
+        }
+
+        if (envValues.length === 0) {
+            const detected = detectEnvironments(ADAPTERS);
+            if (detected.length > 0) {
+                if (isUpdate) {
+                    for (const env of detected) {
+                        if (!envValues.includes(env)) envValues.push(env);
+                    }
+                    selectedEnvResolved = envValues[0];
+                } else {
+                    if (detected.length === 1) {
+                        const env = detected[0];
+                        const adapterName = ADAPTERS[env].description || env;
+                        console.log(`\n💡 Detected ${adapterName} (${ADAPTERS[env].marker}/ directory found).`);
+                        let shouldAdopt = autoAccept;
+                        if (!shouldAdopt) {
+                            const answer = await askQuestion(`   Install ${env} adapter instead of default? (y/N): `);
+                            shouldAdopt = answer.toLowerCase() === 'y';
+                        }
+                        if (shouldAdopt) {
+                            selectedEnvResolved = env;
+                        }
+                    } else {
+                        console.log(`\n💡 Multiple environments detected: ${detected.join(', ')}`);
+                        console.log(`   Use --env <name> or --<name> to target specific one.`);
+                    }
                 }
             }
         }
@@ -757,36 +815,45 @@ async function main() {
         }
 
         // 2. Adapters
-        if (!isUpdate) {
-            if (envValues.length > 0) {
-                for (const env of envValues) {
-                    installAdapter(sourceRoot, env, ADAPTERS);
-                }
-            } else if (selectedEnvResolved) {
-                installAdapter(sourceRoot, selectedEnvResolved, ADAPTERS);
-            } else {
-                // Default install
-                const srcEng = path.join(sourceRoot, AGENT_DIR);
-                const destEng = path.join(cwd, AGENT_DIR);
-                fs.mkdirSync(destEng, { recursive: true });
-                fs.mkdirSync(path.join(destEng, WORKFLOWS_DIR), { recursive: true });
-
-                for (const wfName of WORKFLOWS) {
-                    const file = wfName + DEFAULT_EXT;
-                    const srcWf = path.join(srcEng, WORKFLOWS_DIR, file);
-                    if (fs.existsSync(srcWf)) {
-                        fs.copyFileSync(srcWf, path.join(destEng, WORKFLOWS_DIR, file));
-                    }
+        let adapterChecksums = {};
+        if (envValues.length > 0) {
+            for (const env of envValues) {
+                Object.assign(adapterChecksums, installAdapter(sourceRoot, env, ADAPTERS, conflictsToSkip));
+            }
+        } else if (selectedEnvResolved) {
+            Object.assign(adapterChecksums, installAdapter(sourceRoot, selectedEnvResolved, ADAPTERS, conflictsToSkip));
+        } else if (!isUpdate) {
+            // Default install
+            const srcEng = path.join(sourceRoot, AGENT_DIR);
+            const destEng = path.join(cwd, AGENT_DIR);
+            fs.mkdirSync(destEng, { recursive: true });
+            fs.mkdirSync(path.join(destEng, WORKFLOWS_DIR), { recursive: true });
+
+            for (const wfName of WORKFLOWS) {
+                const file = wfName + DEFAULT_EXT;
+                const srcWf = path.join(srcEng, WORKFLOWS_DIR, file);
+                if (fs.existsSync(srcWf)) {
+                    const destWf = path.join(destEng, WORKFLOWS_DIR, file);
+                    fs.copyFileSync(srcWf, destWf);
+                    const relTarget = path.relative(cwd, destWf).replace(/\\/g, '/');
+                    adapterChecksums[relTarget] = getFileChecksum(destWf);
                 }
+            }
 
-                // Copy other files in .agent if any (not workflows subfolder which we handled selectively)
+            // Copy other files in .agent if any (not workflows subfolder which we handled selectively)
+            if (fs.existsSync(srcEng)) {
                 const items = fs.readdirSync(srcEng, { withFileTypes: true });
                 for (const item of items) {
                     if (item.name === WORKFLOWS_DIR) continue;
+                    const srcItem = path.join(srcEng, item.name);
+                    const destItem = path.join(destEng, item.name);
                     if (item.isDirectory()) {
-                        copyDir(path.join(srcEng, item.name), path.join(destEng, item.name));
+                        copyDir(srcItem, destItem);
+                        Object.assign(adapterChecksums, getDirectoryChecksums(destItem, cwd));
                     } else {
-                        fs.copyFileSync(path.join(srcEng, item.name), path.join(destEng, item.name));
+                        fs.copyFileSync(srcItem, destItem);
+                        const relTarget = path.relative(cwd, destItem).replace(/\\/g, '/');
+                        adapterChecksums[relTarget] = getFileChecksum(destItem);
                     }
                 }
             }
@@ -842,20 +909,27 @@ async function main() {
             console.warn(`⚠️  Failed to write .magic/.version: ${vErr.message}`);
         }
 
-        // 5. Update .magicrc - [T-2C02]
-        try {
-            const newConfig = {
-                env: selectedEnvResolved || magicrc.env || 'default',
-                version: version
-            };
-            saveMagicRc(newConfig);
-        } catch (rcErr) {
-            console.warn(`⚠️  Failed to update .magicrc: ${rcErr.message}`);
-        }
 
         // 6. Save checksums - [T-2C03]
         try {
             const currentChecksums = getDirectoryChecksums(path.join(cwd, '.magic'));
+
+            if (isUpdate) {
+                const checksumsFile = path.join(cwd, '.magic', '.checksums');
+                if (fs.existsSync(checksumsFile)) {
+                    try {
+                        const oldChecksums = JSON.parse(fs.readFileSync(checksumsFile, 'utf8'));
+                        for (const skipped of conflictsToSkip) {
+                            if (oldChecksums[skipped]) {
+                                currentChecksums[skipped] = oldChecksums[skipped];
+                            }
+                        }
+                    } catch (e) { }
+                }
+            }
+
+            Object.assign(currentChecksums, adapterChecksums);
+
             fs.writeFileSync(path.join(cwd, '.magic', '.checksums'), JSON.stringify(currentChecksums, null, 2), 'utf8');
         } catch (cErr) {
             console.warn(`⚠️  Failed to save checksums: ${cErr.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-spec",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Magic Specification-Driven Development (SDD) Workflow",
   "author": "Oleg Alexandrov <alexandrovoleg.ru@gmail.com>",
   "license": "MIT",