@event4u/agent-config 8.4.0 → 8.4.1

package/src/install/conflict.ts

@@ -0,0 +1,226 @@
+/**
+ * Conflict resolution — Phase A5 (simplified, three modes).
+ *
+ * Three decisions only, replacing the legacy `prompt → write / skip /
+ * abort` triple from `scripts/install.py:_resolve_file_conflict`:
+ *
+ * - `write`   — target either does not exist OR policy authorises overwrite.
+ * - `skip`    — target exists, known path, not forced: leave it alone.
+ * - `surface` — foreign collision: defer to the wizard's conflict screen
+ *               (Phase B3). Headless callers translate `surface` to `skip`
+ *               unless `policy.force` is true.
+ *
+ * JSON-aware deep-merge stays: callers that detect a `.json` target with
+ * matching `knownPointers` route through {@link mergeJsonContent} instead
+ * of byte-equality.
+ */
+
+import { existsSync } from 'node:fs';
+
+import { sha256File } from './plan.js';
+import type {
+    ConflictEntry,
+    ConflictPolicy,
+    ConflictResolution,
+    FileEntry,
+    InstallPlan,
+} from './types.js';
+
+/** Outcome of {@link resolveFileConflict}. */
+export type ConflictOutcome = 'write' | 'skip' | 'surface';
+
+/** Inputs the resolver needs — purely the target + the active policy. */
+export interface ResolveInputs {
+    /** Absolute path of the target on disk. */
+    readonly targetPath: string;
+    /** True when the byte-comparison says the target matches the plan. */
+    readonly idempotent: boolean;
+    /** True when the target already exists on disk. */
+    readonly exists: boolean;
+    /** Active install policy. */
+    readonly policy: ConflictPolicy;
+}
+
+/**
+ * Decide what to do with a single planned target.
+ *
+ * Decision matrix (mirrors the Python legacy with the 3-option prompt
+ * collapsed into `surface`):
+ *
+ * | Exists? | Idempotent? | Known? | Force? | → Outcome  |
+ * |---------|-------------|--------|--------|------------|
+ * | no      | —           | —      | —      | `write`    |
+ * | yes     | yes         | —      | —      | `skip`     |
+ * | yes     | no          | yes    | no     | `skip`     |
+ * | yes     | no          | yes    | yes    | `write`    |
+ * | yes     | no          | no     | yes    | `write`    |
+ * | yes     | no          | no     | no     | `surface`  |
+ *
+ * Headless callers (B1 CLI) collapse `surface` to `skip` automatically
+ * because there is no UI to defer to; the apply layer records the entry
+ * under {@link ApplyResult.conflicts} so the wizard can pick it up next.
+ */
+export function resolveFileConflict(inputs: ResolveInputs): ConflictOutcome {
+    const { targetPath, idempotent, exists, policy } = inputs;
+    if (!exists) return 'write';
+    if (idempotent) return 'skip';
+
+    const isKnown = policy.knownPaths.has(targetPath);
+    if (isKnown) {
+        return policy.force ? 'write' : 'skip';
+    }
+    if (policy.force) return 'write';
+    return 'surface';
+}
+
+/** JSON value the deep-merge accepts. */
+export type JsonValue = null | boolean | number | string | JsonArray | JsonObject;
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export type JsonArray = ReadonlyArray<JsonValue>;
+
+/**
+ * Recursive object merge — overlay wins, nested dicts merged, arrays replaced.
+ *
+ * Mirrors `scripts/install.py:deep_merge`. Arrays do **not** concatenate;
+ * Claude / Cursor / Cline hook configs rely on whole-array replacement to
+ * stay idempotent across re-runs.
+ *
+ * Returns a fresh object — both inputs remain untouched.
+ */
+export function deepMerge(base: JsonObject, overlay: JsonObject): JsonObject {
+    const out: Record<string, JsonValue> = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        const prev = out[key];
+        if (isPlainObject(prev) && isPlainObject(value)) {
+            out[key] = deepMerge(prev, value);
+        } else {
+            out[key] = cloneValue(value);
+        }
+    }
+    return out;
+}
+
+/**
+ * Merge `overlay` into `existing` and return the canonical 4-space JSON.
+ *
+ * Format matches `write_json_file` in the Python installer (4-space indent,
+ * trailing newline, no ASCII-escape) so the apply layer can compare bytes
+ * to detect idempotent merges and skip the write.
+ */
+export function mergeJsonContent(existing: JsonObject, overlay: JsonObject): string {
+    const merged = deepMerge(existing, overlay);
+    return `${JSON.stringify(merged, null, 4)}\n`;
+}
+
+/**
+ * Parse JSON bytes leniently — invalid / non-object payloads collapse to `{}`.
+ *
+ * Matches `read_json_file` in the legacy script: corrupt JSON is treated
+ * as an empty doc rather than a hard failure, so the merge step always
+ * produces a well-formed output even when an upstream tool wrote a
+ * truncated config.
+ */
+export function parseJsonLenient(content: string): JsonObject {
+    try {
+        const parsed = JSON.parse(content) as unknown;
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed as JsonObject;
+        }
+    } catch {
+        /* fall through — treat as empty */
+    }
+    return {};
+}
+
+/** Heuristic for routing a {@link FileEntry} through JSON merge. */
+export function isJsonTarget(entry: FileEntry): boolean {
+    return entry.kind === 'deployed' && entry.path.endsWith('.json');
+}
+
+/**
+ * Threshold at which the wizard switches the conflict screen from
+ * single-pick to batch-resolution mode (council Finding #19).
+ *
+ * Below the threshold the user picks a resolution per row; at or above
+ * it the screen renders a summary table + global CTAs to dodge the
+ * 50-click stale-tree problem.
+ */
+export const CONFLICT_BATCH_THRESHOLD = 5;
+
+/**
+ * Walk an {@link InstallPlan} and return one {@link ConflictEntry} per
+ * planned target the policy would `surface` to the UI.
+ *
+ * Pure-ish — reads from the filesystem only to compute idempotency
+ * (`existsSync` + `sha256File`). Skips bridges (`sha256 === null`) since
+ * bridge writers own a separate idempotency model. Skips entries whose
+ * `path` is in `policy.knownPaths`, and skips entries that are
+ * byte-equal to the planned content. Returns an empty array when
+ * `policy.force` is true — overwrite mode silences the screen.
+ */
+export function computeConflicts(plan: InstallPlan): readonly ConflictEntry[] {
+    if (plan.policy.force) return [];
+    const out: ConflictEntry[] = [];
+    for (const entries of Object.values(plan.filesByTool)) {
+        for (const entry of entries) {
+            if (entry.kind === 'bridge') continue;
+            if (entry.sha256 === null) continue;
+            if (!existsSync(entry.path)) continue;
+            if (plan.policy.knownPaths.has(entry.path)) continue;
+            const onDisk = sha256File(entry.path);
+            if (onDisk === entry.sha256) continue;
+            out.push({
+                path: entry.path,
+                kind: entry.kind,
+                plannedSha256: entry.sha256,
+                existingSha256: onDisk,
+                mergeable: isJsonTarget(entry),
+            });
+        }
+    }
+    return out;
+}
+
+/**
+ * Expand a batch choice into a per-path {@link ConflictResolution} map.
+ *
+ * The wizard sends either `resolutions` directly (single-pick mode) or
+ * a `batchChoice` (≥ 5 conflicts) that the server fans out across every
+ * surfaced entry. `merge-json` maps non-JSON entries to `skip` since
+ * deep-merge is JSON-only — the council picked skip over overwrite so a
+ * single non-JSON file in a batch never silently overwrites.
+ */
+export function expandBatchChoice(
+    conflicts: ReadonlyArray<ConflictEntry>,
+    choice: 'skip-all' | 'overwrite-all' | 'merge-json',
+): Record<string, ConflictResolution> {
+    const out: Record<string, ConflictResolution> = {};
+    for (const c of conflicts) {
+        if (choice === 'skip-all') {
+            out[c.path] = 'skip';
+        } else if (choice === 'overwrite-all') {
+            out[c.path] = 'overwrite';
+        } else {
+            out[c.path] = c.mergeable ? 'merge' : 'skip';
+        }
+    }
+    return out;
+}
+
+function isPlainObject(v: unknown): v is JsonObject {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function cloneValue(v: JsonValue): JsonValue {
+    if (Array.isArray(v)) {
+        return v.map(cloneValue);
+    }
+    if (isPlainObject(v)) {
+        const out: Record<string, JsonValue> = {};
+        for (const [k, val] of Object.entries(v)) out[k] = cloneValue(val);
+        return out;
+    }
+    return v;
+}

package/src/install/detect.ts

@@ -0,0 +1,280 @@
+/**
+ * Detection layer — Phase A2 port of `scripts/install.py:detect_*`.
+ *
+ * Pure functions only: read once, return a plan. No side effects in
+ * the detection itself — atomic writes and conflict resolution happen
+ * in later phases against the data this module returns.
+ *
+ * Mirrors:
+ *   - `SCOPE_DETECT_MANIFESTS`            → {@link SCOPE_DETECT_MANIFESTS}
+ *   - `SCOPE_DETECT_AI_DIRS`              → {@link SCOPE_DETECT_AI_DIRS}
+ *   - `SCOPE_DETECT_AI_FILES`             → {@link SCOPE_DETECT_AI_FILES}
+ *   - `detect_scope(cwd)`                 → {@link detectScope}
+ *   - `detect_package_root(project_root)` → {@link detectPackageRoot}
+ *   - `detect_package_type(...)`          → {@link detectPackageType}
+ *
+ * v4 addition (no Python counterpart): {@link discoverPacks} walks the
+ * monorepo `packages/` tree to enumerate available packs.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import type { InstallTarget } from './types.js';
+
+/**
+ * Settings-file name used as the strongest project-scope signal.
+ *
+ * Matches `SETTINGS_FILE` in `scripts/install.py`. Presence in `cwd`
+ * short-circuits scope detection to `'project'` without consulting
+ * the manifest / AI-tool lists.
+ */
+export const SETTINGS_FILE = '.agent-settings.yml';
+
+/**
+ * Manifest files that, when present, count as a project-shape signal.
+ *
+ * Listed in the order they are most commonly canonical; detection
+ * short-circuits on the first hit. `.git/` is intentionally absent —
+ * monorepos, dotfile-git repos, and non-Git workspaces all break it
+ * (ADR-007 D2).
+ */
+export const SCOPE_DETECT_MANIFESTS: readonly string[] = [
+    'package.json',
+    'composer.json',
+    'pyproject.toml',
+    'Cargo.toml',
+    'go.mod',
+    'Gemfile',
+];
+
+/** Project-local AI-tool config directories that count as a presence signal. */
+export const SCOPE_DETECT_AI_DIRS: readonly string[] = [
+    '.claude',
+    '.cursor',
+    '.windsurf',
+    '.augment',
+    '.clinerules',
+    '.copilot',
+    '.gemini',
+    '.codex',
+    '.aider',
+    '.continue',
+    '.roo',
+    '.kilocode',
+];
+
+/** Project-local AI-tool config files that count as a presence signal. */
+export const SCOPE_DETECT_AI_FILES: readonly string[] = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    'GEMINI.md',
+    '.windsurfrules',
+    '.aider.conf.yml',
+];
+
+/**
+ * Scope detection outcome.
+ *
+ * - `project` — install into `cwd` (existing `.agent-settings.yml`).
+ * - `prompt`  — caller MUST resolve the ambiguity (manifest + AI marker).
+ * - `global`  — install to user-scope paths (default).
+ */
+export type Scope = 'project' | 'prompt' | 'global';
+
+/** Reason string carried alongside a {@link Scope} for UI / log surfaces. */
+export interface ScopeDecision {
+    readonly scope: Scope;
+    readonly reason: string;
+}
+
+/**
+ * Multi-signal scope detection (ADR-007 D2 / Phase 1.3).
+ *
+ * 1:1 port of `scripts/install.py:detect_scope`. Pure — no side effects.
+ */
+export function detectScope(cwd: string): ScopeDecision {
+    if (existsSync(join(cwd, SETTINGS_FILE))) {
+        return { scope: 'project', reason: `existing ${SETTINGS_FILE}` };
+    }
+
+    const manifest = SCOPE_DETECT_MANIFESTS.find((m) => existsSync(join(cwd, m)));
+    const aiDir = SCOPE_DETECT_AI_DIRS.find((d) => isDir(join(cwd, d)));
+    const aiFile = SCOPE_DETECT_AI_FILES.find((f) => existsSync(join(cwd, f)));
+
+    if (manifest !== undefined && (aiDir !== undefined || aiFile !== undefined)) {
+        const marker = aiDir ?? aiFile;
+        return {
+            scope: 'prompt',
+            reason: `manifest (${manifest}) + AI-tool config (${marker ?? ''})`,
+        };
+    }
+
+    return { scope: 'global', reason: 'no project-scope signals' };
+}
+
+/**
+ * Map a {@link Scope} to the {@link InstallTarget} consumed by plan builder.
+ *
+ * `prompt` is treated as ambiguous — caller resolves via CLI flag or UI.
+ * Defaulting `prompt` to `global` here would silently swallow the signal.
+ */
+export function scopeToTarget(scope: Scope): InstallTarget | null {
+    if (scope === 'project') return 'project';
+    if (scope === 'global') return 'global';
+    return null;
+}
+
+/** Project shape inferred from manifest presence. */
+export interface ProjectShape {
+    readonly kind: 'composer' | 'npm' | 'cargo' | 'pyproject' | 'go' | 'ruby' | 'unknown';
+    readonly root: string;
+    readonly manifest: string | null;
+}
+
+/**
+ * Detect project shape from manifest markers — pure read of cwd.
+ *
+ * Manifest-to-kind mapping mirrors {@link SCOPE_DETECT_MANIFESTS}:
+ * `package.json` → npm, `composer.json` → composer, etc.
+ */
+export function detectProjectShape(root: string): ProjectShape {
+    const manifest = SCOPE_DETECT_MANIFESTS.find((m) => existsSync(join(root, m)));
+    if (manifest === undefined) {
+        return { kind: 'unknown', root, manifest: null };
+    }
+    const kind = ({
+        'package.json': 'npm',
+        'composer.json': 'composer',
+        'pyproject.toml': 'pyproject',
+        'Cargo.toml': 'cargo',
+        'go.mod': 'go',
+        Gemfile: 'ruby',
+    } as const)[manifest] ?? 'unknown';
+    return { kind, root, manifest };
+}
+
+/** AI-tool presence flags discovered in a project tree. */
+export interface ToolPresence {
+    readonly augment: boolean;
+    readonly claude: boolean;
+    readonly cursor: boolean;
+    readonly cline: boolean;
+    readonly windsurf: boolean;
+    readonly agentsMd: boolean;
+}
+
+/** Read AI-tool presence flags from `root`. Pure — no writes. */
+export function detectToolPresence(root: string): ToolPresence {
+    return {
+        augment: isDir(join(root, '.augment')),
+        claude: isDir(join(root, '.claude')),
+        cursor: isDir(join(root, '.cursor')),
+        cline: isDir(join(root, '.clinerules')),
+        windsurf: isDir(join(root, '.windsurf')) || existsSync(join(root, '.windsurfrules')),
+        agentsMd: existsSync(join(root, 'AGENTS.md')),
+    };
+}
+
+/**
+ * Discover packs under a workspace root (`packages/pack-*` convention).
+ *
+ * Returns absolute paths to every directory under `<workspace>/packages/`
+ * whose name starts with `pack-`. v4-only addition — the legacy Python
+ * installer has no equivalent because packs are a v4 concept.
+ */
+export function discoverPacks(workspaceRoot: string): readonly string[] {
+    const packagesDir = join(workspaceRoot, 'packages');
+    if (!isDir(packagesDir)) {
+        return [];
+    }
+    return readdirSync(packagesDir)
+        .filter((name) => name.startsWith('pack-'))
+        .map((name) => resolve(packagesDir, name))
+        .filter(isDir);
+}
+
+/**
+ * Locate the agent-config package root from a project root.
+ *
+ * 1:1 port of `scripts/install.py:detect_package_root` — prefers an
+ * npm-installed copy under `node_modules/@event4u/agent-config/`,
+ * falls back to the project root itself for in-package development
+ * (presence of `src/config/profiles/minimal.ini` is the development-mode
+ * signal in the Python script; we mirror it).
+ *
+ * Returns `null` instead of failing — caller decides UX (Python `fail`
+ * exits the process; the TS engine surfaces the error to the wizard).
+ */
+export function detectPackageRoot(projectRoot: string): string | null {
+    const npmPath = join(projectRoot, 'node_modules', '@event4u', 'agent-config');
+    if (isDir(npmPath)) {
+        return resolve(npmPath);
+    }
+    if (existsSync(join(projectRoot, 'src', 'config', 'profiles', 'minimal.ini'))) {
+        return projectRoot;
+    }
+    return null;
+}
+
+/** Classify a package root as `npm` (under node_modules) or `local`. */
+export function detectPackageType(packageRoot: string): 'npm' | 'local' {
+    return packageRoot.split(/[\\/]/).includes('node_modules') ? 'npm' : 'local';
+}
+
+function isDir(path: string): boolean {
+    try {
+        return statSync(path).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Result of a v3-on-disk probe. road-to-unified-setup § Phase E2.
+ *
+ * The v4 wizard renders a backup-screen with two CTAs when a v3 install
+ * is detected — `path` reports where the legacy tree lives, `version`
+ * carries the first non-empty line of `<path>/VERSION` for the operator
+ * banner, `backupTarget` is the suggested destination for the rsync /
+ * cp copy. `present: false` short-circuits the banner.
+ */
+export interface LegacyV3Detection {
+    readonly present: boolean;
+    readonly path: string;
+    readonly version: string | null;
+    readonly backupTarget: string;
+}
+
+/**
+ * Detect a v3.x install at `~/.event4u/agent-config/` (or the override
+ * passed in). Returns `present: false` when the directory or the
+ * `VERSION` file is missing, or when the recorded major version is not
+ * `3.x`. The caller decides what to do with `present: true` — the wire
+ * route in `installRoute` exposes the structure 1:1.
+ */
+export function detectLegacyV3(opts: { home?: string } = {}): LegacyV3Detection {
+    const home = opts.home ?? homedir();
+    const path = join(home, '.event4u', 'agent-config');
+    const backupTarget = join(home, '.event4u', 'agent-config.v3.bak');
+    if (!isDir(path)) {
+        return { present: false, path, version: null, backupTarget };
+    }
+    const versionFile = join(path, 'VERSION');
+    if (!existsSync(versionFile)) {
+        return { present: false, path, version: null, backupTarget };
+    }
+    let raw = '';
+    try {
+        raw = readFileSync(versionFile, 'utf8').trim();
+    } catch {
+        return { present: false, path, version: null, backupTarget };
+    }
+    const firstLine = raw.split('\n', 1)[0]?.trim() ?? '';
+    const major = firstLine.split('.')[0]?.trim();
+    if (major !== '3') {
+        return { present: false, path, version: firstLine || null, backupTarget };
+    }
+    return { present: true, path, version: firstLine, backupTarget };
+}

package/src/install/paths.ts

@@ -0,0 +1,90 @@
+/**
+ * Centralised path resolution for the unified TS install engine.
+ *
+ * Council Finding #16: every downstream module reads paths from one
+ * place — no inline `os.tmpdir()` or `~/.event4u/...` literals scattered
+ * across A2–A6.
+ *
+ * All helpers accept an optional `home` argument so tests can drive
+ * platform behaviour (POSIX vs Windows env-var fallback) without
+ * mocking `node:os`. Production callers omit it and `os.homedir()` is
+ * consulted lazily.
+ *
+ * Platform notes:
+ *   - POSIX: `os.homedir()` reads `$HOME`.
+ *   - Windows: `os.homedir()` reads `$USERPROFILE`, then `$HOMEDRIVE+$HOMEPATH`.
+ *
+ * The install root and log path live under a fixed `.event4u/agent-config/`
+ * sub-tree so both platforms land on the same logical location.
+ */
+
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Sub-tree under the user's home where v4 installs land.
+ *
+ * Matches the legacy Python installer's target (`~/.event4u/agent-config/`)
+ * so v3 and v4 read/write the same physical tree and v3-detection (Phase E2)
+ * can introspect a prior install without a migration step.
+ */
+export const INSTALL_ROOT_SUBPATH = '.event4u/agent-config';
+
+/**
+ * Active transaction log filename written by Phase A4 atomic-writer.
+ *
+ * Per Phase A4 + council Finding #18: rotation produces sibling files
+ * (`install-log.<ISO>.jsonl.gz`); recovery only scans the active log.
+ */
+export const INSTALL_LOG_FILENAME = 'install-log.jsonl';
+
+/**
+ * Resolve the home directory.
+ *
+ * `home` override is accepted so tests can pin platform behaviour
+ * without mocking the `node:os` module. Empty / falsy override falls
+ * back to `os.homedir()`.
+ */
+function resolveHome(home?: string): string {
+    if (home && home.length > 0) {
+        return home;
+    }
+    const fromOs = homedir();
+    if (!fromOs) {
+        throw new Error(
+            'Cannot resolve home directory — both $HOME (POSIX) and $USERPROFILE (Windows) are unset.',
+        );
+    }
+    return fromOs;
+}
+
+/**
+ * Absolute path to the v4 install root: `~/.event4u/agent-config/`.
+ *
+ * Stable across platforms because the suffix is a POSIX-style join
+ * applied via `path.join`, which normalises separators per platform.
+ */
+export function getInstallRoot(home?: string): string {
+    return join(resolveHome(home), INSTALL_ROOT_SUBPATH);
+}
+
+/**
+ * Absolute path to the active transaction log:
+ * `~/.event4u/agent-config/install-log.jsonl`.
+ *
+ * Phase A4 writers append here on every successful atomic rename.
+ */
+export function getLogPath(home?: string): string {
+    return join(getInstallRoot(home), INSTALL_LOG_FILENAME);
+}
+
+/**
+ * OS-level temp directory.
+ *
+ * Wraps `os.tmpdir()` so callers funnel through one symbol — drop-in
+ * replacement when a future test harness needs to redirect temp writes
+ * to a scratch dir without monkey-patching `node:os`.
+ */
+export function getTempPath(): string {
+    return tmpdir();
+}