@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/config.d.ts

@@ -0,0 +1,50 @@
+export declare const OPENSPEC_DIR_NAME = "freespec";
+export declare const OPENSPEC_SKILL_NAMES: readonly ["freespec-新建", "freespec-深思", "freespec-需求", "freespec-设计", "freespec-任务", "freespec-审文档", "freespec-用例", "freespec-验收", "freespec-写Java", "freespec-审Java"];
+export declare const OPENSPEC_MARKERS: {
+    start: string;
+    end: string;
+};
+export interface FreeSpecConfig {
+    aiTools: string[];
+}
+export interface AIToolOption {
+    name: string;
+    value: string;
+    available: boolean;
+    successLabel?: string;
+    skillsDir?: string;
+    legacySkillsDirs?: string[];
+    globalSkillsDir?: string;
+    detectionPaths?: string[];
+    searchAliases?: string[];
+    setupNote?: string;
+    requiresIdeRestart?: boolean;
+}
+export declare const AI_TOOLS: AIToolOption[];
+/**
+ * The vendor-neutral target every assistant that is not listed above can use.
+ * Named wherever a tool lookup comes up empty, so "my tool isn't here" is never
+ * a dead end (#653).
+ */
+export declare const UNIVERSAL_TOOL_ID = "agents";
+/** The universal target's entry, or undefined if it was removed from AI_TOOLS. */
+export declare function getUniversalTool(): AIToolOption | undefined;
+/**
+ * One-line pointer at the universal target for non-interactive errors, the
+ * scripted counterpart of the picker's empty-search hint. Undefined when the
+ * target is not among the tools on offer, so the hint never names a choice the
+ * caller cannot make.
+ */
+export declare function universalToolFallbackHint(offeredToolIds: string[]): string | undefined;
+/**
+ * Retired tool ids that still resolve, so a rebrand does not break scripted
+ * `--tools` invocations. Windsurf was rebranded to Devin Desktop on
+ * 2026-06-02 and its config directory moved from `.windsurf/` to `.devin/`;
+ * `--tools windsurf` therefore configures `devin`.
+ */
+export declare const TOOL_ID_ALIASES: Record<string, string>;
+/**
+ * Resolves a tool id through TOOL_ID_ALIASES, leaving current ids untouched.
+ */
+export declare function resolveToolIdAlias(toolId: string): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.js

@@ -0,0 +1,122 @@
+export const OPENSPEC_DIR_NAME = 'freespec';
+export const OPENSPEC_SKILL_NAMES = [
+    'freespec-新建',
+    'freespec-深思',
+    'freespec-需求',
+    'freespec-设计',
+    'freespec-任务',
+    'freespec-审文档',
+    'freespec-用例',
+    'freespec-验收',
+    'freespec-写Java',
+    'freespec-审Java',
+];
+export const OPENSPEC_MARKERS = {
+    start: '<!-- FREESPEC:START -->',
+    end: '<!-- FREESPEC:END -->'
+};
+export const AI_TOOLS = [
+    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq', requiresIdeRestart: true },
+    { name: 'Amp', value: 'amp', available: true, successLabel: 'Amp', skillsDir: '.agents', detectionPaths: ['.amp', '.agents/skills'] },
+    // Antigravity moved workspace skills and workflows from `.agent` to the
+    // shared `.agents` root in v1.20.5. Detection keys off `.agent` and
+    // `.agents/workflows` rather than the bare `.agents` root: that root is
+    // shared with Codex, Zed, and the vendor-neutral target, so its presence
+    // alone says nothing about Antigravity.
+    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agents', legacySkillsDirs: ['.agent'], detectionPaths: ['.agent', '.agents/workflows'], requiresIdeRestart: true },
+    { name: 'AtomCode', value: 'atomcode', available: true, successLabel: 'AtomCode', skillsDir: '.atomcode' },
+    { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
+    { name: 'IBM Bob', value: 'bob', available: true, successLabel: 'IBM Bob', skillsDir: '.bob' },
+    { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude' },
+    { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline', requiresIdeRestart: true },
+    { name: 'Command Code', value: 'command-code', available: true, successLabel: 'Command Code', skillsDir: '.commandcode' },
+    { name: 'CodeArts', value: 'codeartsagent', available: true, successLabel: 'CodeArts', skillsDir: '.codeartsdoer' },
+    { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.agents', legacySkillsDirs: ['.codex'], detectionPaths: ['.agents/skills', '.codex/skills'] },
+    { name: 'DeepSeek Harness', value: 'dsh', available: true, successLabel: 'DeepSeek Harness', skillsDir: '.dsh' },
+    { name: 'Devin Desktop (formerly Windsurf)', value: 'devin', available: true, successLabel: 'Devin Desktop', skillsDir: '.devin', detectionPaths: ['.devin', '.windsurf'], requiresIdeRestart: true },
+    { name: 'ForgeCode', value: 'forgecode', available: true, successLabel: 'ForgeCode', skillsDir: '.forge' },
+    { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy' },
+    { name: 'Code Studio', value: 'codestudio', available: true, successLabel: 'Code Studio', skillsDir: '.codestudio', requiresIdeRestart: true },
+    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue', requiresIdeRestart: true },
+    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec', requiresIdeRestart: true },
+    { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush', skillsDir: '.crush' },
+    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor', requiresIdeRestart: true },
+    { name: 'EasyCode', value: 'easycode', available: true, successLabel: 'EasyCode', skillsDir: '.easycode' },
+    { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid', skillsDir: '.factory' },
+    { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI', skillsDir: '.gemini' },
+    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'], requiresIdeRestart: true },
+    { name: 'GigaCode', value: 'gigacode', available: true, successLabel: 'GigaCode', skillsDir: '.gigacode' },
+    { name: 'Grok Build', value: 'grok', available: true, successLabel: 'Grok Build', skillsDir: '.grok' },
+    { name: 'GSD', value: 'gsd', available: true, successLabel: 'GSD', skillsDir: '.agents', detectionPaths: ['.gsd'] },
+    { name: 'Hermes Agent', value: 'hermes', available: true, successLabel: 'Hermes Agent', skillsDir: '.hermes', detectionPaths: ['.hermes', 'HERMES.md', '.hermes.md'], setupNote: "Hermes only loads skills from ~/.hermes/skills by default. Add this project's .hermes/skills directory to skills.external_dirs in ~/.hermes/config.yaml so Hermes picks up the generated FreeSpec skills." },
+    { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow' },
+    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie', requiresIdeRestart: true },
+    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode', requiresIdeRestart: true },
+    { name: 'Kimi Code', value: 'kimi', available: true, successLabel: 'Kimi Code', skillsDir: '.kimi-code', detectionPaths: ['.kimi-code', '.kimi'] },
+    { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro', requiresIdeRestart: true },
+    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma', requiresIdeRestart: true },
+    { name: 'MiniMax Code', value: 'minimax-code', available: true, successLabel: 'MiniMax Code', globalSkillsDir: '.minimax' },
+    { name: 'Mistral Vibe', value: 'vibe', available: true, successLabel: 'Mistral Vibe', skillsDir: '.vibe' },
+    { name: 'Oh My Pi', value: 'oh-my-pi', available: true, successLabel: 'Oh My Pi', skillsDir: '.omp' },
+    { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode', skillsDir: '.opencode' },
+    { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },
+    { name: 'SourceCraft Code Assistant', value: 'codeassistant', available: true, successLabel: 'SourceCraft Code Assistant', skillsDir: '.codeassistant' },
+    { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder', requiresIdeRestart: true },
+    { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen' },
+    { name: 'Rovo Dev CLI', value: 'rovodev', available: true, successLabel: 'Rovo Dev CLI', skillsDir: '.rovodev', detectionPaths: ['.rovodev/skills', '.rovodev'] },
+    { name: 'Zoo Code', value: 'roocode', available: true, successLabel: 'Zoo Code', skillsDir: '.roo', requiresIdeRestart: true },
+    { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae', requiresIdeRestart: true },
+    { name: 'Veai', value: 'veai', available: true, successLabel: 'Veai', skillsDir: '.veai' },
+    { name: 'Warp', value: 'warp', available: true, successLabel: 'Warp', skillsDir: '.warp', detectionPaths: ['.warp', 'WARP.md'] },
+    { name: 'Zed Agent', value: 'zed', available: true, successLabel: 'Zed Agent', skillsDir: '.agents', detectionPaths: ['.zed', '.agents/skills'] },
+    { name: 'ZCode', value: 'zcode', available: true, successLabel: 'ZCode', skillsDir: '.zcode' },
+    // Vendor-neutral target for assistants that read the shared `.agents` root.
+    // Detection keys off `.agents/skills` rather than the bare root: frameworks use
+    // `.agents/` for more than skills, so the root alone says nothing about skills.
+    // A project that does keep skills there is a project this target fits, the same
+    // way `.claude/` selects Claude Code — the signal is the user's setup, not
+    // FreeSpec's own files.
+    // The picker is searchable, so this entry also answers to the words someone
+    // whose assistant is not on the list actually types (#653) — it is named for
+    // a directory, which none of them would guess. Aliases are single words: the
+    // space bar toggles a selection rather than typing into the search box.
+    { name: 'Other / Universal (shared .agents skills)', value: 'agents', available: true, successLabel: 'shared .agents skills', skillsDir: '.agents', detectionPaths: ['.agents/skills'], searchAliases: ['universal', 'other', 'generic', 'custom', 'proprietary', 'unlisted', 'unsupported', 'vendor-neutral', 'agents.md'] }
+];
+/**
+ * The vendor-neutral target every assistant that is not listed above can use.
+ * Named wherever a tool lookup comes up empty, so "my tool isn't here" is never
+ * a dead end (#653).
+ */
+export const UNIVERSAL_TOOL_ID = 'agents';
+/** The universal target's entry, or undefined if it was removed from AI_TOOLS. */
+export function getUniversalTool() {
+    return AI_TOOLS.find((tool) => tool.value === UNIVERSAL_TOOL_ID);
+}
+/**
+ * One-line pointer at the universal target for non-interactive errors, the
+ * scripted counterpart of the picker's empty-search hint. Undefined when the
+ * target is not among the tools on offer, so the hint never names a choice the
+ * caller cannot make.
+ */
+export function universalToolFallbackHint(offeredToolIds) {
+    const universal = getUniversalTool();
+    if (!universal || !offeredToolIds.includes(universal.value))
+        return undefined;
+    return `Tool not listed? Use --tools ${universal.value}: the vendor-neutral target that writes ${universal.skillsDir}/skills/ for any assistant.`;
+}
+/**
+ * Retired tool ids that still resolve, so a rebrand does not break scripted
+ * `--tools` invocations. Windsurf was rebranded to Devin Desktop on
+ * 2026-06-02 and its config directory moved from `.windsurf/` to `.devin/`;
+ * `--tools windsurf` therefore configures `devin`.
+ */
+export const TOOL_ID_ALIASES = {
+    windsurf: 'devin',
+};
+/**
+ * Resolves a tool id through TOOL_ID_ALIASES, leaving current ids untouched.
+ */
+export function resolveToolIdAlias(toolId) {
+    return TOOL_ID_ALIASES[toolId] ?? toolId;
+}
+//# sourceMappingURL=config.js.map

package/dist/core/file-state.d.ts

@@ -0,0 +1,36 @@
+import * as nodeFs from 'node:fs';
+import { StoreError } from './store/errors.js';
+/**
+ * Shared machine-local state-file mechanics (extracted from the store
+ * registry in slice 7.1, its second consumer). Callers own the
+ * diagnostic data (code, target, wording); the factory owns the
+ * shared mechanics - the fix strings describe the lock's own
+ * behavior (stale-steal, creation), so their templates live here.
+ */
+export type FileLockErrorKind = 'create-failed' | 'timeout';
+export interface FileLockErrorInfo {
+    lockPath: string;
+    /** The original errno error for 'create-failed'. */
+    cause?: unknown;
+}
+export interface FileLockOptions {
+    lockPath: string;
+    errorFor: (kind: FileLockErrorKind, info: FileLockErrorInfo) => Error;
+}
+export interface LockErrorData {
+    /** Noun phrase for the create-failed message, e.g. "the registry lock file". */
+    createSubject: string;
+    /** The full timeout message, e.g. "Store registry is busy." */
+    busyMessage: string;
+    code: string;
+    target: string;
+}
+/** One template for lock diagnostics; callers supply the data. */
+export declare function makeLockErrorFactory(data: LockErrorData): (kind: FileLockErrorKind, info: FileLockErrorInfo) => StoreError;
+export declare function isNodeErrorCode(error: unknown, code: string): boolean;
+export declare function pathIsFile(filePath: string): Promise<boolean>;
+export declare function pathIsDirectory(dirPath: string): Promise<boolean>;
+export declare function writeFileAtomically(filePath: string, content: string): Promise<void>;
+export declare function acquireFileLock(options: FileLockOptions): Promise<nodeFs.promises.FileHandle>;
+export declare function releaseFileLock(lock: nodeFs.promises.FileHandle, lockPath: string): Promise<void>;
+//# sourceMappingURL=file-state.d.ts.map

package/dist/core/file-state.js

@@ -0,0 +1,144 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { StoreError } from './store/errors.js';
+const fs = nodeFs.promises;
+/** One template for lock diagnostics; callers supply the data. */
+export function makeLockErrorFactory(data) {
+    return (kind, info) => {
+        if (kind === 'create-failed') {
+            // A permission or filesystem problem, not contention - say so.
+            return new StoreError(`Cannot create ${data.createSubject} ${info.lockPath} (${info.cause?.code ?? info.cause}).`, data.code, {
+                target: data.target,
+                fix: `Check permissions on ${path.dirname(info.lockPath)}.`,
+            });
+        }
+        return new StoreError(data.busyMessage, data.code, {
+            target: data.target,
+            fix: `Retry shortly; if this persists, delete the stale lock file ${info.lockPath}.`,
+        });
+    };
+}
+const LOCK_DEADLINE_MS = 5000;
+const LOCK_POLL_MS = 25;
+const PRIVATE_FILE_MODE = 0o600;
+const lockOwnership = new WeakMap();
+function isUnsupportedSyncError(error) {
+    return (isNodeErrorCode(error, 'EINVAL') ||
+        isNodeErrorCode(error, 'ENOTSUP') ||
+        isNodeErrorCode(error, 'ENOSYS'));
+}
+export function isNodeErrorCode(error, code) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === code);
+}
+export async function pathIsFile(filePath) {
+    try {
+        return (await fs.stat(filePath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+// Deliberately not FileSystemUtils.directoryExists: that variant
+// debug-logs non-ENOENT failures, which is noise inside prompt
+// validators, and pathIsFile has no FileSystemUtils equivalent - the
+// silent symmetric pair lives here.
+export async function pathIsDirectory(dirPath) {
+    try {
+        return (await fs.stat(dirPath)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function sleep(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+export async function writeFileAtomically(filePath, content) {
+    const dirPath = path.dirname(filePath);
+    await FileSystemUtils.createDirectory(dirPath);
+    const tempPath = path.join(dirPath, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
+    try {
+        await fs.writeFile(tempPath, content, {
+            encoding: 'utf-8',
+            mode: PRIVATE_FILE_MODE,
+        });
+        await fs.rename(tempPath, filePath);
+    }
+    catch (error) {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+export async function acquireFileLock(options) {
+    const { lockPath, errorFor } = options;
+    const lockDir = path.dirname(lockPath);
+    await FileSystemUtils.createDirectory(lockDir);
+    if (!(await FileSystemUtils.canWriteFile(lockDir))) {
+        throw errorFor('create-failed', { lockPath, cause: 'EACCES' });
+    }
+    const deadline = Date.now() + LOCK_DEADLINE_MS;
+    while (true) {
+        try {
+            const lock = await fs.open(lockPath, 'wx', PRIVATE_FILE_MODE);
+            const ownershipToken = `${process.pid}:${randomUUID()}`;
+            try {
+                await lock.writeFile(ownershipToken, 'utf-8');
+                try {
+                    await lock.sync();
+                }
+                catch (error) {
+                    // Some FUSE and network filesystems support exclusive lock files but
+                    // explicitly do not implement fsync. The token is still visible to
+                    // cooperating processes, so do not make those projects unusable.
+                    if (!isUnsupportedSyncError(error)) {
+                        throw error;
+                    }
+                }
+            }
+            catch (error) {
+                await lock.close().catch(() => undefined);
+                await fs.rm(lockPath, { force: true }).catch(() => undefined);
+                throw error;
+            }
+            lockOwnership.set(lock, ownershipToken);
+            return lock;
+        }
+        catch (error) {
+            if (!isNodeErrorCode(error, 'EEXIST')) {
+                // A permission or filesystem problem, not contention - say so.
+                throw errorFor('create-failed', { lockPath, cause: error });
+            }
+            // Never steal by age: unlinking a supposedly stale path can race with
+            // its replacement and erase a live owner's lock. The timeout diagnostic
+            // gives the user an explicit recovery path for genuinely orphaned locks.
+            if (Date.now() >= deadline) {
+                throw errorFor('timeout', { lockPath });
+            }
+            await sleep(LOCK_POLL_MS);
+        }
+    }
+}
+export async function releaseFileLock(lock, lockPath) {
+    const ownershipToken = lockOwnership.get(lock);
+    lockOwnership.delete(lock);
+    await lock.close().catch(() => undefined);
+    if (ownershipToken === undefined) {
+        return;
+    }
+    try {
+        const currentToken = await fs.readFile(lockPath, 'utf-8');
+        if (currentToken === ownershipToken) {
+            await fs.rm(lockPath, { force: true });
+        }
+    }
+    catch {
+        // The lock was already removed or replaced with an unreadable path.
+        // In either case, this owner must not remove anything else.
+    }
+}
+//# sourceMappingURL=file-state.js.map

package/dist/core/file-view.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How a check reads the files it inspects. Normally the disk. `update
+ * --dry-run` passes the tree as it has planned it, so a step that reads what
+ * an earlier step wrote sees the same thing it would in a real update.
+ */
+export interface FileView {
+    exists(filePath: string): boolean;
+    /** Throws, like `fs.readFileSync`, when the file is absent. */
+    read(filePath: string): string;
+    isDirectory(filePath: string): boolean;
+}
+export declare const DISK_VIEW: FileView;
+//# sourceMappingURL=file-view.d.ts.map

package/dist/core/file-view.js

@@ -0,0 +1,14 @@
+import * as fs from 'fs';
+export const DISK_VIEW = {
+    exists: (filePath) => fs.existsSync(filePath),
+    read: (filePath) => fs.readFileSync(filePath, 'utf-8'),
+    isDirectory: (filePath) => {
+        try {
+            return fs.statSync(filePath).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    },
+};
+//# sourceMappingURL=file-view.js.map

package/dist/core/global-config.d.ts

@@ -0,0 +1,101 @@
+export declare const GLOBAL_CONFIG_DIR_NAME = "freespec";
+export declare const GLOBAL_CONFIG_FILE_NAME = "config.json";
+export declare const GLOBAL_DATA_DIR_NAME = "freespec";
+export type Profile = 'core' | 'custom';
+export type Delivery = 'both' | 'skills' | 'commands';
+/** Telemetry section of global config (identity + opt-out). */
+export interface TelemetryConfig {
+    /** When false, telemetry is disabled. Unset means enabled (opt-out model). */
+    enabled?: boolean;
+    /** Anonymous random UUID; no relation to the user. */
+    anonymousId?: string;
+    /** Whether the first-run telemetry notice has been shown. */
+    noticeSeen?: boolean;
+}
+export interface GlobalConfig {
+    featureFlags?: Record<string, boolean>;
+    profile?: Profile;
+    delivery?: Delivery;
+    workflows?: string[];
+    /**
+     * Machine-level fallback store id, consulted during root resolution only
+     * when no --store flag, local root, or project-level store: pointer resolves.
+     */
+    defaultStore?: string;
+    /** Workset opener rows (slice 7.1); hand-edited, validated on use. */
+    openers?: unknown;
+    /** Anonymous usage analytics settings and identity. */
+    telemetry?: TelemetryConfig;
+    /** Whether the first-run shell-completions tip has been shown. */
+    completionTipSeen?: boolean;
+    /** Whether the one-time note about the standalone install has been shown. */
+    standaloneTipSeen?: boolean;
+}
+/**
+ * Gets the global configuration directory path following XDG Base Directory Specification.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/freespec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/freespec/
+ * - Windows fallback: %APPDATA%/freespec/
+ */
+export declare function getGlobalConfigDir(): string;
+/**
+ * Gets the global data directory path following XDG Base Directory Specification.
+ * Used for user data like schema overrides.
+ *
+ * - All platforms: $XDG_DATA_HOME/freespec/ if XDG_DATA_HOME is set
+ * - Unix/macOS fallback: ~/.local/share/freespec/
+ * - Windows fallback: %LOCALAPPDATA%/freespec/
+ */
+export interface GlobalDataDirOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    homedir?: string;
+}
+export declare function getGlobalDataDir(options?: GlobalDataDirOptions): string;
+/**
+ * Gets the path to the global config file.
+ */
+export declare function getGlobalConfigPath(): string;
+/**
+ * Loads the global configuration from disk.
+ * Returns default configuration if file doesn't exist or is invalid.
+ * Merges loaded config with defaults to ensure new fields are available.
+ */
+export declare function getGlobalConfig(): GlobalConfig;
+/**
+ * Whether a parsed JSON root can serve as a global config object.
+ *
+ * Valid JSON that is not a plain object (`null`, an array, a string, a number,
+ * a boolean) still reads as defaults, so it is just as unsafe to save over as
+ * a file that did not parse at all. Every reader and writer of the global
+ * config shares this one predicate so they cannot drift apart.
+ */
+export declare function isConfigRootObject(parsed: unknown): boolean;
+/**
+ * The one-line, actionable refusal every global-config writer reports when it
+ * declines to overwrite a file it could not read.
+ */
+export declare function unreadableGlobalConfigMessage(configPath: string): string;
+/**
+ * Whether the global config file exists but cannot be read or parsed.
+ *
+ * getGlobalConfig() answers with defaults for such a file so that reads keep
+ * working, but those defaults are not the user's settings: saving them back
+ * would erase everything the file holds, and the file may contain an opt-out
+ * such as `telemetry.enabled: false` that the defaults do not.
+ */
+export declare function isGlobalConfigUnreadable(): boolean;
+export interface SaveGlobalConfigOptions {
+    /** Overwrite a config file that cannot be parsed. Only a reset should. */
+    replaceUnreadable?: boolean;
+}
+/**
+ * Saves the global configuration to disk.
+ * Creates the config directory if it doesn't exist. Refuses to overwrite an
+ * existing file it cannot parse unless `replaceUnreadable` is set.
+ */
+export declare function saveGlobalConfig(config: GlobalConfig, options?: SaveGlobalConfigOptions): void;
+/** The bytes `saveGlobalConfig` writes, for a caller that only plans the write. */
+export declare function serializeGlobalConfig(config: GlobalConfig): string;
+//# sourceMappingURL=global-config.d.ts.map