peaks-loop 4.1.3 → 4.1.4

package/dist/services/skills/hooks-settings-file-shape.d.ts

@@ -0,0 +1,43 @@
+import { type PeaksHookEntry } from './hooks-codegate-superpowers.js';
+import type { HookEntryTarget, HookMatcherEntry, HookTarget } from './hooks-settings-types.js';
+/** True when `target` already holds everything the install would write to it. */
+export declare function targetIsSatisfied(target: HookTarget, allSentinels: ReadonlyArray<string>): boolean;
+/** Flatten the resolved targets into one `{ matcher, sentinel, settingsPath }` row per entry. */
+export declare function describeEntryTargets(targets: ReadonlyArray<HookTarget>): HookEntryTarget[];
+/** Read a settings file as an object, or `{}` when it does not exist yet. */
+export declare function readSettingsFile(settingsPath: string): Record<string, unknown>;
+/** Read the existing hook array entries for the adapter's hookEvent (tolerant of any prior shape). */
+export declare function readHookEventEntries(settings: Record<string, unknown>, eventKey: string): HookMatcherEntry[];
+/** Read the existing hook array entries from a `settings.hooks` object (already extracted). */
+export declare function readHookEntriesFromHooks(hooks: Record<string, unknown>, eventKey: string): HookMatcherEntry[];
+/** True when every command handler in the entry matches a known peaks sentinel for the given IDE. */
+export declare function entryIsPeaksManaged(entry: HookMatcherEntry, sentinels: ReadonlyArray<string>): boolean;
+export declare function isInstalledForEntries(settings: Record<string, unknown>, entries: ReadonlyArray<PeaksHookEntry>): boolean;
+/**
+ * Slice #014: detect the "stale progress entry after pre-#014 install"
+ * case. The desired shape is gate-enforce-only. If the file currently
+ * has a peaks-managed progress-start entry (left behind by a pre-#014
+ * install), the install is NOT a no-op — it must strip the stale
+ * entry. This helper returns true exactly when the desired shape is
+ * fully reflected on disk: gate-enforce present AND no legacy
+ * progress-start present.
+ */
+export declare function shapeMatchesDesired(settings: Record<string, unknown>, entries: ReadonlyArray<PeaksHookEntry>, allPeaksSentinels: ReadonlyArray<string>): boolean;
+/**
+ * Merge a target's peaks-managed hook entries into `settings`, preserving
+ * all other keys and hooks. Entries routed to a DIFFERENT settings file are
+ * not part of `entries`, so the legacy-sentinel filter below strips them
+ * from this file (that is what migrates a gate-enforce entry that an older
+ * peaks release wrote into the shared file).
+ */
+export declare function withHooksInstalled(settings: Record<string, unknown>, entries: ReadonlyArray<PeaksHookEntry>, allSentinels: ReadonlyArray<string>): Record<string, unknown>;
+/**
+ * Strip every peaks-managed hook row from one target's settings file, on every
+ * event key the file carries — a pre-#014 install could have left the legacy
+ * progress-start entry on a different event than the gate-enforce one. Returns
+ * the rewritten settings plus whether anything was actually removed.
+ */
+export declare function stripPeaksEntries(target: HookTarget, sentinels: ReadonlyArray<string>): {
+    settings: Record<string, unknown>;
+    removed: boolean;
+};

package/dist/services/skills/hooks-settings-file-shape.js

@@ -0,0 +1,207 @@
+/**
+ * Reading and comparing the hook rows a settings file actually holds.
+ *
+ * Split out of `hooks-settings-service.ts` (file-size cap campaign). The
+ * service re-exports every name declared here, so existing importers keep
+ * using `./hooks-settings-service.js` unchanged.
+ */
+import { existsSync } from 'node:fs';
+import { readJsonObjectFile } from '../ide/shared/atomic-json.js';
+import { hasExternalGateExemptions } from './hooks-codegate-superpowers.js';
+/** True when `target` already holds everything the install would write to it. */
+export function targetIsSatisfied(target, allSentinels) {
+    const settings = readSettingsFile(target.settingsPath);
+    if (!shapeMatchesDesired(settings, target.entries, allSentinels))
+        return false;
+    return target.envExemptions !== true || hasExternalGateExemptions(settings);
+}
+/** Flatten the resolved targets into one `{ matcher, sentinel, settingsPath }` row per entry. */
+export function describeEntryTargets(targets) {
+    return targets.flatMap((target) => target.entries.map((entry) => ({
+        matcher: entry.matcher,
+        sentinel: entry.sentinel,
+        settingsPath: target.settingsPath
+    })));
+}
+/** Read a settings file as an object, or `{}` when it does not exist yet. */
+export function readSettingsFile(settingsPath) {
+    return existsSync(settingsPath) ? readJsonObjectFile(settingsPath) : {};
+}
+/** Read the existing hook array entries for the adapter's hookEvent (tolerant of any prior shape). */
+export function readHookEventEntries(settings, eventKey) {
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
+        return [];
+    const arr = hooks[eventKey];
+    return Array.isArray(arr) ? arr : [];
+}
+/** Read the existing hook array entries from a `settings.hooks` object (already extracted). */
+export function readHookEntriesFromHooks(hooks, eventKey) {
+    const arr = hooks[eventKey];
+    return Array.isArray(arr) ? arr : [];
+}
+/** True when every command handler in the entry matches a known peaks sentinel for the given IDE. */
+export function entryIsPeaksManaged(entry, sentinels) {
+    const handlers = Array.isArray(entry?.hooks) ? entry.hooks : [];
+    if (handlers.length === 0)
+        return false;
+    return handlers.every((h) => {
+        if (typeof h?.command !== 'string')
+            return false;
+        const cmd = h.command;
+        return sentinels.some((sentinel) => cmd.includes(sentinel));
+    });
+}
+export function isInstalledForEntries(settings, entries) {
+    const sentinels = entries.map((e) => e.sentinel);
+    // Check every distinct event key our entries could be on.
+    const eventKeys = new Set(entries.map((e) => e.event));
+    for (const eventKey of eventKeys) {
+        if (readHookEventEntries(settings, eventKey).some((e) => entryIsPeaksManaged(e, sentinels))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Slice #014: detect the "stale progress entry after pre-#014 install"
+ * case. The desired shape is gate-enforce-only. If the file currently
+ * has a peaks-managed progress-start entry (left behind by a pre-#014
+ * install), the install is NOT a no-op — it must strip the stale
+ * entry. This helper returns true exactly when the desired shape is
+ * fully reflected on disk: gate-enforce present AND no legacy
+ * progress-start present.
+ */
+export function shapeMatchesDesired(settings, entries, allPeaksSentinels) {
+    const eventKeys = new Set(entries.map((e) => e.event));
+    for (const eventKey of eventKeys) {
+        // Only the entries that belong to THIS event key can be expected on it —
+        // the desired set must be per-event, or a target whose entries span two
+        // event keys (claude-code: SessionStart + PreToolUse) would never look
+        // installed and every `peaks hooks install` would rewrite the files.
+        const desiredSentinels = new Set(entries.filter((e) => e.event === eventKey).map((e) => e.sentinel));
+        const present = readHookEventEntries(settings, eventKey);
+        const peaksPresent = present.filter((e) => entryIsPeaksManaged(e, allPeaksSentinels));
+        // (a) every peaks-managed entry currently on disk must match the
+        //     desired sentinel set (no stale entries the caller wants removed).
+        for (const entry of peaksPresent) {
+            const entrySentinels = (entry.hooks ?? [])
+                .map((h) => allPeaksSentinels.find((s) => String(h.command ?? '').includes(s)))
+                .filter((s) => Boolean(s));
+            if (entrySentinels.some((s) => !desiredSentinels.has(s))) {
+                return false;
+            }
+        }
+        // (b) every desired entry must be on disk AND carry the matcher it declares.
+        //     Presence alone cannot see a WRONG matcher, and a wrong matcher is not
+        //     cosmetic: `''` and `Bash|Task` route the same command to different
+        //     tool sets, so the entry is present while the hook never fires on the
+        //     residual R2): a `PostCompact` entry hand-corrupted to matcher
+        //     `auto|manual` survived `peaks hooks install` unchanged, and the
+        //     installer was structurally unable to repair it.
+        //     An absent matcher reads as `''` — the form Claude Code takes as "every
+        //     source" — so a file written before matchers were explicit converges
+        //     once instead of churning on every install.
+        for (const desired of entries.filter((e) => e.event === eventKey)) {
+            // The identity of a desired entry is the PAIR (sentinel, matcher), not the
+            // sentinel alone: one command may legitimately be installed under several
+            // matchers (the read-only MCP surface rides `peaks gate enforce` under its
+            // own matcher set). Matching on the sentinel first found that first entry
+            // every time, so the second one never looked installed and every install
+            // rewrote the file. A wrong matcher is still un-repaired — it fails to
+            // match and the caller rewrites.
+            const onDisk = peaksPresent.find((entry) => (entry.matcher ?? '') === desired.matcher &&
+                (entry.hooks ?? []).some((h) => String(h.command ?? '').includes(desired.sentinel)));
+            if (onDisk === undefined)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Merge a target's peaks-managed hook entries into `settings`, preserving
+ * all other keys and hooks. Entries routed to a DIFFERENT settings file are
+ * not part of `entries`, so the legacy-sentinel filter below strips them
+ * from this file (that is what migrates a gate-enforce entry that an older
+ * peaks release wrote into the shared file).
+ */
+export function withHooksInstalled(settings, entries, allSentinels) {
+    const existingHooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
+        ? settings.hooks
+        : {};
+    // Our entries may sit on more than one event key. Group by event so each
+    // event array is independently merged.
+    const ourByEvent = new Map();
+    for (const spec of entries) {
+        const list = ourByEvent.get(spec.event) ?? [];
+        list.push(spec);
+        ourByEvent.set(spec.event, list);
+    }
+    // Slice #014: the legacy sentinel set includes the progress-start
+    // sentinel so a pre-#014 install's stale progress-start entry is
+    // stripped by the filter (the file converges on the new
+    // gate-enforce-only shape, idempotently). The desired set (passed
+    // in below) only contains the gate-enforce sentinel.
+    const nextHooks = { ...existingHooks };
+    // An event key this file used to carry but whose entries all moved to the
+    // other file still needs its stale peaks entries stripped.
+    const eventKeys = new Set([...ourByEvent.keys(), ...Object.keys(existingHooks)]);
+    for (const eventKey of eventKeys) {
+        const existing = readHookEntriesFromHooks(nextHooks, eventKey);
+        const nonPeaks = existing.filter((entry) => !entryIsPeaksManaged(entry, allSentinels));
+        const ourFormatted = (ourByEvent.get(eventKey) ?? []).map((spec) => ({
+            matcher: spec.matcher,
+            hooks: [
+                {
+                    type: 'command',
+                    command: spec.command,
+                    ...(spec.shell !== undefined ? { shell: spec.shell } : {})
+                }
+            ]
+        }));
+        const merged = [...nonPeaks, ...ourFormatted];
+        if (merged.length > 0) {
+            nextHooks[eventKey] = merged;
+        }
+        else {
+            delete nextHooks[eventKey];
+        }
+    }
+    return {
+        ...settings,
+        hooks: nextHooks
+    };
+}
+/**
+ * Strip every peaks-managed hook row from one target's settings file, on every
+ * event key the file carries — a pre-#014 install could have left the legacy
+ * progress-start entry on a different event than the gate-enforce one. Returns
+ * the rewritten settings plus whether anything was actually removed.
+ */
+export function stripPeaksEntries(target, sentinels) {
+    const settings = readJsonObjectFile(target.settingsPath);
+    const existingHooks = settings.hooks ?? {};
+    const eventKeys = new Set([...target.entries.map((e) => e.event), ...Object.keys(existingHooks)]);
+    const nextHooks = { ...existingHooks };
+    let removed = false;
+    for (const eventKey of eventKeys) {
+        const entries = readHookEntriesFromHooks(nextHooks, eventKey);
+        const kept = entries.filter((entry) => !entryIsPeaksManaged(entry, sentinels));
+        if (kept.length !== entries.length)
+            removed = true;
+        if (kept.length > 0) {
+            nextHooks[eventKey] = kept;
+        }
+        else {
+            delete nextHooks[eventKey];
+        }
+    }
+    const nextSettings = { ...settings };
+    if (Object.keys(nextHooks).length > 0) {
+        nextSettings.hooks = nextHooks;
+    }
+    else {
+        delete nextSettings.hooks;
+    }
+    return { settings: nextSettings, removed };
+}

package/dist/services/skills/hooks-settings-paths.d.ts

@@ -0,0 +1,34 @@
+import { type HookScope } from '../ide/shared/safe-path.js';
+import type { IdeId } from '../ide/ide-types.js';
+/** Resolve settings root dir for a scope. */
+export declare function resolveSettingsRoot(scope: HookScope, projectRoot: string | undefined): string;
+export declare function assertSafeSettingsPathCompat(scope: HookScope, ide: IdeId, root: string, settingsPath: string): void;
+/**
+ * Resolve the machine-local settings file an IDE may carry (e.g. Claude
+ * Code's `.claude/settings.local.json`), or `undefined` when there is none.
+ *
+ * B3(b) 2026-09-13: the machine-local layer is an adapter-DECLARED capability,
+ * not a name list. It used to be two hardcoded facts here — a `Set(['claude-code'])`
+ * membership test and the filename literal `'settings.local.json'` — i.e. a
+ * module that routes per-IDE was itself naming one IDE and one IDE's file.
+ * Both now read off the adapter that owns them
+ * (`IdeSettingsLocation.localSettingsFileName`), exactly as
+ * `auto-compact-dispatcher.ts` already did for the same field.
+ *
+ * Behaviour is UNCHANGED, and that was verified rather than assumed: over all
+ * nine registered `IdeId`s, `IDES_WITH_LOCAL_SETTINGS.has(id)` was `true` for
+ * exactly the ids whose adapter declares `localSettingsFileName` (claude-code
+ * alone, `'settings.local.json'`). So the set was an exact duplicate of a
+ * declaration the adapters already carried, not an independent policy — and
+ * a new adapter that declares the field now gets this path for free instead
+ * of being silently denied it.
+ *
+ * This ALSO removes a live instance of the vendor guard's limit 1 (indirect
+ * identity: `SET.has(ide)`), which no AST check over comparisons or literals
+ * can see. The guard's header named this exact line as the example.
+ *
+ * Global scope resolves to `undefined`: the global settings file
+ * (`~/.claude/settings.json`) is already machine-local, so nothing needs
+ * relocating there.
+ */
+export declare function resolveLocalSettingsPath(scope: HookScope, ide: IdeId, projectRoot: string | undefined): string | undefined;

package/dist/services/skills/hooks-settings-paths.js

@@ -0,0 +1,75 @@
+/**
+ * The safety checks on an IDE settings path, and the machine-local sibling.
+ *
+ * Split out of `hooks-settings-service.ts` (file-size cap campaign). The
+ * service re-exports every name declared here, so existing importers keep
+ * using `./hooks-settings-service.js` unchanged.
+ */
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { assertSafeSettingsFile } from '../ide/shared/safe-path.js';
+import { getAdapter } from '../ide/ide-registry.js';
+/** Resolve settings root dir for a scope. */
+export function resolveSettingsRoot(scope, projectRoot) {
+    if (scope === 'global')
+        return resolve(homedir());
+    if (!projectRoot) {
+        throw new Error('Project scope requires a project root');
+    }
+    return resolve(projectRoot);
+}
+export function assertSafeSettingsPathCompat(scope, ide, root, settingsPath) {
+    const adapter = getAdapter(ide);
+    assertSafeSettingsFile(scope, root, adapter.settings.dirName, adapter.settings.settingsFileName);
+    // The compat path receives the already-computed settingsPath; double-check
+    // that the computed path matches what assertSafeSettingsFile would have
+    // produced. This guards against drift between the two resolvers.
+    const expected = adapter.settings.resolveSettingsFile(scope, scope === 'global' ? homedir() : root);
+    if (expected !== settingsPath) {
+        throw new Error(`settings path drift: ${expected} vs ${settingsPath}`);
+    }
+}
+/**
+ * Resolve the machine-local settings file an IDE may carry (e.g. Claude
+ * Code's `.claude/settings.local.json`), or `undefined` when there is none.
+ *
+ * B3(b) 2026-09-13: the machine-local layer is an adapter-DECLARED capability,
+ * not a name list. It used to be two hardcoded facts here — a `Set(['claude-code'])`
+ * membership test and the filename literal `'settings.local.json'` — i.e. a
+ * module that routes per-IDE was itself naming one IDE and one IDE's file.
+ * Both now read off the adapter that owns them
+ * (`IdeSettingsLocation.localSettingsFileName`), exactly as
+ * `auto-compact-dispatcher.ts` already did for the same field.
+ *
+ * Behaviour is UNCHANGED, and that was verified rather than assumed: over all
+ * nine registered `IdeId`s, `IDES_WITH_LOCAL_SETTINGS.has(id)` was `true` for
+ * exactly the ids whose adapter declares `localSettingsFileName` (claude-code
+ * alone, `'settings.local.json'`). So the set was an exact duplicate of a
+ * declaration the adapters already carried, not an independent policy — and
+ * a new adapter that declares the field now gets this path for free instead
+ * of being silently denied it.
+ *
+ * This ALSO removes a live instance of the vendor guard's limit 1 (indirect
+ * identity: `SET.has(ide)`), which no AST check over comparisons or literals
+ * can see. The guard's header named this exact line as the example.
+ *
+ * Global scope resolves to `undefined`: the global settings file
+ * (`~/.claude/settings.json`) is already machine-local, so nothing needs
+ * relocating there.
+ */
+export function resolveLocalSettingsPath(scope, ide, projectRoot) {
+    if (scope === 'global')
+        return undefined;
+    const adapter = getAdapter(ide);
+    const localFileName = adapter.settings.localSettingsFileName;
+    // `undefined` = this IDE has no machine-local layer. Note the order: a
+    // caller reaching here with an id the registry does not know still throws
+    // from `getAdapter` above, exactly as it did before — every path into this
+    // function already called `getAdapter(ide)` via `resolveSettingsPath`, so
+    // no new throw path is introduced.
+    if (localFileName === undefined)
+        return undefined;
+    const root = resolveSettingsRoot(scope, projectRoot);
+    assertSafeSettingsFile(scope, root, adapter.settings.dirName, localFileName);
+    return join(root, adapter.settings.dirName, localFileName);
+}

package/dist/services/skills/hooks-settings-read-installed.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What `peaks hooks status` reports: the peaks-managed rows actually on disk.
+ *
+ * Split out of `hooks-settings-service.ts` (file-size cap campaign). The
+ * service re-exports every name declared here, so existing importers keep
+ * using `./hooks-settings-service.js` unchanged.
+ */
+import type { IdeId } from '../ide/ide-types.js';
+/**
+ * Slice #014: read the *actually-installed* peaks-managed hook entries
+ * from a settings object. Replaces the pre-#014 `listInstalledEntriesForIde`
+ * helper in `hooks-commands.ts`, which returned the IDE-EXPECTED list
+ * (a hardcoded 2-entry array per adapter) rather than what was on disk.
+ * That bug surfaced when slice #013's local cleanup installed
+ * `peaks hooks install --no-progress` (gate-enforce only), but the
+ * status command still reported `entries: [Bash, Task]` because the
+ * helper didn't read the file.
+ *
+ * The new helper:
+ *   1. reads each `hooks.<event>` array,
+ *   2. filters to entries that are peaks-managed for the given IDE
+ *      (matches the legacy sentinel set: gate-enforce + the no-longer-
+ *      installed progress-start),
+ *   3. returns one `{ matcher, sentinel }` row per entry, taking the
+ *      FIRST matching sentinel per entry (entries have a single command
+ *      handler in practice, but the loop tolerates multi-handler
+ *      entries by taking the first match).
+ *
+ * Pre-#014 settings.json files that have a stale progress-start entry
+ * will see it surface in the result. This is intentional: the status
+ * command is the user's tool for "what is on disk right now", and
+ * surfacing a stale entry is the only way the user can know to run
+ * `peaks hooks install` (which now strips it) or `peaks hooks
+ * uninstall` (which removes it).
+ */
+export declare function readInstalledEntriesFromSettings(settings: Record<string, unknown>, ide: IdeId): ReadonlyArray<{
+    matcher: string;
+    sentinel: string;
+}>;

package/dist/services/skills/hooks-settings-read-installed.js

@@ -0,0 +1,60 @@
+import { resolveLegacySentinels } from './hooks-codegate-superpowers.js';
+import { entryIsPeaksManaged, readHookEntriesFromHooks } from './hooks-settings-file-shape.js';
+/**
+ * Slice #014: read the *actually-installed* peaks-managed hook entries
+ * from a settings object. Replaces the pre-#014 `listInstalledEntriesForIde`
+ * helper in `hooks-commands.ts`, which returned the IDE-EXPECTED list
+ * (a hardcoded 2-entry array per adapter) rather than what was on disk.
+ * That bug surfaced when slice #013's local cleanup installed
+ * `peaks hooks install --no-progress` (gate-enforce only), but the
+ * status command still reported `entries: [Bash, Task]` because the
+ * helper didn't read the file.
+ *
+ * The new helper:
+ *   1. reads each `hooks.<event>` array,
+ *   2. filters to entries that are peaks-managed for the given IDE
+ *      (matches the legacy sentinel set: gate-enforce + the no-longer-
+ *      installed progress-start),
+ *   3. returns one `{ matcher, sentinel }` row per entry, taking the
+ *      FIRST matching sentinel per entry (entries have a single command
+ *      handler in practice, but the loop tolerates multi-handler
+ *      entries by taking the first match).
+ *
+ * Pre-#014 settings.json files that have a stale progress-start entry
+ * will see it surface in the result. This is intentional: the status
+ * command is the user's tool for "what is on disk right now", and
+ * surfacing a stale entry is the only way the user can know to run
+ * `peaks hooks install` (which now strips it) or `peaks hooks
+ * uninstall` (which removes it).
+ */
+export function readInstalledEntriesFromSettings(settings, ide) {
+    const sentinels = resolveLegacySentinels(ide);
+    // Walk every event key the settings file has, not just the
+    // adapter-declared one. A pre-#014 install could have left a
+    // progress-start entry on a different event than the gate-enforce
+    // entry (Trae: both on beforeToolCall, but a stale install on a
+    // future IDE could split them).
+    const hooksRoot = settings.hooks;
+    if (!hooksRoot || typeof hooksRoot !== 'object' || Array.isArray(hooksRoot))
+        return [];
+    const result = [];
+    for (const eventKey of Object.keys(hooksRoot)) {
+        const entries = readHookEntriesFromHooks(hooksRoot, eventKey);
+        for (const entry of entries) {
+            if (!entryIsPeaksManaged(entry, sentinels))
+                continue;
+            const matcher = typeof entry.matcher === 'string' ? entry.matcher : '';
+            // Find the first matching sentinel inside the entry's command
+            // handlers. For each handler, find the first sentinel substring
+            // it contains. We pick the first handler's first matching
+            // sentinel (entries have a single command in practice).
+            const firstHandler = Array.isArray(entry.hooks) ? entry.hooks[0] : undefined;
+            const cmd = typeof firstHandler?.command === 'string' ? firstHandler.command : '';
+            const sentinel = sentinels.find((s) => cmd.includes(s));
+            if (matcher === '' || sentinel === undefined)
+                continue;
+            result.push({ matcher, sentinel });
+        }
+    }
+    return result;
+}