@mindfoldhq/trellis 0.5.0-beta.8 → 0.5.0-rc.0

package/dist/commands/update.js

@@ -2,17 +2,30 @@ import fs from "node:fs";
 import path from "node:path";
 import chalk from "chalk";
 import inquirer from "inquirer";
-import { PATHS, DIR_NAMES } from "../constants/paths.js";
+import { DIR_NAMES, FILE_NAMES, PATHS } from "../constants/paths.js";
 import { VERSION, PACKAGE_NAME } from "../constants/version.js";
 import { getMigrationsForVersion, getAllMigrations, getMigrationMetadata, } from "../migrations/index.js";
 import { loadHashes, saveHashes, updateHashes, isTemplateModified, removeHash, renameHash, computeHash, } from "../utils/template-hash.js";
 import { compareVersions } from "../utils/compare-versions.js";
+import { toPosix } from "../utils/posix.js";
 import { setupProxy } from "../utils/proxy.js";
+import { emptyTaskJson } from "../utils/task-json.js";
 // Import templates for comparison
 import { getAllScripts, 
 // Configuration
 configYamlTemplate, gitignoreTemplate, workflowMdTemplate, } from "../templates/trellis/index.js";
+import { agentsMdContent } from "../templates/markdown/index.js";
 import { ALL_MANAGED_DIRS, getConfiguredPlatforms, collectPlatformTemplates, isManagedPath, isManagedRootDir, } from "../configurators/index.js";
+const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
+const TRELLIS_BLOCK_START = "<!-- TRELLIS:START -->";
+const TRELLIS_BLOCK_END = "<!-- TRELLIS:END -->";
+const LEGACY_UNTRACKED_AGENTS_MD_BLOCK_HASHES = new Set([
+    // v0.5.0-beta.17 and earlier wrote AGENTS.md but did not hash-track it.
+    // This hash is the pristine Trellis-managed block before the Subagents
+    // section was added, so old untouched projects can be updated without a
+    // false "modified by you" conflict.
+    "c1f511b1cfc1902f2147da159f09cc51f380b0c9e341cdb3ac5dea5233f3e307",
+]);
 // Paths that should never be touched (true user data)
 // spec/ is user-customized content created during init; update should never modify it
 const PROTECTED_PATHS = [
@@ -22,6 +35,160 @@ const PROTECTED_PATHS = [
     `${DIR_NAMES.WORKFLOW}/.developer`,
     `${DIR_NAMES.WORKFLOW}/.current-task`,
 ];
+function getTrellisManagedBlock(content) {
+    const start = content.indexOf(TRELLIS_BLOCK_START);
+    if (start === -1) {
+        return null;
+    }
+    const end = content.indexOf(TRELLIS_BLOCK_END, start);
+    if (end === -1) {
+        return null;
+    }
+    return content.slice(start, end + TRELLIS_BLOCK_END.length);
+}
+function replaceTrellisManagedBlock(existingContent, templateContent) {
+    const existingStart = existingContent.indexOf(TRELLIS_BLOCK_START);
+    if (existingStart === -1) {
+        return null;
+    }
+    const existingEnd = existingContent.indexOf(TRELLIS_BLOCK_END, existingStart);
+    if (existingEnd === -1) {
+        return null;
+    }
+    const templateBlock = getTrellisManagedBlock(templateContent);
+    if (!templateBlock) {
+        return null;
+    }
+    return (existingContent.slice(0, existingStart) +
+        templateBlock +
+        existingContent.slice(existingEnd + TRELLIS_BLOCK_END.length));
+}
+/**
+ * Workflow-state breadcrumb tag-block replacement (used by buildWorkflowMdTemplate).
+ *
+ * Each `[workflow-state:STATUS]...[/workflow-state:STATUS]` block in workflow.md
+ * is the runtime source of truth for the per-turn breadcrumb that
+ * inject-workflow-state.py / .js read on every UserPromptSubmit. The blocks are
+ * managed by Trellis: when the CLI ships an updated breadcrumb body, every
+ * downstream user project must pick it up (otherwise the per-turn nudge stays
+ * silent on new mandatory steps — see Phase 3.4 commit drift / Phase 1.3 jsonl
+ * curation drift, the bugs that motivated workflow-state-contract.md).
+ *
+ * Replacement contract:
+ *   - For every status block present in the *template* workflow.md, replace
+ *     the user's same-named block with the template version.
+ *   - If a block exists in the template but not in the user's file (either the
+ *     user removed it, or they're upgrading from a pre-tag version), append
+ *     the template block at the end of the file so the runtime hook can find it.
+ *   - Everything outside the named blocks (the user's narrative customizations
+ *     to the Phase Index, Skill Routing tables, etc.) is preserved verbatim.
+ */
+const WORKFLOW_STATE_TAG_RE = /\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n([\s\S]*?)\n\s*\[\/workflow-state:\1\]/g;
+function extractWorkflowStateBlocks(content) {
+    const blocks = new Map();
+    for (const match of content.matchAll(WORKFLOW_STATE_TAG_RE)) {
+        blocks.set(match[1], match[0]);
+    }
+    return blocks;
+}
+function replaceWorkflowStateBlock(content, status, newBlock) {
+    const re = new RegExp(`\\[workflow-state:${status}\\]\\s*\\n[\\s\\S]*?\\n\\s*\\[/workflow-state:${status}\\]`);
+    const match = content.match(re);
+    if (match?.index === undefined) {
+        return { content, replaced: false };
+    }
+    return {
+        content: content.slice(0, match.index) +
+            newBlock +
+            content.slice(match.index + match[0].length),
+        replaced: true,
+    };
+}
+function buildWorkflowMdTemplate(cwd) {
+    const fullPath = path.join(cwd, DIR_NAMES.WORKFLOW, "workflow.md");
+    if (!fs.existsSync(fullPath)) {
+        return workflowMdTemplate;
+    }
+    let existingContent;
+    try {
+        existingContent = fs.readFileSync(fullPath, "utf-8");
+    }
+    catch {
+        return workflowMdTemplate;
+    }
+    const templateBlocks = extractWorkflowStateBlocks(workflowMdTemplate);
+    if (templateBlocks.size === 0) {
+        // Template has no breadcrumb tags — fall back to full overwrite contract.
+        return workflowMdTemplate;
+    }
+    const existingBlocks = extractWorkflowStateBlocks(existingContent);
+    let merged = existingContent;
+    const appendQueue = [];
+    const customizedOverwritten = [];
+    for (const [status, block] of templateBlocks) {
+        const existing = existingBlocks.get(status);
+        if (existing && existing !== block) {
+            customizedOverwritten.push(status);
+        }
+        const result = replaceWorkflowStateBlock(merged, status, block);
+        if (result.replaced) {
+            merged = result.content;
+        }
+        else {
+            // User's file lacks this tag (older format, or user pruned it). Queue
+            // for append so the per-turn hook can find it; runtime degrades to
+            // generic "Refer to workflow.md" otherwise.
+            appendQueue.push(block);
+        }
+    }
+    if (appendQueue.length > 0) {
+        const trimmed = merged.replace(/\s+$/, "");
+        merged = `${trimmed}\n\n${appendQueue.join("\n\n")}\n`;
+    }
+    if (customizedOverwritten.length > 0) {
+        // Surface a one-line note so users who customized breadcrumb bodies know
+        // their edits were replaced. Same trade-off as the AGENTS.md
+        // TRELLIS:START/END managed-block: customizations inside the marked
+        // region are owned by the CLI; everything outside is preserved verbatim.
+        console.log(chalk.yellow(`  Note: workflow.md [workflow-state:${customizedOverwritten.join(", ")}] block(s) ` +
+            `were updated to the latest CLI version. If you had customized breadcrumb wording, ` +
+            `re-apply your edits to the new bodies (content outside [workflow-state:*] tags is preserved).`));
+    }
+    return merged;
+}
+function buildAgentsMdTemplate(cwd) {
+    const fullPath = path.join(cwd, FILE_NAMES.AGENTS);
+    if (!fs.existsSync(fullPath)) {
+        return agentsMdContent;
+    }
+    const existingContent = fs.readFileSync(fullPath, "utf-8");
+    // Existing file already has TRELLIS:START/END markers — replace just the
+    // managed block, preserving everything outside it.
+    const replaced = replaceTrellisManagedBlock(existingContent, agentsMdContent);
+    if (replaced !== null) {
+        return replaced;
+    }
+    // Existing file has no managed-block markers (pre-0.5.0-beta.18 project, or
+    // user hand-wrote AGENTS.md without ever running through Trellis). Append
+    // the template's managed block at the end so user content is preserved
+    // instead of clobbered.
+    const templateBlock = getTrellisManagedBlock(agentsMdContent);
+    if (!templateBlock) {
+        return agentsMdContent;
+    }
+    const trimmed = existingContent.replace(/\s+$/, "");
+    return `${trimmed}\n\n${templateBlock}\n`;
+}
+function isKnownUntrackedTemplate(relativePath, existingContent) {
+    if (relativePath !== FILE_NAMES.AGENTS) {
+        return false;
+    }
+    const managedBlock = getTrellisManagedBlock(existingContent);
+    if (!managedBlock) {
+        return false;
+    }
+    return LEGACY_UNTRACKED_AGENTS_MD_BLOCK_HASHES.has(computeHash(managedBlock));
+}
 /**
  * Check if a path is blocked by PROTECTED_PATHS
  */
@@ -227,6 +394,29 @@ function needsCodexUpgrade(cwd) {
     const hashes = loadHashes(cwd);
     return Object.keys(hashes).some((key) => key.startsWith(".agents/skills/"));
 }
+function preserveExistingClaudeStatusLine(cwd, templates) {
+    const newSettingsContent = templates.get(CLAUDE_SETTINGS_PATH);
+    if (!newSettingsContent)
+        return;
+    const settingsPath = path.join(cwd, CLAUDE_SETTINGS_PATH);
+    if (!fs.existsSync(settingsPath))
+        return;
+    try {
+        const existingSettings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+        if (!Object.prototype.hasOwnProperty.call(existingSettings, "statusLine")) {
+            return;
+        }
+        const newSettings = JSON.parse(newSettingsContent);
+        if (Object.prototype.hasOwnProperty.call(newSettings, "statusLine")) {
+            return;
+        }
+        newSettings.statusLine = existingSettings.statusLine;
+        templates.set(CLAUDE_SETTINGS_PATH, `${JSON.stringify(newSettings, null, 2)}\n`);
+    }
+    catch {
+        // Invalid local JSON is handled by the normal conflict path.
+    }
+}
 function collectTemplateFiles(cwd, extraPlatforms, 
 /**
  * Bypass `update.skip` when collecting templates. Enable this for breaking
@@ -255,11 +445,20 @@ bypassUpdateSkip = false) {
     // just user-facing documentation — `## Phase Index`, `## Phase 1/2/3` headings,
     // and `[workflow-state:STATUS]` tag blocks are parsed by get_context.py /
     // shared hooks, so scripts break silently when workflow.md drifts from the
-    // CLI version. Users who customized their copy land in the normal
-    // "Modified by you" confirm prompt at write time (not force-overwritten).
-    files.set(`${DIR_NAMES.WORKFLOW}/workflow.md`, workflowMdTemplate);
+    // CLI version.
+    //
+    // Starting v0.5.0-rc.0, the breadcrumb tag blocks
+    // `[workflow-state:STATUS]...[/workflow-state:STATUS]` are managed via
+    // per-block replacement (similar to AGENTS.md's TRELLIS:START/END managed
+    // block) so user customizations to the rest of the file (Phase Index,
+    // Skill Routing tables, narrative customizations) are preserved while the
+    // runtime-critical breadcrumb bodies still pick up CLI updates. Outside
+    // the tag blocks the file falls through to the normal "Modified by you"
+    // confirm prompt at write time when the user has edited it.
+    files.set(`${DIR_NAMES.WORKFLOW}/workflow.md`, buildWorkflowMdTemplate(cwd));
     // workspace/index.md stays excluded — it's runtime-appended by add_session.py
     // (journal index) and has no script-parsed structure.
+    files.set(FILE_NAMES.AGENTS, buildAgentsMdTemplate(cwd));
     // Platform-specific templates (only for configured platforms)
     for (const platformId of platforms) {
         const platformFiles = collectPlatformTemplates(platformId);
@@ -269,6 +468,7 @@ bypassUpdateSkip = false) {
             }
         }
     }
+    preserveExistingClaudeStatusLine(cwd, files);
     // Apply update.skip from config.yaml (unless bypassed for breaking release)
     if (!bypassUpdateSkip) {
         const skipPaths = loadUpdateSkipPaths(cwd);
@@ -331,9 +531,11 @@ function analyzeChanges(cwd, hashes, templates) {
                 // Content differs - check if user modified or template updated
                 const storedHash = hashes[relativePath];
                 const currentHash = computeHash(existingContent);
-                if (storedHash && storedHash === currentHash) {
-                    // Hash matches stored hash - user didn't modify, template was updated
-                    // Safe to auto-update
+                if ((storedHash && storedHash === currentHash) ||
+                    (!storedHash &&
+                        isKnownUntrackedTemplate(relativePath, existingContent))) {
+                    // Either the tracked hash matches, or this is a known pristine template
+                    // from before the path was hash-tracked. Safe to auto-update.
                     change.status = "changed";
                     result.autoUpdateFiles.push(change);
                 }
@@ -348,6 +550,15 @@ function analyzeChanges(cwd, hashes, templates) {
     }
     return result;
 }
+function collectMissingAgentsMdHash(changes, hashes) {
+    const files = new Map();
+    for (const file of changes.unchangedFiles) {
+        if (file.relativePath === FILE_NAMES.AGENTS && !hashes[file.relativePath]) {
+            files.set(file.relativePath, file.newContent);
+        }
+    }
+    return files;
+}
 /**
  * Print change summary
  */
@@ -481,11 +692,14 @@ function backupFile(cwd, backupDir, relativePath) {
  * Directories to backup as complete snapshot (derived from platform registry)
  */
 const BACKUP_DIRS = ALL_MANAGED_DIRS;
+/** Root-level managed files to include in update backups. */
+const BACKUP_FILES = [FILE_NAMES.AGENTS];
 /**
  * Patterns to exclude from backup (user data that shouldn't be backed up)
  */
 const BACKUP_EXCLUDE_PATTERNS = [
     ".backup-", // Previous backups
+    "/node_modules", // Installed dependencies; restore via package manager
     "/workspace/", // Developer workspace (user data)
     "/tasks/", // Task data (user data)
     "/spec/", // Spec files (user-customized content)
@@ -506,8 +720,16 @@ const BACKUP_EXCLUDE_PATTERNS = [
  * @internal Exported for testing only
  */
 export function shouldExcludeFromBackup(relativePath) {
+    // Normalize Windows backslashes to forward slashes so patterns like
+    // "/worktrees/" / "/tasks/" match regardless of host OS. Without this,
+    // Windows `path.relative` returns `.claude\worktrees\...` and none of
+    // the slash-prefixed exclude patterns trigger — which causes
+    // `collectAllFiles` to descend into platform worktrees (full nested
+    // project copies) and explode the scan. Same normalization pattern
+    // used by `isManagedPath` in configurators/index.ts.
+    const normalized = relativePath.replace(/\\/g, "/");
     for (const pattern of BACKUP_EXCLUDE_PATTERNS) {
-        if (relativePath.includes(pattern)) {
+        if (normalized.includes(pattern)) {
             return true;
         }
     }
@@ -525,7 +747,7 @@ function createFullBackup(cwd) {
         const dirPath = path.join(cwd, dir);
         if (!fs.existsSync(dirPath))
             continue;
-        const files = collectAllFiles(dirPath);
+        const files = collectAllFiles(dirPath, cwd);
         for (const fullPath of files) {
             const relativePath = path.relative(cwd, fullPath);
             // Skip excluded paths
@@ -539,6 +761,18 @@ function createFullBackup(cwd) {
             backupFile(cwd, backupDir, relativePath);
         }
     }
+    for (const relativePath of BACKUP_FILES) {
+        const fullPath = path.join(cwd, relativePath);
+        if (!fs.existsSync(fullPath))
+            continue;
+        if (shouldExcludeFromBackup(relativePath))
+            continue;
+        if (!hasFiles) {
+            fs.mkdirSync(backupDir, { recursive: true });
+            hasFiles = true;
+        }
+        backupFile(cwd, backupDir, relativePath);
+    }
     return hasFiles ? backupDir : null;
 }
 /**
@@ -577,18 +811,32 @@ async function getLatestNpmVersion() {
 /**
  * Recursively collect all files in a directory
  */
-function collectAllFiles(dirPath) {
+function collectAllFiles(dirPath, cwd = process.cwd()) {
     if (!fs.existsSync(dirPath))
         return [];
     const files = [];
-    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
-    for (const entry of entries) {
-        const fullPath = path.join(dirPath, entry.name);
-        if (entry.isDirectory()) {
-            files.push(...collectAllFiles(fullPath));
-        }
-        else if (entry.isFile()) {
-            files.push(fullPath);
+    const stack = [dirPath];
+    while (stack.length > 0) {
+        const currentDir = stack.pop();
+        if (!currentDir)
+            continue;
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+            const relativePath = path.relative(cwd, fullPath);
+            // Never follow symlinks / Windows directory junctions — a junction
+            // pointing at an ancestor would loop the scan forever. Node's
+            // `isSymbolicLink()` returns true for NTFS junctions since v12.
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                if (!shouldExcludeFromBackup(relativePath)) {
+                    stack.push(fullPath);
+                }
+            }
+            else if (entry.isFile()) {
+                files.push(fullPath);
+            }
         }
     }
     return files;
@@ -603,11 +851,13 @@ function isDirectorySafeToReplace(cwd, dirRelativePath, hashes, templates) {
     const dirFullPath = path.join(cwd, dirRelativePath);
     if (!fs.existsSync(dirFullPath))
         return true;
-    const files = collectAllFiles(dirFullPath);
+    const files = collectAllFiles(dirFullPath, cwd);
     if (files.length === 0)
         return true; // Empty directory is safe
     for (const fullPath of files) {
-        const relativePath = path.relative(cwd, fullPath);
+        // POSIX-normalize: hashes/templates keys are persisted as POSIX, but
+        // `path.relative` returns OS-native separators (backslash on Windows).
+        const relativePath = toPosix(path.relative(cwd, fullPath));
         const storedHash = hashes[relativePath];
         const templateContent = templates.get(relativePath);
         // Check if file matches template content (handles untracked files)
@@ -1256,6 +1506,7 @@ export async function update(options) {
     }
     // Analyze changes (pass hashes for modification detection)
     const changes = analyzeChanges(cwd, hashes, templates);
+    const missingAgentsMdHash = collectMissingAgentsMdHash(changes, hashes);
     // Print summary
     printChangeSummary(changes);
     // First-time hash tracking hint
@@ -1278,6 +1529,9 @@ export async function update(options) {
         changes.changedFiles.length === 0 &&
         !hasPendingMigrations &&
         !hasSafeDeletes) {
+        if (!options.dryRun && missingAgentsMdHash.size > 0) {
+            updateHashes(cwd, missingAgentsMdHash);
+        }
         if (isSameVersion) {
             console.log(chalk.green("✓ Already up to date!"));
         }
@@ -1338,18 +1592,21 @@ export async function update(options) {
         console.log(chalk.gray("[Dry run] No changes made."));
         return;
     }
-    // Confirm
-    const { proceed } = await inquirer.prompt([
-        {
-            type: "confirm",
-            name: "proceed",
-            message: "Proceed?",
-            default: true,
-        },
-    ]);
-    if (!proceed) {
-        console.log(chalk.yellow("Update cancelled."));
-        return;
+    // Batch-resolution flags are explicit consent for non-interactive runs.
+    // Prompting here breaks CI and `node ... update --force --migrate` smoke tests.
+    if (!options.force && !options.skipAll && !options.createNew) {
+        const { proceed } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "proceed",
+                message: "Proceed?",
+                default: true,
+            },
+        ]);
+        if (!proceed) {
+            console.log(chalk.yellow("Update cancelled."));
+            return;
+        }
     }
     // Create complete backup of all managed platform/workflow directories
     const backupDir = createFullBackup(cwd);
@@ -1466,7 +1723,7 @@ export async function update(options) {
     // Update version file
     updateVersionFile(cwd);
     // Update template hashes for new, auto-updated, and overwritten files
-    const filesToHash = new Map();
+    const filesToHash = new Map(missingAgentsMdHash);
     for (const file of changes.newFiles) {
         filesToHash.set(file.relativePath, file.newContent);
     }
@@ -1547,37 +1804,21 @@ export async function update(options) {
                         currentDeveloper = nameMatch[1];
                     }
                 }
-                // Build task.json
+                // Build task.json — canonical 24-field shape via shared factory.
                 const taskTitle = `Migrate to v${cliVersion}`;
                 const todayStr = today.toISOString().split("T")[0];
-                const taskJson = {
+                const taskJson = emptyTaskJson({
+                    id: taskSlug,
+                    name: taskSlug,
                     title: taskTitle,
                     description: `Breaking change migration from v${projectVersion} to v${cliVersion}`,
                     status: "planning",
-                    dev_type: null,
                     scope: "migration",
                     priority: "P1",
                     creator: "trellis-update",
                     assignee: currentDeveloper,
                     createdAt: todayStr,
-                    completedAt: null,
-                    branch: null,
-                    base_branch: null,
-                    worktree_path: null,
-                    current_phase: 0,
-                    next_action: [
-                        { phase: 1, action: "review-guide" },
-                        { phase: 2, action: "update-files" },
-                        { phase: 3, action: "run-migrate" },
-                        { phase: 4, action: "test" },
-                    ],
-                    commit: null,
-                    pr_url: null,
-                    subtasks: [],
-                    children: [],
-                    parent: null,
-                    meta: {},
-                };
+                });
                 // Write task.json
                 const taskJsonPath = path.join(taskDir, "task.json");
                 fs.writeFileSync(taskJsonPath, JSON.stringify(taskJson, null, 2));