peaks-loop 4.1.3 → 4.1.4

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

@@ -1,228 +1,28 @@
-import type { IdeId } from '../ide/ide-types.js';
 import type { HookScope } from '../ide/shared/safe-path.js';
 import { type PeaksHookEntry } from './hooks-codegate-superpowers.js';
 export { HOOK_ENFORCE_SENTINEL, HOOK_CODE_GATE_SENTINEL, HOOK_CODE_GATE_MATCHER, HOOK_CODE_GATE_EVENT, HOOK_CODE_GATE_COMMAND, SUPERPOWERS_DENIED_SKILLS, type PeaksHookEntry } from './hooks-codegate-superpowers.js';
 /**
  * Install (and remove) the Peaks-managed hooks in an IDE's settings.json.
  *
- * The hook runs `peaks gate enforce` (Claude) or `peaks hook handle` (Trae /
- * other future adapters) before every relevant tool call; when a SOP guard's
- * gates fail it returns the adapter-specific deny shape, which blocks the
- * tool call BEFORE the IDE's permission checks — making the gate
- * un-bypassable by the agent.
+ * The hook runs `peaks gate enforce` before every relevant tool call; when a SOP
+ * guard's gates fail it returns the adapter-specific deny shape, which blocks the
+ * tool call BEFORE the IDE's permission checks — making the gate un-bypassable.
  *
- * Slice #1 refactor: this service delegates to the `IdeAdapter` for
- * `claude-code`. Slice #2 added Trae. Adapter provides `dirName` /
- * `settingsFileName` / `envVar` / `hookEvent` / `toolMatcher`. The Claude
- *
- * Slice #3 refactor (this commit): the service is now per-IDE aware via an
- * optional `options.ide` parameter. The CLI command is responsible for
- * resolving the IDE (env → stdin shape → cwd → fallback to 'claude-code')
- * via `detectIdeFromContext` and passing the result here. When `ide` is
- * omitted, the service defaults to `'claude-code'` so existing tests and
- * downstream callers continue to work without modification.
- *
- * Installation is an EXPLICIT user command (never postinstall): skills describe,
- * the CLI performs side effects. Writes preserve all other settings keys and
- * any other hooks, reject symlinked targets, and use an atomic rename so a
- * partial write can never corrupt the settings file. Our entry is merged into
- * (not replacing) the existing `hooks.<event>` array and is identified by a
- * sentinel substring in its command, so install is idempotent and uninstall
- * removes only our own entry.
+ * This file owns the policy and the four operations; the mechanisms live in the
+ * `hooks-settings-*` siblings. Installation is an EXPLICIT user command (never
+ * postinstall): skills describe, the CLI performs side effects. Writes preserve every
+ * other key and hook, reject symlinked targets, and use an atomic rename.
  */
 export type { HookScope } from '../ide/shared/safe-path.js';
-export type HookInstallOptions = {
-    /**
-     * Which IDE's adapter to install for. Defaults to `'claude-code'` for
-     * backward compatibility. The CLI command should resolve this from
-     * `detectIdeFromContext({ env, cwd, parsedStdin })` and pass the result.
-     * Throws if the IDE is not registered in the adapter registry.
-     */
-    readonly ide?: IdeId;
-    /**
-     * Slice #013 (bugfix — peaks hooks install --no-progress): when `true`,
-     * skip emitting the progress-start PreToolUse hook entry while still
-     * installing the gate-enforce entry. The progress-start hook auto-spawns
-     * a new terminal running `peaks progress watch`; with dispatch +
-     * heartbeat (slice #009 + #010) that auto-spawn is dead weight. Default
-     * `false` preserves the pre-slice install shape (both entries). The
-     * sentinel-based install is idempotent: re-running with `skipProgress:
-     * true` over a settings.json that previously had the progress entry
-     * installed will remove that entry. `uninstall` honors the same flag
-     * so it can find and remove both entries when both are present and
-     * only the gate-enforce entry when only the gate-enforce is present.
-     *
-     * Slice #014 (refactor — full removal of legacy progress-start surface):
-     * the field is preserved for API stability, but the underlying
-     * install only ever emits the gate-enforce entry. The progress-start
-     * entry is no longer installed regardless of this flag's value. The
-     * legacy `peaks progress start|watch|close` CLI surface is gone
-     * (replaced by `peaks sub-agent dispatch|heartbeat|share`); the hook
-     * entry would have been pointing at a `peaks progress start` that no
-     * longer exists. The sentinel `peaks progress start` constant is still
-     * exported (some tests + back-compat reads rely on it) but no new
-     * hook entries use it.
-     */
-    readonly skipProgress?: boolean;
-};
-/** Default (claude-code) hook command — kept as a stable export for tests. */
+export type { HookEntryTarget, HookInstallOptions, HookInstallPlan, HookInstallResult, HookRemoveResult, HookStatus } from './hooks-settings-types.js';
+export { readInstalledEntriesFromSettings } from './hooks-settings-read-installed.js';
+export { TRIGGER_PHRASES, listSuperpowersDenyEntries, withSuperpowersSkillDenylist, withTriggeredDenyList, withoutSuperpowersSkillDenylist, withoutTriggeredDenyList } from './hooks-settings-deny-list.js';
+import type { HookInstallOptions, HookInstallPlan, HookInstallResult, HookRemoveResult, HookStatus } from './hooks-settings-types.js';
+/** Default (claude-code) hook command. */
 export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\" --json";
-/**
- * One peaks-managed entry paired with the settings file it is (or will be)
- * written to.
- *
- * `entries` is a flat list of the same matcher/sentinel pairs, which reads as
- * "written to `settingsPath`" even when the entry is routed to the other file
- * (see `resolveHookTargets`). This carries the routing explicitly so the
- * dry-run can name the real target without a real run.
- */
-export type HookEntryTarget = {
-    matcher: string;
-    sentinel: string;
-    settingsPath: string;
-};
-export type HookInstallPlan = {
-    scope: HookScope;
-    settingsPath: string;
-    exists: boolean;
-    alreadyInstalled: boolean;
-    desiredCommand: string;
-    sentinel: string;
-    matcher: string;
-    /**
-     * Machine-local, gitignored settings file that the gate-enforce entry is
-     * written to instead of `settingsPath`. Undefined when the IDE has no such
-     * file (or the scope is global, where the settings file is already
-     * machine-local). See `resolveHookTargets`.
-     */
-    localSettingsPath?: string;
-    /** Every entry the install writes, paired with its target file. */
-    entryTargets: ReadonlyArray<HookEntryTarget>;
-};
-export type HookInstallResult = HookInstallPlan & {
-    applied: boolean;
-};
-export type HookRemoveResult = {
-    scope: HookScope;
-    settingsPath: string;
-    localSettingsPath?: string;
-    removed: boolean;
-};
-export type HookStatus = {
-    scope: HookScope;
-    settingsPath: string;
-    exists: boolean;
-    localSettingsPath?: string;
-    localExists?: boolean;
-    installed: boolean;
-    /**
-     * Whether this IDE can host a peaks hook AT ALL (`hasHookSpec`).
-     *
-     * `status` answers "what is on disk", and for an IDE with no
-     * `HOOK_COMMAND_BY_IDE` entry the answer is "nothing, and nothing ever will
-     * be" — which is a successful query returning a negative fact, not a failed
-     * one. The exit code says the query succeeded; this field says what it found.
-     * Without it `installed: false` would be indistinguishable from a supported
-     * IDE that simply has no hook installed yet, which is a state the user can
-     * act on.
-     */
-    supportsHooks: boolean;
-};
-/**
- * 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;
-}>;
-/**
- * Merge the peaks-managed Skill denylist into the existing settings object.
- * Preserves every other `permissions.deny` entry the user (or another tool)
- * has written so the install is additive, not destructive. The output is
- * always deterministic: the same input always yields the same output,
- * regardless of insertion order in the source array.
- *
- * Defensive behavior:
- * - `settings.permissions` is missing or non-object → install creates a
- *   fresh `permissions: { deny: [...our entries] }` object.
- * - `settings.permissions.deny` is missing or non-array → install replaces
- *   the field with a fresh array containing only our entries.
- * - Duplicate entries (any source) are collapsed to one via `new Set`.
- *
- * The function is pure: it does not mutate the input. Atomic write happens
- * at the call site (`applyHookInstall`).
- */
-export declare function withSuperpowersSkillDenylist(settings: Record<string, unknown>): Record<string, unknown>;
-/**
- * Inverse of `withSuperpowersSkillDenylist`. Removes every peaks-managed
- * `UseSkill(...)` entry from the deny list. If the resulting deny list is
- * empty, the `deny` field itself is deleted; if the `permissions` object
- * becomes empty, the `permissions` field itself is deleted. This is the
- * uninstall path: every field we wrote must be removed exactly, and no
- * other field may be touched.
- *
- * Pure (no mutation).
- */
-export declare function withoutSuperpowersSkillDenylist(settings: Record<string, unknown>): Record<string, unknown>;
-/**
- * Read-only introspection. Returns the deny entries that `peaks hooks
- * install` would write today. Useful for `peaks hooks status` and the
- * dry-run envelope.
- */
-export declare function listSuperpowersDenyEntries(): ReadonlyArray<string>;
 /** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. Slice #014: only the gate-enforce entry. */
 export declare const PEAKS_HOOK_ENTRIES: ReadonlyArray<PeaksHookEntry>;
 export declare function planHookInstall(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookInstallPlan;
 export declare function applyHookInstall(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookInstallResult;
 export declare function removeHookInstall(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookRemoveResult;
 export declare function readHookStatus(scope: HookScope, projectRoot?: string, options?: HookInstallOptions): HookStatus;
-/**
- *
- * In addition to the static SUPERPOWERS_DENIED_SKILLS list, peaks
- * scans the existing settings file for "trigger phrases" that
- * indicate the user has configured the superpowers chain (or
- * any other auto-run worktree-creating tool) and appends a
- * defensive deny to prevent the chain from running raw
- * `git worktree add` (or `podman run`) directly.
- *
- * Triggers detected (substring match on the existing
- * permissions.deny / permissions.allow list):
- *
- *  - `superpowers:using-git-worktrees` — the chain's ground zero
- *  - `superpowers:brainstorming` etc. — the upstream skill
- *  - `Bash(git worktree add` — the user has explicitly
- *    allowed raw git worktree, which our L2 lease-aware gate
- *    would also intercept (defense in depth)
- *
- * Append-only — never replaces, never re-orders, never removes
- * existing entries. Idempotent: re-running the install with
- * the same input yields the same output.
- */
-export declare const TRIGGER_PHRASES: ReadonlyArray<string>;
-export declare function withTriggeredDenyList(settings: Record<string, unknown>): Record<string, unknown>;
-/** Inverse of withTriggeredDenyList: strip every deny-trigger entry. */
-export declare function withoutTriggeredDenyList(settings: Record<string, unknown>): Record<string, unknown>;