peaks-cli 1.3.9 → 1.4.0

package/dist/src/services/skill-scope/adapters/claude-code.js

@@ -0,0 +1,304 @@
+/**
+ * `peaks skill scope` — Claude Code adapter (full impl, slice 025.1).
+ *
+ * Strategy (tech-doc-025 §3):
+ * 1. PRIMARY: write `.claude/settings.local.json` with
+ *    `permissions.allow: ["Skill(name)", ...]` + `permissions.deny: [...]`.
+ * 2. FALLBACK (R1, `--shadow-fallback`): when the runtime probe determines
+ *    Claude Code rejects `Skill(name)` in `permissions.deny`, write a
+ *    shadow stub at `.claude/skills/<name>/SKILL.md` for each denylisted
+ *    skill. Tagged with `_peaks_scope_disabled: true` (R6).
+ *
+ * Idempotency: dedupe the allow/deny arrays; shadow-stub writes skip
+ * when the marker is already present. AC11.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** Adapter id. */
+const IDE_ID = 'claude-code';
+/** Format the `Skill(name)` string Claude Code's permission system uses. */
+export function skillRef(name) {
+    return `Skill(${name})`;
+}
+/** Dedupe a list preserving the first-seen order. */
+function dedupe(list) {
+    const seen = new Set();
+    const out = [];
+    for (const item of list) {
+        if (!seen.has(item)) {
+            seen.add(item);
+            out.push(item);
+        }
+    }
+    return out;
+}
+const EMPTY_SETTINGS = { permissions: { allow: [], deny: [] } };
+/**
+ * Read the existing `.claude/settings.local.json` (returns empty settings
+ * if the file does not exist). On parse failure returns empty settings
+ * and a warning rather than throwing — the user can still write fresh
+ * settings.
+ */
+async function readSettingsLocal(projectRoot) {
+    const file = join(projectRoot, '.claude', 'settings.local.json');
+    if (!existsSync(file))
+        return { settings: EMPTY_SETTINGS, existed: false, malformed: false };
+    try {
+        const raw = await readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object') {
+            return { settings: EMPTY_SETTINGS, existed: true, malformed: true };
+        }
+        const obj = parsed;
+        const permsRaw = obj.permissions;
+        const perms = permsRaw !== null && typeof permsRaw === 'object'
+            ? {
+                allow: Array.isArray(permsRaw.allow)
+                    ? permsRaw.allow
+                    : [],
+                deny: Array.isArray(permsRaw.deny)
+                    ? permsRaw.deny
+                    : [],
+            }
+            : { allow: [], deny: [] };
+        return { settings: { ...obj, permissions: perms }, existed: true, malformed: false };
+    }
+    catch {
+        return { settings: EMPTY_SETTINGS, existed: true, malformed: true };
+    }
+}
+/**
+ * Write the JSON file atomically via `.peaks-tmp` + `rename`. Removes the
+ * temp file on partial failure.
+ */
+async function writeJsonAtomic(file, data) {
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.peaks-tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+        await rename(tmp, file);
+    }
+    catch (error) {
+        if (existsSync(tmp)) {
+            try {
+                await rm(tmp, { force: true });
+            }
+            catch { /* best-effort */ }
+        }
+        throw error;
+    }
+}
+/**
+ * Map allowlist/denylist → permissions.allow/permissions.deny. Never sorts;
+ * preserves input order. Always dedupes.
+ */
+export function toPermissions(allowlist, denylist) {
+    return {
+        permissions: {
+            allow: dedupe(allowlist.map(skillRef)),
+            deny: dedupe(denylist.map(skillRef)),
+        },
+    };
+}
+/**
+ * Strip any peaks-* name from the denylist (G6 hard constraint). Returns
+ * the cleaned denylist + the list of stripped names for the audit log.
+ */
+export function stripPeaksFromDenylist(denylist) {
+    const cleaned = [];
+    const stripped = [];
+    for (const name of denylist) {
+        if (name.startsWith('peaks-')) {
+            stripped.push(name);
+        }
+        else {
+            cleaned.push(name);
+        }
+    }
+    return { cleaned, stripped };
+}
+/** Render the shadow-stub SKILL.md body (R6 marker). */
+function shadowStubBody(name) {
+    return `---
+name: ${name}
+description: _peaks_scope_disabled
+_peaks_scope_disabled: true
+---
+# Disabled by \`peaks skill scope --apply\`
+
+This skill is shadowed because the project has marked it as out of scope.
+To restore, run \`peaks skill scope --reset\` or edit \`.peaks/scope/skills.json\`.
+`;
+}
+async function writeShadowStub(projectRoot, name) {
+    const file = join(projectRoot, '.claude', 'skills', name, 'SKILL.md');
+    await mkdir(dirname(file), { recursive: true });
+    // Skip if already has the marker
+    if (existsSync(file)) {
+        try {
+            const existing = await readFile(file, 'utf8');
+            if (existing.includes('_peaks_scope_disabled: true')) {
+                return file;
+            }
+        }
+        catch { /* fall through and overwrite */ }
+    }
+    await writeFile(file, shadowStubBody(name), 'utf8');
+    return file;
+}
+/**
+ * Runtime probe for whether Claude Code supports `Skill(name)` syntax in
+ * `permissions.deny` (R1). For slice 025.1 we return `unknown` and let
+ * the caller decide. Replace this with a real check when Claude Code's
+ * `permissions.deny` schema is documented.
+ */
+export async function probeSkillDenySupport() {
+    return 'unknown';
+}
+/**
+ * Decision: should the denylist use shadow stubs instead of `permissions.deny`?
+ * Returns true when:
+ * - The caller passes `shadowFallback: true`, OR
+ * - The runtime probe returns `support-allow-only` / `unknown`.
+ */
+async function shouldUseShadowStubs(input) {
+    if (input.shadowFallback)
+        return true;
+    const probe = await probeSkillDenySupport();
+    return probe !== 'support-allow-and-deny';
+}
+/** Strip the peaks-* shadow stubs written by a previous apply. */
+function shadowStubDir(projectRoot, name) {
+    return join(projectRoot, '.claude', 'skills', name, 'SKILL.md');
+}
+async function removeShadowStubIfPresent(projectRoot, name) {
+    const file = shadowStubDir(projectRoot, name);
+    if (!existsSync(file))
+        return false;
+    try {
+        const raw = await readFile(file, 'utf8');
+        if (!raw.includes('_peaks_scope_disabled: true'))
+            return false;
+        await rm(file, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export class ClaudeCodeSkillScope {
+    ide = IDE_ID;
+    supported = true;
+    constructor(_opts) {
+        // projectRoot is supplied on every method call; the class is stateless.
+        void _opts;
+    }
+    /** detect(): returns 1.0 when the project root has a .claude/ dir. */
+    async detect(projectRoot) {
+        return existsSync(join(projectRoot, '.claude')) ? 1.0 : 0.5;
+    }
+    async applyScope(input) {
+        const written = [];
+        const removed = [];
+        // G6: strip peaks-* from the denylist.
+        const { cleaned: cleanedDeny, stripped } = stripPeaksFromDenylist(input.denylist);
+        if (stripped.length > 0) {
+            removed.push(...stripped);
+        }
+        const useShadows = await shouldUseShadowStubs(input);
+        // 1. Write (or skip) settings.local.json
+        const { settings: existing } = await readSettingsLocal(input.projectRoot);
+        const next = toPermissions(input.allowlist, cleanedDeny);
+        // Preserve existing non-permissions fields (theme, env, etc.).
+        const preserved = { ...existing };
+        delete preserved.permissions;
+        // Merge with the user's pre-existing allow/deny entries (deduped).
+        const existingAllow = (existing.permissions.allow ?? []);
+        const existingDeny = (existing.permissions.deny ?? []);
+        const merged = {
+            ...preserved,
+            permissions: {
+                allow: dedupe([...existingAllow, ...next.permissions.allow]),
+                deny: dedupe([...existingDeny, ...next.permissions.deny]),
+            },
+        };
+        if (input.simulateWriteFailure) {
+            throw new Error('simulated write failure (settings.local.json)');
+        }
+        const settingsFile = join(input.projectRoot, '.claude', 'settings.local.json');
+        await writeJsonAtomic(settingsFile, merged);
+        written.push(settingsFile);
+        // 2. Optionally write shadow stubs for the (stripped, cleaned) denylist
+        let usedShadowStub = false;
+        if (useShadows) {
+            usedShadowStub = true;
+            for (const name of cleanedDeny) {
+                const stub = await writeShadowStub(input.projectRoot, name);
+                written.push(stub);
+            }
+        }
+        return {
+            ide: this.ide,
+            ok: true,
+            writtenFiles: written,
+            usedShadowStub,
+            notSupported: false,
+            strippedFromDenylist: stripped,
+        };
+    }
+    async showScope(projectRoot) {
+        const settingsFile = join(projectRoot, '.claude', 'settings.local.json');
+        let native = null;
+        if (existsSync(settingsFile)) {
+            try {
+                native = JSON.parse(await readFile(settingsFile, 'utf8'));
+            }
+            catch {
+                native = null;
+            }
+        }
+        return { source: null, native, ide: this.ide };
+    }
+    async resetScope(input) {
+        const removed = [];
+        const settingsFile = join(input.projectRoot, '.claude', 'settings.local.json');
+        if (existsSync(settingsFile)) {
+            // Only remove if it has a permissions.allow/deny field shaped by us,
+            // otherwise leave the user's hand-curated file alone.
+            try {
+                const raw = await readFile(settingsFile, 'utf8');
+                const parsed = JSON.parse(raw);
+                if (parsed !== null &&
+                    typeof parsed === 'object' &&
+                    parsed.permissions !== undefined) {
+                    await rm(settingsFile, { force: true });
+                    removed.push(settingsFile);
+                }
+            }
+            catch {
+                // best-effort
+            }
+        }
+        // Also remove shadow stubs (we don't know which skills are stubbed, so
+        // we don't blindly walk .claude/skills; the caller can re-run detect +
+        // reset if they need a full sweep). For the explicit case we know
+        // about, we strip any stub whose marker is present.
+        const skillsDir = join(input.projectRoot, '.claude', 'skills');
+        if (existsSync(skillsDir)) {
+            // Best-effort scan: only act when the file is unmistakably a stub.
+            const { readdirSync } = await import('node:fs');
+            const entries = readdirSync(skillsDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                const removedStub = await removeShadowStubIfPresent(input.projectRoot, entry.name);
+                if (removedStub) {
+                    removed.push(join(input.projectRoot, '.claude', 'skills', entry.name, 'SKILL.md'));
+                }
+            }
+        }
+        return { ide: this.ide, removedFiles: removed };
+    }
+}
+export const CLAUDE_CODE_SKILL_SCOPE = new ClaudeCodeSkillScope();

package/dist/src/services/skill-scope/adapters/codex.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const CODEX_SKILL_SCOPE: SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/codex.js

@@ -0,0 +1,12 @@
+// TODO(slice-025.4-codex): research Codex's per-project skill scoping
+// config format. Codex uses `.codex/` for project-local config.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/codex-skills.json` (source-of-truth) on every
+//    `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// CodexSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const CODEX_SKILL_SCOPE = makeStubAdapter('codex', 'slice-025.4-codex', 'Codex');

package/dist/src/services/skill-scope/adapters/cursor.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const CURSOR_SKILL_SCOPE: SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/cursor.js

@@ -0,0 +1,13 @@
+// TODO(slice-025.3-cursor): research Cursor's per-project skill scoping
+// config format. Cursor uses `.cursor/` for project-local config; the
+// skill-scope hook may live there or in `.cursor/rules/`.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/cursor-skills.json` (source-of-truth) on every
+//    `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// CursorSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const CURSOR_SKILL_SCOPE = makeStubAdapter('cursor', 'slice-025.3-cursor', 'Cursor');

package/dist/src/services/skill-scope/adapters/qoder.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const QODER_SKILL_SCOPE: SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/qoder.js

@@ -0,0 +1,13 @@
+// TODO(slice-025.5-qoder): research Qoder's per-project skill scoping
+// config format. Qoder is an AI IDE by Alibaba; per-project config dir
+// is unconfirmed at slice 025.1.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/qoder-skills.json` (source-of-truth) on every
+//    `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// QoderSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const QODER_SKILL_SCOPE = makeStubAdapter('qoder', 'slice-025.5-qoder', 'Qoder');

package/dist/src/services/skill-scope/adapters/tongyi.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const TONGYI_SKILL_SCOPE: SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/tongyi.js

@@ -0,0 +1,13 @@
+// TODO(slice-025.6-tongyi): research Tongyi Lingma's per-project skill
+// scoping config format. Tongyi Lingma is an AI IDE by Alibaba; per-
+// project config dir is unconfirmed at slice 025.1.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/tongyi-lingma-skills.json` (source-of-truth)
+//    on every `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// TongyiSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const TONGYI_SKILL_SCOPE = makeStubAdapter('tongyi-lingma', 'slice-025.6-tongyi', 'Tongyi Lingma');

package/dist/src/services/skill-scope/adapters/trae.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const TRAE_SKILL_SCOPE: SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/trae.js

@@ -0,0 +1,12 @@
+// TODO(slice-025.2-trae): research Trae's per-project skill scoping config
+// format. Likely candidates: `.trae/skills.json` or `.trae/settings.json`.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/trae-skills.json` (source-of-truth) on every
+//    `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// TraeSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const TRAE_SKILL_SCOPE = makeStubAdapter('trae', 'slice-025.2-trae', 'Trae IDE');

package/dist/src/services/skill-scope/detect.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Detection algorithm for `peaks skill scope`.
+ *
+ * Pure function: given a project root and the installed-skills path, the
+ * algorithm produces a `DetectResult` (signals + per-skill classification
+ * + counts). No filesystem writes, no randomness, no time-of-day. AC11.
+ *
+ * Three layers:
+ * 1. `extractProjectSignals(projectRoot)` — read package.json + tsconfig +
+ *    file tree (top-50 extensions).
+ * 2. `classifySkill(skill, signals, hardcodedRules)` — keyword matching
+ *    against the skill's SKILL.md description.
+ * 3. `detectSkillScope({ projectRoot, installedSkillsPath })` — top-level
+ *    orchestrator that returns the JSON envelope (AC1).
+ */
+import type { ProjectSignals, SkillKind, SkillScopeCounts, SkillScopeRecord } from './types.js';
+/**
+ * Walk `src/` (recursively) AND the project root, collecting the top-50
+ * unique file extensions. Sorted lexicographically.
+ */
+export declare function scanFileTree(projectRoot: string, maxExtensions?: number): string[];
+/**
+ * Build the `ProjectSignals` object from the project root.
+ */
+export declare function extractProjectSignals(projectRoot: string): Promise<ProjectSignals>;
+export interface InstalledSkill {
+    readonly name: string;
+    readonly description: string;
+    readonly skillPath: string;
+}
+interface HardcodedRules {
+    readonly alwaysRelevant: ReadonlySet<string>;
+    readonly nonTsPrefixes: readonly string[];
+}
+/**
+ * Infer the `SkillKind` for a skill by name. Used for the JSON envelope.
+ */
+export declare function inferSkillKind(name: string, alwaysRelevant: ReadonlySet<string>): SkillKind;
+/**
+ * Classify a single skill given the project signals. Returns the relevance
+ * + a list of human-readable reasons (stable for fixtures, so unit tests
+ * can assert exact strings).
+ */
+export declare function classifySkill(skill: InstalledSkill, signals: ProjectSignals, rules: HardcodedRules): SkillScopeRecord;
+export interface DetectInput {
+    readonly projectRoot: string;
+    readonly installedSkillsPath?: string;
+    readonly detectedIde?: string | null;
+}
+export interface DetectResult {
+    readonly detectedIde: string | null;
+    readonly projectSignals: ProjectSignals;
+    readonly skills: readonly SkillScopeRecord[];
+    readonly counts: SkillScopeCounts;
+}
+/**
+ * Discover the installed skills under `installedSkillsPath` (default:
+ * `~/.claude/skills`). Each subdir containing a SKILL.md counts as an
+ * installed skill.
+ */
+export declare function listInstalledSkills(installedSkillsPath: string): Promise<InstalledSkill[]>;
+/**
+ * The default installed-skills path: `~/.claude/skills`. Resolved at call
+ * time so the orchestrator stays pure-ish (no module-level side effects).
+ */
+export declare function defaultInstalledSkillsPath(): string;
+/**
+ * Top-level orchestrator. Reads package.json + tsconfig + file tree,
+ * discovers installed skills, classifies each one, returns the JSON
+ * envelope. Idempotent: same input → same output. No filesystem writes.
+ */
+export declare function detectSkillScope(input: DetectInput): Promise<DetectResult>;
+/** Compute a stable summary hash (used by tests to assert no time-dependent fields). */
+export declare function detectSummary(result: DetectResult): string;
+export {};