peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/skillhub/types.d.ts

@@ -0,0 +1,115 @@
+export interface BeeReleaseRow {
+    id: number;
+    bee_name: string;
+    version: string;
+    source: "user";
+    archived_at: string;
+    archived_by: "user" | "llm";
+    user_intent_raw: string | null;
+    description: string | null;
+    parent_version: string | null;
+    changelog: string | null;
+    /**
+     * M3 / spec §4.2: `shareable` defaults to true (1 in SQLite).
+     * Enforced at the export CLI layer in M7; M3 only adds the column.
+     */
+    shareable: 0 | 1;
+    /**
+     * M3 / spec §4.2: `desktop_visible` defaults to true (1 in SQLite).
+     * Desktop visibility is a UI accelerator filter; M7 reads this.
+     */
+    desktop_visible: 0 | 1;
+}
+export interface BeeReleasePointerRow {
+    bee_name: string;
+    latest_version: string;
+    released_at: string;
+}
+export interface BeeManifestRow {
+    release_id: number;
+    schema_version: string;
+    description: string;
+    segments_json: string;
+    entrypoint_preamble: string | null;
+    promotion: string;
+    min_cycles: number | null;
+    requires_human: number;
+    requires_smoke: number;
+    retire_on_misses: number | null;
+}
+export interface BeeSegmentRefRow {
+    id: number;
+    release_id: number;
+    segment_name: string;
+    inputs_json: string | null;
+    outputs_json: string | null;
+    side_effects: string | null;
+}
+export interface BeeFileRow {
+    id: number;
+    release_id: number;
+    owner_kind: "bee" | "segment";
+    owner_name: string;
+    path: string;
+    kind: "markdown" | "script" | "reference" | "binary" | "other";
+    size_bytes: number;
+    sha256: string;
+    blob_path: string;
+}
+export interface BeeChangeRow {
+    id: number;
+    release_id: number;
+    change_kind: string;
+    target_kind: string;
+    target_name: string;
+    detail: string | null;
+}
+/**
+ * Shape of `manifest.json` inside a release export tarball.
+ *
+ * Producer: `src/services/skillhub/release-export.ts` writes this file via
+ *   `JSON.stringify({ bee_name, version, manifestRows, segRows, fileRows, changeRows })`.
+ * Consumer: `src/services/skillhub/release-import.ts` parses it back with
+ *   `JSON.parse(readFileSync(join(stageDir, "manifest.json"), "utf-8"))`.
+ *
+ * Defining it once here (rather than as an inline anonymous type at the
+ * call-site) lets both sides share a structural contract. If a future
+ * field is added — e.g. an exported schema-version stamp — it lands in
+ * one place and TypeScript flags every consumer that needs updating.
+ */
+export interface ExportPayload {
+    bee_name: string;
+    version: string;
+    manifestRows: Array<{
+        schema_version: string;
+        description: string;
+        segments_json: string;
+        entrypoint_preamble: string | null;
+        promotion: string;
+        min_cycles: number | null;
+        requires_human: number;
+        requires_smoke: number;
+        retire_on_misses: number | null;
+    }>;
+    segRows: Array<{
+        segment_name: string;
+        inputs_json: string | null;
+        outputs_json: string | null;
+        side_effects: string | null;
+    }>;
+    fileRows: Array<{
+        owner_kind: string;
+        owner_name: string;
+        path: string;
+        kind: string;
+        size_bytes: number;
+        sha256: string;
+        blob_path: string;
+    }>;
+    changeRows: Array<{
+        change_kind: string;
+        target_kind: string;
+        target_name: string;
+        detail: string | null;
+    }>;
+}

package/dist/services/skillhub/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,212 @@
+import type { IdeId } from '../ide/ide-types.js';
+import type { HookScope } from '../ide/shared/safe-path.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.
+ *
+ * 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
+ * install path is byte-level-compat with slice #0 (AC-1).
+ *
+ * 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.
+ */
+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;
+};
+/** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
+export declare const HOOK_ENFORCE_SENTINEL = "peaks gate enforce";
+/** Default (claude-code) hook command — kept as a stable export for tests. */
+export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\"";
+export type HookInstallPlan = {
+    scope: HookScope;
+    settingsPath: string;
+    exists: boolean;
+    alreadyInstalled: boolean;
+    desiredCommand: string;
+    sentinel: string;
+    matcher: string;
+};
+export type HookInstallResult = HookInstallPlan & {
+    applied: boolean;
+};
+export type HookRemoveResult = {
+    scope: HookScope;
+    settingsPath: string;
+    removed: boolean;
+};
+export type HookStatus = {
+    scope: HookScope;
+    settingsPath: string;
+    exists: boolean;
+    installed: 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;
+}>;
+/** A typed descriptor for a single peaks-managed hook entry. */
+export type PeaksHookEntry = {
+    sentinel: string;
+    matcher: string;
+    command: string;
+    event: string;
+};
+/**
+ * The set of Skills whose use is denied at the IDE permissions layer for
+ * every `peaks hooks install` call. Each entry is the namespace-qualified
+ * skill id; the helper `formatSuperpowersDenyEntry` wraps it in the IDE's
+ * `UseSkill(...)` envelope.
+ *
+ * Slice 2026-07-29-worktree-layer3-deny: the list is empty-aware. To deny a
+ * new skill, append its id here and re-run `peaks hooks install`. The list
+ * is also the inverse for uninstall: `removeHookInstall` rebuilds the deny
+ * list by filtering out anything whose wrapped form matches one of these
+ * ids.
+ */
+export declare const SUPERPOWERS_DENIED_SKILLS: ReadonlyArray<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;
+/**
+ * Slice 2026-07-29-worktree-l2-extended Part 27 — trigger-style deny.
+ *
+ * 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>;