@event4u/agent-config 8.4.0 → 8.4.1

package/src/install/plan.ts

@@ -0,0 +1,205 @@
+/**
+ * Plan builder — Phase A3 port of `scripts/install.py:_build_install_plan`.
+ *
+ * Pure: walks one or more source directories, computes the target path
+ * + SHA-256 of every file, and returns a declarative {@link InstallPlan}.
+ * The applier (Phase A4) consumes the plan verbatim — it never recomputes
+ * paths or re-reads the source tree.
+ *
+ * Mirrors:
+ *   - `_sha256_of_file(path)`           → {@link sha256File}
+ *   - `_file_entry(path, kind, ...)`    → {@link fileEntry}
+ *   - `_files_by_tool_from_deploy(...)` → buildInstallPlan loop
+ *   - `_copy_dir_dereferencing_symlinks` walk → {@link walkSourceTree}
+ *
+ * v4 simplifies the Python shape: instead of three helper tables
+ * (`GLOBAL_DEPLOY_SOURCES` × `USER_SCOPE_PATHS` × `_bridge_marker`) the
+ * planner receives a flat list of `(srcDir, destDir, toolId, kind)`
+ * tuples. The mapping table lives in a higher layer (B0 dispatcher) so
+ * the planner stays a pure file walker.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+import type {
+    ConflictPolicy,
+    FileEntry,
+    FileKind,
+    InstallPlan,
+    InstallTarget,
+} from './types.js';
+
+/**
+ * One (source-dir → dest-dir) mapping fed to {@link buildInstallPlan}.
+ *
+ * Mirrors one row of `GLOBAL_DEPLOY_SOURCES[tool_id]` plus its
+ * `USER_SCOPE_PATHS[tool_id]` anchor resolved to an absolute path.
+ */
+export interface PlanSource {
+    /** Tool ID this source belongs to (e.g. `augment`, `cursor`). */
+    readonly toolId: string;
+    /** Absolute source directory to walk. */
+    readonly srcDir: string;
+    /** Absolute destination directory for the walked files. */
+    readonly destDir: string;
+    /** Kind recorded on every {@link FileEntry} produced from this source. */
+    readonly kind: FileKind;
+}
+
+/** Inputs the planner needs to walk source trees and produce an {@link InstallPlan}. */
+export interface PlanInputs {
+    /** Where the install lands (global vs project). */
+    readonly target: InstallTarget;
+    /** Absolute install root anchor (passed through to {@link InstallPlan.root}). */
+    readonly root: string;
+    /** One or more `(srcDir, destDir, toolId, kind)` mappings. */
+    readonly sources: ReadonlyArray<PlanSource>;
+    /** Conflict policy active for this run. */
+    readonly policy: ConflictPolicy;
+}
+
+/**
+ * Hex SHA-256 of `path` content, or `null` if unreadable.
+ *
+ * 1:1 port of `_sha256_of_file`. Bridges intentionally skip this and
+ * pass `null` (their content is a pointer, not committed bytes).
+ */
+export function sha256File(path: string): string | null {
+    try {
+        const data = readFileSync(path);
+        return createHash('sha256').update(data).digest('hex');
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Build one v2 `files[]` entry.
+ *
+ * 1:1 port of `_file_entry(path, kind, hash_content=...)`. `hashContent`
+ * toggles SHA-256 computation: deployed/marker pass `true`, bridges pass
+ * `false` (sha256 stays `null`).
+ */
+export function fileEntry(
+    path: string,
+    kind: FileKind,
+    options: { hashContent: boolean },
+): FileEntry {
+    return {
+        path,
+        kind,
+        sha256: options.hashContent ? sha256File(path) : null,
+    };
+}
+
+/**
+ * Recursively list every file under `dir` (depth-first, sorted).
+ *
+ * Symlinks are followed via `statSync` (matches Python's
+ * `_copy_dir_dereferencing_symlinks` behaviour). Missing directories
+ * return `[]` rather than throwing — caller already validated `srcDir`.
+ */
+export function walkSourceTree(dir: string): readonly string[] {
+    const out: string[] = [];
+    walkInto(dir, out);
+    return out;
+}
+
+function walkInto(dir: string, out: string[]): void {
+    let entries: string[];
+    try {
+        entries = readdirSync(dir).sort();
+    } catch {
+        return;
+    }
+    for (const name of entries) {
+        const full = join(dir, name);
+        let isDir: boolean;
+        try {
+            isDir = statSync(full).isDirectory();
+        } catch {
+            continue;
+        }
+        if (isDir) {
+            walkInto(full, out);
+        } else {
+            out.push(full);
+        }
+    }
+}
+
+/**
+ * Build a declarative install plan.
+ *
+ * For each {@link PlanSource}, walks `srcDir` and emits one {@link FileEntry}
+ * per file with `path = destDir + (file path relative to srcDir)` and a
+ * fresh SHA-256 of the source file (computed once, never recomputed by
+ * the applier). Bridges (`kind=bridge`) keep `sha256=null` per the
+ * Python schema.
+ *
+ * The applier (Phase A4) is path-only — it does not re-walk `srcDir`
+ * and does not re-hash. The plan is the source of truth.
+ */
+export function buildInstallPlan(inputs: PlanInputs): InstallPlan {
+    const filesByTool: Record<string, FileEntry[]> = {};
+
+    for (const source of inputs.sources) {
+        const bucket = filesByTool[source.toolId] ?? [];
+        const files = walkSourceTree(source.srcDir);
+        for (const srcFile of files) {
+            const rel = relative(source.srcDir, srcFile);
+            const destPath = resolve(source.destDir, rel);
+            bucket.push(
+                fileEntry(srcFile, source.kind, {
+                    hashContent: source.kind !== 'bridge',
+                }),
+            );
+            // Override `path` so the entry reflects the *target* (the
+            // applier writes here), not the source we read from.
+            bucket[bucket.length - 1] = {
+                ...bucket[bucket.length - 1]!,
+                path: destPath,
+            };
+        }
+        filesByTool[source.toolId] = bucket;
+    }
+
+    // Ensure every requested toolId appears, even with zero files —
+    // mirrors `_files_by_tool_from_deploy` emitting `[]` so a shrinking
+    // install actually shrinks the recorded inventory.
+    for (const source of inputs.sources) {
+        if (!(source.toolId in filesByTool)) {
+            filesByTool[source.toolId] = [];
+        }
+    }
+
+    return {
+        version: 2,
+        target: inputs.target,
+        root: inputs.root,
+        filesByTool,
+        mergedKeysByTool: {},
+        policy: inputs.policy,
+    };
+}
+
+/**
+ * True when the plan would not modify any file on disk.
+ *
+ * Wizard renders the "nothing to do" screen on `true` (Phase B2).
+ */
+export function isEmptyPlan(plan: InstallPlan): boolean {
+    for (const entries of Object.values(plan.filesByTool)) {
+        if (entries.length > 0) {
+            return false;
+        }
+    }
+    for (const entries of Object.values(plan.mergedKeysByTool)) {
+        if (entries.length > 0) {
+            return false;
+        }
+    }
+    return true;
+}

package/src/install/preflight.ts

@@ -0,0 +1,210 @@
+/**
+ * Pre-flight validation stage — road-to-flow-learnings Phase 0.
+ *
+ * Pure-ish (read-only filesystem probes, no writes) validation that runs
+ * BEFORE {@link buildInstallPlan} output is applied. Each probe produces a
+ * typed {@link PreflightFinding} instead of crashing, so callers (the init
+ * CLI's `--validate-only`, the fleet runner, the wizard) can render the
+ * full finding list and decide.
+ *
+ * Severity contract:
+ *   - `blocking` — the install would fail or corrupt state; `--validate-only`
+ *     exits non-zero on any blocking finding.
+ *   - `warning`  — the install can proceed but the operator should look.
+ *   - `info`     — context surfaced for the report, never gating.
+ */
+
+import { accessSync, constants, existsSync, statSync } from 'node:fs';
+import * as fs from 'node:fs';
+import { dirname } from 'node:path';
+
+import type { PlanInputs } from './plan.js';
+import { buildInstallPlan } from './plan.js';
+import { computeConflicts } from './conflict.js';
+import { detectToolPresence } from './detect.js';
+
+/** Stable identifiers for the four pre-flight probes. */
+export type PreflightCheckId =
+    | 'permissions'
+    | 'disk-space'
+    | 'conflicts'
+    | 'host-detection';
+
+/** One typed pre-flight finding — never a thrown error. */
+export interface PreflightFinding {
+    readonly id: PreflightCheckId;
+    readonly severity: 'blocking' | 'warning' | 'info';
+    /** Absolute path the finding refers to (when path-scoped). */
+    readonly path?: string;
+    readonly message: string;
+    readonly remedy: string;
+}
+
+/** Tunables — defaults are deliberately conservative. */
+export interface PreflightOptions {
+    /** Minimum free bytes required on the volume holding `root`. */
+    readonly diskFloorBytes?: number;
+}
+
+/** Default free-disk floor: 50 MiB — far above any real payload size. */
+export const DEFAULT_DISK_FLOOR_BYTES = 50 * 1024 * 1024;
+
+/** Walk up from `p` to the nearest existing ancestor (inclusive). */
+function nearestExistingAncestor(p: string): string {
+    let cur = p;
+    while (!existsSync(cur)) {
+        const parent = dirname(cur);
+        if (parent === cur) return cur;
+        cur = parent;
+    }
+    return cur;
+}
+
+/** Probe 1 — every distinct destination root must be writable (or creatable). */
+export function checkPermissions(inputs: PlanInputs): PreflightFinding[] {
+    const out: PreflightFinding[] = [];
+    const roots = new Set<string>([inputs.root, ...inputs.sources.map((s) => s.destDir)]);
+    for (const root of roots) {
+        const probe = nearestExistingAncestor(root);
+        try {
+            accessSync(probe, constants.W_OK);
+        } catch {
+            out.push({
+                id: 'permissions',
+                severity: 'blocking',
+                path: root,
+                message: `target root is not writable (nearest existing ancestor: ${probe})`,
+                remedy: `fix permissions on ${probe} or choose a different target`,
+            });
+        }
+        if (existsSync(root)) {
+            try {
+                if (!statSync(root).isDirectory()) {
+                    out.push({
+                        id: 'permissions',
+                        severity: 'blocking',
+                        path: root,
+                        message: 'target root exists but is not a directory',
+                        remedy: `move or remove the file at ${root}`,
+                    });
+                }
+            } catch {
+                // statSync raced with a concurrent delete — treat as absent.
+            }
+        }
+    }
+    return out;
+}
+
+/** Probe 2 — free-disk floor on the volume holding the install root. */
+export function checkDiskSpace(
+    inputs: PlanInputs,
+    opts: PreflightOptions = {},
+): PreflightFinding[] {
+    const floor = opts.diskFloorBytes ?? DEFAULT_DISK_FLOOR_BYTES;
+    const probe = nearestExistingAncestor(inputs.root);
+    // statfsSync is Node >= 18.15; treat absence as "check unavailable",
+    // never as a pass or a fail.
+    const statfsSync = (fs as unknown as {
+        statfsSync?: (p: string) => { bavail: number; bsize: number };
+    }).statfsSync;
+    if (typeof statfsSync !== 'function') {
+        return [
+            {
+                id: 'disk-space',
+                severity: 'info',
+                path: probe,
+                message: 'free-disk check unavailable on this Node runtime',
+                remedy: '',
+            },
+        ];
+    }
+    try {
+        const st = statfsSync(probe);
+        const free = st.bavail * st.bsize;
+        if (free < floor) {
+            return [
+                {
+                    id: 'disk-space',
+                    severity: 'blocking',
+                    path: probe,
+                    message: `free disk ${free} B is below the ${floor} B floor`,
+                    remedy: 'free disk space on the target volume, then re-run',
+                },
+            ];
+        }
+    } catch {
+        return [
+            {
+                id: 'disk-space',
+                severity: 'info',
+                path: probe,
+                message: 'free-disk probe failed (statfs error) — check skipped',
+                remedy: '',
+            },
+        ];
+    }
+    return [];
+}
+
+/** Probe 3 — surface plan conflicts as findings (reuses `computeConflicts`). */
+export function checkConflicts(inputs: PlanInputs): PreflightFinding[] {
+    const plan = buildInstallPlan(inputs);
+    const conflicts = computeConflicts(plan);
+    return conflicts.map((c) => ({
+        id: 'conflicts' as const,
+        severity: 'warning' as const,
+        path: c.path,
+        message: `existing file conflicts with planned ${c.kind} content`,
+        remedy: 'resolve interactively, or pass --force to overwrite',
+    }));
+}
+
+/** Probe 4 — host-detection sanity: report what the target tree looks like. */
+export function checkHostDetection(inputs: PlanInputs): PreflightFinding[] {
+    const presence = detectToolPresence(inputs.root);
+    const detected = Object.entries(presence)
+        .filter(([, v]) => v === true)
+        .map(([k]) => k);
+    if (detected.length === 0) {
+        return [
+            {
+                id: 'host-detection',
+                severity: 'info',
+                path: inputs.root,
+                message: 'no AI-tool directories detected at the target root',
+                remedy: 'expected for a first global install; verify the target path is right',
+            },
+        ];
+    }
+    return [
+        {
+            id: 'host-detection',
+            severity: 'info',
+            path: inputs.root,
+            message: `detected AI-tool surfaces: ${detected.join(', ')}`,
+            remedy: '',
+        },
+    ];
+}
+
+/**
+ * Run the full pre-flight suite. Never throws for probe-level problems —
+ * every issue is a typed finding. Ordering is stable (probe order above).
+ */
+export function runPreflight(
+    inputs: PlanInputs,
+    opts: PreflightOptions = {},
+): PreflightFinding[] {
+    return [
+        ...checkPermissions(inputs),
+        ...checkDiskSpace(inputs, opts),
+        ...checkConflicts(inputs),
+        ...checkHostDetection(inputs),
+    ];
+}
+
+/** True when any finding blocks the install (`--validate-only` exit contract). */
+export function hasBlockingFinding(findings: readonly PreflightFinding[]): boolean {
+    return findings.some((f) => f.severity === 'blocking');
+}

package/src/install/selectedTools.ts

@@ -0,0 +1,52 @@
+/**
+ * Persisted record of the AI tools the user actually selected in the wizard,
+ * at `~/.event4u/agent-config/wizard-tools.json`. This is the user's prior
+ * *selection* — distinct from `installed.lock` (every tool agent-config was
+ * deployed to, which for an `--tools=all` install is the full set) and from
+ * machine tool *detection*.
+ *
+ * Written by the apply route on a real (non-dry-run) wizard-v2 apply, and
+ * read by `detect-tools` so Step 1 pre-selects exactly the prior selection on
+ * a repeat run. Empty / missing → first run → Step 1 falls back to
+ * pre-selecting every installed tool.
+ *
+ * `AGENT_CONFIG_WIZARD_TOOLS` overrides the path (tests only).
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve, dirname } from 'node:path';
+
+function selectedToolsPath(): string {
+    const override = process.env['AGENT_CONFIG_WIZARD_TOOLS'];
+    if (override !== undefined && override.length > 0) return override;
+    return resolve(homedir(), '.event4u', 'agent-config', 'wizard-tools.json');
+}
+
+export function writeSelectedTools(tools: string[]): void {
+    try {
+        const path = selectedToolsPath();
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, `${JSON.stringify({ tools }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    } catch {
+        // Best-effort: a failed write just means the next run falls back to
+        // pre-selecting installed tools.
+    }
+}
+
+/**
+ * Return the recorded selection, or `[]` when absent / unreadable. Optionally
+ * intersect with the known-tool set so a stale id never surfaces.
+ */
+export function readSelectedTools(knownIds?: ReadonlySet<string>): string[] {
+    try {
+        const raw = readFileSync(selectedToolsPath(), 'utf8');
+        const parsed = JSON.parse(raw) as { tools?: unknown };
+        const tools = Array.isArray(parsed.tools)
+            ? parsed.tools.filter((t): t is string => typeof t === 'string')
+            : [];
+        return knownIds === undefined ? tools : tools.filter((t) => knownIds.has(t));
+    } catch {
+        return [];
+    }
+}

package/src/install/toolDetection.ts

@@ -0,0 +1,120 @@
+/**
+ * Native AI-tool presence detection (road-to-wizard-ux-improvements § Phase 2).
+ *
+ * Distinct from `detectToolPresence` (detect.ts), which checks the *project*
+ * for agent-config bridge dirs ("we set up a bridge here"). This module
+ * answers "is the AI tool itself installed on this machine?" by probing the
+ * user's home dir, well-known app bundles, and `$PATH` — so the wizard's
+ * Step-1 list can pre-select detected tools (first run) and show a per-tool
+ * installed/not-installed badge.
+ *
+ * The signal table is intentionally data-driven and best-effort: a tool with
+ * no reliable signal (e.g. a VS Code extension) simply reports `false`
+ * (badge = not installed, no pre-select) — false negatives are acceptable,
+ * false positives are not. Extend `TOOL_SIGNALS` as new tools/signals are
+ * learned; that is the single place to maintain (the accepted trade-off).
+ */
+
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+/** Detection signals for one tool. A tool is "installed" if ANY signal hits. */
+interface ToolSignal {
+    /** Paths relative to the user's home dir (dir or file). */
+    readonly homePaths?: readonly string[];
+    /** Absolute paths (e.g. macOS `/Applications/*.app` bundles). */
+    readonly absPaths?: readonly string[];
+    /** Executable names looked up on `$PATH`. */
+    readonly bins?: readonly string[];
+}
+
+/**
+ * Best-effort signal table keyed by the tool id used in the wizard's
+ * `VALID_TOOLS` (src/ui/wizard/state.ts). Keep ids in sync with that list.
+ */
+const TOOL_SIGNALS: Readonly<Record<string, ToolSignal>> = {
+    'claude-code': { bins: ['claude'], homePaths: ['.claude', '.claude.json', '.config/claude'] },
+    'claude-desktop': { absPaths: ['/Applications/Claude.app'], homePaths: ['Library/Application Support/Claude', '.config/Claude'] },
+    'cursor': { bins: ['cursor'], absPaths: ['/Applications/Cursor.app'], homePaths: ['.cursor'] },
+    'windsurf': { bins: ['windsurf'], absPaths: ['/Applications/Windsurf.app'], homePaths: ['.codeium/windsurf'] },
+    'cline': { homePaths: ['Documents/Cline'] },
+    'gemini-cli': { bins: ['gemini'], homePaths: ['.gemini'] },
+    'copilot': { bins: ['copilot'], homePaths: ['.config/github-copilot'] },
+    'augment': { bins: ['auggie', 'augment'], homePaths: ['.augment'] },
+    'aider': { bins: ['aider'], homePaths: ['.aider.conf.yml'] },
+    'codex': { bins: ['codex'], homePaths: ['.codex'] },
+    'roocode': {},
+    'continue': { homePaths: ['.continue'] },
+    'kilocode': {},
+    'zed': { bins: ['zed'], absPaths: ['/Applications/Zed.app'], homePaths: ['.config/zed'] },
+    'jetbrains': { homePaths: ['Library/Application Support/JetBrains', '.config/JetBrains'] },
+    'kiro': { bins: ['kiro'], absPaths: ['/Applications/Kiro.app'], homePaths: ['.kiro'] },
+    'qoder': { absPaths: ['/Applications/Qoder.app'], homePaths: ['.qoder'] },
+    'opencode': { bins: ['opencode'], homePaths: ['.opencode', '.config/opencode'] },
+    'trae': { absPaths: ['/Applications/Trae.app'], homePaths: ['.trae'] },
+    'antigravity': { absPaths: ['/Applications/Antigravity.app'], homePaths: ['.antigravity'] },
+    'codebuddy': { homePaths: ['.codebuddy'] },
+    'droid': { bins: ['droid'], homePaths: ['.factory', '.droid'] },
+    'warp': { absPaths: ['/Applications/Warp.app', '/Applications/Warp.app/Contents'], homePaths: ['.warp', '.local/share/warp-terminal'] },
+};
+
+export interface DetectToolsOptions {
+    /** User home dir (defaults to `os.homedir()`). Injected for tests. */
+    readonly home?: string;
+    /** `$PATH` value (defaults to `process.env.PATH`). Injected for tests. */
+    readonly pathEnv?: string | undefined;
+}
+
+/** Tool ids this module knows how to probe (the wizard's full tool set). */
+export function knownToolIds(): readonly string[] {
+    return Object.keys(TOOL_SIGNALS);
+}
+
+/**
+ * Is an executable named `name` resolvable on `$PATH`? Exported for one-off
+ * presence checks (e.g. `rtk` on the Editor-and-tooling step). Defaults to
+ * `process.env.PATH`.
+ */
+export function isBinaryOnPath(name: string, pathEnv?: string): boolean {
+    return binOnPath(name, pathEnv ?? process.env['PATH'] ?? '');
+}
+
+function binOnPath(name: string, pathEnv: string): boolean {
+    if (pathEnv.length === 0) return false;
+    for (const dir of pathEnv.split(delimiter)) {
+        if (dir.length === 0) continue;
+        if (existsSync(join(dir, name))) return true;
+        // Windows-style executables.
+        if (existsSync(join(dir, `${name}.exe`)) || existsSync(join(dir, `${name}.cmd`))) return true;
+    }
+    return false;
+}
+
+function isToolInstalled(signal: ToolSignal, home: string, pathEnv: string): boolean {
+    for (const rel of signal.homePaths ?? []) {
+        if (existsSync(join(home, rel))) return true;
+    }
+    for (const abs of signal.absPaths ?? []) {
+        if (existsSync(abs)) return true;
+    }
+    for (const bin of signal.bins ?? []) {
+        if (binOnPath(bin, pathEnv)) return true;
+    }
+    return false;
+}
+
+/**
+ * Probe every known tool and return a `{ <toolId>: installed }` map. Tools
+ * with no reliable signal report `false`. Pure w.r.t. injected `home`/`pathEnv`
+ * (only reads the filesystem), so it's safe to call per wizard boot.
+ */
+export function detectInstalledTools(opts: DetectToolsOptions = {}): Record<string, boolean> {
+    const home = opts.home ?? homedir();
+    const pathEnv = opts.pathEnv ?? process.env['PATH'] ?? '';
+    const out: Record<string, boolean> = {};
+    for (const [id, signal] of Object.entries(TOOL_SIGNALS)) {
+        out[id] = isToolInstalled(signal, home, pathEnv);
+    }
+    return out;
+}