@event4u/agent-config 16.2.0 → 16.4.0

package/src/install/claudePathsPlan.ts

@@ -188,6 +188,21 @@ export interface ClaudePathsPlan {
     dropped: { pattern: string; reason: 'unresolved-placeholder' | 'over-budget' | 'mixed-triggers' }[];
 }
 
+/**
+ * The two trigger keys `derive_trigger_globs` turns into a host glob. Kept
+ * beside it deliberately: the day a third path-shaped key is added there, this
+ * set is the other half of the same edit, and a reader looking at either one
+ * sees the pair.
+ */
+const PATH_SHAPED_TRIGGER_KEYS: ReadonlySet<string> = new Set(['file_pattern', 'path_prefix']);
+
+/**
+ * Keys on a trigger object that match nothing. `reason:` documents why the
+ * trigger exists; counting it would make every annotated path trigger look
+ * mixed and scope nothing at all.
+ */
+const NON_MATCHING_TRIGGER_KEYS: ReadonlySet<string> = new Set(['reason']);
+
 /**
  * Does this rule declare any trigger that is NOT path-shaped?
  *
@@ -199,6 +214,18 @@ export interface ClaudePathsPlan {
  * rule loads unconditionally. The emitter fed both semantics from one list, so
  * a rule that declared keywords *and* one path glob silently became
  * path-gated-only on Claude.
+ *
+ * **The test is a negation, not a list of non-path kinds**, and the difference
+ * is not stylistic. The predicate used to enumerate `keyword` and `phrase`,
+ * which left `command` — a prompt route like any other — uncounted:
+ * `roadmap-progress-sync` declares one `path_prefix` and three `command`
+ * triggers, so it was emitted with an exclusive `paths:` and its three command
+ * routes never fired on this host. A list can only ever be as current as its
+ * last edit; the schema's `additionalProperties: false` means a new match key
+ * arrives as a deliberate schema change, and until someone teaches
+ * `derive_trigger_globs` to make a glob from it, treating it as promptable is
+ * the fail-safe reading — the rule stays unconditional rather than silently
+ * narrowing to a path it does not have.
  */
 export function _has_non_path_trigger(meta: Record<string, unknown>): boolean {
     const triggers = meta['triggers'];
@@ -206,8 +233,21 @@ export function _has_non_path_trigger(meta: Record<string, unknown>): boolean {
     for (const t of triggers) {
         if (t === null || typeof t !== 'object' || Array.isArray(t)) continue;
         const obj = t as Record<string, unknown>;
-        if (typeof obj['keyword'] === 'string' && obj['keyword']) return true;
-        if (typeof obj['phrase'] === 'string' && obj['phrase']) return true;
+        for (const [key, value] of Object.entries(obj)) {
+            if (PATH_SHAPED_TRIGGER_KEYS.has(key) || NON_MATCHING_TRIGGER_KEYS.has(key)) continue;
+            // A string that is not blank, or ANY non-string value. The schema
+            // types all five match keys as strings today, so the second half is
+            // for the key that arrives later: a `keyword: ["a","b"]` read as
+            // "not a string, so not a trigger" would silently narrow the rule
+            // to a path it does not have, which is the exact failure the
+            // negation above exists to prevent. Undefined and null are the one
+            // shape that means "absent".
+            if (typeof value === 'string') {
+                if (value.trim() !== '') return true;
+            } else if (value !== undefined && value !== null) {
+                return true;
+            }
+        }
     }
     return false;
 }
@@ -230,8 +270,10 @@ export function _claude_paths_plan(meta: Record<string, unknown>): ClaudePathsPl
     const globs: string[] = [];
     const dropped: ClaudePathsPlan['dropped'] = [];
 
-    // A rule that ALSO declares keyword / phrase triggers gets no `paths:` at
-    // all, and therefore keeps loading unconditionally on Claude Code.
+    // A rule that ALSO declares a non-path trigger — keyword, phrase, command,
+    // or a match key added to the schema later — gets no `paths:` at all, and
+    // therefore keeps loading unconditionally on Claude Code. The predicate is
+    // a negation of the two path-shaped keys, deliberately: see its docblock.
     //
     // Emitting `paths:` here would narrow the rule to a path match and discard
     // every keyword the author wrote, because this host reads the list as the

package/src/install/claudeRuleRewrite.ts

@@ -132,7 +132,7 @@ export function rewriteAndReport(
     quiet: boolean,
     info: (m: string) => void,
     warn: (m: string) => void,
-    wrappers?: { wrapped: readonly string[]; reserved: readonly string[] },
+    wrappers?: { wrapped: readonly string[]; reserved: readonly string[]; foreign?: readonly string[] },
     preserved: ReadonlySet<string> = new Set(),
 ): ClaudeRuleRewriteResult {
     const result = rewriteClaudeRules(rulesDir, preserved);
@@ -157,6 +157,15 @@ export function rewriteAndReport(
                     'commands remain available',
             );
         }
+        if (wrappers.foreign !== undefined && wrappers.foreign.length > 0) {
+            // Reported, never removed. The name shadows a host built-in, but
+            // this package did not write the file, so deleting it would be
+            // taking a neighbour's command away without saying so.
+            info(
+                `  claude-code: kept ${wrappers.foreign.length} neighbour command file(s) whose ` +
+                    `name is a Claude Code built-in (${wrappers.foreign.join(', ')}); not ours to remove`,
+            );
+        }
     }
     if (result.rewritten > 0 && !quiet) {
         info(

package/src/install/emit_host_rules_cli.ts

@@ -44,6 +44,14 @@ import {
     _emit_windsurf_rule,
     strip_frontmatter,
 } from '../scripts/condense.js';
+import {
+    WINDSURFRULES_HEADER,
+    cleanOwnedOnly,
+    keptLine,
+    mayWriteRuleFile,
+    mayWriteWindsurfRules,
+    ownedPaths,
+} from './host_rule_ownership.js';
 
 function _ruleFiles(rulesDir: string): string[] {
     return fs
@@ -60,63 +68,64 @@ function _ruleFiles(rulesDir: string): string[] {
         });
 }
 
-/** Remove entries not in `valid` (mirror of condense's `_clean_modern_dir`). */
-function _cleanDir(dir: string, valid: ReadonlySet<string>): void {
-    let entries: string[];
-    try {
-        entries = fs.readdirSync(dir);
-    } catch {
-        return;
-    }
-    for (const name of entries) {
-        if (name === 'README.md' || valid.has(name)) {
-            continue;
-        }
-        const full = path.join(dir, name);
-        try {
-            if (fs.lstatSync(full).isDirectory()) {
-                fs.rmSync(full, { recursive: true, force: true });
-            } else {
-                fs.unlinkSync(full);
-            }
-        } catch {
-            /* best-effort clean */
-        }
-    }
-}
-
 export function emitCursor(rulesDir: string, projectRoot: string): number {
     const targetDir = path.join(projectRoot, '.cursor', 'rules');
     const files = _ruleFiles(rulesDir);
+    const owned = ownedPaths(projectRoot);
     const valid = new Set<string>();
+    let blocked = 0;
     for (const src of files) {
         const name = `${path.basename(src, '.md')}.mdc`;
-        _emit_cursor_mdc(src, path.join(targetDir, name));
+        const target = path.join(targetDir, name);
+        // Ownership BEFORE the write: a neighbour's file under one of our
+        // names would otherwise be destroyed and then skipped by the cleanup
+        // pass, which only looks at names this run did not emit.
+        if (!mayWriteRuleFile(target, owned)) {
+            blocked += 1;
+            continue;
+        }
+        _emit_cursor_mdc(src, target);
         valid.add(name);
     }
-    _cleanDir(targetDir, valid);
+    const { kept } = cleanOwnedOnly(targetDir, valid, owned);
+    const line = keptLine(kept + blocked);
+    if (line !== null) process.stdout.write(`cursor: ${line}\n`);
     return files.length;
 }
 
 export function emitWindsurf(rulesDir: string, projectRoot: string): number {
     const perRuleDir = path.join(projectRoot, '.windsurf', 'rules');
     const files = _ruleFiles(rulesDir);
+    const owned = ownedPaths(projectRoot);
     const valid = new Set<string>();
+    let blocked = 0;
     for (const src of files) {
         const name = path.basename(src);
-        _emit_windsurf_rule(src, path.join(perRuleDir, name));
+        const target = path.join(perRuleDir, name);
+        if (!mayWriteRuleFile(target, owned)) {
+            blocked += 1;
+            continue;
+        }
+        _emit_windsurf_rule(src, target);
         valid.add(name);
     }
-    _cleanDir(perRuleDir, valid);
+    const { kept } = cleanOwnedOnly(perRuleDir, valid, owned);
+    const line = keptLine(kept + blocked);
+    if (line !== null) process.stdout.write(`windsurf: ${line}\n`);
 
     // Concatenated legacy surface — same format as the projection-path
     // generator (condense.generate_windsurfrules), consumer-sourced header.
-    const parts = ['# Auto-generated from .augment/rules/ — do not edit directly\n'];
-    for (const src of files) {
-        const content = strip_frontmatter(fs.readFileSync(src, 'utf-8'));
-        parts.push(`---\n\n${content.trim()}\n`);
+    const target = path.join(projectRoot, '.windsurfrules');
+    if (mayWriteWindsurfRules(target, owned)) {
+        const parts = [`${WINDSURFRULES_HEADER}\n`];
+        for (const src of files) {
+            const content = strip_frontmatter(fs.readFileSync(src, 'utf-8'));
+            parts.push(`---\n\n${content.trim()}\n`);
+        }
+        fs.writeFileSync(target, parts.join('\n') + '\n', 'utf-8');
+    } else {
+        process.stdout.write('windsurf: kept: 1 neighbour file(s) (.windsurfrules)\n');
     }
-    fs.writeFileSync(path.join(projectRoot, '.windsurfrules'), parts.join('\n') + '\n', 'utf-8');
     return files.length;
 }
 

package/src/install/globalRuleScope.ts

@@ -0,0 +1,109 @@
+/**
+ * The rule scope governing a GLOBAL deploy.
+ *
+ * Moved out of `src/scripts/install.ts` by
+ * `road-to-an-installed-layer-that-is-thinned` step 1.1, which adds the thinning
+ * call to the same deploy loop. `check_source_size_budget` is a one-way ratchet
+ * with no per-change headroom, and this repository's stated convention is that
+ * the total falls through EXTRACTION and never rises through a baseline edit —
+ * the same reason `claudeRuleRewrite` holds the claude-code post-copy reporting
+ * rather than the installer. This function is the nearest self-contained block
+ * to the change: it is the predicate the deploy loop resolves once per run, it
+ * reaches nothing else in the installer, and its four environment touches are
+ * already parameters in all but name.
+ *
+ * BEHAVIOUR IS UNCHANGED, DELIBERATELY. The body is the installer's, verbatim
+ * apart from the four injected seams below; `install.ts` keeps a wrapper of the
+ * same name and signature, so its re-export and every caller and test see what
+ * they saw before. A behaviour change smuggled into an extraction is the one
+ * thing that would make the line saving not worth having.
+ *
+ * The seams are injected rather than imported because each one is an
+ * install-time decision the installer owns: where the global settings doc lives,
+ * how this build reads and parses YAML, what the packaged template says, and
+ * where a warning goes.
+ */
+
+import { LEGACY_ALL, ruleScopeFromSettings, type RuleScope } from './rule_scope.js';
+
+export interface GlobalRuleScopeInputs {
+    /** The global settings file, or `null` when no artefact exists at all. */
+    readonly settingsPath: string | null;
+    /** The package being installed from. */
+    readonly packageRoot: string;
+    /** Read a file as text; throws like `fs.readFileSync` when it cannot. */
+    readonly readText: (p: string) => string;
+    /** Parse YAML permissively — anything unparseable comes back non-object. */
+    readonly parseYaml: (text: string) => unknown;
+    /** The packaged template settings, read only on a genuinely fresh machine. */
+    readonly loadDefaults: () => Record<string, unknown>;
+    /** Where a loud fallback goes. */
+    readonly warn: (message: string) => void;
+}
+
+function isPlainObject(v: unknown): boolean {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Resolve the rule scope governing THIS global deploy — the same way the wizard
+ * does (`src/server/routes/install.ts::_resolveRuleScope`), so the two global
+ * paths cannot ship different rule sets for the same settings.
+ *
+ * Settings resolution mirrors `_resolve_scoped_projection` above: an existing
+ * global settings doc is authoritative, and only a genuinely fresh machine falls
+ * through to the packaged template. Any read or parse failure resolves to
+ * `LEGACY_ALL` — over-shipping is the safe direction, and the compat exclusion
+ * (`source-of-truth.md`) still applies even then.
+ */
+export function resolveGlobalRuleScope(inputs: GlobalRuleScopeInputs): RuleScope {
+    const { packageRoot, warn } = inputs;
+    const settings_path = inputs.settingsPath;
+
+    // No global settings artefact at all — a genuinely fresh machine. Fall
+    // through to the packaged template silently: there is no user decision to
+    // contradict, and this is the documented upgrade-compat path.
+    if (settings_path === null) {
+        try {
+            return ruleScopeFromSettings(inputs.loadDefaults(), packageRoot);
+        } catch {
+            return LEGACY_ALL;
+        }
+    }
+
+    // A doc EXISTS, so the user has expressed a configuration. Failing to read
+    // it is not the same as not having one: falling back to legacy-all here
+    // ships the maintainer-only rules the user may have deliberately scoped out,
+    // and `_load_yaml_doc` would report that as an indistinguishable `{}`. So
+    // parse it explicitly and be LOUD when it does not parse — over-shipping
+    // stays the safe direction, but it must not be a silent one.
+    let text: string;
+    try {
+        text = inputs.readText(settings_path);
+    } catch (e) {
+        warn(
+            `could not read ${settings_path} (${String(e)}) — rule scoping falls back ` +
+                'to legacy-all, so ALL rules including maintainer-only ones will be ' +
+                'installed. Fix the file to restore scoping.',
+        );
+        return LEGACY_ALL;
+    }
+    const parsed = inputs.parseYaml(text);
+    if (!isPlainObject(parsed)) {
+        warn(
+            `${settings_path} is not a YAML mapping — rule scoping falls back to ` +
+                'legacy-all, so ALL rules including maintainer-only ones will be ' +
+                'installed. Fix the file to restore scoping.',
+        );
+        return LEGACY_ALL;
+    }
+    try {
+        return ruleScopeFromSettings(parsed as Record<string, unknown>, packageRoot);
+    } catch (e) {
+        warn(
+            `could not derive rule scope from ${settings_path} (${String(e)}) — ` +
+                'falling back to legacy-all; ALL rules will be installed.',
+        );
+        return LEGACY_ALL;
+    }
+}

package/src/install/host_rule_ownership.ts

@@ -0,0 +1,170 @@
+/**
+ * Which host-rule files this package may delete or overwrite.
+ *
+ * The defect this closes: `_cleanDir` removed every entry under
+ * `.cursor/rules` and `.windsurf/rules` whose NAME was not one this run had
+ * just emitted, and `.windsurfrules` was overwritten unconditionally. A rule
+ * file another agent package wrote — or one the consumer wrote by hand — was
+ * destroyed on every install, which is the opposite of what the uninstall
+ * claim promises.
+ *
+ * Ownership is read from the installed-tools manifest's `files[]` inventory,
+ * never from a marker inside the file. The `.mdc` emitter writes no package
+ * tag (`condense.ts` `_emit_cursor_mdc`), so a tag-based gate would classify
+ * every file this package ever wrote as foreign and therefore never remove a
+ * stale one — it would read as conservative and in fact be inert. The manifest
+ * is the record of what this installer actually put on disk, so it is the
+ * thing that can answer the question.
+ *
+ * This module only READS that manifest. It never rewrites it: the available
+ * reader (`installed_tools.read_manifest`) drops nested `files[]` by design,
+ * so a read-modify-write through it would erase every other tool's inventory —
+ * the failure `manifestFiles.ts` documents at length.
+ *
+ * The consequence, stated rather than implied: a consumer whose manifest does
+ * not claim a path gets that path KEPT. Unproven means kept, never deleted.
+ * That is the safe direction for this lane and it is also a real limit — a
+ * stale file of ours sitting under an unclaimed path stays until something
+ * claims it.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { sha256OfFile } from './fsPrimitives.js';
+import { classifyOwnership, recordedHashesForRoot, type RecordedHashes } from './recordedOwnership.js';
+
+/** The first line every `.windsurfrules` this package generates carries. */
+export const WINDSURFRULES_HEADER = '# Auto-generated from .augment/rules/ — do not edit directly';
+
+export interface CleanResult {
+    /** Entry names removed from the directory. */
+    removed: string[];
+    /** Entries kept because nothing proves this package wrote them. */
+    kept: number;
+}
+
+/** Every file path beneath `full`, or `[full]` when it is a file. */
+function filesUnder(full: string): string[] {
+    let stat: fs.Stats;
+    try {
+        stat = fs.lstatSync(full);
+    } catch {
+        return [];
+    }
+    if (!stat.isDirectory()) return [full];
+    const out: string[] = [];
+    for (const name of fs.readdirSync(full)) {
+        out.push(...filesUnder(path.join(full, name)));
+    }
+    return out;
+}
+
+/**
+ * Is this exact file ours AND still carrying the bytes we wrote?
+ *
+ * The recorded digest is the point, not the path. A path-membership test
+ * answers "did we ever write here", which merges two materially different
+ * trees: a generated file still as we left it, and one the consumer has since
+ * edited. Deleting the second loses their work, and `recordedOwnership` exists
+ * to tell them apart — importing its map and then ignoring its hashes was the
+ * defect an independent review named here.
+ */
+function isUnchangedOurs(file: string, owned: RecordedHashes): boolean {
+    const target = path.resolve(file);
+    if (!owned.has(target)) return false;
+    return classifyOwnership(owned.get(target), sha256OfFile(target)) === 'recorded-unchanged';
+}
+
+/**
+ * Remove the stale entries of ours from `dir`, keeping everything else.
+ *
+ * An entry is removable only when every file it contains is ours AND
+ * unmodified: one unclaimed or edited file inside a directory keeps the whole
+ * directory, because removing it would take that file with it.
+ */
+export function cleanOwnedOnly(
+    dir: string,
+    valid: ReadonlySet<string>,
+    owned: RecordedHashes,
+): CleanResult {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return { removed: [], kept: 0 };
+    }
+    const removed: string[] = [];
+    let kept = 0;
+    for (const name of entries) {
+        if (name === 'README.md' || valid.has(name)) continue;
+        const full = path.join(dir, name);
+        const contained = filesUnder(full);
+        const ours = contained.length > 0 && contained.every((f) => isUnchangedOurs(f, owned));
+        if (!ours) {
+            kept += 1;
+            continue;
+        }
+        try {
+            fs.rmSync(full, { recursive: true, force: true });
+            removed.push(name);
+        } catch {
+            kept += 1;
+        }
+    }
+    return { removed, kept };
+}
+
+/**
+ * May this package write `.windsurfrules` at `target`?
+ *
+ * Yes when the file is absent, or when it still carries the header this
+ * package generates. Nothing else.
+ *
+ * A manifest claim is deliberately NOT a second route in. The file is
+ * generated and overwritten on every install, so the header IS the ownership
+ * signal and it is content-derived: if the header is gone, something replaced
+ * the file, and "the manifest says we wrote here once" is exactly the stale
+ * fact that would let us overwrite a neighbour's replacement. An independent
+ * review caught that route open, with a fixture asserting it.
+ */
+export function mayWriteWindsurfRules(target: string, owned: RecordedHashes): boolean {
+    void owned;
+    if (!fs.existsSync(target)) return true;
+    let head: string;
+    try {
+        head = fs.readFileSync(target, 'utf-8').split('\n', 1)[0] ?? '';
+    } catch {
+        // Unreadable is unproven, and unproven means do not touch it.
+        return false;
+    }
+    return head.trim() === WINDSURFRULES_HEADER;
+}
+
+/**
+ * May this package write a rule file at `target`?
+ *
+ * The cleanup pass is not enough on its own, and an independent review found
+ * the hole: `_cleanDir` skips every name this run just emitted, so a
+ * neighbour's `foo.mdc` that happens to share a basename with one of our
+ * rules was already OVERWRITTEN by the time ownership was consulted. The
+ * check has to run BEFORE the write, which is what this is for.
+ *
+ * Absent, or ours and unmodified → write. Anything else is someone's file or
+ * someone's edit, and is left exactly as it is.
+ */
+export function mayWriteRuleFile(target: string, owned: RecordedHashes): boolean {
+    if (!fs.existsSync(target)) return true;
+    return isUnchangedOurs(target, owned);
+}
+
+/** The manifest's claimed paths for a consumer root; empty when none resolves. */
+export function ownedPaths(projectRoot: string): RecordedHashes {
+    return recordedHashesForRoot(projectRoot);
+}
+
+/** The one line the emitter prints when it kept a neighbour's files. */
+export function keptLine(kept: number): string | null {
+    if (kept <= 0) return null;
+    return `kept: ${kept} neighbour file(s)`;
+}