xtrm-cli 0.5.0

package/src/core/interactive-plan.ts

@@ -0,0 +1,165 @@
+// @ts-ignore
+import prompts from 'prompts';
+import kleur from 'kleur';
+import type { PreflightPlan, TargetPlan, OptionalServerItem } from './preflight.js';
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface SelectedFileItem {
+    target: string;
+    name: string;
+    status: 'missing' | 'outdated' | 'drifted';
+    category: string;
+}
+
+export interface SelectedMcpItem {
+    target: string;
+    agent: string;
+    name: string;
+}
+
+export interface SelectedPlan {
+    files: SelectedFileItem[];
+    mcpCore: SelectedMcpItem[];
+    optionalServers: OptionalServerItem[];
+    repoRoot: string;
+    syncMode: 'copy' | 'symlink';
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+const STATUS_LABEL: Record<string, string> = {
+    missing:  kleur.green('[+]'),
+    outdated: kleur.yellow('[↑]'),    // yellow = actionable warning, not blue
+    drifted:  kleur.magenta('[≠]'),   // magenta = conflict/divergence
+};
+
+function fileChoices(target: TargetPlan): any[] {
+    if (target.files.length === 0) return [];
+    const choices: any[] = [
+        { title: kleur.bold().dim(`  ── ${target.label} files ──`), disabled: true, value: null },
+    ];
+    for (const f of target.files) {
+        const label = STATUS_LABEL[f.status] ?? '[?]';
+        const hint = f.status === 'drifted' ? kleur.dim('  local edits — skip recommended') : '';
+        choices.push({
+            title: `  ${label} ${f.category}/${f.name}${hint}`,
+            value: { type: 'file', target: target.target, name: f.name, status: f.status, category: f.category },
+            selected: f.status !== 'drifted',
+        });
+    }
+    return choices;
+}
+
+function mcpCoreChoices(target: TargetPlan): any[] {
+    const uninstalled = target.mcpCore.filter(m => !m.installed);
+    const installed   = target.mcpCore.filter(m => m.installed);
+    if (target.mcpCore.length === 0) return [];
+
+    const choices: any[] = [
+        { title: kleur.bold().dim(`  ── ${target.label} MCP servers ──`), disabled: true, value: null },
+    ];
+    for (const m of uninstalled) {
+        choices.push({
+            title: `  ${kleur.green('[+]')} ${m.name}`,
+            value: { type: 'mcp-core', target: target.target, agent: target.agent, name: m.name },
+            selected: true,
+        });
+    }
+    for (const m of installed) {
+        choices.push({
+            title: kleur.dim(`  [=] ${m.name}  (already installed)`),
+            disabled: true,
+            value: null,
+        });
+    }
+    return choices;
+}
+
+function optionalChoices(optionalServers: OptionalServerItem[]): any[] {
+    if (optionalServers.length === 0) return [];
+    const choices: any[] = [
+        { title: kleur.bold().dim('  ── optional servers ──'), disabled: true, value: null },
+    ];
+    for (const s of optionalServers) {
+        const prereq = s.prerequisite ? kleur.yellow(` ⚠ ${s.prerequisite}`) : '';
+        choices.push({
+            title: `  ${kleur.yellow('[?]')} ${s.name}${prereq}`,
+            value: { type: 'mcp-optional', server: s },
+            selected: false,
+        });
+    }
+    return choices;
+}
+
+// ── Main export ────────────────────────────────────────────────────────────
+
+export async function interactivePlan(
+    plan: PreflightPlan,
+    opts: { dryRun?: boolean; yes?: boolean } = {}
+): Promise<SelectedPlan | null> {
+    const allChoices = [
+        ...plan.targets.flatMap(t => [...fileChoices(t), ...mcpCoreChoices(t)]),
+        ...optionalChoices(plan.optionalServers),
+    ].filter(c => c.title); // remove any undefined entries
+
+    const totalSelectable = allChoices.filter(c => !c.disabled && c.value !== null).length;
+
+    if (totalSelectable === 0) {
+        console.log(kleur.green('\n✓ Everything is up-to-date\n'));
+        return { files: [], mcpCore: [], optionalServers: [], repoRoot: plan.repoRoot, syncMode: plan.syncMode };
+    }
+
+    console.log(kleur.bold('\n📋 Sync Plan') + kleur.dim('  (space to toggle, a = all, enter to confirm)\n'));
+
+    if (opts.dryRun) {
+        // Just display, don't prompt
+        for (const c of allChoices) {
+            if (c.disabled) { console.log(kleur.dim(c.title)); continue; }
+            const bullet = c.selected ? '◉' : '◯';
+            console.log(`  ${bullet} ${c.title?.trim()}`);
+        }
+        console.log(kleur.cyan('\n💡 Dry run — no changes written\n'));
+        return null;
+    }
+
+    if (opts.yes) {
+        // Select all pre-selected defaults, skip prompt
+        const selected = allChoices.filter(c => !c.disabled && c.selected && c.value).map(c => c.value);
+        return buildSelectedPlan(selected, plan);
+    }
+
+    const response = await prompts({
+        type: 'multiselect',
+        name: 'selected',
+        message: 'Select items to sync:',
+        choices: allChoices,
+        hint: 'space to toggle · a = all · enter to confirm',
+        instructions: false,
+        min: 0,
+    });
+
+    // ctrl+c returns undefined
+    if (!response || response.selected === undefined) {
+        console.log(kleur.gray('\n  Cancelled.\n'));
+        return null;
+    }
+
+    return buildSelectedPlan(response.selected, plan);
+}
+
+function buildSelectedPlan(selected: any[], plan: PreflightPlan): SelectedPlan {
+    const files: SelectedFileItem[] = selected
+        .filter(v => v?.type === 'file')
+        .map(v => ({ target: v.target, name: v.name, status: v.status, category: v.category }));
+
+    const mcpCore: SelectedMcpItem[] = selected
+        .filter(v => v?.type === 'mcp-core')
+        .map(v => ({ target: v.target, agent: v.agent, name: v.name }));
+
+    const optionalServers: OptionalServerItem[] = selected
+        .filter(v => v?.type === 'mcp-optional')
+        .map(v => v.server);
+
+    return { files, mcpCore, optionalServers, repoRoot: plan.repoRoot, syncMode: plan.syncMode };
+}

package/src/core/manifest.ts

@@ -0,0 +1,26 @@
+import fs from 'fs-extra';
+import { join } from 'path';
+import { Manifest, ManifestSchema } from '../types/config.js';
+
+const MANIFEST_FILE = '.jaggers-sync-manifest.json';
+
+export function getManifestPath(projectDir: string): string {
+    return join(projectDir, MANIFEST_FILE);
+}
+
+export async function loadManifest(projectDir: string): Promise<Manifest | null> {
+    const manifestPath = join(projectDir, MANIFEST_FILE);
+
+    try {
+        const content = await fs.readJson(manifestPath);
+        // Let schema validation gracefully fail or handle legacy
+        return ManifestSchema.parse(content) as Manifest;
+    } catch {
+        return null;
+    }
+}
+
+export async function saveManifest(projectDir: string, manifest: any): Promise<void> {
+    const manifestPath = join(projectDir, MANIFEST_FILE);
+    await fs.writeJson(manifestPath, manifest, { spaces: 2 });
+}

package/src/core/preflight.ts

@@ -0,0 +1,142 @@
+import path from 'path';
+import os from 'os';
+import fs from 'fs-extra';
+import { spawnSync } from 'child_process';
+import { calculateDiff } from './diff.js';
+import {
+    loadCanonicalMcpConfig,
+    getCurrentServers,
+    detectAgent,
+} from '../utils/sync-mcp-cli.js';
+import type { ChangeSet, ChangeSetCategory } from '../types/config.js';
+import type { AgentName } from '../utils/sync-mcp-cli.js';
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface FileItem {
+    name: string;
+    status: 'missing' | 'outdated' | 'drifted';
+    category: string;
+}
+
+export interface McpItem {
+    name: string;
+    installed: boolean;
+}
+
+export interface TargetPlan {
+    target: string;
+    label: string;
+    agent: string | null;
+    files: FileItem[];
+    mcpCore: McpItem[];
+    changeSet: ChangeSet;
+}
+
+export interface OptionalServerItem {
+    name: string;
+    description: string;
+    prerequisite?: string;
+    installCmd?: string;
+    postInstallMessage?: string;
+}
+
+export interface PreflightPlan {
+    targets: TargetPlan[];
+    optionalServers: OptionalServerItem[];
+    repoRoot: string;
+    syncMode: 'copy' | 'symlink' | 'prune';
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function getCandidatePaths(): Array<{ label: string; path: string }> {
+    const home = os.homedir();
+    return [
+        { label: '~/.claude (hooks + skills)', path: path.join(home, '.claude') },
+        { label: '.qwen', path: path.join(home, '.qwen') },
+        { label: '~/.agents/skills', path: path.join(home, '.agents', 'skills') },
+    ];
+}
+
+export function isBinaryAvailable(binary: string): boolean {
+    // Uses spawnSync (not shell exec) to avoid shell injection; binary is always
+    // a hard-coded internal constant, never user-supplied input.
+    const result = spawnSync('which', [binary], { stdio: 'pipe' });
+    return result.status === 0;
+}
+
+// ── Main export ────────────────────────────────────────────────────────────
+
+export async function runPreflight(
+    repoRoot: string,
+    prune = false
+): Promise<PreflightPlan> {
+    const candidates = getCandidatePaths();
+
+    // Fix 4: Hoist canonical MCP config load outside the per-target map (read once, not N times)
+    const canonicalMcp = loadCanonicalMcpConfig(repoRoot);
+
+    // Run all target checks in parallel
+    const targetResults = await Promise.all(
+        candidates.map(async (c) => {
+            // Fix 1: Per-target error isolation — one bad target doesn't abort the whole preflight
+            try {
+                const exists = await fs.pathExists(c.path);
+                if (!exists) return null;
+
+                const agent = detectAgent(c.path);
+
+                const changeSet = await calculateDiff(repoRoot, c.path, prune);
+
+                // Fix 3: Use proper ChangeSetCategory type cast instead of `cat as any`
+                const files: FileItem[] = [];
+                for (const [category, cat] of Object.entries(changeSet) as [string, ChangeSetCategory][]) {
+                    for (const name of cat.missing)  files.push({ name, status: 'missing',  category });
+                    for (const name of cat.outdated) files.push({ name, status: 'outdated', category });
+                    for (const name of cat.drifted)  files.push({ name, status: 'drifted',  category });
+                }
+
+                const installedMcp = agent ? getCurrentServers(agent) : [];
+                const mcpCore: McpItem[] = Object.keys(canonicalMcp.mcpServers || {}).map(name => ({
+                    name,
+                    installed: installedMcp.includes(name),
+                }));
+
+                return { target: c.path, label: c.label, agent, files, mcpCore, changeSet };
+            } catch (err) {
+                console.warn(`⚠ Preflight skipped ${c.label}: ${(err as Error).message}`);
+                return null;
+            }
+        })
+    );
+
+    const targets = targetResults.filter((t): t is TargetPlan => t !== null);
+
+    // Fix 2: Gather all actually installed MCP servers (across all agents, core + optional)
+    // allInstalledMcp previously only contained core server names from mcpCore — optional servers
+    // installed via CLI were never excluded from the optionalServers list.
+    const allInstalledMcp = new Set<string>();
+    for (const t of targets) {
+        if (t.agent) {
+            const installed = getCurrentServers(t.agent as AgentName);
+            for (const name of installed) allInstalledMcp.add(name);
+        }
+    }
+
+    // Load optional servers config
+    const optionalConfig = loadCanonicalMcpConfig(repoRoot, true);
+
+    const optionalServers: OptionalServerItem[] = Object.entries(optionalConfig.mcpServers || {})
+        .filter(([name]) => !allInstalledMcp.has(name))
+        .map(([name, server]: [string, any]) => ({
+            name,
+            description: server._notes?.description || '',
+            prerequisite: server._notes?.prerequisite,
+            installCmd: server._notes?.install_cmd,
+            postInstallMessage: server._notes?.post_install_message,
+        }));
+
+    const syncMode: 'copy' | 'symlink' | 'prune' = prune ? 'prune' : 'copy';
+    return { targets, optionalServers, repoRoot, syncMode };
+}

package/src/core/rollback.ts

@@ -0,0 +1,32 @@
+import fs from 'fs-extra';
+
+export interface BackupInfo {
+    originalPath: string;
+    backupPath: string;
+    timestamp: Date;
+}
+
+export async function createBackup(filePath: string): Promise<BackupInfo> {
+    const timestamp = Date.now();
+    const backupPath = `${filePath}.backup-${timestamp}`;
+
+    if (await fs.pathExists(filePath)) {
+        await fs.copy(filePath, backupPath);
+    }
+
+    return {
+        originalPath: filePath,
+        backupPath,
+        timestamp: new Date(),
+    };
+}
+
+export async function restoreBackup(backup: BackupInfo): Promise<void> {
+    if (await fs.pathExists(backup.backupPath)) {
+        await fs.move(backup.backupPath, backup.originalPath, { overwrite: true });
+    }
+}
+
+export async function cleanupBackup(backup: BackupInfo): Promise<void> {
+    await fs.remove(backup.backupPath);
+}

package/src/core/session-state.ts

@@ -0,0 +1,139 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+export const SESSION_STATE_FILE = '.xtrm-session-state.json';
+
+export const SESSION_PHASES = [
+  'claimed',
+  'phase1-done',
+  'waiting-merge',
+  'conflicting',
+  'pending-cleanup',
+  'merged',
+  'cleanup-done',
+] as const;
+
+export type SessionPhase = typeof SESSION_PHASES[number];
+
+export interface SessionState {
+  issueId: string;
+  branch: string;
+  worktreePath: string;
+  prNumber: number | null;
+  prUrl: string | null;
+  phase: SessionPhase;
+  conflictFiles: string[];
+  startedAt: string;
+  lastChecked: string;
+}
+
+const ALLOWED_TRANSITIONS: Record<SessionPhase, SessionPhase[]> = {
+  claimed: ['phase1-done', 'waiting-merge', 'conflicting', 'pending-cleanup', 'cleanup-done'],
+  'phase1-done': ['waiting-merge', 'conflicting', 'pending-cleanup', 'cleanup-done'],
+  'waiting-merge': ['conflicting', 'pending-cleanup', 'merged', 'cleanup-done'],
+  conflicting: ['waiting-merge', 'pending-cleanup', 'merged', 'cleanup-done'],
+  'pending-cleanup': ['waiting-merge', 'conflicting', 'merged', 'cleanup-done'],
+  merged: ['cleanup-done'],
+  'cleanup-done': [],
+};
+
+const nowIso = () => new Date().toISOString();
+
+function isPhase(value: unknown): value is SessionPhase {
+  return typeof value === 'string' && (SESSION_PHASES as readonly string[]).includes(value);
+}
+
+function normalizeState(value: unknown): SessionState {
+  if (!value || typeof value !== 'object') {
+    throw new Error('Invalid session state payload');
+  }
+
+  const state = value as Partial<SessionState>;
+  if (!state.issueId || !state.branch || !state.worktreePath || !state.phase) {
+    throw new Error('Session state requires issueId, branch, worktreePath, and phase');
+  }
+  if (!isPhase(state.phase)) throw new Error(`Invalid session phase: ${String(state.phase)}`);
+
+  return {
+    issueId: String(state.issueId),
+    branch: String(state.branch),
+    worktreePath: String(state.worktreePath),
+    prNumber: state.prNumber ?? null,
+    prUrl: state.prUrl ?? null,
+    phase: state.phase,
+    conflictFiles: Array.isArray(state.conflictFiles) ? state.conflictFiles.map(String) : [],
+    startedAt: state.startedAt || nowIso(),
+    lastChecked: nowIso(),
+  };
+}
+
+function findRepoRoot(cwd: string): string | null {
+  try {
+    return execSync('git rev-parse --show-toplevel', {
+      encoding: 'utf8',
+      cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 5000,
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function findSessionStateFile(startCwd: string = process.cwd()): string | null {
+  let current = path.resolve(startCwd);
+  for (;;) {
+    const candidate = path.join(current, SESSION_STATE_FILE);
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export function readSessionState(startCwd: string = process.cwd()): SessionState | null {
+  const filePath = findSessionStateFile(startCwd);
+  if (!filePath) return null;
+
+  try {
+    const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+    return normalizeState(parsed);
+  } catch {
+    return null;
+  }
+}
+
+export function writeSessionState(state: Partial<SessionState>, cwd: string = process.cwd()): string {
+  const filePath = findSessionStateFile(cwd)
+    ?? (findRepoRoot(cwd) ? path.join(findRepoRoot(cwd) as string, SESSION_STATE_FILE) : path.join(cwd, SESSION_STATE_FILE));
+
+  const normalized = normalizeState(state);
+  writeFileSync(filePath, JSON.stringify(normalized, null, 2) + '\n', 'utf8');
+  return filePath;
+}
+
+export function updateSessionPhase(nextPhase: SessionPhase, startCwd: string = process.cwd(), patch: Partial<SessionState> = {}): SessionState {
+  const filePath = findSessionStateFile(startCwd);
+  if (!filePath) throw new Error('Session state file not found');
+
+  const current = readSessionState(startCwd);
+  if (!current) throw new Error('Session state file invalid');
+
+  if (!isPhase(nextPhase)) {
+    throw new Error(`Invalid session phase: ${String(nextPhase)}`);
+  }
+
+  if (current.phase !== nextPhase && !ALLOWED_TRANSITIONS[current.phase].includes(nextPhase)) {
+    throw new Error(`Invalid phase transition: ${current.phase} -> ${nextPhase}`);
+  }
+
+  const nextState = normalizeState({
+    ...current,
+    ...patch,
+    phase: nextPhase,
+  });
+
+  writeFileSync(filePath, JSON.stringify(nextState, null, 2) + '\n', 'utf8');
+  return nextState;
+}