peaks-loop 3.0.0

package/dist/src/services/complexity/complexity-estimator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * v2.15.0 follow-up — G10: complexity estimator.
+ *
+ * 12 Gaps memory: the G2 complexity tier drives user-attended vs overnight
+ * scheduling. This service estimates the complexity of a set of files
+ * based on LOC + a few cheap heuristics.
+ *
+ * Tier thresholds (G2 12 Gaps memory):
+ *   - trivial : ≤ 50 lines, no async, no IO
+ *   - simple  : ≤ 200 lines, ≤ 3 exports
+ *   - complex : > 200 lines, OR many exports, OR has async/await
+ *
+ * Pure function. CLI: `peaks complexity estimate --files <list>`.
+ */
+export type ComplexityTier = 'trivial' | 'simple' | 'complex';
+export interface FileComplexity {
+    readonly file: string;
+    readonly lines: number;
+    readonly exports: number;
+    readonly hasAsync: boolean;
+    readonly tier: ComplexityTier;
+}
+export interface ComplexityEstimate {
+    readonly files: readonly FileComplexity[];
+    readonly overall: ComplexityTier;
+    readonly summary: {
+        trivial: number;
+        simple: number;
+        complex: number;
+    };
+}
+export declare function estimateFileComplexity(file: string): FileComplexity | null;
+export declare function aggregateTier(tiers: readonly ComplexityTier[]): ComplexityTier;
+export declare function estimateComplexity(projectRoot: string, files: readonly string[]): ComplexityEstimate;

package/dist/src/services/complexity/complexity-estimator.js

@@ -0,0 +1,64 @@
+/**
+ * v2.15.0 follow-up — G10: complexity estimator.
+ *
+ * 12 Gaps memory: the G2 complexity tier drives user-attended vs overnight
+ * scheduling. This service estimates the complexity of a set of files
+ * based on LOC + a few cheap heuristics.
+ *
+ * Tier thresholds (G2 12 Gaps memory):
+ *   - trivial : ≤ 50 lines, no async, no IO
+ *   - simple  : ≤ 200 lines, ≤ 3 exports
+ *   - complex : > 200 lines, OR many exports, OR has async/await
+ *
+ * Pure function. CLI: `peaks complexity estimate --files <list>`.
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+function countMatches(content, regex) {
+    return (content.match(regex) ?? []).length;
+}
+export function estimateFileComplexity(file) {
+    if (!existsSync(file))
+        return null;
+    const stat = statSync(file);
+    if (!stat.isFile())
+        return null;
+    let content;
+    try {
+        content = readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        console.warn(`estimateFileComplexity: failed to read ${file}: ${err.message}`);
+        return null;
+    }
+    const lines = content.split('\n').length;
+    const exports = countMatches(content, /^export\s+/gm);
+    const hasAsync = /\basync\s+(function|\([^)]*\)\s*=>|[a-zA-Z_$][a-zA-Z0-9_$]*\s*\()/m.test(content);
+    let tier = 'trivial';
+    if (lines > 200 || exports > 10 || hasAsync)
+        tier = 'complex';
+    else if (lines > 50 || exports > 3)
+        tier = 'simple';
+    return { file, lines, exports, hasAsync, tier };
+}
+export function aggregateTier(tiers) {
+    if (tiers.some((t) => t === 'complex'))
+        return 'complex';
+    if (tiers.some((t) => t === 'simple'))
+        return 'simple';
+    return 'trivial';
+}
+export function estimateComplexity(projectRoot, files) {
+    const results = [];
+    for (const f of files) {
+        const path = resolve(projectRoot, f);
+        const c = estimateFileComplexity(path);
+        if (c !== null)
+            results.push(c);
+    }
+    const summary = { trivial: 0, simple: 0, complex: 0 };
+    for (const r of results) {
+        summary[r.tier]++;
+    }
+    return { files: results, overall: aggregateTier(results.map((r) => r.tier)), summary };
+}

package/dist/src/services/config/config-migration.d.ts

@@ -0,0 +1,45 @@
+export declare const CONFIG_SCHEMA_VERSION_V2 = "2.0.0";
+/**
+ * Slim 2.0 schema for `~/.peaks/config.json`. After migration,
+ * the only meaningful fields are `version` + `ocr.llm.*`; everything
+ * else lives in sidecar files (`providers.json`, `proxy.json`,
+ * `workspaces.json`) or per-project `preferences.json`. The type is
+ * intentionally permissive: extra keys are ignored at runtime, not
+ * rejected, so a hand-written or partially-migrated file does not
+ * fail the loader.
+ */
+export interface ConfigV2 {
+    readonly version: typeof CONFIG_SCHEMA_VERSION_V2;
+}
+export declare function isConfigV2(raw: unknown): raw is ConfigV2;
+/**
+ * Per-project fields that the 1.x → 2.0 migration moves
+ * from `~/.peaks/config.json` (global) to `<project>/.peaks/preferences.json`
+ * (per-project). Per spec §10.4 line 1215: "economyMode / swarmMode
+ * 字段从 global 迁移到当前 workspace 的 .peaks/preferences.json".
+ */
+declare const PER_PROJECT_FIELDS: readonly ["economyMode", "swarmMode"];
+type PerProjectField = (typeof PER_PROJECT_FIELDS)[number];
+export interface MigrationOptions {
+    currentProjectRoot: string;
+}
+export interface MigrationPlan {
+    alreadyAtV2: boolean;
+    detectedSchemaVersion: string | null;
+    newConfigSchemaVersion: string;
+    /** Field names that would be migrated on apply (1.x → 2.0). */
+    willMigrateFields: readonly PerProjectField[];
+}
+export interface MigrationResult extends MigrationPlan {
+    applied: boolean;
+    backupPath?: string;
+    newConfigPath?: string;
+    error?: string;
+}
+export declare function globalConfigPath(): string;
+export declare function backupConfigPath(): string;
+export declare function planMigration(opts: MigrationOptions): MigrationPlan;
+export declare function executeMigration(opts: MigrationOptions & {
+    apply: boolean;
+}): MigrationResult;
+export {};

package/dist/src/services/config/config-migration.js

@@ -0,0 +1,154 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { savePreferences } from '../preferences/preferences-service.js';
+import { providersConfigPath, proxyConfigPath, SIDECAR_SCHEMA_VERSION, workspacesConfigPath, writeSidecarJson } from './sidecar-store.js';
+export const CONFIG_SCHEMA_VERSION_V2 = '2.0.0';
+const BACKUP_NAME = 'config.json.1.x.bak';
+export function isConfigV2(raw) {
+    return (typeof raw === 'object' &&
+        raw !== null &&
+        raw.version === CONFIG_SCHEMA_VERSION_V2);
+}
+/**
+ * Per-project fields that the 1.x → 2.0 migration moves
+ * from `~/.peaks/config.json` (global) to `<project>/.peaks/preferences.json`
+ * (per-project). Per spec §10.4 line 1215: "economyMode / swarmMode
+ * 字段从 global 迁移到当前 workspace 的 .peaks/preferences.json".
+ */
+const PER_PROJECT_FIELDS = ['economyMode', 'swarmMode'];
+export function globalConfigPath() {
+    return join(homedir(), '.peaks', 'config.json');
+}
+export function backupConfigPath() {
+    return join(homedir(), '.peaks', BACKUP_NAME);
+}
+/**
+ * Inspect the on-disk 1.x config and return the subset of
+ * per-project fields that are present and would be migrated on
+ * apply. The list is used both by `planMigration` (to populate
+ * `willMigrateFields`) and by `executeMigration` (to know which
+ * fields to forward to `savePreferences`).
+ */
+function discoverMigratableFields(raw) {
+    const out = [];
+    for (const f of PER_PROJECT_FIELDS) {
+        if (typeof raw[f] === 'boolean')
+            out.push(f);
+    }
+    return out;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function planMigration(opts) {
+    const configPath = globalConfigPath();
+    let detectedSchemaVersion = null;
+    let willMigrateFields = [];
+    if (existsSync(configPath)) {
+        const raw = JSON.parse(readFileSync(configPath, 'utf8'));
+        detectedSchemaVersion = raw.version ?? null;
+        willMigrateFields = discoverMigratableFields(raw);
+    }
+    if (detectedSchemaVersion === CONFIG_SCHEMA_VERSION_V2) {
+        return {
+            alreadyAtV2: true,
+            detectedSchemaVersion,
+            newConfigSchemaVersion: CONFIG_SCHEMA_VERSION_V2,
+            willMigrateFields: [],
+        };
+    }
+    return {
+        alreadyAtV2: false,
+        detectedSchemaVersion,
+        newConfigSchemaVersion: CONFIG_SCHEMA_VERSION_V2,
+        willMigrateFields,
+    };
+}
+export function executeMigration(opts) {
+    const configPath = globalConfigPath();
+    if (!existsSync(configPath)) {
+        throw new Error('NO_CONFIG: ~/.peaks/config.json not found');
+    }
+    const plan = planMigration(opts);
+    if (plan.alreadyAtV2) {
+        return { ...plan, applied: false };
+    }
+    if (!opts.apply) {
+        return { ...plan, applied: false };
+    }
+    const original = JSON.parse(readFileSync(configPath, 'utf8'));
+    // 1. Backup
+    const bak = backupConfigPath();
+    writeFileSync(bak, JSON.stringify(original, null, 2) + '\n', 'utf8');
+    // 2. Forward per-project fields to <projectRoot>/.peaks/preferences.json
+    //    (per spec §10.4). The preferences service merges over the existing
+    //    schema-valid preferences.json; boolean fields only, with the
+    //    discoverMigratableFields() allowlist as the source of truth.
+    if (plan.willMigrateFields.length > 0) {
+        const overrides = {};
+        for (const f of plan.willMigrateFields) {
+            const v = original[f];
+            if (typeof v === 'boolean')
+                overrides[f] = v;
+        }
+        savePreferences(opts.currentProjectRoot, overrides);
+    }
+    // 2.5. Forward LIVE runtime fields to dedicated sidecar files
+    //      under ~/.peaks/. These fields are global/cross-project and
+    //      do NOT belong in per-project preferences.json. Sidecar files
+    //      are owned by their respective services (provider-service.ts,
+    //      proxy-service.ts, workspace-state-service.ts). Only write
+    //      if the legacy field is present in the on-disk file.
+    if (isPlainObject(original.providers)) {
+        const providersPath = providersConfigPath();
+        if (!existsSync(providersPath)) {
+            writeSidecarJson(providersPath, {
+                version: SIDECAR_SCHEMA_VERSION,
+                providers: original.providers
+            });
+        }
+    }
+    if (isPlainObject(original.proxy) && typeof original.proxy.httpProxy === 'string') {
+        const proxyPath = proxyConfigPath();
+        if (!existsSync(proxyPath)) {
+            writeSidecarJson(proxyPath, {
+                version: SIDECAR_SCHEMA_VERSION,
+                httpProxy: original.proxy.httpProxy
+            });
+        }
+    }
+    if (Array.isArray(original.workspaces) || typeof original.currentWorkspace === 'string') {
+        const workspacesPath = workspacesConfigPath();
+        if (!existsSync(workspacesPath)) {
+            writeSidecarJson(workspacesPath, {
+                version: SIDECAR_SCHEMA_VERSION,
+                workspaces: Array.isArray(original.workspaces) ? original.workspaces : [],
+                currentWorkspace: typeof original.currentWorkspace === 'string' ? original.currentWorkspace : null
+            });
+        }
+    }
+    // 3. Slim config.json — schema version + discoverable ocr.llm placeholders.
+    //    Per the 2.0.1 slim spec, the on-disk `~/.peaks/config.json` is
+    //    `{ "version": "2.0.1", "ocr": { "llm": { ... } } }`. Legacy fields
+    //    (language, model, economyMode, swarmMode, tokens, providers,
+    //    proxy) live in <project>/.peaks/preferences.json. peaks-cli writes
+    //    the `ocr.llm.*` placeholders so the user has a discoverable spot
+    //    to paste their endpoint; the placeholders are empty strings, not
+    //    auto-configured values, so the post-migration file MUST contain
+    //    the `ocr.llm.*` block with empty defaults.
+    mkdirSync(join(homedir(), '.peaks'), { recursive: true });
+    writeFileSync(configPath, JSON.stringify({
+        version: CONFIG_SCHEMA_VERSION_V2,
+        ocr: {
+            llm: {
+                url: '',
+                authToken: '',
+                model: '',
+                useAnthropic: false,
+                authHeader: 'authorization'
+            }
+        }
+    }, null, 2) + '\n', 'utf8');
+    return { ...plan, applied: true, backupPath: bak, newConfigPath: configPath };
+}

package/dist/src/services/config/config-restore.d.ts

@@ -0,0 +1,10 @@
+export interface RestoreResult {
+    field: string;
+    applied: boolean;
+    sidecarPath?: string;
+}
+export declare function listAvailableFields(): string[];
+export declare function restoreField(opts: {
+    field: string;
+    apply: boolean;
+}): RestoreResult;

package/dist/src/services/config/config-restore.js

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { backupConfigPath } from './config-migration.js';
+/**
+ * Spec §8.6 — restore a single archived field from `config.json.1.x.bak`.
+ * Does NOT modify `config.json` itself (which is now slim v2).
+ * Instead writes a sidecar `config.json.restore-<field>.json` so the user
+ * can review before adopting. Fields in the deferred-design set
+ * (workspaces, providers, proxy) throw RESTORE_GUARDED so the user has
+ * to acknowledge explicitly.
+ */
+const GUARDED_FIELDS = new Set(['workspaces', 'providers', 'proxy']);
+function readBakContent() {
+    const bak = backupConfigPath();
+    if (!existsSync(bak)) {
+        throw new Error('NO_BACKUP: ~/.peaks/config.json.1.x.bak not found');
+    }
+    return JSON.parse(readFileSync(bak, 'utf8'));
+}
+export function listAvailableFields() {
+    const bak = readBakContent();
+    return Object.keys(bak).filter((k) => k !== 'version');
+}
+export function restoreField(opts) {
+    const bak = readBakContent();
+    if (!(opts.field in bak)) {
+        throw new Error(`FIELD_NOT_FOUND: ${opts.field} is not in config.json.1.x.bak`);
+    }
+    if (GUARDED_FIELDS.has(opts.field)) {
+        throw new Error(`RESTORE_GUARDED: restoring "${opts.field}" is discouraged because the deferred design intentionally avoids it; add it to config.json manually if you really need it`);
+    }
+    const home = homedir();
+    const sidecar = join(home, '.peaks', `config.json.restore-${opts.field}.json`);
+    if (!opts.apply) {
+        return { field: opts.field, applied: false };
+    }
+    mkdirSync(join(home, '.peaks'), { recursive: true });
+    const payload = {
+        field: opts.field,
+        value: bak[opts.field],
+        source: 'config.json.1.x.bak',
+        restoredAt: new Date().toISOString(),
+    };
+    writeFileSync(sidecar, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+    return { field: opts.field, applied: true, sidecarPath: sidecar };
+}

package/dist/src/services/config/config-rollback.d.ts

@@ -0,0 +1,13 @@
+export interface RollbackPlan {
+    available: boolean;
+    detectedVersion: string | null;
+    backupPath: string;
+}
+export interface RollbackResult extends RollbackPlan {
+    applied: boolean;
+    restoredConfigPath?: string;
+}
+export declare function planRollback(): RollbackPlan;
+export declare function executeRollback(opts: {
+    apply: boolean;
+}): RollbackResult;

package/dist/src/services/config/config-rollback.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { backupConfigPath, globalConfigPath } from './config-migration.js';
+export function planRollback() {
+    const backup = backupConfigPath();
+    if (!existsSync(backup)) {
+        return { available: false, detectedVersion: null, backupPath: backup };
+    }
+    const raw = JSON.parse(readFileSync(backup, 'utf8'));
+    return {
+        available: true,
+        detectedVersion: raw.version ?? null,
+        backupPath: backup,
+    };
+}
+export function executeRollback(opts) {
+    const plan = planRollback();
+    if (!plan.available) {
+        throw new Error('NO_BACKUP: ~/.peaks/config.json.1.x.bak not found');
+    }
+    if (!opts.apply) {
+        return { ...plan, applied: false };
+    }
+    const restored = JSON.parse(readFileSync(plan.backupPath, 'utf8'));
+    writeFileSync(globalConfigPath(), JSON.stringify(restored, null, 2) + '\n', 'utf8');
+    return { ...plan, applied: true, restoredConfigPath: globalConfigPath() };
+}

package/dist/src/services/config/config-safety.d.ts

@@ -0,0 +1,40 @@
+export declare function getUserConfigPath(): string;
+export declare function isInsidePath(childPath: string, parentPath: string): boolean;
+export declare function findProjectRoot(startPath: string): string | null;
+export declare function resolveProjectRootForConfig(startPath: string): string;
+/**
+ * Canonicalise a user-supplied project root path against git's view of the
+ * repository root. This is the fix for the nested-directory regression
+ * where peaks-cli would write `.peaks/` under a nested sub-folder
+ * (e.g. `prompt-project/prompt-project/.peaks/`) because the LLM passed
+ * `$(pwd)` from inside a sub-directory of a real git repo. Without
+ * canonicalisation, peaks accepted the cwd as-is, built the .peaks/
+ * tree there, and left the team with two parallel state stores.
+ *
+ * Strategy:
+ *   1. If `startPath` (or any ancestor) is inside a git repo, return
+ *      `git rev-parse --show-toplevel` from `startPath`. The git root
+ *      is the *only* correct answer for "where does the .peaks/ tree
+ *      belong?" — sub-folders of a git repo are not their own projects.
+ *   2. If `startPath` is not inside a git repo, fall back to
+ *      `findProjectRoot` (the existing heuristic) so the CLI still
+ *      works for non-git projects.
+ *   3. If both fail, return `startPath` unchanged — better to write
+ *      to the cwd than to refuse the command.
+ *
+ * This is intentionally fail-open: it only *promotes* a path towards
+ * the git root, it never demotes one. A non-git user is unaffected.
+ * The function does NOT throw on a missing git binary or a non-zero
+ * `git rev-parse` exit; both fall through to the heuristic.
+ */
+export declare function resolveCanonicalProjectRoot(startPath: string): string;
+export declare function getProjectConfigPath(projectRoot: string | null): string | null;
+export declare function getProjectBootstrapConfigPath(projectRoot: string): string;
+export declare function validateProjectBootstrapConfigPathForWrite(projectRoot: string, configPath: string): void;
+export declare function validateUserConfigPathForWrite(configPath: string): void;
+export declare function validateArtifactWorkspaceRoot(artifactRoot: string, _workspaceRoot: string): void;
+export declare function validateArtifactWorkspaceMarkerPath(artifactRoot: string, peaksPath: string, markerPath: string): void;
+export declare function readConfigFileSafely(configPath: string, errorMessage: string): string;
+export declare function writeConfigFileSafely(configPath: string, content: string, validateBeforeWrite: () => void, errorMessage: string): void;
+export declare function writeProjectConfigFile(projectRoot: string, configPath: string, content: string): void;
+export declare function writeUserConfigFile(configPath: string, content: string): void;