@blxzer/cursor-trellis 0.2.9 → 0.3.2

package/dist/commands/update.js

@@ -5,6 +5,8 @@ import inquirer from "inquirer";
 import { DIR_NAMES, FILE_NAMES, PATHS } from "../constants/paths.js";
 import { VERSION, PACKAGE_NAME } from "../constants/version.js";
 import { getMigrationsForVersion, getAllMigrations, getMigrationMetadata, getConfigSectionsAddedBetween, } from "../migrations/index.js";
+import { assessCstlDirectoryMigrate } from "../utils/workflow-ownership.js";
+import { isWorkflowInitialized, resolveWorkflowDirName, workflowPath, } from "../utils/workflow-dir.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";
@@ -25,13 +27,18 @@ import { runPostUpdateSmoke } from "../utils/post-update-smoke.js";
 import { assertCursorRulesValid } from "../utils/validate-rules.js";
 import { buildFilePlanFromChanges, createBaseRolloutReport, emitRolloutReport, migrationResultToSummary, summarizeMigrationPlan, } from "../utils/update-rollout-report.js";
 import { snapshotReadinessForRollout } from "../utils/readiness.js";
-const TRELLIS_BLOCK_START = "<!-- TRELLIS:START -->";
-const TRELLIS_BLOCK_END = "<!-- TRELLIS:END -->";
+function logCursor2plusCompatHint(cwd) {
+    const bundleDir = path.join(cwd, DIR_NAMES.WORKFLOW, "local", "cursor2plus");
+    if (!fs.existsSync(bundleDir)) {
+        return;
+    }
+    console.log(chalk.gray("\nCursor++ BYOK: after Cursor/Cursor++ upgrades, run `python .cstl/local/cursor2plus/patch_wpelc8.py --check-compat` before re-applying Method 2.5."));
+}
+const CSTL_BLOCK_START = "<!-- CSTL:START -->";
+const CSTL_BLOCK_END = "<!-- CSTL:END -->";
+const LEGACY_TRELLIS_BLOCK_START = "<!-- TRELLIS:START -->";
+const LEGACY_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)
@@ -43,23 +50,37 @@ const PROTECTED_PATHS = [
     `${DIR_NAMES.WORKFLOW}/.developer`,
     `${DIR_NAMES.WORKFLOW}/.current-task`,
 ];
+function getAgentsBlockMarkers(content) {
+    if (content.includes(CSTL_BLOCK_START)) {
+        return { start: CSTL_BLOCK_START, end: CSTL_BLOCK_END };
+    }
+    if (content.includes(LEGACY_TRELLIS_BLOCK_START)) {
+        return {
+            start: LEGACY_TRELLIS_BLOCK_START,
+            end: LEGACY_TRELLIS_BLOCK_END,
+        };
+    }
+    return null;
+}
 function getTrellisManagedBlock(content) {
-    const start = content.indexOf(TRELLIS_BLOCK_START);
-    if (start === -1) {
+    const markers = getAgentsBlockMarkers(content);
+    if (!markers) {
         return null;
     }
-    const end = content.indexOf(TRELLIS_BLOCK_END, start);
+    const start = content.indexOf(markers.start);
+    const end = content.indexOf(markers.end, start);
     if (end === -1) {
         return null;
     }
-    return content.slice(start, end + TRELLIS_BLOCK_END.length);
+    return content.slice(start, end + markers.end.length);
 }
 function replaceTrellisManagedBlock(existingContent, templateContent) {
-    const existingStart = existingContent.indexOf(TRELLIS_BLOCK_START);
-    if (existingStart === -1) {
+    const existingMarkers = getAgentsBlockMarkers(existingContent);
+    if (!existingMarkers) {
         return null;
     }
-    const existingEnd = existingContent.indexOf(TRELLIS_BLOCK_END, existingStart);
+    const existingStart = existingContent.indexOf(existingMarkers.start);
+    const existingEnd = existingContent.indexOf(existingMarkers.end, existingStart);
     if (existingEnd === -1) {
         return null;
     }
@@ -69,7 +90,28 @@ function replaceTrellisManagedBlock(existingContent, templateContent) {
     }
     return (existingContent.slice(0, existingStart) +
         templateBlock +
-        existingContent.slice(existingEnd + TRELLIS_BLOCK_END.length));
+        existingContent.slice(existingEnd + existingMarkers.end.length));
+}
+function includesCstlRuntimeDirRename(migrations) {
+    return migrations.some((item) => item.type === "rename-dir" &&
+        item.from === ".trellis" &&
+        item.to === ".cstl");
+}
+function upgradeAgentsMdToCstlMarkers(cwd) {
+    const agentsPath = path.join(cwd, FILE_NAMES.AGENTS);
+    if (!fs.existsSync(agentsPath)) {
+        return;
+    }
+    const content = fs.readFileSync(agentsPath, "utf-8");
+    if (!content.includes(LEGACY_TRELLIS_BLOCK_START)) {
+        return;
+    }
+    const upgraded = content
+        .replace(LEGACY_TRELLIS_BLOCK_START, CSTL_BLOCK_START)
+        .replace(LEGACY_TRELLIS_BLOCK_END, CSTL_BLOCK_END)
+        .replace(/\.\/\.trellis\//g, "./.cstl/")
+        .replace(/(?<![A-Za-z0-9_])\.trellis\//g, ".cstl/");
+    fs.writeFileSync(agentsPath, upgraded, "utf-8");
 }
 function buildAgentsMdTemplate(cwd) {
     const fullPath = path.join(cwd, FILE_NAMES.AGENTS);
@@ -201,27 +243,64 @@ function printSafeFileDeleteSummary(classified) {
     console.log("");
 }
 /**
- * Cursor now prefers Agent Skills for manual Trellis entrypoints. Existing
- * legacy `.cursor/commands` files are user-visible duplicates, but update must
- * not delete them silently; surface guidance and leave cleanup explicit.
+ * Commands-only policy residue notice. Cursor's configurator stopped shipping
+ * `.cursor/skills/` (commit acd41a92, v0.2.8); projects initialized before
+ * that carry stale skill directories that pollute the `/` palette with
+ * internal auto-triggered skills and create command+skill double entries for
+ * `finish-work`.
+ *
+ * Safe-file-delete migrations (added in v0.2.10) remove pristine copies
+ * automatically; this notice surfaces residue that survives (user-modified
+ * files, or dry-run preview) so the user knows what remains and why.
  */
-function printCursorCommandSurfaceNotice(cwd) {
-    const legacyCommands = [
-        ".cursor/commands/trellis-continue.md",
-        ".cursor/commands/trellis-finish-work.md",
-    ];
-    const skillEntrypoints = [
-        ".cursor/skills/trellis-continue/SKILL.md",
-        ".cursor/skills/trellis-finish-work/SKILL.md",
-    ];
-    const hasLegacyCommand = legacyCommands.some((relativePath) => fs.existsSync(path.join(cwd, relativePath)));
-    const hasSkillEntrypoint = skillEntrypoints.some((relativePath) => fs.existsSync(path.join(cwd, relativePath)));
-    if (!hasLegacyCommand || !hasSkillEntrypoint)
+const CURSOR_SKILL_RESIDUE_DIRS = [
+    // Current cstl-* names (post-0.3.0)
+    "cstl-brainstorm",
+    "cstl-before-dev",
+    "cstl-check",
+    "cstl-break-loop",
+    "cstl-update-spec",
+    "cstl-finish-work",
+    "cstl-micro-grill",
+    "cstl-meta",
+    "cstl-skill-creator",
+    "cstl-spec-bootstrap",
+    "cstl-cursor2plus-setup",
+    "smart-search-cli",
+    // Legacy trellis-* names also checked for residue detection (pre-0.3.0 projects)
+    "trellis-brainstorm",
+    "trellis-before-dev",
+    "trellis-check",
+    "trellis-break-loop",
+    "trellis-update-spec",
+    "trellis-finish-work",
+    "trellis-micro-grill",
+    "trellis-meta",
+    "trellis-skill-creator",
+    "trellis-spec-bootstrap",
+    "trellis-cursor2plus-setup",
+];
+function printCursorSkillResidueNotice(cwd) {
+    const skillsRoot = path.join(cwd, ".cursor", "skills");
+    if (!fs.existsSync(skillsRoot))
+        return;
+    const foundResidues = [];
+    for (const dir of CURSOR_SKILL_RESIDUE_DIRS) {
+        if (fs.existsSync(path.join(skillsRoot, dir))) {
+            foundResidues.push(dir);
+        }
+    }
+    if (foundResidues.length === 0)
         return;
-    console.log(chalk.cyan("  Cursor command surface notice:"));
-    console.log(chalk.yellow("    Agent Skills are the preferred current Cursor entrypoint surface; " +
-        "legacy .cursor/commands files are compatibility-only and were left untouched."));
-    console.log(chalk.gray("    To remove duplicate Cursor UI entries, delete the legacy command files explicitly after confirming you do not need them."));
+    const hasFinishWorkCmd = fs.existsSync(path.join(cwd, ".cursor", "commands", "cstl-finish-work.md"));
+    const hasFinishWorkSkill = foundResidues.includes("cstl-finish-work") ||
+        foundResidues.includes("trellis-finish-work");
+    console.log(chalk.cyan("  Cursor commands-only skill residue notice:"));
+    console.log(chalk.yellow(`    Found ${foundResidues.length} stale skill director${foundResidues.length === 1 ? "y" : "ies"} under .cursor/skills/ from before the commands-only policy.`));
+    console.log(chalk.gray(`    Pristine copies are auto-removed by safe-file-delete; user-modified files are kept (review manually).`));
+    if (hasFinishWorkCmd && hasFinishWorkSkill) {
+        console.log(chalk.gray("    trellis-finish-work appears as BOTH command and skill — safe-file-delete resolves the duplicate when the skill copy is pristine."));
+    }
     console.log("");
 }
 /**
@@ -245,7 +324,7 @@ function executeSafeFileDeletes(classified, cwd) {
     return deleted;
 }
 /**
- * Load update.skip paths from .trellis/config.yaml
+ * Load update.skip paths from .cstl/config.yaml
  *
  * Parses simple YAML structure:
  *   update:
@@ -256,8 +335,8 @@ function executeSafeFileDeletes(classified, cwd) {
  * @internal Exported for testing only
  */
 export function loadUpdateSkipPaths(cwd) {
-    const configPath = path.join(cwd, DIR_NAMES.WORKFLOW, "config.yaml");
-    if (!fs.existsSync(configPath))
+    const configPath = workflowPath(cwd, "config.yaml");
+    if (!configPath || !fs.existsSync(configPath))
         return [];
     try {
         const content = fs.readFileSync(configPath, "utf-8");
@@ -671,7 +750,9 @@ async function promptConflictResolution(file, options, applyToAll) {
  */
 function createBackupDirPath(cwd) {
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
-    return path.join(cwd, DIR_NAMES.WORKFLOW, `.backup-${timestamp}`);
+    const workflowRoot = workflowPath(cwd, `.backup-${timestamp}`) ??
+        path.join(cwd, DIR_NAMES.WORKFLOW, `.backup-${timestamp}`);
+    return workflowRoot;
 }
 /**
  * Backup a single file to the backup directory
@@ -773,15 +854,16 @@ function createFullBackup(cwd) {
  * Update version file
  */
 function updateVersionFile(cwd) {
-    const versionPath = path.join(cwd, DIR_NAMES.WORKFLOW, ".version");
+    const dirName = resolveWorkflowDirName(cwd) ?? DIR_NAMES.WORKFLOW;
+    const versionPath = path.join(cwd, dirName, ".version");
     fs.writeFileSync(versionPath, VERSION);
 }
 /**
  * Get current installed version
  */
 function getInstalledVersion(cwd) {
-    const versionPath = path.join(cwd, DIR_NAMES.WORKFLOW, ".version");
-    if (fs.existsSync(versionPath)) {
+    const versionPath = workflowPath(cwd, ".version");
+    if (versionPath && fs.existsSync(versionPath)) {
         return fs.readFileSync(versionPath, "utf-8").trim();
     }
     return "unknown";
@@ -913,7 +995,7 @@ function classifyMigrations(migrations, cwd, hashes, templates) {
             continue;
         }
         // For non-rename types, also block writing TO protected paths
-        // rename/rename-dir are allowed to target protected paths (e.g., 0.2.0 renames into .trellis/workspace)
+        // rename/rename-dir are allowed to target protected paths (e.g., 0.2.0 renames into .cstl/workspace)
         if (item.to &&
             isProtectedPath(item.to) &&
             item.type !== "rename" &&
@@ -1266,7 +1348,7 @@ async function executeMigrations(classified, cwd, options) {
         }
         // For `backup-rename`, leave an inline .backup copy of the user's modified
         // original next to the new location (for rename) or in place (for delete).
-        // This is in addition to the full project snapshot at .trellis/.backup-*/;
+        // This is in addition to the full project snapshot at .cstl/.backup-*/;
         // the inline copy is more discoverable when the user wants to diff or merge
         // their customizations against the new template.
         if (item.type === "rename" && item.to) {
@@ -1291,7 +1373,7 @@ async function executeMigrations(classified, cwd, options) {
             const filePath = path.join(cwd, item.from);
             if (action === "backup-rename") {
                 // Keep a .backup copy in place before deletion so the user can recover
-                // inline without digging through .trellis/.backup-*/.
+                // inline without digging through .cstl/.backup-*/.
                 fs.copyFileSync(filePath, filePath + ".backup");
             }
             fs.unlinkSync(filePath);
@@ -1352,7 +1434,7 @@ function releaseBlockersFromReadiness(readiness, cliBehindNpm, cliVersion, lates
         blockers.push({
             code: "cli_behind_npm",
             message: `CLI ${cliVersion} is behind npm ${latestNpmVersion}`,
-            recovery: ["trellis upgrade"],
+            recovery: ["cstl upgrade"],
         });
     }
     if (!readiness.skipped && !readiness.smartSearch.ok) {
@@ -1361,7 +1443,7 @@ function releaseBlockersFromReadiness(readiness, cliBehindNpm, cliVersion, lates
             message: "Smart Search readiness did not pass",
             recovery: [
                 "smart-search doctor --format json",
-                "trellis update --skip-readiness",
+                "cstl update --skip-readiness",
             ],
         });
     }
@@ -1370,7 +1452,7 @@ function releaseBlockersFromReadiness(readiness, cliBehindNpm, cliVersion, lates
             blockers.push({
                 code: `capability_${cap.id}`,
                 message: `Capability ${cap.id} readiness failed`,
-                recovery: ["trellis update --skip-readiness"],
+                recovery: ["cstl update --skip-readiness"],
             });
         }
     }
@@ -1428,10 +1510,10 @@ export async function update(options) {
         });
         finishRollout(options, report);
     };
-    // Check if Trellis is initialized
-    if (!fs.existsSync(path.join(cwd, DIR_NAMES.WORKFLOW))) {
+    // Check if cursor-trellis is initialized (.cstl/ or legacy .trellis/)
+    if (!isWorkflowInitialized(cwd)) {
         console.log(chalk.red("Error: Trellis not initialized in this directory."));
-        console.log(chalk.gray("Run 'trellis init' first."));
+        console.log(chalk.gray("Run 'cstl init' first."));
         emitEarly("blocked_not_initialized");
         return;
     }
@@ -1441,13 +1523,13 @@ export async function update(options) {
     setupProxy();
     checkSmartSearchReadiness({
         skipReadiness: options.skipReadiness,
-        skipReadinessCommand: "trellis update --skip-readiness",
+        skipReadinessCommand: "cstl update --skip-readiness",
     });
     checkProjectCapabilityReadiness({
         cwd,
         selected: loadProjectCapabilities(cwd),
         skipReadiness: options.skipReadiness,
-        skipReadinessCommand: "trellis update --skip-readiness",
+        skipReadinessCommand: "cstl update --skip-readiness",
     });
     readinessSnapshot = snapshotReadinessForRollout({
         cwd,
@@ -1476,7 +1558,7 @@ export async function update(options) {
     // Check if CLI is outdated compared to npm
     if (cliVsNpm < 0 && latestNpmVersion) {
         console.log(chalk.yellow(`⚠️  Your CLI (${cliVersion}) is behind npm (${latestNpmVersion}).`));
-        console.log(chalk.yellow(`   Run: trellis upgrade\n`));
+        console.log(chalk.yellow(`   Run: cstl upgrade\n`));
     }
     // Check for downgrade situation
     if (cliVsProject < 0) {
@@ -1484,8 +1566,8 @@ export async function update(options) {
         console.log(chalk.red(`   This would DOWNGRADE your project!\n`));
         if (!options.allowDowngrade) {
             console.log(chalk.gray("Solutions:"));
-            console.log(chalk.gray(`  1. Update your CLI: trellis upgrade`));
-            console.log(chalk.gray(`  2. Force downgrade: trellis update --allow-downgrade\n`));
+            console.log(chalk.gray(`  1. Update your CLI: cstl upgrade`));
+            console.log(chalk.gray(`  2. Force downgrade: cstl update --allow-downgrade\n`));
             emitEarly("blocked_downgrade");
             return;
         }
@@ -1498,13 +1580,13 @@ export async function update(options) {
     // Handle unknown version - skip regular migrations but safe-file-delete still runs
     const isUnknownVersion = projectVersion === "unknown";
     if (isUnknownVersion) {
-        console.log(chalk.yellow("⚠️  No version file found. Skipping migrations — run trellis init to fix."));
+        console.log(chalk.yellow("⚠️  No version file found. Skipping migrations — run cstl init to fix."));
         console.log(chalk.gray("   Template updates will still be applied."));
         console.log(chalk.gray("   Safe file cleanup will still run (hash-verified).\n"));
     }
     // Self-heal poisoned manifests: prune entries that no current platform
     // configurator owns. This silently removes user-owned paths that early
-    // buggy versions of `trellis init` over-hashed (e.g. legacy session dirs).
+    // buggy versions of `cstl init` over-hashed (e.g. legacy session dirs).
     {
         const configuredPlatforms = new Set(getConfiguredPlatforms(cwd));
         const prune = pruneOrphanManifestKeys(cwd, [...configuredPlatforms], hashes);
@@ -1530,7 +1612,7 @@ export async function update(options) {
         })();
     // Collect templates (used for both migration classification and change analysis)
     const templates = collectTemplateFiles(cwd, breakingBypass);
-    printCursorCommandSurfaceNotice(cwd);
+    printCursorSkillResidueNotice(cwd);
     // Load update.skip paths (used for both safe-file-delete and template collection)
     const skipPaths = loadUpdateSkipPaths(cwd);
     // Collect safe-file-delete items from ALL manifests (hash match is the safety net)
@@ -1592,7 +1674,7 @@ export async function update(options) {
                 console.log(chalk.bgRed.white.bold(" ✖ MIGRATION REQUIRED ") +
                     chalk.red(` Breaking changes between ${projectVersion} → ${cliVersion} require --migrate.`));
                 console.log("");
-                console.log(chalk.yellow(`  Run: trellis update --migrate`));
+                console.log(chalk.yellow(`  Run: cstl update --migrate`));
                 console.log("");
                 console.log(chalk.gray("  Without --migrate, renamed/relocated files from breaking releases aren't moved,\n" +
                     "  leaving your project with stale paths alongside new templates.\n" +
@@ -1770,7 +1852,7 @@ export async function update(options) {
         // pipeline, or any redirected-stdin context). Guide the operator toward an
         // explicit consent flag or a dry-run first.
         if (!process.stdin.isTTY) {
-            throw new Error("Non-interactive `trellis update` requires an explicit consent flag. " +
+            throw new Error("Non-interactive `cstl update` requires an explicit consent flag. " +
                 "Re-run with --force (apply all), --skip-all (preserve modified), --create-new (.new copies), or --dry-run (preview only).");
         }
         const { proceed } = await inquirer.prompt([
@@ -1795,14 +1877,31 @@ export async function update(options) {
     }
     // Execute migrations if --migrate flag is set
     if (options.migrate && classifiedMigrations) {
+        const pendingRenameItems = [
+            ...classifiedMigrations.auto,
+            ...classifiedMigrations.confirm,
+            ...classifiedMigrations.conflict,
+        ];
+        if (includesCstlRuntimeDirRename(pendingRenameItems)) {
+            const assessment = assessCstlDirectoryMigrate(cwd, {
+                forceCstlMigrate: options.forceCstlMigrate,
+            });
+            if (!assessment.ok) {
+                console.error(chalk.red("Error:"), assessment.reason);
+                process.exit(1);
+            }
+        }
         migrationApplyResult = await executeMigrations(classifiedMigrations, cwd, {
             force: options.force,
             skipAll: options.skipAll,
         });
         printMigrationResult(migrationApplyResult);
+        if (includesCstlRuntimeDirRename(pendingRenameItems)) {
+            upgradeAgentsMdToCstlMarkers(cwd);
+        }
         // Hardcoded: Rename traces-*.md to journal-*.md in workspace directories
         // Why hardcoded: The migration system only supports fixed path renames, not pattern-based.
-        // traces-*.md files are in .trellis/workspace/{developer}/ with variable developer names
+        // traces-*.md files are in .cstl/workspace/{developer}/ with variable developer names
         // and variable file numbers (traces-1.md, traces-2.md, etc.), so we can't enumerate them
         // in the migration manifest. This is a one-time migration for the 0.2.0 naming redesign.
         const workspaceDir = path.join(cwd, PATHS.WORKSPACE);
@@ -1969,6 +2068,7 @@ export async function update(options) {
     }
     const actionWord = isDowngrade ? "Downgrade" : "Update";
     console.log(chalk.green(`\n✅ ${actionWord} complete! (${projectVersion} → ${cliVersion})`));
+    logCursor2plusCompatHint(cwd);
     if (createdNew > 0) {
         console.log(chalk.gray("\nTip: Review .new files and merge changes manually if needed."));
     }
@@ -2028,7 +2128,7 @@ export async function update(options) {
                 prdContent += `**From Version**: ${projectVersion}\n`;
                 prdContent += `**To Version**: ${cliVersion}\n`;
                 prdContent += `**Assignee**: ${currentDeveloper}\n\n`;
-                prdContent += `## Status\n\n- [ ] Review migration guide\n- [ ] Update custom files\n- [ ] Run \`trellis update --migrate\`\n- [ ] Test workflows\n\n`;
+                prdContent += `## Status\n\n- [ ] Review migration guide\n- [ ] Update custom files\n- [ ] Run \`cstl update --migrate\`\n- [ ] Test workflows\n\n`;
                 for (const { version, guide, aiInstructions, } of metadata.migrationGuides) {
                     prdContent += `---\n\n## v${version} Migration Guide\n\n`;
                     prdContent += guide;