peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/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-loop 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/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/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/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/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/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-loop 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;

package/dist/services/config/config-safety.js

@@ -0,0 +1,359 @@
+import { closeSync, constants, existsSync, fchmodSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { homedir } from 'node:os';
+export function getUserConfigPath() {
+    return resolve(homedir(), '.peaks', 'config.json');
+}
+export function isInsidePath(childPath, parentPath) {
+    const relativePath = relative(parentPath, childPath);
+    return relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath));
+}
+function isSafeProjectConfigMarker(projectRoot) {
+    const peaksPath = resolve(projectRoot, '.peaks');
+    const markerPath = resolve(peaksPath, 'config.json');
+    try {
+        const projectRootReal = realpathSync(projectRoot);
+        const peaksStats = lstatSync(peaksPath);
+        const peaksReal = realpathSync(peaksPath);
+        const markerStats = lstatSync(markerPath);
+        if (!peaksStats.isDirectory() || peaksStats.isSymbolicLink())
+            return false;
+        if (!markerStats.isFile() || markerStats.isSymbolicLink() || markerStats.nlink !== 1)
+            return false;
+        const markerReal = realpathSync(markerPath);
+        if (!isInsidePath(peaksReal, projectRootReal))
+            return false;
+        if (!isInsidePath(markerReal, projectRootReal))
+            return false;
+        return isInsidePath(markerReal, peaksReal);
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeBoundaryPath(path) {
+    const resolved = resolve(path);
+    let realPath = resolved;
+    try {
+        realPath = existsSync(resolved) ? realpathSync.native(resolved) : resolved;
+    }
+    catch {
+        realPath = resolved;
+    }
+    return process.platform === 'win32' || process.platform === 'darwin' ? realPath.toLowerCase() : realPath;
+}
+function getHomeBoundaryPaths() {
+    return new Set([homedir(), process.env.HOME, process.env.USERPROFILE].filter((path) => typeof path === 'string' && path.length > 0).map(normalizeBoundaryPath));
+}
+export function findProjectRoot(startPath) {
+    const homeBoundaryPaths = getHomeBoundaryPaths();
+    let current = resolve(startPath);
+    let parent = dirname(current);
+    let pkgRoot = null;
+    while (current !== parent && !homeBoundaryPaths.has(normalizeBoundaryPath(current))) {
+        if (existsSync(resolve(current, '.peaks', 'config.json')) && isSafeProjectConfigMarker(current)) {
+            return current;
+        }
+        // .git is the definitive project root — return immediately
+        if (existsSync(resolve(current, '.git'))) {
+            return current;
+        }
+        // package.json alone is ambiguous in monorepos — keep walking up for .git
+        if (pkgRoot === null && existsSync(resolve(current, 'package.json'))) {
+            pkgRoot = current;
+        }
+        parent = current;
+        current = dirname(parent);
+    }
+    return pkgRoot;
+}
+export function resolveProjectRootForConfig(startPath) {
+    const start = resolve(startPath);
+    const homeBoundaryPaths = getHomeBoundaryPaths();
+    let current = start;
+    let parent = dirname(current);
+    let pkgRoot = null;
+    while (current !== parent && !homeBoundaryPaths.has(normalizeBoundaryPath(current))) {
+        if (existsSync(resolve(current, '.peaks', 'config.json')) && isSafeProjectConfigMarker(current)) {
+            return current;
+        }
+        if (existsSync(resolve(current, '.git'))) {
+            return current;
+        }
+        if (pkgRoot === null && existsSync(resolve(current, 'package.json'))) {
+            pkgRoot = current;
+        }
+        parent = current;
+        current = dirname(parent);
+    }
+    return pkgRoot ?? start;
+}
+/**
+ * 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-loop 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 function resolveCanonicalProjectRoot(startPath) {
+    const start = resolve(startPath);
+    const gitRoot = resolveProjectRootFromGit(start);
+    if (gitRoot !== null) {
+        return gitRoot;
+    }
+    // Non-git fallback: walk the heuristic up to the home boundary.
+    // We do NOT call realpathSync on the heuristic result because the
+    // heuristic may legitimately return a path through a symlink that
+    // the caller passed in (no canonicalisation needed in that case).
+    const heuristicRoot = findProjectRoot(start);
+    if (heuristicRoot !== null) {
+        return heuristicRoot;
+    }
+    return start;
+}
+function resolveProjectRootFromGit(startPath) {
+    // execFileSync (not execSync) so a malicious `startPath` cannot
+    // inject argv into the spawned git invocation. The child only
+    // receives `startPath` as the cwd, never as a flag.
+    let rawRoot;
+    try {
+        const stdout = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: startPath,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        const trimmed = stdout.trim();
+        if (trimmed.length === 0)
+            return null;
+        rawRoot = resolve(trimmed);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // git not on PATH, startPath is not in a repo, or some other
+        // benign failure — fall through to the heuristic.
+        return null;
+    }
+    // On macOS, /tmp is a symlink to /private/tmp; git returns the
+    // realpath. If the caller passed a path through the symlink, the
+    // two strings won't match byte-for-byte even though they refer
+    // to the same directory. realpathSync the git root and the
+    // startPath through the same lens so callers get a canonical
+    // answer that compares equal to the path they passed in.
+    try {
+        return realpathSync(rawRoot);
+    }
+    catch {
+        return rawRoot;
+    }
+}
+export function getProjectConfigPath(projectRoot) {
+    if (!projectRoot)
+        return null;
+    if (!isSafeProjectConfigMarker(projectRoot))
+        return null;
+    return resolve(projectRoot, '.peaks', 'config.json');
+}
+export function getProjectBootstrapConfigPath(projectRoot) {
+    const projectRootPath = resolve(projectRoot);
+    const peaksPath = resolve(projectRootPath, '.peaks');
+    const configPath = resolve(peaksPath, 'config.json');
+    if (!isInsidePath(configPath, projectRootPath)) {
+        throw new Error('Project config path must stay inside the project root');
+    }
+    if (!existsSync(peaksPath)) {
+        mkdirSync(peaksPath, { recursive: true });
+    }
+    validateProjectBootstrapConfigPath(projectRootPath, peaksPath, configPath);
+    return configPath;
+}
+function validateProjectBootstrapConfigPath(projectRootPath, peaksPath, configPath) {
+    const projectRootReal = realpathSync(projectRootPath);
+    const peaksStats = lstatSync(peaksPath);
+    const peaksReal = realpathSync(peaksPath);
+    if (!peaksStats.isDirectory() || peaksStats.isSymbolicLink() || peaksReal !== resolve(projectRootReal, '.peaks')) {
+        throw new Error('Project config path must stay inside the project root');
+    }
+    try {
+        const markerStats = lstatSync(configPath);
+        if (!markerStats.isFile() || markerStats.isSymbolicLink()) {
+            throw new Error('Project config path must stay inside the project root');
+        }
+        if (markerStats.nlink !== 1) {
+            throw new Error('Config path must not be hardlinked');
+        }
+        const markerReal = realpathSync(configPath);
+        if (!isInsidePath(markerReal, projectRootReal) || !isInsidePath(markerReal, peaksReal)) {
+            throw new Error('Project config path must stay inside the project root');
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+export function validateProjectBootstrapConfigPathForWrite(projectRoot, configPath) {
+    const projectRootPath = resolve(projectRoot);
+    validateProjectBootstrapConfigPath(projectRootPath, resolve(projectRootPath, '.peaks'), configPath);
+}
+export function validateUserConfigPathForWrite(configPath) {
+    const userRoot = resolve(homedir());
+    const peaksPath = resolve(userRoot, '.peaks');
+    const userRootReal = realpathSync(userRoot);
+    const peaksStats = lstatSync(peaksPath);
+    const peaksReal = realpathSync(peaksPath);
+    if (!peaksStats.isDirectory() || peaksStats.isSymbolicLink() || peaksReal !== resolve(userRootReal, '.peaks')) {
+        throw new Error('User config path must stay inside the user root');
+    }
+    try {
+        const markerStats = lstatSync(configPath);
+        if (!markerStats.isFile() || markerStats.isSymbolicLink()) {
+            throw new Error('User config path must stay inside the user root');
+        }
+        if (markerStats.nlink !== 1) {
+            throw new Error('Config path must not be hardlinked');
+        }
+        const markerReal = realpathSync(configPath);
+        if (!isInsidePath(markerReal, userRootReal) || !isInsidePath(markerReal, peaksReal)) {
+            throw new Error('User config path must stay inside the user root');
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+export function validateArtifactWorkspaceRoot(artifactRoot, _workspaceRoot) {
+    const artifactStats = lstatSync(artifactRoot);
+    if (!artifactStats.isDirectory() || artifactStats.isSymbolicLink()) {
+        throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+    }
+}
+export function validateArtifactWorkspaceMarkerPath(artifactRoot, peaksPath, markerPath) {
+    const artifactStats = lstatSync(artifactRoot);
+    if (!artifactStats.isDirectory() || artifactStats.isSymbolicLink()) {
+        throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+    }
+    const artifactRootReal = realpathSync(artifactRoot);
+    const peaksStats = lstatSync(peaksPath);
+    const peaksReal = realpathSync(peaksPath);
+    if (!peaksStats.isDirectory() || peaksStats.isSymbolicLink() || peaksReal !== resolve(artifactRootReal, '.peaks')) {
+        throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+    }
+    try {
+        const markerStats = lstatSync(markerPath);
+        if (!markerStats.isFile() || markerStats.isSymbolicLink()) {
+            throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+        }
+        if (markerStats.nlink !== 1) {
+            throw new Error('Config path must not be hardlinked');
+        }
+        const markerReal = realpathSync(markerPath);
+        if (!isInsidePath(markerReal, artifactRootReal) || !isInsidePath(markerReal, peaksReal)) {
+            throw new Error('Artifact workspace marker must stay inside the artifact workspace');
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+function validateOpenConfigFile(fd, tempPath, errorMessage) {
+    const fdStats = fstatSync(fd);
+    const pathStats = lstatSync(tempPath);
+    if (!fdStats.isFile() || !pathStats.isFile() || fdStats.dev !== pathStats.dev || fdStats.ino !== pathStats.ino) {
+        throw new Error(errorMessage);
+    }
+    if (fdStats.nlink !== 1 || pathStats.nlink !== 1) {
+        throw new Error('Config path must not be hardlinked');
+    }
+}
+function getSafeTempOpenFlags() {
+    const baseFlags = constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL;
+    return typeof constants.O_NOFOLLOW === 'number' ? baseFlags | constants.O_NOFOLLOW : baseFlags;
+}
+function getSafeReadOpenFlags() {
+    return typeof constants.O_NOFOLLOW === 'number' ? constants.O_RDONLY | constants.O_NOFOLLOW : constants.O_RDONLY;
+}
+export function readConfigFileSafely(configPath, errorMessage) {
+    const fd = openSync(configPath, getSafeReadOpenFlags());
+    try {
+        validateOpenConfigFile(fd, configPath, errorMessage);
+        return readFileSync(fd, 'utf-8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function writeConfigFileSafely(configPath, content, validateBeforeWrite, errorMessage) {
+    validateBeforeWrite();
+    const tempPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+    let fd = openSync(tempPath, getSafeTempOpenFlags(), 0o600);
+    let renamed = false;
+    let closeError;
+    try {
+        validateOpenConfigFile(fd, tempPath, errorMessage);
+        fchmodSync(fd, 0o600);
+        writeFileSync(fd, content, 'utf-8');
+        const writeFd = fd;
+        fd = null;
+        closeSync(writeFd);
+        validateBeforeWrite();
+        const readFd = openSync(tempPath, getSafeReadOpenFlags());
+        try {
+            validateOpenConfigFile(readFd, tempPath, errorMessage);
+        }
+        finally {
+            closeSync(readFd);
+        }
+        renameSync(tempPath, configPath);
+        renamed = true;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch (error) {
+                closeError = error;
+            }
+        }
+        try {
+            if (!renamed && existsSync(tempPath)) {
+                unlinkSync(tempPath);
+            }
+        }
+        finally {
+            if (closeError) {
+                throw closeError;
+            }
+        }
+    }
+}
+export function writeProjectConfigFile(projectRoot, configPath, content) {
+    writeConfigFileSafely(configPath, content, () => validateProjectBootstrapConfigPathForWrite(projectRoot, configPath), 'Project config path must stay inside the project root');
+}
+export function writeUserConfigFile(configPath, content) {
+    writeConfigFileSafely(configPath, content, () => validateUserConfigPathForWrite(configPath), 'User config path must stay inside the user root');
+}