intentdna 1.6.4 → 1.7.0

package/dist/cli/commands/sync.js

@@ -10,22 +10,25 @@
  *
  * Targets: claude-md, soul-md, cursorrules, system-prompt
  */
-import { resolve, dirname, basename } from "node:path";
+import { resolve, dirname } from "node:path";
 import { readFile, writeFile as writeFileAsync, stat, mkdir, readdir, unlink, rm } from "node:fs/promises";
 import { createHash } from "node:crypto";
-import { fileURLToPath } from "node:url";
 import { createInterface } from "node:readline";
-import { loadDNA, compileFromFiles } from "../../compiler/index.js";
+import { assertNoNamespaceCollisions, compileFromFiles, detectDNAConfigs, expandDNAInputFiles, loadDNA, } from "../../compiler/index.js";
 import { parseYAML } from "../../schema/yaml-parser.js";
+import { findTemplateCatalogEntry } from "../../templates/catalog.js";
 import { compileToMarkdown, injectIntoFile, removeFromFile } from "../../runtime/markdown.js";
+import { syncInjectMarkdownTargets } from "../../runtime/markdown-target-registry.js";
+import { getSyncOutputArtifactMetadata } from "../../runtime/output-artifact-registry.js";
+import { compileWorkflow } from "../../compiler/workflow.js";
 import { compileAllRolesToAgentMD, writeAgentMDFiles, removeAgentMDFiles } from "../../runtime/agent-md.js";
 import { removeWorkflowScripts } from "../../runtime/workflow-runner.js";
-import { compileWorkflowToSkill, compileControllerToSkill, writeSkillFiles } from "../../runtime/skill-adapter.js";
+import { compileWorkflowToSkill, compileControllerToSkill, writeSkillFiles, removeSkillFiles } from "../../runtime/skill-adapter.js";
 import { compilePluginSettings, detectEnabledEvents, mergeSettingsFile, recommendHookTimeouts } from "../../runtime/settings-adapter.js";
 import { createCompiledIR, writeCompiledIR } from "../../runtime/plugin-adapter.js";
 import { cascadeDNA } from "../../compiler/cascade.js";
 import { EvolutionEngine } from "../../evolution/index.js";
-const VALID_TARGETS = ["claude-md", "soul-md", "cursorrules", "system-prompt"];
+const VALID_TARGETS = syncInjectMarkdownTargets();
 /**
  * Detect whether intentdna is running as a Claude Code plugin or standalone binary.
  *
@@ -71,32 +74,6 @@ const LEGACY_BASH_HOOKS = [
     "dna-pre-compact.sh",
     "dna-notification.sh",
 ];
-const TEMPLATES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates");
-function calculateTemplateHash(content) {
-    return createHash("sha256").update(content, "utf-8").digest("hex").slice(0, 16);
-}
-async function findTemplateFile(templateName) {
-    // Try direct filename match first
-    const directPath = resolve(TEMPLATES_DIR, `${templateName}.dna.yaml`);
-    if (await fileExists(directPath))
-        return directPath;
-    // Fallback: search by id or name field
-    try {
-        const files = await readdir(TEMPLATES_DIR);
-        for (const file of files) {
-            if (!file.endsWith(".dna.yaml") && !file.endsWith(".dna.yml"))
-                continue;
-            const fullPath = resolve(TEMPLATES_DIR, file);
-            const content = await readFile(fullPath, "utf-8");
-            const data = parseYAML(content);
-            if (data.id === templateName || data.name === templateName) {
-                return fullPath;
-            }
-        }
-    }
-    catch { /* fail-open */ }
-    return null;
-}
 /**
  * Remove legacy bash hook scripts written by previous Intent DNA versions.
  * Only removes files that contain the sentinel comment.
@@ -127,11 +104,11 @@ export async function cleanStaleDNAFiles(dir, type, activeNamespaces) {
         const entries = await readdir(dir, { withFileTypes: true });
         for (const entry of entries) {
             const fullPath = resolve(dir, entry.name);
-            // Match active namespace prefixes directly so multi-hyphen names like
-            // dna-frw-fix-loop still resolve to namespace frw.
-            if (!activeNamespaces.some(ns => entry.name.startsWith(`dna-${ns}-`))) {
+            if (activeNamespaces.length === 0)
+                continue;
+            const matchesActiveScope = activeNamespaces.some(ns => entry.name.startsWith(`dna-${ns}-`));
+            if (!matchesActiveScope)
                 continue;
-            }
             if (type === "agents" && entry.isFile() && entry.name.endsWith(".md")) {
                 const content = await readFile(fullPath, "utf-8").catch(() => "");
                 if (content.includes(DNA_SENTINEL)) {
@@ -169,7 +146,7 @@ function promptVariable(description, defaultValue) {
  * prompt user interactively. If already plain strings, use as-is.
  * Saves resolved values back to config file.
  */
-async function resolveVariables(rawVars, configPath) {
+async function resolveVariables(rawVars, configPath, options) {
     const resolved = {};
     const needsPrompt = [];
     for (const [key, val] of Object.entries(rawVars)) {
@@ -180,7 +157,7 @@ async function resolveVariables(rawVars, configPath) {
             needsPrompt.push({ key, desc: val.description, def: val.default });
         }
     }
-    if (needsPrompt.length > 0 && process.stdin.isTTY) {
+    if (needsPrompt.length > 0 && process.stdin.isTTY && !options?.dryRun) {
         process.stderr.write("\nProject variables (press Enter for default):\n");
         for (const v of needsPrompt) {
             const value = await promptVariable(v.desc, v.def);
@@ -216,42 +193,8 @@ async function resolveVariables(rawVars, configPath) {
  * Auto-detect DNA config file in current directory (legacy single-config).
  * Priority: .dna/config.yaml > .dna/config.yml > .dna/config.json > .dna.yaml > .dna.yml > .dna.json
  */
-async function autoDetectDNA() {
-    const cwd = process.cwd();
-    const candidates = [
-        ".dna/config.yaml", ".dna/config.yml", ".dna/config.json",
-        ".dna.yaml", ".dna.yml", ".dna.json",
-    ];
-    for (const name of candidates) {
-        const path = resolve(cwd, name);
-        if (await fileExists(path))
-            return path;
-    }
-    return null;
-}
-/**
- * Auto-detect DNA configs: multi-config (.dna/configs/*.yaml) or legacy single-config.
- * Returns array of absolute paths.
- */
 export async function autoDetectConfigs() {
-    const cwd = process.cwd();
-    // Priority 1: .dna/configs/*.yaml (multi-config)
-    const configsDir = resolve(cwd, ".dna", "configs");
-    try {
-        const files = await readdir(configsDir);
-        const yamls = files
-            .filter(f => f.endsWith(".yaml") || f.endsWith(".yml"))
-            .sort()
-            .map(f => resolve(configsDir, f));
-        if (yamls.length > 0)
-            return yamls;
-    }
-    catch { /* dir doesn't exist */ }
-    // Fallback: legacy single-config paths
-    const legacy = await autoDetectDNA();
-    if (legacy)
-        return [legacy];
-    return [];
+    return detectDNAConfigs(process.cwd());
 }
 /**
  * Read the current package version from package.json.
@@ -262,26 +205,7 @@ export { getPackageVersion } from "../util/version.js";
  * Throws if two configs declare the same namespace.
  */
 export async function checkNamespaceCollisions(configPaths) {
-    const namespaces = new Map();
-    for (const configPath of configPaths) {
-        try {
-            const content = await readFile(configPath, "utf-8");
-            const data = parseYAML(content);
-            const ns = typeof data.namespace === "string" ? data.namespace : undefined;
-            if (ns) {
-                const file = basename(configPath);
-                if (namespaces.has(ns)) {
-                    throw new Error(`Namespace "${ns}" conflict: ${namespaces.get(ns)} and ${file}. Each template must have a unique namespace.`);
-                }
-                namespaces.set(ns, file);
-            }
-        }
-        catch (err) {
-            if (err instanceof Error && err.message.includes("conflict"))
-                throw err;
-            // Parse error — will be caught later during compilation
-        }
-    }
+    await assertNoNamespaceCollisions(configPaths);
 }
 /**
  * Compare two semver strings. Returns:
@@ -306,10 +230,8 @@ export function compareSemver(a, b) {
     return 0;
 }
 /**
- * Check template versions against current template content hashes.
- * Returns upgrade info for changed configs and prints human-readable suggestions.
- *
- * Uses content hash comparison instead of semver — detects any template content change.
+ * Check stamped template metadata against the current template catalog.
+ * Version mismatch is the primary upgrade signal; content hash drift is a fallback.
  */
 export async function checkTemplateVersions(configPaths) {
     const upgrades = [];
@@ -322,26 +244,37 @@ export async function checkTemplateVersions(configPaths) {
             const tmplVersion = typeof data._template_version === "string" ? data._template_version : undefined;
             if (!tmplName)
                 continue;
-            const templatePath = await findTemplateFile(tmplName);
-            if (!templatePath)
+            const template = await findTemplateCatalogEntry(tmplName);
+            if (!template)
+                continue;
+            if (tmplVersion && template.version && compareSemver(template.version, tmplVersion) > 0) {
+                upgrades.push({
+                    configPath,
+                    templateName: tmplName,
+                    currentVersion: tmplVersion,
+                    availableVersion: template.version,
+                    reason: "version-update",
+                });
+                process.stderr.write(`Template update available: "${tmplName}" ${tmplVersion} → ${template.version}. Run: dna init --upgrade ${tmplName}\n`);
                 continue;
-            const currentTemplateContent = await readFile(templatePath, "utf-8");
-            const currentHash = calculateTemplateHash(currentTemplateContent);
+            }
             if (!tmplHash) {
                 upgrades.push({
                     configPath,
                     templateName: tmplName,
                     currentVersion: tmplVersion ?? "unknown",
-                    availableVersion: "content-changed",
+                    availableVersion: template.version ?? "content-changed",
+                    reason: "missing-hash",
                 });
                 process.stderr.write(`Upgrade available: "${tmplName}" has no content hash. Run: dna init --upgrade ${tmplName}\n`);
             }
-            else if (currentHash !== tmplHash) {
+            else if (template.contentHash !== tmplHash) {
                 upgrades.push({
                     configPath,
                     templateName: tmplName,
                     currentVersion: tmplVersion ?? "unknown",
                     availableVersion: "content-changed",
+                    reason: "content-drift",
                 });
                 process.stderr.write(`Template content changed: "${tmplName}". Run: dna init --upgrade ${tmplName}\n`);
             }
@@ -352,39 +285,6 @@ export async function checkTemplateVersions(configPaths) {
     }
     return upgrades;
 }
-function resolveSpeciesPath(ref) {
-    if (!ref.startsWith("species:"))
-        return null;
-    const name = ref.slice("species:".length);
-    const thisDir = dirname(fileURLToPath(import.meta.url));
-    return resolve(thisDir, "..", "..", "species", `${name}.dna.json`);
-}
-async function expandFiles(files) {
-    const expanded = [];
-    const seen = new Set();
-    for (const file of files) {
-        const abs = resolve(file);
-        if (seen.has(abs))
-            continue;
-        seen.add(abs);
-        expanded.push(abs);
-        try {
-            const raw = await readFile(abs, "utf-8");
-            const dna = JSON.parse(raw);
-            for (const ref of dna.cascade?.inherits ?? []) {
-                const speciesPath = resolveSpeciesPath(ref);
-                if (speciesPath && !seen.has(speciesPath)) {
-                    seen.add(speciesPath);
-                    expanded.unshift(speciesPath);
-                }
-            }
-        }
-        catch {
-            // Will fail later with proper error
-        }
-    }
-    return expanded;
-}
 function fileSha256(content) {
     return createHash("sha256").update(content, "utf-8").digest("hex");
 }
@@ -392,6 +292,32 @@ async function computeFileHash(filePath) {
     const content = await readFile(filePath, "utf-8");
     return fileSha256(content);
 }
+function trackSyncOutput(trackedOutputs, artifact, path) {
+    if (!getSyncOutputArtifactMetadata(artifact)) {
+        throw new Error(`Unknown sync output artifact: ${artifact}`);
+    }
+    trackedOutputs.push({ artifact, path: resolve(path) });
+}
+function summarizeSyncOutputs(trackedOutputs, dryRun) {
+    if (trackedOutputs.length === 0)
+        return;
+    const sorted = trackedOutputs.slice().sort((a, b) => {
+        const aMeta = getSyncOutputArtifactMetadata(a.artifact);
+        const bMeta = getSyncOutputArtifactMetadata(b.artifact);
+        return aMeta.order - bMeta.order || a.path.localeCompare(b.path);
+    });
+    process.stderr.write(dryRun ? "Dry-run output plan:\n" : "Sync output summary:\n");
+    for (const output of sorted) {
+        const metadata = getSyncOutputArtifactMetadata(output.artifact);
+        const tracked = metadata.trackedByLock ? "lock-tracked" : "untracked";
+        process.stderr.write(`  - ${metadata.label}: ${output.path} (${tracked})\n`);
+    }
+}
+function lockTrackedOutputPaths(trackedOutputs) {
+    return trackedOutputs
+        .filter((output) => getSyncOutputArtifactMetadata(output.artifact)?.trackedByLock)
+        .map((output) => output.path);
+}
 async function generateLockFile(lockPath, dnaSources, outputFiles) {
     const outputs = {};
     for (const f of outputFiles) {
@@ -419,10 +345,8 @@ export async function runSync(opts) {
             }
             // Namespace collision check (multi-config)
             if (autoFiles.length > 1) {
-                await checkNamespaceCollisions(autoFiles);
+                await assertNoNamespaceCollisions(autoFiles);
             }
-            // Template version check
-            await checkTemplateVersions(autoFiles);
         }
     }
     if (!opts.remove && !opts.inject && !opts.hooksDir && !opts.agentsDir && !opts.workflowDir && !opts.skillsDir && !opts.settingsPath) {
@@ -438,18 +362,17 @@ export async function runSync(opts) {
             process.stderr.write(`Auto-detect: Claude Code → CLAUDE.md + agents + skills + settings\n`);
         }
     }
-    // Auto-detect plugin vs bin mode if --plugin not explicitly set
-    if (!opts.remove && opts.plugin === undefined) {
-        const mode = await detectMode();
-        if (mode === "plugin") {
-            opts.plugin = true;
-            process.stderr.write("Auto-detect: plugin mode (intentdna registered as Claude Code plugin)\n");
-        }
+    const requestedMode = opts.mode ?? (opts.plugin === true ? "plugin" : opts.plugin === false ? "bin" : "auto");
+    let resolvedMode = requestedMode === "auto" ? "bin" : requestedMode;
+    if (!opts.remove && requestedMode === "auto") {
+        resolvedMode = await detectMode();
+        process.stderr.write(`Auto-detect: ${resolvedMode} mode${resolvedMode === "plugin" ? " (intentdna registered as Claude Code plugin)" : ""}\n`);
     }
+    opts.plugin = resolvedMode === "plugin";
     // Handle --remove
     if (opts.remove) {
-        if (!opts.inject && !opts.hooksDir && !opts.agentsDir && !opts.workflowDir) {
-            process.stderr.write("Error: --inject, --hooks, --agents, or --workflow is required with --remove\n");
+        if (!opts.inject && !opts.hooksDir && !opts.agentsDir && !opts.workflowDir && !opts.skillsDir) {
+            process.stderr.write("Error: --inject, --hooks, --agents, --workflow, or --skills is required with --remove\n");
             return 2;
         }
         if (opts.inject) {
@@ -488,6 +411,15 @@ export async function runSync(opts) {
                 process.stderr.write(`No Intent DNA workflow scripts found in ${opts.workflowDir}\n`);
             }
         }
+        if (opts.skillsDir) {
+            const count = await removeSkillFiles(opts.skillsDir);
+            if (count > 0) {
+                process.stderr.write(`Removed ${count} Intent DNA skill dir(s) from ${opts.skillsDir}\n`);
+            }
+            else {
+                process.stderr.write(`No Intent DNA skill dirs found in ${opts.skillsDir}\n`);
+            }
+        }
         return 0;
     }
     if (opts.files.length === 0) {
@@ -509,11 +441,18 @@ export async function runSync(opts) {
         // Step 0: Expand and pre-validate all DNA files before any work
         // loadDNA() calls validateDNA() internally — validation failures throw here,
         // before evolve/compile/inject waste any work.
-        const expandedFiles = await expandFiles(opts.files);
+        const expandedFiles = await expandDNAInputFiles(opts.files);
+        await checkTemplateVersions(expandedFiles);
         const loadedDNAs = await Promise.all(expandedFiles.map(loadDNA));
+        if (opts.dryRun) {
+            process.stderr.write("Dry-run: no files will be written or removed.\n");
+        }
         // Step 1: Evolve if requested
         let epigeneticMarkers = undefined;
-        if (opts.evolve) {
+        if (opts.evolve && opts.dryRun) {
+            process.stderr.write("Dry-run: would run evolution before compiling\n");
+        }
+        else if (opts.evolve) {
             const dnas = loadedDNAs;
             // Use the highest-priority DNA's ID
             const primaryDna = dnas.reduce((a, b) => a.cascade.priority >= b.cascade.priority ? a : b);
@@ -533,15 +472,21 @@ export async function runSync(opts) {
         // Step 3: Render and inject markdown
         if (opts.inject) {
             const target = opts.target;
-            const markdown = compileToMarkdown(ir, target);
-            const modified = await injectIntoFile(opts.inject, markdown);
-            if (modified) {
-                process.stderr.write(`Synced to ${opts.inject} (${target})\n`);
+            if (opts.dryRun) {
+                compileToMarkdown(ir, target);
+                process.stderr.write(`Dry-run: would sync ${opts.inject} (${target})\n`);
             }
             else {
-                process.stderr.write(`No changes needed in ${opts.inject}\n`);
+                const markdown = compileToMarkdown(ir, target);
+                const modified = await injectIntoFile(opts.inject, markdown);
+                if (modified) {
+                    process.stderr.write(`Synced to ${opts.inject} (${target})\n`);
+                }
+                else {
+                    process.stderr.write(`No changes needed in ${opts.inject}\n`);
+                }
             }
-            trackedOutputs.push(resolve(opts.inject));
+            trackSyncOutput(trackedOutputs, "markdown-injection", opts.inject);
         }
         // Step 3.5: Write compiled IR (needed for both plugin and bin mode)
         {
@@ -550,17 +495,36 @@ export async function runSync(opts) {
             const cascadedForIR = cascadeDNA(dnas);
             const roles = cascadedForIR.roles;
             const compiled = createCompiledIR(ir, roles);
-            const irPath = await writeCompiledIR(cwd, compiled);
-            process.stderr.write(`Wrote compiled IR: ${irPath}\n`);
-            trackedOutputs.push(resolve(irPath));
+            const irPath = resolve(cwd, ".dna", "compiled", "ir.json");
+            if (opts.dryRun) {
+                JSON.stringify(compiled);
+                process.stderr.write(`Dry-run: would write compiled IR: ${irPath}\n`);
+            }
+            else {
+                const writtenIrPath = await writeCompiledIR(cwd, compiled);
+                process.stderr.write(`Wrote compiled IR: ${writtenIrPath}\n`);
+            }
+            trackSyncOutput(trackedOutputs, "compiled-ir", irPath);
             // Clean up old bash hooks if they exist
             const oldHooksDir = resolve(cwd, ".claude", "hooks");
-            const removed = await removeLegacyBashHooks(oldHooksDir);
-            if (removed > 0) {
-                process.stderr.write(`Cleaned ${removed} legacy bash hook(s) from ${oldHooksDir}\n`);
+            if (opts.dryRun) {
+                process.stderr.write(`Dry-run: would clean legacy bash hooks in ${oldHooksDir}\n`);
+            }
+            else {
+                const removed = await removeLegacyBashHooks(oldHooksDir);
+                if (removed > 0) {
+                    process.stderr.write(`Cleaned ${removed} legacy bash hook(s) from ${oldHooksDir}\n`);
+                }
             }
             // G2/G3: Register built-in DNA MCP server in .claude/.mcp.json
-            await registerDNAMCPServer(cwd);
+            const mcpPath = resolve(cwd, ".claude", ".mcp.json");
+            if (opts.dryRun) {
+                process.stderr.write(`Dry-run: would register dna-mcp server in ${mcpPath}\n`);
+            }
+            else {
+                await registerDNAMCPServer(cwd);
+            }
+            trackSyncOutput(trackedOutputs, "mcp-config", mcpPath);
         }
         // Step 3.6: Register hooks in settings.json (bin mode only)
         // Plugin mode: hooks managed by plugin framework — skip settings.json
@@ -568,9 +532,15 @@ export async function runSync(opts) {
             const enabledEvents = detectEnabledEvents(ir);
             if (enabledEvents.length > 0) {
                 const pluginSettings = compilePluginSettings(enabledEvents, 10, recommendHookTimeouts(ir));
-                await mergeSettingsFile(pluginSettings, opts.settingsPath);
-                process.stderr.write(`Bin mode: registered ${enabledEvents.length} hook event(s) in ${opts.settingsPath}\n`);
-                trackedOutputs.push(resolve(opts.settingsPath));
+                if (opts.dryRun) {
+                    JSON.stringify(pluginSettings);
+                    process.stderr.write(`Dry-run: would register ${enabledEvents.length} hook event(s) in ${opts.settingsPath}\n`);
+                }
+                else {
+                    await mergeSettingsFile(pluginSettings, opts.settingsPath);
+                    process.stderr.write(`Bin mode: registered ${enabledEvents.length} hook event(s) in ${opts.settingsPath}\n`);
+                }
+                trackSyncOutput(trackedOutputs, "settings-hooks", opts.settingsPath);
             }
         }
         else if (opts.plugin && opts.settingsPath) {
@@ -583,9 +553,14 @@ export async function runSync(opts) {
         // Step 5: Generate agent MD files
         if (opts.agentsDir) {
             // Clean stale DNA-managed agents before regenerating
-            const staleAgents = await cleanStaleDNAFiles(opts.agentsDir, "agents", activeNamespaces);
-            if (staleAgents.length > 0) {
-                process.stderr.write(`Cleaned ${staleAgents.length} stale agent file(s)\n`);
+            if (opts.dryRun) {
+                process.stderr.write(`Dry-run: would clean stale agent file(s) in ${opts.agentsDir}\n`);
+            }
+            else {
+                const staleAgents = await cleanStaleDNAFiles(opts.agentsDir, "agents", activeNamespaces);
+                if (staleAgents.length > 0) {
+                    process.stderr.write(`Cleaned ${staleAgents.length} stale agent file(s)\n`);
+                }
             }
             const dnas = loadedDNAs;
             const cascaded = cascadeDNA(dnas);
@@ -595,14 +570,19 @@ export async function runSync(opts) {
             }
             else {
                 const results = compileAllRolesToAgentMD(roles, ir);
-                const written = await writeAgentMDFiles(results, opts.agentsDir);
-                if (written.length > 0) {
+                const written = results.map((result) => resolve(opts.agentsDir, result.fileName));
+                if (opts.dryRun) {
+                    process.stderr.write(`Dry-run: would generate ${written.length} agent file(s) in ${opts.agentsDir}\n`);
+                }
+                else {
+                    await writeAgentMDFiles(results, opts.agentsDir);
                     process.stderr.write(`Generated ${written.length} agent file(s) in ${opts.agentsDir}\n`);
                     for (const f of written) {
                         process.stderr.write(`  ${f}\n`);
                     }
-                    trackedOutputs.push(...written.map(f => resolve(f)));
                 }
+                for (const file of written)
+                    trackSyncOutput(trackedOutputs, "agents", file);
             }
         }
         // Step 6: Generate workflow script(s)
@@ -614,7 +594,6 @@ export async function runSync(opts) {
                 process.stderr.write("No workflow defined in DNA files\n");
             }
             else {
-                const { compileWorkflow } = await import("../../compiler/workflow.js");
                 const { compileWorkflowToShell, writeWorkflowScript } = await import("../../runtime/workflow-runner.js");
                 // If --workflow-name specified, only compile that workflow; otherwise compile all
                 const targetWorkflows = opts.workflowName
@@ -634,9 +613,15 @@ export async function runSync(opts) {
                     }
                     else {
                         const shellResult = compileWorkflowToShell(result.plan);
-                        const written = await writeWorkflowScript(shellResult, opts.workflowDir);
-                        process.stderr.write(`Generated workflow script: ${written}\n`);
-                        trackedOutputs.push(resolve(written));
+                        const written = resolve(opts.workflowDir, shellResult.fileName);
+                        if (opts.dryRun) {
+                            process.stderr.write(`Dry-run: would generate workflow script: ${written}\n`);
+                        }
+                        else {
+                            await writeWorkflowScript(shellResult, opts.workflowDir);
+                            process.stderr.write(`Generated workflow script: ${written}\n`);
+                        }
+                        trackSyncOutput(trackedOutputs, "workflows", written);
                     }
                 }
             }
@@ -644,9 +629,14 @@ export async function runSync(opts) {
         // Step 7: Generate skill files from workflows
         if (opts.skillsDir) {
             // Clean stale DNA-managed skills before regenerating
-            const staleSkills = await cleanStaleDNAFiles(opts.skillsDir, "skills", activeNamespaces);
-            if (staleSkills.length > 0) {
-                process.stderr.write(`Cleaned ${staleSkills.length} stale skill dir(s)\n`);
+            if (opts.dryRun) {
+                process.stderr.write(`Dry-run: would clean stale skill dir(s) in ${opts.skillsDir}\n`);
+            }
+            else {
+                const staleSkills = await cleanStaleDNAFiles(opts.skillsDir, "skills", activeNamespaces);
+                if (staleSkills.length > 0) {
+                    process.stderr.write(`Cleaned ${staleSkills.length} stale skill dir(s)\n`);
+                }
             }
             const dnas = loadedDNAs;
             const cascadedForSkills = cascadeDNA(dnas);
@@ -660,7 +650,7 @@ export async function runSync(opts) {
                     Object.assign(rawVars, d.variables);
             }
             const configPath = opts.files.length === 1 ? opts.files[0] : null;
-            const variables = await resolveVariables(rawVars, configPath);
+            const variables = await resolveVariables(rawVars, configPath, { dryRun: opts.dryRun });
             // Step 8: Generate .claude/.mcp.json from MCP dependencies (inside skillsDir block, shares variables)
             {
                 const mcpDeps = {};
@@ -671,15 +661,19 @@ export async function runSync(opts) {
                 if (Object.keys(mcpDeps).length > 0) {
                     const cwd = process.cwd();
                     const mcpJsonPath = resolve(cwd, ".claude", ".mcp.json");
-                    await writeMCPConfig(mcpDeps, mcpJsonPath, variables);
-                    process.stderr.write(`MCP: wrote ${Object.keys(mcpDeps).length} server(s) to ${mcpJsonPath}\n`);
+                    if (opts.dryRun) {
+                        process.stderr.write(`Dry-run: would write ${Object.keys(mcpDeps).length} MCP server(s) to ${mcpJsonPath}\n`);
+                    }
+                    else {
+                        await writeMCPConfig(mcpDeps, mcpJsonPath, variables);
+                        process.stderr.write(`MCP: wrote ${Object.keys(mcpDeps).length} server(s) to ${mcpJsonPath}\n`);
+                    }
                 }
             }
             if (Object.keys(workflows).length === 0 && Object.keys(controllers).length === 0) {
                 process.stderr.write("No workflow or controller defined — no skills to generate\n");
             }
             else {
-                const { compileWorkflow } = await import("../../compiler/workflow.js");
                 const skillResults = [];
                 for (const [name, wfDef] of Object.entries(workflows)) {
                     const result = compileWorkflow(wfDef, { workflow_key: name });
@@ -691,12 +685,27 @@ export async function runSync(opts) {
                     skillResults.push(compileControllerToSkill(name, controllerDef, variables, workflows));
                 }
                 if (skillResults.length > 0) {
-                    const written = await writeSkillFiles(skillResults, opts.skillsDir);
-                    process.stderr.write(`Generated ${written.length} skill file(s) in ${opts.skillsDir}\n`);
-                    for (const f of written) {
-                        process.stderr.write(`  ${f}\n`);
+                    let written = skillResults.flatMap((result) => {
+                        const files = [resolve(opts.skillsDir, result.dirName, "SKILL.md")];
+                        if (result.bodyFileName)
+                            files.push(resolve(opts.skillsDir, result.dirName, "skill-bodies", result.bodyFileName));
+                        return files;
+                    });
+                    if (skillResults.some((result) => result.mapEntry)) {
+                        written.push(resolve(opts.skillsDir, ".intentdna-skill-map.json"));
+                    }
+                    if (opts.dryRun) {
+                        process.stderr.write(`Dry-run: would generate ${written.length} skill artifact(s) in ${opts.skillsDir}\n`);
+                    }
+                    else {
+                        written = await writeSkillFiles(skillResults, opts.skillsDir);
+                        process.stderr.write(`Generated ${written.length} skill artifact(s) in ${opts.skillsDir}\n`);
+                        for (const f of written) {
+                            process.stderr.write(`  ${f}\n`);
+                        }
                     }
-                    trackedOutputs.push(...written.map(f => resolve(f)));
+                    for (const file of written)
+                        trackSyncOutput(trackedOutputs, "skills-controllers", file);
                 }
             }
         }
@@ -708,8 +717,17 @@ export async function runSync(opts) {
         // Step 9: Generate .dna/lock file (only when --lock is specified or outputs exist)
         if (opts.lockFile && trackedOutputs.length > 0) {
             const lockPath = resolve(opts.lockFile);
-            await generateLockFile(lockPath, expandedFiles, trackedOutputs);
-            process.stderr.write(`Lock file: ${lockPath}\n`);
+            if (opts.dryRun) {
+                process.stderr.write(`Dry-run: would write lock file: ${lockPath}\n`);
+            }
+            else {
+                await generateLockFile(lockPath, expandedFiles, lockTrackedOutputPaths(trackedOutputs));
+                process.stderr.write(`Lock file: ${lockPath}\n`);
+            }
+            trackSyncOutput(trackedOutputs, "lock-file", lockPath);
+        }
+        if (opts.dryRun || opts.postSummary) {
+            summarizeSyncOutputs(trackedOutputs, opts.dryRun === true);
         }
         return 0;
     }
@@ -781,7 +799,7 @@ async function registerDNAMCPServer(cwd) {
     const mcpServers = (existing.mcpServers ?? {});
     // Don't overwrite if user already configured it
     if (mcpServers["intentdna"])
-        return;
+        return mcpJsonPath;
     mcpServers["intentdna"] = {
         command: "dna-mcp",
         args: ["--project-dir", cwd],
@@ -790,4 +808,5 @@ async function registerDNAMCPServer(cwd) {
     await mkdir(dirname(mcpJsonPath), { recursive: true });
     await writeFileAsync(mcpJsonPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
     process.stderr.write(`MCP: registered dna-mcp server in ${mcpJsonPath}\n`);
+    return mcpJsonPath;
 }

package/dist/cli/commands/templates.d.ts

@@ -1,5 +1,5 @@
 /**
- * dna templates deploy — copy local src/templates/*.dna.yaml to global intentdna install
+ * dna templates — template catalog and deployment commands.
  */
 export interface TemplatesDeployOptions {
     /** Override local templates dir (for testing) */
@@ -7,4 +7,13 @@ export interface TemplatesDeployOptions {
     /** Override global target dir (for testing) */
     globalDir?: string;
 }
+export interface TemplatesListOptions {
+    projectDir?: string;
+}
+export interface TemplatesShowOptions {
+    name: string;
+    projectDir?: string;
+}
+export declare function runTemplatesList(opts?: TemplatesListOptions): Promise<number>;
+export declare function runTemplatesShow(opts: TemplatesShowOptions): Promise<number>;
 export declare function runTemplatesDeploy(opts?: TemplatesDeployOptions): Promise<number>;