@blxzer/cursor-trellis 0.4.1 → 0.4.3

package/dist/commands/update.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import chalk from "chalk";
 import inquirer from "inquirer";
-import { DIR_NAMES, FILE_NAMES, PATHS } from "../constants/paths.js";
+import { DIR_NAMES, FILE_NAMES, PATHS, isUserMiddlewareOverlayPath, } 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";
@@ -11,29 +11,30 @@ import { loadHashes, saveHashes, updateHashes, isTemplateModified, removeHash, r
 import { compareVersions } from "../utils/compare-versions.js";
 import { toPosix } from "../utils/posix.js";
 import { setupProxy } from "../utils/proxy.js";
-import { checkProjectCapabilityReadiness, checkSmartSearchReadiness, } from "../utils/readiness.js";
+import { reportUpdateReadiness, snapshotReadinessForRollout, } from "../utils/readiness.js";
 import { collectProjectCapabilityTemplates, loadProjectCapabilities, } from "../utils/project-capabilities.js";
+import { applyArtifactMigration, applyKernelCreate, planArtifactMigration, planWaveC, scanContractMigration, writeWaveCConfirmed, } from "@blxzer/cursor-trellis-core/task";
 import { emptyTaskJson } from "../utils/task-json.js";
+import { applyOfficialRetire, composeP36Plan, officialWorkPending, planOfficialSurfaceA, printP36Vernacular, p36SummaryForRollout, waveCWorkPending, } from "../utils/p36-upgrade.js";
 // Import templates for comparison
-import { cursor2plusPatchScript, cursor2plusReadme, cursor2plusConfigExample, subagentModelsExample, trellisTaskModelsJson5Example, trellisTaskModelsConfigPy, } from "../templates/trellis/local/index.js";
 import { getAllScripts, getAllPoolSkeleton, 
 // Configuration
 configYamlTemplate, gitignoreTemplate, workflowMdTemplate, executionStrategyRulesJson, } from "../templates/trellis/index.js";
-import { agentsMdContent } from "../templates/markdown/index.js";
+import { agentsMdContent, frameworkDocs } from "../templates/markdown/index.js";
 import { ALL_MANAGED_DIRS, getConfiguredPlatforms, collectPlatformTemplates, isManagedPath, isManagedRootDir, } from "../configurators/index.js";
 import { getWorkflowRootTemplateFiles } from "../configurators/workflow.js";
 import { replacePythonCommandLiterals } from "../configurators/shared.js";
 import { pruneOrphanManifestKeys } from "../utils/manifest-prune.js";
 import { runPostUpdateSmoke } from "../utils/post-update-smoke.js";
 import { assertCursorRulesValid } from "../utils/validate-rules.js";
+import { cleanupCursor2plusResidue, hasCursor2plusBundleResidue, } from "../utils/cursor2plus-residue-cleanup.js";
 import { buildFilePlanFromChanges, createBaseRolloutReport, emitRolloutReport, migrationResultToSummary, summarizeMigrationPlan, } from "../utils/update-rollout-report.js";
-import { snapshotReadinessForRollout } from "../utils/readiness.js";
-function logCursor2plusCompatHint(cwd) {
-    const bundleDir = path.join(cwd, DIR_NAMES.WORKFLOW, "local", "cursor2plus");
-    if (!fs.existsSync(bundleDir)) {
+function logCursor2plusRetiredResidueNotice(cwd) {
+    if (!hasCursor2plusBundleResidue(cwd)) {
         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."));
+    console.log(chalk.yellow("\nCursor++ path retired: leftover `.cstl/local/cursor2plus/` (or `.trellis/…`) is not an install surface."));
+    console.log(chalk.gray("  Do not run patch scripts. Unmodified managed residue is removed by update hash-safe cleanup; review and manually delete any user-modified leftover files if unused."));
 }
 const CSTL_BLOCK_START = "<!-- CSTL:START -->";
 const CSTL_BLOCK_END = "<!-- CSTL:END -->";
@@ -48,6 +49,7 @@ const PROTECTED_PATHS = [
     `${DIR_NAMES.WORKFLOW}/${DIR_NAMES.WORKSPACE}`, // workspace/
     `${DIR_NAMES.WORKFLOW}/${DIR_NAMES.TASKS}`, // tasks/
     `${DIR_NAMES.WORKFLOW}/${DIR_NAMES.SPEC}`, // spec/
+    PATHS.MIDDLEWARE, // user overlay — never write/delete/hash
     `${DIR_NAMES.WORKFLOW}/.developer`,
     `${DIR_NAMES.WORKFLOW}/.current-task`,
 ];
@@ -509,19 +511,8 @@ bypassUpdateSkip = false) {
     files.set(`${DIR_NAMES.WORKFLOW}/config.yaml`, configYamlTemplate);
     files.set(`${DIR_NAMES.WORKFLOW}/config/execution-strategy-rules.json`, executionStrategyRulesJson);
     files.set(`${DIR_NAMES.WORKFLOW}/.gitignore`, gitignoreTemplate);
-    const localPrefix = `${DIR_NAMES.WORKFLOW}/local`;
-    // Cursor++ BYOK bundle is opt-in from 1.1.0. On update, only refresh it
-    // when the project already has the directory (keep existing installs;
-    // never inject it into projects that declined the opt-in at init time).
-    const cursor2plusInstalled = fs.existsSync(path.join(cwd, localPrefix, "cursor2plus"));
-    if (cursor2plusInstalled) {
-        files.set(`${localPrefix}/cursor2plus/patch_wpelc8.py`, cursor2plusPatchScript);
-        files.set(`${localPrefix}/cursor2plus/trellis_task_models_config.py`, trellisTaskModelsConfigPy);
-        files.set(`${localPrefix}/cursor2plus/README.md`, cursor2plusReadme);
-        files.set(`${localPrefix}/cursor2plus/config.local.json.example`, cursor2plusConfigExample);
-        files.set(`${localPrefix}/subagent-models.json.example`, subagentModelsExample);
-        files.set(`${localPrefix}/trellis-task-models.json5.example`, trellisTaskModelsJson5Example);
-    }
+    // Cursor++ local bundle is retired — never refresh or inject
+    // `.cstl/local/cursor2plus/` (or sibling example files) on update.
     // workflow.md is included here because it is runtime-parsed by
     // get_context.py and shared hooks. Keep it on the normal template update
     // path: if the installed file still matches the tracked hash, update the
@@ -530,6 +521,12 @@ bypassUpdateSkip = false) {
     // platform routing markers outside [workflow-state:*] blocks are also
     // script-consumed.
     files.set(`${DIR_NAMES.WORKFLOW}/workflow.md`, workflowMdTemplate);
+    // Framework docs (.cstl/framework/) — framework-owned, refreshed by update.
+    // New files flow through the standard new/auto-update/hash-conflict
+    // analysis; .cstl/spec/ stays fully protected.
+    for (const doc of frameworkDocs) {
+        files.set(`${PATHS.FRAMEWORK}/${doc.name}`, doc.content);
+    }
     // Project domain glossary stub + ADR rules (user-maintained; conflict
     // handling works the same as workflow.md — modified files prompt first).
     for (const [relativePath, content] of getWorkflowRootTemplateFiles()) {
@@ -566,6 +563,14 @@ bypassUpdateSkip = false) {
     for (const [filePath, content] of files) {
         files.set(filePath, replacePythonCommandLiterals(content));
     }
+    // User overlay is never a template — strip even if a future collector
+    // accidentally adds it. Cursor++ residue cleanup is a separate allow-list
+    // and must not target this directory.
+    for (const [filePath] of [...files]) {
+        if (isUserMiddlewareOverlayPath(filePath)) {
+            files.delete(filePath);
+        }
+    }
     return files;
 }
 /**
@@ -790,6 +795,7 @@ const BACKUP_EXCLUDE_PATTERNS = [
     "/workspace/", // Developer workspace (user data)
     "/tasks/", // Task data (user data)
     "/spec/", // Spec files (user-customized content)
+    "/middleware/", // User middleware overlay (never managed)
     "/backlog/", // Backlog data (user data)
     "/agent-traces/", // Agent traces (user data, legacy name)
     // Platform-native worktree dirs — these are full sub-repos the CLI
@@ -1427,6 +1433,7 @@ function rolloutOptionsFromUpdate(options) {
         migrate: Boolean(options.migrate),
         allowDowngrade: Boolean(options.allowDowngrade),
         skipReadiness: Boolean(options.skipReadiness),
+        writeArtifacts: Boolean(options.writeArtifacts),
     };
 }
 function upgradeDirectionFromCompare(cliVsProject, projectVersion) {
@@ -1450,10 +1457,10 @@ function releaseBlockersFromReadiness(readiness, cliBehindNpm, cliVersion, lates
     if (!readiness.skipped && !readiness.smartSearch.ok) {
         blockers.push({
             code: "smart_search_readiness",
-            message: "Smart Search readiness did not pass",
+            message: "Smart Search readiness unverified (does not block Proceed?)",
             recovery: [
                 "smart-search doctor --format json",
-                "cstl update --skip-readiness",
+                "Treat Smart Search as unverified; official files can still update after Proceed?",
             ],
         });
     }
@@ -1461,8 +1468,10 @@ function releaseBlockersFromReadiness(readiness, cliBehindNpm, cliVersion, lates
         if (!cap.ok) {
             blockers.push({
                 code: `capability_${cap.id}`,
-                message: `Capability ${cap.id} readiness failed`,
-                recovery: ["cstl update --skip-readiness"],
+                message: `Capability ${cap.id} readiness unverified (does not block Proceed?)`,
+                recovery: [
+                    "Treat this capability as unverified; official files can still update after Proceed?",
+                ],
             });
         }
     }
@@ -1531,21 +1540,12 @@ export async function update(options) {
     console.log(chalk.cyan("══════════════\n"));
     // Set up proxy before any network calls (npm version check)
     setupProxy();
-    checkSmartSearchReadiness({
-        skipReadiness: options.skipReadiness,
-        skipReadinessCommand: "cstl update --skip-readiness",
-    });
-    checkProjectCapabilityReadiness({
-        cwd,
-        selected: loadProjectCapabilities(cwd),
-        skipReadiness: options.skipReadiness,
-        skipReadinessCommand: "cstl update --skip-readiness",
-    });
     readinessSnapshot = snapshotReadinessForRollout({
         cwd,
         selected: loadProjectCapabilities(cwd),
         skipReadiness: options.skipReadiness,
     });
+    reportUpdateReadiness(readinessSnapshot);
     // Get versions
     projectVersion = getInstalledVersion(cwd);
     cliVersion = VERSION;
@@ -1716,6 +1716,19 @@ export async function update(options) {
     if (safeFileDeletes.length > 0) {
         printSafeFileDeleteSummary(safeFileDeletes);
     }
+    // Preview Cursor++ residue cleanup (hash-safe; always considered)
+    const cursor2plusResiduePreview = cleanupCursor2plusResidue(cwd, {
+        dryRun: true,
+    });
+    if (cursor2plusResiduePreview.deleted.length > 0) {
+        console.log(chalk.cyan("\nCursor++ residue cleanup (hash-safe):"));
+        for (const rel of cursor2plusResiduePreview.deleted) {
+            console.log(chalk.gray(`  would delete: ${rel}`));
+        }
+    }
+    if (cursor2plusResiduePreview.preservedModified.length > 0) {
+        console.log(chalk.yellow(`  preserve (user-modified): ${cursor2plusResiduePreview.preservedModified.join(", ")}`));
+    }
     // Analyze changes (pass hashes for modification detection)
     const changes = analyzeChanges(cwd, hashes, templates);
     const missingAgentsMdHash = collectMissingAgentsMdHash(changes, hashes);
@@ -1733,6 +1746,7 @@ export async function update(options) {
         userDeletedFiles: changes.userDeletedFiles,
         safeDeletePaths,
     });
+    const p36State = {};
     const emitRollout = (outcome, extra) => {
         const readiness = readinessSnapshot ??
             snapshotReadinessForRollout({
@@ -1759,11 +1773,32 @@ export async function update(options) {
             apply: extra?.apply,
             postUpdateSmoke: extra?.postUpdateSmoke,
             releaseBlockers: releaseBlockersFromReadiness(readiness, cliVsNpm < 0 && latestNpmVersion !== null, cliVersion, latestNpmVersion),
+            p36: extra?.p36 ?? p36State.report,
         });
         finishRollout(options, report);
     };
     // Print summary
     printChangeSummary(changes);
+    const officialPlan = planOfficialSurfaceA({
+        cwd,
+        hashes,
+        refresh: changes.autoUpdateFiles.map((file) => file.relativePath),
+        preserved: changes.changedFiles.map((file) => file.relativePath),
+        added: changes.newFiles.map((file) => file.relativePath),
+    });
+    const artifactPlan = planArtifactMigration({ root: cwd });
+    const waveCPlan = planWaveC({
+        root: cwd,
+        report: scanContractMigration({ root: cwd }),
+    });
+    const p36Plan = composeP36Plan({
+        official: officialPlan,
+        artifacts: artifactPlan,
+        writeArtifacts: Boolean(options.writeArtifacts),
+        waveC: waveCPlan,
+    });
+    p36State.report = p36SummaryForRollout(p36Plan);
+    printP36Vernacular(p36Plan);
     // First-time hash tracking hint
     if (isFirstHashTracking && changes.changedFiles.length > 0) {
         console.log(chalk.cyan("ℹ️  First update with hash tracking enabled."));
@@ -1779,11 +1814,17 @@ export async function update(options) {
         classifiedMigrations &&
         (classifiedMigrations.auto.length > 0 ||
             classifiedMigrations.confirm.length > 0);
+    const hasOfficialP36 = officialWorkPending(officialPlan);
+    const hasMaintainerArtifactWrites = Boolean(options.writeArtifacts) && artifactPlan.writable.length > 0;
+    const hasWaveCPending = waveCWorkPending(p36Plan);
     if (changes.newFiles.length === 0 &&
         changes.autoUpdateFiles.length === 0 &&
         changes.changedFiles.length === 0 &&
         !hasPendingMigrations &&
-        !hasSafeDeletes) {
+        !hasSafeDeletes &&
+        !hasOfficialP36 &&
+        !hasMaintainerArtifactWrites &&
+        !hasWaveCPending) {
         if (!options.dryRun && missingAgentsMdHash.size > 0) {
             updateHashes(cwd, missingAgentsMdHash);
         }
@@ -1853,6 +1894,10 @@ export async function update(options) {
         emitRollout("would_apply", { files: buildRolloutFilePlan() });
         return;
     }
+    // File-conflict flags (--force / --skip-all / --create-new) consent to apply
+    // official A writes. They are not Wave C stop-read confirm. Only interactive
+    // Proceed? yes writes `.cstl/.p36-wave-c.json`.
+    let waveCInteractivelyConfirmed = false;
     // 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) {
@@ -1878,6 +1923,7 @@ export async function update(options) {
             emitRollout("cancelled", { files: buildRolloutFilePlan() });
             return;
         }
+        waveCInteractivelyConfirmed = true;
     }
     // Create complete backup of all managed platform/workflow directories
     const backupDir = createFullBackup(cwd);
@@ -1885,6 +1931,10 @@ export async function update(options) {
     if (backupDir) {
         console.log(chalk.gray(`\nBackup created: ${path.relative(cwd, backupDir)}/`));
     }
+    const officialRetired = applyOfficialRetire(cwd, officialPlan);
+    if (officialRetired > 0) {
+        console.log(chalk.cyan(`\nStopped ${officialRetired} extra official always-on rule(s)`));
+    }
     // Execute migrations if --migrate flag is set
     if (options.migrate && classifiedMigrations) {
         const pendingRenameItems = [
@@ -1946,6 +1996,15 @@ export async function update(options) {
             console.log(chalk.cyan(`\nCleaned up ${safeDeleted} deprecated command file(s)`));
         }
     }
+    // Hash-safe Cursor++ residue cleanup (retired product surfaces)
+    const cursor2plusCleanup = cleanupCursor2plusResidue(cwd);
+    if (cursor2plusCleanup.deleted.length > 0) {
+        safeDeleted += cursor2plusCleanup.deleted.length;
+        console.log(chalk.cyan(`\nCleaned up ${cursor2plusCleanup.deleted.length} retired Cursor++ file(s)`));
+    }
+    if (cursor2plusCleanup.preservedModified.length > 0) {
+        console.log(chalk.yellow(`Preserved user-modified Cursor++ residue: ${cursor2plusCleanup.preservedModified.join(", ")}`));
+    }
     // Track results
     let added = 0;
     let autoUpdated = 0;
@@ -2050,6 +2109,22 @@ export async function update(options) {
     if (filesToHash.size > 0) {
         updateHashes(cwd, filesToHash);
     }
+    let artifactApply = null;
+    if (options.writeArtifacts && artifactPlan.writable.length > 0) {
+        artifactApply = applyArtifactMigration({
+            root: cwd,
+            plan: artifactPlan,
+        });
+        if (artifactApply.ok) {
+            console.log(chalk.cyan(`\nWrote ${artifactApply.written} artifact projection(s); business text kept.`));
+        }
+        else {
+            console.log(chalk.yellow("产物写入失败，已回到双读。项目仍可用，可再跑 update。"));
+            if (artifactApply.error) {
+                console.log(chalk.gray(`  ${artifactApply.error}`));
+            }
+        }
+    }
     // Print summary
     console.log(chalk.cyan("\n--- Summary ---\n"));
     if (added > 0) {
@@ -2073,12 +2148,36 @@ export async function update(options) {
     if (configSectionsAppended > 0) {
         console.log(`  Config sections added: ${configSectionsAppended}`);
     }
+    if (officialRetired > 0) {
+        console.log(`  Official always-on stopped: ${officialRetired}`);
+    }
+    if (artifactApply?.ok && artifactApply.written > 0) {
+        console.log(`  Artifact projections written: ${artifactApply.written}`);
+    }
+    if (artifactApply && !artifactApply.ok) {
+        console.log("  Artifact projections: rolled back to dual-read");
+    }
+    if (hasWaveCPending && waveCInteractivelyConfirmed) {
+        try {
+            writeWaveCConfirmed(cwd);
+            console.log("  已确认停读旧形状（leftover kind/mode/classification 不再当唯一真相）");
+        }
+        catch (err) {
+            console.log(chalk.yellow("停读确认未写上。项目仍可用，旧字段仍双读，可再跑 update。"));
+            if (err instanceof Error && err.message) {
+                console.log(chalk.gray(`  ${err.message}`));
+            }
+        }
+    }
+    else if (hasWaveCPending) {
+        console.log(chalk.yellow("  旧字段仍双读。停读需要再跑一次交互式 `cstl update` 并确认 Proceed?（--force / --skip-all / --create-new 不算停读确认）。"));
+    }
     if (backupDir) {
         console.log(`  Backup: ${path.relative(cwd, backupDir)}/`);
     }
     const actionWord = isDowngrade ? "Downgrade" : "Update";
     console.log(chalk.green(`\n✅ ${actionWord} complete! (${projectVersion} → ${cliVersion})`));
-    logCursor2plusCompatHint(cwd);
+    logCursor2plusRetiredResidueNotice(cwd);
     if (createdNew > 0) {
         console.log(chalk.gray("\nTip: Review .new files and merge changes manually if needed."));
     }
@@ -2129,9 +2228,13 @@ export async function update(options) {
                     assignee: currentDeveloper,
                     createdAt: todayStr,
                 });
-                // Write task.json
-                const taskJsonPath = path.join(taskDir, "task.json");
-                fs.writeFileSync(taskJsonPath, JSON.stringify(taskJson, null, 2));
+                applyKernelCreate({
+                    taskDir,
+                    actor: "cstl update",
+                    idempotencyKey: `update:${taskSlug}`,
+                    record: taskJson,
+                    evidence: "cstl update migration skeleton",
+                });
                 // Build PRD content
                 let prdContent = `# Migration Task: Upgrade to v${cliVersion}\n\n`;
                 prdContent += `**Created**: ${todayStr}\n`;