@ghl-ai/aw 0.1.37-beta.8 → 0.1.37

package/commands/push-rules.mjs

@@ -0,0 +1,212 @@
+import { existsSync, mkdtempSync, statSync } from 'node:fs';
+import { execFileSync, execSync } from 'node:child_process';
+import { join, normalize, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { REGISTRY_BASE_BRANCH, REGISTRY_REPO, RULES_SOURCE_DIR, AW_CO_AUTHOR } from '../constants.mjs';
+import { syncFileTree } from '../file-tree.mjs';
+
+function normalizeSlashes(path) {
+  return path.replace(/\\/g, '/');
+}
+
+export function isRulesPushInput(input) {
+  if (!input) return false;
+  const normalized = normalizeSlashes(input).replace(/\/+$/, '');
+  return normalized === RULES_SOURCE_DIR
+    || normalized.startsWith(`${RULES_SOURCE_DIR}/`)
+    || normalized === `.aw_registry/${RULES_SOURCE_DIR}`
+    || normalized.startsWith(`.aw_registry/${RULES_SOURCE_DIR}/`);
+}
+
+export function resolveRulesPushSource(input, cwd = process.cwd()) {
+  const localRulesRoot = join(cwd, RULES_SOURCE_DIR);
+  const syncedRulesRoot = join(cwd, '.aw_registry', RULES_SOURCE_DIR);
+
+  if (!input) {
+    if (existsSync(localRulesRoot)) return { sourceRoot: localRulesRoot, sourceType: 'local' };
+    if (existsSync(syncedRulesRoot)) return { sourceRoot: syncedRulesRoot, sourceType: 'synced' };
+    return null;
+  }
+
+  const normalizedInput = normalizeSlashes(input).replace(/\/+$/, '');
+
+  if (normalizedInput === RULES_SOURCE_DIR || normalizedInput.startsWith(`${RULES_SOURCE_DIR}/`)) {
+    if (!existsSync(localRulesRoot)) return null;
+    return { sourceRoot: localRulesRoot, sourceType: 'local' };
+  }
+
+  if (normalizedInput === `.aw_registry/${RULES_SOURCE_DIR}` || normalizedInput.startsWith(`.aw_registry/${RULES_SOURCE_DIR}/`)) {
+    if (!existsSync(syncedRulesRoot)) return null;
+
+    const relativeRulesPath = normalizedInput.slice(`.aw_registry/${RULES_SOURCE_DIR}`.length).replace(/^\/+/, '');
+    const localOverridePath = relativeRulesPath ? join(localRulesRoot, relativeRulesPath) : localRulesRoot;
+    if (existsSync(localOverridePath)) {
+      return { sourceRoot: localRulesRoot, sourceType: 'local' };
+    }
+
+    return { sourceRoot: syncedRulesRoot, sourceType: 'synced' };
+  }
+
+  return null;
+}
+
+export function hasRulesChanges(cwd = process.cwd()) {
+  const candidateDirs = [RULES_SOURCE_DIR, `.aw_registry/${RULES_SOURCE_DIR}`]
+    .filter(rel => existsSync(join(cwd, rel)));
+
+  if (candidateDirs.length === 0) return false;
+
+  try {
+    const output = execSync(
+      `git status --short --untracked-files=all -- ${candidateDirs.map(dir => `"${dir}"`).join(' ')}`,
+      { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    return output.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export function buildRulesPushFile(input, cwd = process.cwd()) {
+  const resolved = resolveRulesPushSource(input, cwd);
+  if (!resolved) return null;
+
+  return {
+    absPath: resolved.sourceRoot,
+    registryTarget: RULES_SOURCE_DIR,
+    type: 'rules',
+    namespace: 'platform',
+    slug: 'rules',
+    isDir: true,
+  };
+}
+
+function buildRulesPrTitle(sourceRoot, cwd) {
+  const rel = normalizeSlashes(relative(cwd, sourceRoot));
+  return rel === RULES_SOURCE_DIR
+    ? 'sync: update platform rules'
+    : `sync: update platform rules from ${rel}`;
+}
+
+function buildRulesPrBody(sourceRoot, sourceType, cwd) {
+  const rel = normalizeSlashes(relative(cwd, sourceRoot)) || RULES_SOURCE_DIR;
+  return [
+    '## Platform Rules Sync',
+    '',
+    `- **Source:** \`${rel}\``,
+    `- **Mode:** ${sourceType === 'local' ? 'canonical local rules' : 'synced rules copy'}`,
+    '',
+    'Uploaded via `aw push-rules`',
+  ].join('\n');
+}
+
+function pushRulesTree(sourceRoot, { repo, dryRun, cwd }) {
+  if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory()) {
+    fmt.cancel(`Rules path not found: ${sourceRoot}`);
+  }
+
+  if (dryRun) {
+    fmt.logInfo(`Would push rules from ${chalk.cyan(normalizeSlashes(relative(cwd, sourceRoot)) || RULES_SOURCE_DIR)}`);
+    fmt.logWarn('No changes made (--dry-run)');
+    fmt.outro(chalk.dim('Remove --dry-run to push'));
+    return;
+  }
+
+  const s = fmt.spinner();
+  s.start('Cloning registry...');
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'aw-push-rules-'));
+
+  try {
+    const repoUrl = repo.startsWith('http') ? repo : `https://github.com/${repo}.git`;
+    execSync(`git clone --filter=blob:none --no-checkout "${repoUrl}" "${tempDir}"`, { stdio: 'pipe' });
+    execSync(`git checkout ${REGISTRY_BASE_BRANCH}`, { cwd: tempDir, stdio: 'pipe' });
+    s.stop('Repository cloned');
+
+    const branch = `sync/rules-${Date.now().toString(36).slice(-5)}`;
+    execSync(`git checkout -b ${branch}`, { cwd: tempDir, stdio: 'pipe' });
+
+    const s2 = fmt.spinner();
+    s2.start('Copying platform rules...');
+
+    syncFileTree(sourceRoot, join(tempDir, RULES_SOURCE_DIR));
+    execSync(`git add -A "${RULES_SOURCE_DIR}"`, { cwd: tempDir, stdio: 'pipe' });
+
+    const diffStatus = execSync('git diff --cached --name-only', { cwd: tempDir, encoding: 'utf8' }).trim();
+    if (!diffStatus) {
+      s2.stop('No changes');
+      fmt.cancel('Nothing to push — remote rules already match local content.');
+    }
+
+    const sourceType = normalize(sourceRoot).includes(normalize(join('.aw_registry', RULES_SOURCE_DIR)))
+      ? 'synced'
+      : 'local';
+    const prTitle = buildRulesPrTitle(sourceRoot, cwd);
+    const prBody = buildRulesPrBody(sourceRoot, sourceType, cwd);
+
+    execSync(`git commit -m "registry: sync platform rules\n\n${AW_CO_AUTHOR}"`, { cwd: tempDir, stdio: 'pipe' });
+    s2.stop('Rules sync prepared');
+
+    const s3 = fmt.spinner();
+    s3.start('Pushing and creating PR...');
+
+    execSync(`git push -u origin ${branch}`, { cwd: tempDir, stdio: 'pipe' });
+
+    let prUrl;
+    try {
+      prUrl = execFileSync('gh', [
+        'pr', 'create',
+        '--base', REGISTRY_BASE_BRANCH,
+        '--title', prTitle,
+        '--body', prBody,
+      ], { cwd: tempDir, encoding: 'utf8' }).trim();
+    } catch {
+      const repoBase = repo.replace(/\.git$/, '');
+      prUrl = `https://github.com/${repoBase}/compare/${REGISTRY_BASE_BRANCH}...${branch}?expand=1`;
+    }
+
+    s3.stop('Branch pushed');
+    fmt.logSuccess(`PR: ${chalk.cyan(prUrl)}`);
+    fmt.outro('Rules push complete');
+  } catch (e) {
+    fmt.cancel(`Rules push failed: ${e.message}`);
+  } finally {
+    execSync(`rm -rf "${tempDir}"`, { stdio: 'pipe' });
+  }
+}
+
+export function pushRulesCommand(args) {
+  const input = args._positional?.[0];
+  const dryRun = args['--dry-run'] === true;
+  const repo = args['--repo'] || REGISTRY_REPO;
+  const cwd = process.cwd();
+
+  fmt.intro('aw push-rules');
+
+  const resolved = resolveRulesPushSource(input, cwd);
+  if (!resolved) {
+    fmt.cancel([
+      'Could not find a rules source to push.',
+      '',
+      `  Checked ${chalk.cyan('.aw_rules/')} and ${chalk.cyan('.aw_registry/.aw_rules/')}.`,
+      '',
+      '  Use `aw pull platform` first or create a local `.aw_rules/` authoring tree.',
+    ].join('\n'));
+  }
+
+  if (resolved.sourceType === 'synced') {
+    fmt.logWarn('Pushing from synced `.aw_registry/.aw_rules/`. Local `.aw_rules/` is safer for authoring.');
+  }
+
+  pushRulesTree(resolved.sourceRoot, { repo, dryRun, cwd });
+}
+
+export const __test__ = {
+  buildRulesPushFile,
+  isRulesPushInput,
+  resolveRulesPushSource,
+  hasRulesChanges,
+};

package/commands/push.mjs

@@ -11,7 +11,7 @@ const exec = promisify(execCb);
 const execFile = promisify(execFileCb);
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
-import { REGISTRY_REPO, REGISTRY_URL, REGISTRY_BASE_BRANCH, REGISTRY_DIR } from '../constants.mjs';
+import { REGISTRY_REPO, REGISTRY_URL, REGISTRY_BASE_BRANCH, REGISTRY_DIR, AW_CO_AUTHOR } from '../constants.mjs';
 import { resolveInput } from '../paths.mjs';
 import { walkRegistryTree } from '../registry.mjs';
 import {
@@ -20,11 +20,11 @@ import {
   createPushBranch,
   checkoutMain,
   isValidClone,
-  findNearestWorktree,
   getLocalRegistryDir,
   commitsAheadOfMain,
   logAheadOfMain,
 } from '../git.mjs';
+import { hasRulesChanges, isRulesPushInput, pushRulesCommand } from './push-rules.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).version;
@@ -192,7 +192,7 @@ function generateCommitMsg(files) {
   const countParts = [...addedParts, ...deletedParts];
 
   const version = VERSION;
-  const trailer = `\n\nGenerated-By: aw/${version}`;
+  const trailer = `\n\nGenerated-By: aw/${version}\n${AW_CO_AUTHOR}`;
 
   if (files.length === 1) {
     const f = files[0];
@@ -452,14 +452,27 @@ export async function pushCommand(args) {
 
   fmt.intro('aw push');
 
+  if (isRulesPushInput(input)) {
+    fmt.logInfo('Detected platform rules path — redirecting to `aw push-rules`.');
+    pushRulesCommand(args);
+    return;
+  }
+
   const repoUrl = REGISTRY_URL;
   if (!isValidClone(awHome, repoUrl)) {
+    if (!input && hasRulesChanges(cwd)) {
+      fmt.logInfo('Detected changes under platform rules — redirecting to `aw push-rules`.');
+      pushRulesCommand(args);
+      return;
+    }
     fmt.cancel('Registry not initialized. Run: aw init');
     return;
   }
 
   // No args = staged files first (git commit behaviour), else auto-detect all changes
   if (!input) {
+    const rulesChanged = hasRulesChanges(cwd);
+
     // Extra paths outside .aw_registry/ that aw also manages: content/ and CODEOWNERS.
     // Detect staged variants for staged-mode and unstaged variants for auto-mode.
     const getExtraStagedPaths = async () => {
@@ -498,6 +511,9 @@ export async function pushCommand(args) {
         };
       });
       const totalCount = files.length + extraStaged.length;
+      if (rulesChanged) {
+        fmt.logWarn('Detected .aw_rules changes — push them separately with `aw push-rules`.');
+      }
       fmt.logInfo(`${chalk.dim('mode:')} staged (${totalCount} file${totalCount > 1 ? 's' : ''})`);
       await doPush(files, awHome, dryRun, worktreeFlow, true, extraStaged);
       return;
@@ -519,6 +535,11 @@ export async function pushCommand(args) {
     }
 
     if (allEntries.length === 0 && extraChanged.length === 0) {
+      if (rulesChanged) {
+        fmt.logInfo('Detected changes under platform rules — redirecting to `aw push-rules`.');
+        pushRulesCommand(args);
+        return;
+      }
       fmt.cancel('Nothing to push — no staged or modified files.\n\n  Stage files in your IDE or use `aw status` to see changes.');
       return;
     }
@@ -548,6 +569,9 @@ export async function pushCommand(args) {
     }
 
     const totalCount = files.length + extraChanged.length;
+    if (rulesChanged) {
+      fmt.logWarn('Detected .aw_rules changes — push them separately with `aw push-rules`.');
+    }
     fmt.logInfo(`${chalk.dim('mode:')} auto (${totalCount} file${totalCount > 1 ? 's' : ''} — stage specific files to push a subset)`);
     await doPush(files, awHome, dryRun, worktreeFlow, false, extraChanged);
     return;

package/commands/slack-sim.mjs

@@ -0,0 +1,128 @@
+import * as fmt from '../fmt.mjs';
+import { loadScenario, listBuiltInScenarios } from '../slack-sim/scenario.mjs';
+import { printDryRun, printScenarioIntro, printState } from '../slack-sim/render.mjs';
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function slackSimCommand(args) {
+  const [subcommand = 'list-scenarios', scenarioRef] = args._positional;
+
+  if (args['--help']) {
+    printHelp();
+    return;
+  }
+
+  if (subcommand === 'list-scenarios') {
+    fmt.intro('aw slack-sim list-scenarios');
+    const scenarios = listBuiltInScenarios();
+    fmt.note(
+      scenarios.map((s) => `${s.name}  ${fmt.chalk.dim(s.path)}`).join('\n'),
+      'Built-in scenarios',
+    );
+    fmt.outro('Done');
+    return;
+  }
+
+  if (!['run', 'replay'].includes(subcommand)) {
+    fmt.cancel(`Unknown slack-sim subcommand: ${subcommand}`);
+    return;
+  }
+
+  const scenario = loadScenario(scenarioRef);
+  const useHttp = Boolean(args['--api-base']) && !args['--in-process'];
+
+  printScenarioIntro(scenario, useHttp ? 'http' : 'in-process');
+  fmt.note(
+    [
+      `source: ${scenario.__file}`,
+      `actions: ${scenario.actions.length}`,
+      `org: ${scenario.session.orgId}`,
+      `team: ${scenario.session.teamId}`,
+    ].join('\n'),
+    'Scenario',
+  );
+
+  if (args['--dry-run']) {
+    printDryRun(scenario);
+    fmt.outro('Dry run complete');
+    return;
+  }
+
+  const transport = useHttp
+    ? await (await import('../slack-sim/http.mjs')).createHttpTransport({
+        apiBase: args['--api-base'],
+        orgId: scenario.session.orgId,
+        teamId: scenario.session.teamId,
+      })
+    : await (await import('../slack-sim/in-process.mjs')).createInProcessTransport();
+
+  try {
+    await transport.start?.();
+    let currentChannel = scenario.defaults.channel;
+    let currentThreadTs = scenario.defaults.threadTs;
+    for (let i = 0; i < scenario.actions.length; i++) {
+      const action = scenario.actions[i];
+      const actionResult = await transport.runAction(action, scenario);
+      currentChannel = actionResult?.channel || action.channel || currentChannel;
+      currentThreadTs = actionResult?.threadTs || action.threadTs || action.thread_ts || (action.type === 'app_mention_top_level' ? actionResult?.ts : currentThreadTs);
+      const state = await transport.getState({
+        channel: currentChannel,
+        threadTs: currentThreadTs,
+      });
+      if (action.type === 'assert') {
+        assertState(state, action);
+        fmt.logSuccess(`Assertion ${i + 1} passed`);
+        continue;
+      }
+      printState(i, action, state);
+      if (args['--wait-for-finish'] && state.status === 'running' && action.type !== 'wait') {
+        await sleep(250);
+      }
+    }
+    fmt.outro('Scenario complete');
+  } finally {
+    await transport.close?.();
+  }
+}
+
+function assertState(state, action) {
+  const failures = [];
+  if (action.status && state.status !== action.status) failures.push(`expected status=${action.status}, got ${state.status}`);
+  if (action.prRole && state.prRole !== action.prRole) failures.push(`expected prRole=${action.prRole}, got ${state.prRole}`);
+  if (action.pollerActive !== undefined && state.pollerActive !== action.pollerActive) {
+    failures.push(`expected pollerActive=${action.pollerActive}, got ${state.pollerActive}`);
+  }
+  if (action.checkpointActive !== undefined && state.checkpointActive !== action.checkpointActive) {
+    failures.push(`expected checkpointActive=${action.checkpointActive}, got ${state.checkpointActive}`);
+  }
+  if (action.prUrlIncludes && !String(state.prUrl || '').includes(action.prUrlIncludes)) {
+    failures.push(`expected prUrl to include "${action.prUrlIncludes}", got ${state.prUrl || '<none>'}`);
+  }
+  if (action.threadContains) {
+    const haystack = (state.messages || []).map((m) => m.text).join('\n');
+    if (!haystack.includes(action.threadContains)) failures.push(`expected thread to contain "${action.threadContains}"`);
+  }
+  if (action.threadNotContains) {
+    const haystack = (state.messages || []).map((m) => m.text).join('\n');
+    if (haystack.includes(action.threadNotContains)) failures.push(`expected thread to not contain "${action.threadNotContains}"`);
+  }
+
+  if (failures.length) {
+    throw new Error(failures.join('; '));
+  }
+}
+
+function printHelp() {
+  fmt.intro('aw slack-sim');
+  fmt.note(
+    [
+      'aw slack-sim list-scenarios',
+      'aw slack-sim run <scenario-file-or-name> [--dry-run] [--in-process] [--api-base <url>]',
+      'aw slack-sim replay <scenario-file-or-name> [--dry-run] [--in-process] [--api-base <url>]',
+    ].join('\n'),
+    'Usage',
+  );
+  fmt.outro('Done');
+}

package/config.mjs

@@ -38,7 +38,7 @@ export function save(workspaceDir, config) {
 export function create(workspaceDir, { namespace, user }) {
   const config = {
     ...DEFAULTS,
-    namespace: namespace || null,
+    namespace: namespace || 'platform',
     user: user || '',
     include: [],
   };

package/constants.mjs

@@ -25,5 +25,12 @@ export const DOCS_SOURCE_DIR = 'content';
 /** Persistent git clone root — ~/.aw/ */
 export const AW_HOME = join(homedir(), '.aw');
 
+/** Directory in platform-docs repo containing platform rules (pulled into .aw_registry/.aw_rules/) */
+export const RULES_SOURCE_DIR = '.aw_rules';
 /** Telemetry endpoint — override with AW_TELEMETRY_URL env var */
-export const TELEMETRY_URL = process.env.AW_TELEMETRY_URL || 'https://services.leadconnectorhq.com/v1/events';
+export const TELEMETRY_URL = process.env.AW_TELEMETRY_URL || 'https://services.leadconnectorhq.com/agentic-workspace/api/telemetry/events';
+
+/** AW bot identity for Co-Authored-By trailers */
+export const AW_BOT_NAME = 'AW';
+export const AW_BOT_EMAIL = process.env.AW_BOT_EMAIL || '273421570+ghl-aw@users.noreply.github.com';
+export const AW_CO_AUTHOR = `Co-Authored-By: ${AW_BOT_NAME} <${AW_BOT_EMAIL}>`;

package/ecc.mjs

@@ -9,7 +9,7 @@ import * as fmt from "./fmt.mjs";
 
 const AW_ECC_REPO_SSH = "git@github.com:shreyansh-ghl/aw-ecc.git";
 const AW_ECC_REPO_HTTPS = "https://github.com/shreyansh-ghl/aw-ecc.git";
-const AW_ECC_TAG = "v1.2.2";
+const AW_ECC_TAG = "v1.2.9";
 
 const MARKETPLACE_NAME = "aw-marketplace";
 const PLUGIN_KEY = `aw@${MARKETPLACE_NAME}`;
@@ -28,10 +28,71 @@ const TARGET_STATE = {
   codex:  { state: ".codex/ecc-install-state.json" },
 };
 
+// User-owned config files that must never be clobbered by aw-ecc install.
+// If these files already exist before `aw init`, we preserve them exactly.
+const PROTECTED_CONFIG_BY_TARGET = {
+  claude: [".claude/settings.json", ".claude.json"],
+  cursor: [".cursor/settings.json", ".cursor/mcp.json"],
+  codex: [".codex/config.toml"],
+};
+
 function run(cmd, opts = {}) {
   return execSync(cmd, { stdio: "pipe", ...opts });
 }
 
+function readIfExists(path) {
+  try { return existsSync(path) ? readFileSync(path, "utf8") : null; } catch { return null; }
+}
+
+function snapshotProtectedConfigs(home, target) {
+  const relPaths = PROTECTED_CONFIG_BY_TARGET[target] || [];
+  return relPaths.map((relPath) => {
+    const absPath = join(home, relPath);
+    const content = readIfExists(absPath);
+    return {
+      relPath,
+      absPath,
+      existedBeforeInstall: content !== null,
+      contentBeforeInstall: content,
+    };
+  });
+}
+
+function restoreProtectedConfigs(snapshot) {
+  let restored = 0;
+  for (const entry of snapshot) {
+    if (entry.existedBeforeInstall) {
+      const current = readIfExists(entry.absPath);
+      if (current === entry.contentBeforeInstall) continue;
+      try {
+        mkdirSync(dirname(entry.absPath), { recursive: true });
+        writeFileSync(entry.absPath, entry.contentBeforeInstall ?? "");
+        restored++;
+      } catch { /* best effort */ }
+      continue;
+    }
+
+    // If aw-ecc created a protected settings file from scratch, remove it.
+    // AW should not own these user config files.
+    try {
+      if (existsSync(entry.absPath)) {
+        rmSync(entry.absPath, { force: true });
+        restored++;
+      }
+    } catch { /* best effort */ }
+  }
+  return restored;
+}
+
+function relProtectedPath(absPath, home) {
+  const normalized = String(absPath || "").replace(/\\/g, "/");
+  for (const rel of Object.values(PROTECTED_CONFIG_BY_TARGET).flat()) {
+    const full = join(home, rel).replace(/\\/g, "/");
+    if (normalized === full) return rel;
+  }
+  return null;
+}
+
 function cloneOrUpdate(tag, dest) {
   // AW_ECC_CLONE_URL overrides the remote (used in tests to point at a local fake repo)
   const overrideUrl = process.env.AW_ECC_CLONE_URL;
@@ -132,6 +193,7 @@ export async function installAwEcc(
   if (!silent) fmt.logStep("Installing aw-ecc engine...");
 
   const repoDir = eccDir();
+  const home = homedir();
 
   try {
     cloneOrUpdate(AW_ECC_TAG, repoDir);
@@ -153,6 +215,8 @@ export async function installAwEcc(
       });
       for (const target of fileCopyTargets) {
         try {
+          const snapshot = snapshotProtectedConfigs(home, target);
+
           // Always use HOME as cwd so files land in ~/.<target>/ globally.
           const runCwd = homedir();
           // For claude: skip commands (plugin handles them as /aw:tdd) but
@@ -173,6 +237,10 @@ export async function installAwEcc(
           if (target === "codex") {
             syncEccToCodex(repoDir);
           }
+
+          // Critical: preserve user-owned config files if they existed before
+          // running aw-ecc (aw should only add, never replace user settings).
+          restoreProtectedConfigs(snapshot);
         } catch { /* target not supported — skip */ }
       }
     }
@@ -201,10 +269,18 @@ export function uninstallAwEcc({ silent = false } = {}) {
     try {
       const data = JSON.parse(readFileSync(statePath, "utf8"));
       for (const op of data.operations || []) {
-        if (op.destinationPath && existsSync(op.destinationPath)) {
-          rmSync(op.destinationPath, { recursive: true, force: true });
+        if (!op.destinationPath) continue;
+        const absPath = op.destinationPath.startsWith("/") ? op.destinationPath : join(HOME, op.destinationPath);
+        const relProtected = relProtectedPath(absPath, HOME);
+        if (relProtected) {
+          // Never delete user settings files as part of aw-ecc uninstall.
+          // AW-specific MCP removal is handled separately in removeMcpConfig().
+          continue;
+        }
+        if (existsSync(absPath)) {
+          rmSync(absPath, { recursive: true, force: true });
           removed++;
-          pruneEmptyParents(op.destinationPath, join(HOME, cfg.state.split("/")[0]));
+          pruneEmptyParents(absPath, join(HOME, cfg.state.split("/")[0]));
         }
       }
       rmSync(statePath, { force: true });

package/file-tree.mjs

@@ -0,0 +1,76 @@
+import {
+  mkdirSync,
+  existsSync,
+  readdirSync,
+  copyFileSync,
+  unlinkSync,
+  rmdirSync,
+} from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+
+/**
+ * Collect all file paths (relative) in a directory tree.
+ */
+export function collectAllPaths(dir, base) {
+  const paths = new Set();
+  if (!existsSync(dir)) return paths;
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      for (const relPath of collectAllPaths(full, base)) paths.add(relPath);
+    } else {
+      paths.add(relative(base, full));
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Mirror all files from src to dest.
+ * By default, local-only files are removed so dest stays in sync with src.
+ */
+export function syncFileTree(src, dest, options = {}) {
+  const { deleteMissing = true } = options;
+  mkdirSync(dest, { recursive: true });
+
+  const remotePaths = collectAllPaths(src, src);
+  const localPaths = collectAllPaths(dest, dest);
+
+  for (const relPath of remotePaths) {
+    const srcPath = join(src, relPath);
+    const destPath = join(dest, relPath);
+    mkdirSync(dirname(destPath), { recursive: true });
+    copyFileSync(srcPath, destPath);
+  }
+
+  if (deleteMissing) {
+    for (const relPath of localPaths) {
+      if (!remotePaths.has(relPath)) {
+        const destPath = join(dest, relPath);
+        try {
+          unlinkSync(destPath);
+        } catch {
+          // best effort
+        }
+      }
+    }
+  }
+
+  function pruneEmpty(dir) {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) pruneEmpty(join(dir, entry.name));
+    }
+    try {
+      if (readdirSync(dir).length === 0 && dir !== dest) rmdirSync(dir);
+    } catch {
+      // best effort
+    }
+  }
+
+  pruneEmpty(dest);
+}

package/fmt.mjs

@@ -72,7 +72,21 @@ export const isCancel = p.isCancel;
 
 export const spinner = () => p.spinner();
 
+export class CancelError extends Error {
+  constructor(message, { exitCode = 1 } = {}) {
+    super(message);
+    this.name = 'CancelError';
+    this.exitCode = exitCode;
+  }
+}
+
 export function cancel(msg) {
+  p.cancel(msg);
+  throw new CancelError(msg);
+}
+
+/** Hard exit — for use in process exception handlers where throwing is unsafe */
+export function cancelAndExit(msg) {
   p.cancel(msg);
   process.exit(1);
 }