peaks-cli 1.4.1 → 2.0.0

package/dist/src/services/skill-scope/registry.js

@@ -1,83 +0,0 @@
-/**
- * `peaks skill scope` — adapter registry.
- *
- * The registry owns the map from IdeId → SkillScopeAdapter. It exposes two
- * functions:
- * - `getScopeAdapter(ide)` — direct lookup. Throws on unknown ide.
- * - `resolveActiveAdapter(projectRoot)` — discover the best adapter by
- *   probing every registered adapter's `detect(projectRoot)`. Falls back
- *   to Claude Code with a synthetic score of 0.5 when no adapter scores
- *   ≥ 0.5 (R3: "Claude Code shipped, Trae in progress" per package.json).
- *
- * See tech-doc-025 §7 for the discovery flow + fallback semantics.
- */
-import { CLAUDE_CODE_SKILL_SCOPE } from './adapters/claude-code.js';
-import { CODEX_SKILL_SCOPE } from './adapters/codex.js';
-import { CURSOR_SKILL_SCOPE } from './adapters/cursor.js';
-import { QODER_SKILL_SCOPE } from './adapters/qoder.js';
-import { TONGYI_SKILL_SCOPE } from './adapters/tongyi.js';
-import { TRAE_SKILL_SCOPE } from './adapters/trae.js';
-/**
- * Insertion order: Claude Code first (shipped), then Trae (in progress),
- * then the four roadmap IDEs. The CLI's `--ide <name>` overrides this map.
- */
-const SCOPE_ADAPTERS = new Map([
-    ['claude-code', CLAUDE_CODE_SKILL_SCOPE],
-    ['trae', TRAE_SKILL_SCOPE],
-    ['codex', CODEX_SKILL_SCOPE],
-    ['cursor', CURSOR_SKILL_SCOPE],
-    ['qoder', QODER_SKILL_SCOPE],
-    ['tongyi-lingma', TONGYI_SKILL_SCOPE],
-]);
-/** Get the adapter for a given IDE id. Throws on unsupported IDE. */
-export function getScopeAdapter(ide) {
-    const adapter = SCOPE_ADAPTERS.get(ide);
-    if (adapter === undefined) {
-        throw new Error(`No SkillScopeAdapter for IDE: ${ide}. Registered: ${listScopeAdapterIds().join(', ') || '(none)'}`);
-    }
-    return adapter;
-}
-/** All registered adapter ids (insertion order). */
-export function listScopeAdapterIds() {
-    return Array.from(SCOPE_ADAPTERS.keys());
-}
-/** All registered adapters (insertion order). */
-export function listScopeAdapters() {
-    return Array.from(SCOPE_ADAPTERS.values());
-}
-/**
- * Discover the active adapter for a project root. Returns the highest-
- * scoring adapter; if all adapters score < 0.5, falls back to the Claude
- * Code adapter with a synthetic score of 0.5 (R3). Stubs (Trae, Cursor,
- * Codex, Qoder, Tongyi) return 0.0 from `detect()` so they never win.
- */
-export async function resolveActiveAdapter(projectRoot) {
-    let best = null;
-    for (const adapter of SCOPE_ADAPTERS.values()) {
-        const score = await adapter.detect(projectRoot);
-        if (best === null || score > best.score) {
-            best = { adapter, score };
-        }
-    }
-    if (best === null || best.score < 0.5) {
-        return { adapter: CLAUDE_CODE_SKILL_SCOPE, score: 0.5, isFallback: true };
-    }
-    return { adapter: best.adapter, score: best.score, isFallback: false };
-}
-/**
- * Test seam: replace the registry (used by stub-adapter tests to inject
- * a fresh adapter for an IDE without restarting the module).
- */
-export function _setScopeAdapterForTesting(ide, adapter) {
-    SCOPE_ADAPTERS.set(ide, adapter);
-}
-/** Test seam: reset to built-in defaults. */
-export function _resetScopeAdaptersForTesting() {
-    SCOPE_ADAPTERS.clear();
-    SCOPE_ADAPTERS.set('claude-code', CLAUDE_CODE_SKILL_SCOPE);
-    SCOPE_ADAPTERS.set('trae', TRAE_SKILL_SCOPE);
-    SCOPE_ADAPTERS.set('codex', CODEX_SKILL_SCOPE);
-    SCOPE_ADAPTERS.set('cursor', CURSOR_SKILL_SCOPE);
-    SCOPE_ADAPTERS.set('qoder', QODER_SKILL_SCOPE);
-    SCOPE_ADAPTERS.set('tongyi-lingma', TONGYI_SKILL_SCOPE);
-}

package/dist/src/services/skill-scope/source-of-truth.d.ts

@@ -1,44 +0,0 @@
-/**
- * Source-of-truth helpers for `peaks skill scope`.
- *
- * The source-of-truth file `.peaks/scope/skills.json` is the canonical
- * record of the user's scope intent. Adapters translate it to their
- * IDE-native config; the CLI always reads back from this file on `--show`.
- *
- * Atomicity: every write goes through `.peaks-tmp` first, then `rename`
- * (POSIX-atomic; on Windows `rename` is atomic for files on the same volume).
- * See tech-doc-025 §3.1.
- */
-import type { ScopeConfig } from './types.js';
-/** File name for the canonical source-of-truth. */
-export declare const SCOPE_FILE_NAME = "skills.json";
-/** Resolve the canonical source-of-truth path for a project root. */
-export declare function scopeFilePath(projectRoot: string): string;
-/** Resolve the per-IDE companion file path (kebab-case). */
-export declare function ideCompanionFilePath(projectRoot: string, ide: string): string;
-/** Resolve the `.peaks/scope/` directory for a project root. */
-export declare function scopeDir(projectRoot: string): string;
-/**
- * Read the source-of-truth scope config, or null if it does not exist.
- * Returns null on parse error too — the caller decides whether to surface.
- */
-export declare function readSourceOfTruth(projectRoot: string): Promise<ScopeConfig | null>;
-/**
- * Read the per-IDE companion file (`.peaks/scope/<ide>-skills.json`), or
- * null if it does not exist or is unparseable.
- */
-export declare function readIdeCompanion(projectRoot: string, ide: string): Promise<unknown>;
-/**
- * Write the canonical source-of-truth atomically. The `.peaks-tmp` file
- * is cleaned up in a finally block on partial failure.
- */
-export declare function writeSourceOfTruth(projectRoot: string, config: ScopeConfig): Promise<string>;
-/**
- * Write a generic JSON document atomically. Used by stub adapters for
- * their `<ide>-skills.json` companion file (G3 §4.1).
- */
-export declare function writeJsonAtomic(file: string, data: unknown): Promise<void>;
-/**
- * Remove a file if it exists. Returns true if it was removed.
- */
-export declare function removeIfExists(file: string): Promise<boolean>;

package/dist/src/services/skill-scope/source-of-truth.js

@@ -1,118 +0,0 @@
-/**
- * Source-of-truth helpers for `peaks skill scope`.
- *
- * The source-of-truth file `.peaks/scope/skills.json` is the canonical
- * record of the user's scope intent. Adapters translate it to their
- * IDE-native config; the CLI always reads back from this file on `--show`.
- *
- * Atomicity: every write goes through `.peaks-tmp` first, then `rename`
- * (POSIX-atomic; on Windows `rename` is atomic for files on the same volume).
- * See tech-doc-025 §3.1.
- */
-import { existsSync } from 'node:fs';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-/** File name for the canonical source-of-truth. */
-export const SCOPE_FILE_NAME = 'skills.json';
-/** Resolve the canonical source-of-truth path for a project root. */
-export function scopeFilePath(projectRoot) {
-    return join(projectRoot, '.peaks', 'scope', SCOPE_FILE_NAME);
-}
-/** Resolve the per-IDE companion file path (kebab-case). */
-export function ideCompanionFilePath(projectRoot, ide) {
-    return join(projectRoot, '.peaks', 'scope', `${ide}-skills.json`);
-}
-/** Resolve the `.peaks/scope/` directory for a project root. */
-export function scopeDir(projectRoot) {
-    return join(projectRoot, '.peaks', 'scope');
-}
-/**
- * Read the source-of-truth scope config, or null if it does not exist.
- * Returns null on parse error too — the caller decides whether to surface.
- */
-export async function readSourceOfTruth(projectRoot) {
-    const file = scopeFilePath(projectRoot);
-    if (!existsSync(file))
-        return null;
-    try {
-        const raw = await readFile(file, 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Read the per-IDE companion file (`.peaks/scope/<ide>-skills.json`), or
- * null if it does not exist or is unparseable.
- */
-export async function readIdeCompanion(projectRoot, ide) {
-    const file = ideCompanionFilePath(projectRoot, ide);
-    if (!existsSync(file))
-        return null;
-    try {
-        const raw = await readFile(file, 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Write the canonical source-of-truth atomically. The `.peaks-tmp` file
- * is cleaned up in a finally block on partial failure.
- */
-export async function writeSourceOfTruth(projectRoot, config) {
-    const file = scopeFilePath(projectRoot);
-    await mkdir(scopeDir(projectRoot), { recursive: true });
-    const tmp = `${file}.peaks-tmp`;
-    try {
-        await writeFile(tmp, JSON.stringify(config, null, 2) + '\n', 'utf8');
-        await rename(tmp, file);
-        return file;
-    }
-    catch (error) {
-        if (existsSync(tmp)) {
-            try {
-                await rm(tmp, { force: true });
-            }
-            catch { /* best-effort */ }
-        }
-        throw error;
-    }
-}
-/**
- * Write a generic JSON document atomically. Used by stub adapters for
- * their `<ide>-skills.json` companion file (G3 §4.1).
- */
-export 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;
-    }
-}
-/**
- * Remove a file if it exists. Returns true if it was removed.
- */
-export async function removeIfExists(file) {
-    if (!existsSync(file))
-        return false;
-    try {
-        await rm(file, { force: true });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}

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

@@ -1,195 +0,0 @@
-/**
- * `peaks skill scope` — slice 025 multi-IDE skill scoping types.
- *
- * This file is the single source of truth for the `SkillScopeAdapter`
- * interface (G1). It is consumed by every per-IDE adapter (Claude Code
- * full impl, 5 stub adapters) and by the detection algorithm + CLI.
- *
- * Design notes (see tech-doc-025 §2):
- * - The interface is deliberately small: only the four operations the CLI
- *   actually needs (detect / apply / show / reset).
- * - `detect()` returns a confidence score in [0, 1] so the registry can
- *   pick the best match when several adapters are partially active.
- * - Errors are typed (NotSupportedError / ScopeApplyError), not strings.
- *   The CLI maps `ScopeApplyError.code` to exit codes (see tech-doc §6.3).
- */
-import type { IdeId } from '../ide/ide-types.js';
-/** Detection bucket for a single installed skill (G5). */
-export type SkillRelevance = 'relevant' | 'borderline' | 'irrelevant';
-/** Skill category — used for the JSON envelope's `kind` field (AC1). */
-export type SkillKind = 'peaks-family' | 'generic-ai' | 'language-specific' | 'other';
-/** Per-skill detail emitted by the detect algorithm. */
-export interface SkillScopeRecord {
-    /** Skill directory name (e.g. "peaks-rd", "tdd-guide"). */
-    readonly name: string;
-    /** Category — peaks-family, generic-ai, language-specific, other. */
-    readonly kind: SkillKind;
-    /** Detection bucket. */
-    readonly relevance: SkillRelevance;
-    /** Human-readable reasons that produced the bucket; stable for fixtures. */
-    readonly reasons: readonly string[];
-}
-/** Counts of skills per bucket, for the JSON envelope (AC1). */
-export interface SkillScopeCounts {
-    readonly relevant: number;
-    readonly borderline: number;
-    readonly irrelevant: number;
-}
-/** Project signals extracted from package.json + tsconfig + file tree (G5). */
-export interface ProjectSignals {
-    /** True when the project's root package.json exists. */
-    readonly hasPackageJson: boolean;
-    readonly isTypeScript: boolean;
-    readonly isTypeScriptESM: boolean;
-    readonly isReact: boolean;
-    readonly isVue: boolean;
-    readonly isSvelte: boolean;
-    readonly isNext: boolean;
-    readonly isNestJS: boolean;
-    readonly isExpress: boolean;
-    readonly isFastify: boolean;
-    readonly isPostgres: boolean;
-    readonly isMysql: boolean;
-    readonly isMongo: boolean;
-    readonly isRedis: boolean;
-    readonly isDocker: boolean;
-    readonly isK8s: boolean;
-    readonly isCommander: boolean;
-    readonly isCodegraph: boolean;
-    readonly isHeadroom: boolean;
-    /** True when the project is a Python project (no package.json / has pyproject). */
-    readonly isPython: boolean;
-    /** Major version of Node engine requirement, or null. */
-    readonly nodeEngineMajor: number | null;
-    /** Top file extensions under src/ (max 50, lexicographically sorted, unique). */
-    readonly topExtensions: readonly string[];
-    /** Per-extension presence flags derived from topExtensions. */
-    readonly hasFileExtension: Readonly<Record<string, boolean>>;
-    /**
-     * Per-extension fractional share (file count / total files, in [0, 1]).
-     * Slice 025 / R003.1: replaces the binary `hasFileExtension` for the
-     * keyword-matching path. A language/framework skill becomes `relevant`
-     * only when its corresponding share is >= the configured threshold
-     * (default 0.05). Extensions with 0 files are absent.
-     */
-    readonly shareByExtension: Readonly<Record<string, number>>;
-}
-/**
- * Default threshold for the share-based relevance check (R003.1).
- * Override at runtime with `PEAKS_SCOPE_THRESHOLD=0.05` (env) or
- * `--threshold 0.05` (CLI).
- */
-export declare const SCOPE_THRESHOLD_DEFAULT = 0.05;
-/**
- * Read the threshold from `PEAKS_SCOPE_THRESHOLD` env var, clamped to
- * [0, 1]. Falls back to SCOPE_THRESHOLD_DEFAULT.
- */
-export declare function readScopeThreshold(): number;
-/** The shape of the always-written source-of-truth file. */
-export interface ScopeConfig {
-    /** ISO-8601 UTC timestamp at which this scope was last applied. */
-    readonly generatedAt: string;
-    /** Detected or explicitly-selected IDE id. */
-    readonly ide: IdeId;
-    /** Strictness mode (drives borderline handling). */
-    readonly strict: boolean;
-    /** Skills the user wants available (LLM-invokable). Always includes all peaks-*. */
-    readonly allowlist: readonly string[];
-    /** Skills the user wants hidden. */
-    readonly denylist: readonly string[];
-    /** Per-skill reasons (mirrored from detect, for audit). */
-    readonly skills: readonly SkillScopeRecord[];
-    /** Project signals that drove the classification. */
-    readonly signals: ProjectSignals;
-}
-/** Returned from `applyScope`. */
-export interface ApplyResult {
-    /** Adapter id that handled the apply. */
-    readonly ide: IdeId;
-    /** Whether the apply succeeded (false = NOT_SUPPORTED or hard failure). */
-    readonly ok: boolean;
-    /** Absolute paths the adapter wrote or removed. */
-    readonly writtenFiles: readonly string[];
-    /** Whether shadow stubs were used (Claude Code fallback path). */
-    readonly usedShadowStub: boolean;
-    /** Whether the adapter returned NOT_SUPPORTED and only wrote the source-of-truth. */
-    readonly notSupported: boolean;
-    /** Peaks-* skills the adapter stripped from the denylist (G6 enforcement report). */
-    readonly strippedFromDenylist?: readonly string[];
-    /** Optional error code when ok=false. */
-    readonly error?: {
-        readonly code: string;
-        readonly message: string;
-    };
-}
-/** Returned from `showScope`. */
-export interface ShowScopeResult {
-    /** The source-of-truth config, or null if no scope has been applied. */
-    readonly source: ScopeConfig | null;
-    /** Whatever the adapter can read back from its native config. Null if not supported. */
-    readonly native: unknown;
-    /** Adapter id. */
-    readonly ide: IdeId;
-}
-/** Reset output mirrors apply but without the lists. */
-export interface ResetScopeResult {
-    readonly ide: IdeId;
-    readonly removedFiles: readonly string[];
-}
-/** Sentinel error type for stub adapters (G3). */
-export declare class NotSupportedError extends Error {
-    readonly code: "NOT_SUPPORTED";
-    readonly ide: IdeId;
-    constructor(ide: IdeId, message: string);
-}
-/** Errors emitted by adapters (validated by runtime probe in claude-code §3.4). */
-export type ScopeApplyErrorCode = 'NOT_SUPPORTED' | 'IO_ERROR' | 'MALFORMED_CONFIG' | 'WRITE_FAILED' | 'PARTIAL_FAILURE';
-export declare class ScopeApplyError extends Error {
-    readonly code: ScopeApplyErrorCode;
-    readonly ide: IdeId;
-    constructor(code: ScopeApplyErrorCode, message: string, ide: IdeId);
-}
-/** Input to `applyScope`. */
-export interface ApplyScopeInput {
-    /** Final allowlist (the CLI guarantees peaks-* is in here before calling). */
-    readonly allowlist: readonly string[];
-    /** Final denylist. */
-    readonly denylist: readonly string[];
-    /** Strictness mode. */
-    readonly strict: boolean;
-    /** Project root for resolving relative paths. */
-    readonly projectRoot: string;
-    /** Source-of-truth config that the adapter MAY re-derive fields from. */
-    readonly sourceConfig: ScopeConfig;
-    /** When true, prefer shadow-stub fallback over the native config. */
-    readonly shadowFallback: boolean;
-    /** Test seam: simulate an adapter write failure (returns the partial path written before failure). */
-    readonly simulateWriteFailure?: boolean;
-}
-/** Reset input mirrors apply but without the lists. */
-export interface ResetScopeInput {
-    readonly projectRoot: string;
-}
-/** The interface every adapter implements. */
-export interface SkillScopeAdapter {
-    /** Adapter id; matches the IdeId it pairs with. */
-    readonly ide: IdeId;
-    /** Whether this adapter supports a real (non-stub) implementation. */
-    readonly supported: boolean;
-    /** Detect this adapter's IDE is active in the given project root. Returns a confidence score in [0,1]. */
-    detect(projectRoot: string): Promise<number>;
-    /** Write the IDE-specific scope config. */
-    applyScope(input: ApplyScopeInput): Promise<ApplyResult>;
-    /** Read the current scope config. */
-    showScope(projectRoot: string): Promise<ShowScopeResult>;
-    /** Remove the IDE-specific scope config. */
-    resetScope(input: ResetScopeInput): Promise<ResetScopeResult>;
-}
-/** Helper: build a NOT_SUPPORTED ApplyResult (for stub adapters that pre-write source-of-truth). */
-export declare function makeNotSupportedResult(ide: IdeId, message: string, writtenFiles?: readonly string[]): ApplyResult;
-/** Hard-coded allowlist of peaks-* skills (G6 + generic AI-engineering skills per AC2). */
-export declare const ALWAYS_RELEVANT_SKILLS: readonly string[];
-/** Hard-coded denylist prefixes: non-TS language families (G5 §5.4). */
-export declare const NON_TS_SKILL_PREFIXES: readonly string[];
-/** File extensions the file-tree walker looks for (top-50 limit per tech-doc §5.1). */
-export declare const TRACKED_EXTENSIONS: readonly string[];

package/dist/src/services/skill-scope/types.js

@@ -1,97 +0,0 @@
-/**
- * `peaks skill scope` — slice 025 multi-IDE skill scoping types.
- *
- * This file is the single source of truth for the `SkillScopeAdapter`
- * interface (G1). It is consumed by every per-IDE adapter (Claude Code
- * full impl, 5 stub adapters) and by the detection algorithm + CLI.
- *
- * Design notes (see tech-doc-025 §2):
- * - The interface is deliberately small: only the four operations the CLI
- *   actually needs (detect / apply / show / reset).
- * - `detect()` returns a confidence score in [0, 1] so the registry can
- *   pick the best match when several adapters are partially active.
- * - Errors are typed (NotSupportedError / ScopeApplyError), not strings.
- *   The CLI maps `ScopeApplyError.code` to exit codes (see tech-doc §6.3).
- */
-/**
- * Default threshold for the share-based relevance check (R003.1).
- * Override at runtime with `PEAKS_SCOPE_THRESHOLD=0.05` (env) or
- * `--threshold 0.05` (CLI).
- */
-export const SCOPE_THRESHOLD_DEFAULT = 0.05;
-/**
- * Read the threshold from `PEAKS_SCOPE_THRESHOLD` env var, clamped to
- * [0, 1]. Falls back to SCOPE_THRESHOLD_DEFAULT.
- */
-export function readScopeThreshold() {
-    const raw = process.env['PEAKS_SCOPE_THRESHOLD'];
-    if (raw === undefined || raw === '')
-        return SCOPE_THRESHOLD_DEFAULT;
-    const parsed = Number(raw);
-    if (!Number.isFinite(parsed))
-        return SCOPE_THRESHOLD_DEFAULT;
-    if (parsed < 0)
-        return 0;
-    if (parsed > 1)
-        return 1;
-    return parsed;
-}
-/** Sentinel error type for stub adapters (G3). */
-export class NotSupportedError extends Error {
-    code = 'NOT_SUPPORTED';
-    ide;
-    constructor(ide, message) {
-        super(`${ide}: ${message}`);
-        this.name = 'NotSupportedError';
-        this.ide = ide;
-    }
-}
-export class ScopeApplyError extends Error {
-    code;
-    ide;
-    constructor(code, message, ide) {
-        super(`${ide}: ${message}`);
-        this.name = 'ScopeApplyError';
-        this.code = code;
-        this.ide = ide;
-    }
-}
-/** Helper: build a NOT_SUPPORTED ApplyResult (for stub adapters that pre-write source-of-truth). */
-export function makeNotSupportedResult(ide, message, writtenFiles = []) {
-    return {
-        ide,
-        ok: false,
-        writtenFiles: [...writtenFiles],
-        usedShadowStub: false,
-        notSupported: true,
-        error: { code: 'NOT_SUPPORTED', message },
-    };
-}
-/** Hard-coded allowlist of peaks-* skills (G6 + generic AI-engineering skills per AC2). */
-export const ALWAYS_RELEVANT_SKILLS = [
-    // peaks-* family (G6 hard constraint)
-    'peaks-rd', 'peaks-qa', 'peaks-solo', 'peaks-prd', 'peaks-sc',
-    'peaks-txt', 'peaks-sop', 'peaks-solo-resume', 'peaks-solo-status',
-    'peaks-solo-test', 'peaks-ui', 'peaks-ide',
-    // generic AI-engineering skills (per AC2)
-    'tdd-guide', 'coding-standards', 'karpathy-guidelines',
-    'continuous-learning', 'code-tour', 'agent-harness-construction',
-    'security-review', 'code-review',
-];
-/** Hard-coded denylist prefixes: non-TS language families (G5 §5.4). */
-export const NON_TS_SKILL_PREFIXES = [
-    'kotlin-', 'python-', 'java-', 'rust-', 'go-', 'ruby-',
-    'swift-', 'csharp-', 'cpp-',
-];
-/** File extensions the file-tree walker looks for (top-50 limit per tech-doc §5.1). */
-export const TRACKED_EXTENSIONS = [
-    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
-    '.swift', '.kt', '.kts', '.java', '.scala',
-    '.py', '.pyx', '.go', '.rs',
-    '.rb', '.php', '.cs', '.cpp', '.c', '.h', '.hpp',
-    '.vue', '.svelte', '.html', '.css', '.scss',
-    '.json', '.yaml', '.yml', '.toml', '.md',
-    '.sql', '.sh', '.bash', '.ps1',
-    '.dockerfile', '.dockerignore', '.lua', '.ex', '.exs', '.erl', '.hs',
-    '.dart', '.r', '.jl', '.clj',
-];