synarcx 0.1.0

package/dist/core/completions/templates/zsh-templates.js

@@ -0,0 +1,45 @@
+/**
+ * Static template strings for Zsh completion scripts.
+ * These are Zsh-specific helper functions that never change.
+ */
+export const ZSH_DYNAMIC_HELPERS = `# Dynamic completion helpers
+
+# Use synarcx __complete to get available changes
+_synarcx_complete_changes() {
+  local -a changes
+  while IFS=$'\\t' read -r id desc; do
+    changes+=("$id:$desc")
+  done < <(synarcx __complete changes 2>/dev/null)
+  _describe "change" changes
+}
+
+# Use synarcx __complete to get available specs
+_synarcx_complete_specs() {
+  local -a specs
+  while IFS=$'\\t' read -r id desc; do
+    specs+=("$id:$desc")
+  done < <(synarcx __complete specs 2>/dev/null)
+  _describe "spec" specs
+}
+
+# Get both changes and specs
+_synarcx_complete_items() {
+  local -a items
+  while IFS=$'\\t' read -r id desc; do
+    items+=("$id:$desc")
+  done < <(synarcx __complete changes 2>/dev/null)
+  while IFS=$'\\t' read -r id desc; do
+    items+=("$id:$desc")
+  done < <(synarcx __complete specs 2>/dev/null)
+  _describe "item" items
+}
+
+# Use synarcx __complete to get available schemas
+_synarcx_complete_schemas() {
+  local -a schemas
+  while IFS=$'\\t' read -r id desc; do
+    schemas+=("$id:$desc")
+  done < <(synarcx __complete schemas 2>/dev/null)
+  _describe "schema" schemas
+}`;
+//# sourceMappingURL=zsh-templates.js.map

package/dist/core/completions/types.d.ts

@@ -0,0 +1,101 @@
+import { SupportedShell } from '../../utils/shell-detection.js';
+/**
+ * Definition of a command-line flag/option
+ */
+export interface FlagDefinition {
+    /**
+     * Flag name without dashes (e.g., "json", "strict", "no-interactive")
+     */
+    name: string;
+    /**
+     * Short flag name without dash (e.g., "y" for "-y")
+     */
+    short?: string;
+    /**
+     * Human-readable description of what the flag does
+     */
+    description: string;
+    /**
+     * Whether the flag takes an argument value
+     */
+    takesValue?: boolean;
+    /**
+     * Possible values for the flag (for completion suggestions)
+     */
+    values?: string[];
+}
+export type PositionalType = 'change-id' | 'spec-id' | 'change-or-spec-id' | 'path' | 'shell' | 'schema-name';
+/**
+ * Definition of a positional argument.
+ */
+export interface PositionalDefinition {
+    /**
+     * Positional name used in generated shell metadata.
+     */
+    name: string;
+    /**
+     * Type of positional argument for dynamic completion.
+     */
+    type?: PositionalType;
+    /**
+     * Whether this positional is optional in the CLI syntax.
+     */
+    optional?: boolean;
+}
+/**
+ * Definition of a CLI command
+ */
+export interface CommandDefinition {
+    /**
+     * Command name (e.g., "init", "validate", "show")
+     */
+    name: string;
+    /**
+     * Human-readable description of the command
+     */
+    description: string;
+    /**
+     * Flags/options supported by this command
+     */
+    flags: FlagDefinition[];
+    /**
+     * Subcommands (e.g., "change show", "spec validate")
+     */
+    subcommands?: CommandDefinition[];
+    /**
+     * Whether this command accepts a positional argument (e.g., item name, path)
+     */
+    acceptsPositional?: boolean;
+    /**
+     * Type of positional argument for dynamic completion
+     * - 'change-id': Complete with active change IDs
+     * - 'spec-id': Complete with spec IDs
+     * - 'change-or-spec-id': Complete with both changes and specs
+     * - 'path': Complete with file paths
+     * - 'shell': Complete with supported shell names
+     * - 'schema-name': Complete with available schema names
+     * - undefined: No specific completion
+     */
+    positionalType?: PositionalType;
+    /**
+     * Ordered positional arguments when a command accepts more than one.
+     */
+    positionals?: PositionalDefinition[];
+}
+/**
+ * Interface for shell-specific completion script generators
+ */
+export interface CompletionGenerator {
+    /**
+     * The shell type this generator targets
+     */
+    readonly shell: SupportedShell;
+    /**
+     * Generate the completion script content
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns The shell-specific completion script as a string
+     */
+    generate(commands: CommandDefinition[]): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/completions/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,9 @@
+import type { ProjectConfig } from './project-config.js';
+/**
+ * Serialize config to YAML string with helpful comments.
+ *
+ * @param config - Partial config object (schema required, context/rules optional)
+ * @returns YAML string ready to write to file
+ */
+export declare function serializeConfig(config: Partial<ProjectConfig>): string;
+//# sourceMappingURL=config-prompts.d.ts.map

package/dist/core/config-prompts.js

@@ -0,0 +1,34 @@
+/**
+ * Serialize config to YAML string with helpful comments.
+ *
+ * @param config - Partial config object (schema required, context/rules optional)
+ * @returns YAML string ready to write to file
+ */
+export function serializeConfig(config) {
+    const lines = [];
+    // Schema (required)
+    lines.push(`schema: ${config.schema}`);
+    lines.push('');
+    // Context section with comments
+    lines.push('# Project context (optional)');
+    lines.push('# This is shown to AI when creating artifacts.');
+    lines.push('# Add your tech stack, conventions, style guides, domain knowledge, etc.');
+    lines.push('# Example:');
+    lines.push('#   context: |');
+    lines.push('#     Tech stack: TypeScript, React, Node.js');
+    lines.push('#     We use conventional commits');
+    lines.push('#     Domain: e-commerce platform');
+    lines.push('');
+    // Rules section with comments
+    lines.push('# Per-artifact rules (optional)');
+    lines.push('# Add custom rules for specific artifacts.');
+    lines.push('# Example:');
+    lines.push('#   rules:');
+    lines.push('#     proposal:');
+    lines.push('#       - Keep proposals under 500 words');
+    lines.push('#       - Always include a "Non-goals" section');
+    lines.push('#     tasks:');
+    lines.push('#       - Break tasks into chunks of max 2 hours');
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=config-prompts.js.map

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

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * Zod schema for global synarcx configuration.
+ * Uses passthrough() to preserve unknown fields for forward compatibility.
+ */
+export declare const GlobalConfigSchema: z.ZodObject<{
+    featureFlags: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>>;
+    profile: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        core: "core";
+        custom: "custom";
+    }>>>;
+    delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        commands: "commands";
+        skills: "skills";
+        both: "both";
+    }>>>;
+    workflows: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type GlobalConfigType = z.infer<typeof GlobalConfigSchema>;
+/**
+ * Default configuration values.
+ */
+export declare const DEFAULT_CONFIG: GlobalConfigType;
+/**
+ * Validate a config key path for CLI set operations.
+ * Unknown top-level keys are rejected unless explicitly allowed by the caller.
+ */
+export declare function validateConfigKeyPath(path: string): {
+    valid: boolean;
+    reason?: string;
+};
+/**
+ * Get a nested value from an object using dot notation.
+ *
+ * @param obj - The object to access
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns The value at the path, or undefined if not found
+ */
+export declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;
+/**
+ * Set a nested value in an object using dot notation.
+ * Creates intermediate objects as needed.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @param value - The value to set
+ */
+export declare function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * Delete a nested value from an object using dot notation.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns true if the key existed and was deleted, false otherwise
+ */
+export declare function deleteNestedValue(obj: Record<string, unknown>, path: string): boolean;
+/**
+ * Coerce a string value to its appropriate type.
+ * - "true" / "false" -> boolean
+ * - Numeric strings -> number
+ * - Everything else -> string
+ *
+ * @param value - The string value to coerce
+ * @param forceString - If true, always return the value as a string
+ * @returns The coerced value
+ */
+export declare function coerceValue(value: string, forceString?: boolean): string | number | boolean;
+/**
+ * Format a value for YAML-like display.
+ *
+ * @param value - The value to format
+ * @param indent - Current indentation level
+ * @returns Formatted string
+ */
+export declare function formatValueYaml(value: unknown, indent?: number): string;
+/**
+ * Validate a configuration object against the schema.
+ *
+ * @param config - The configuration to validate
+ * @returns Validation result with success status and optional error message
+ */
+export declare function validateConfig(config: unknown): {
+    success: boolean;
+    error?: string;
+};
+//# sourceMappingURL=config-schema.d.ts.map

package/dist/core/config-schema.js

@@ -0,0 +1,213 @@
+import { z } from 'zod';
+/**
+ * Zod schema for global synarcx configuration.
+ * Uses passthrough() to preserve unknown fields for forward compatibility.
+ */
+export const GlobalConfigSchema = z
+    .object({
+    featureFlags: z
+        .record(z.string(), z.boolean())
+        .optional()
+        .default({}),
+    profile: z
+        .enum(['core', 'custom'])
+        .optional()
+        .default('core'),
+    delivery: z
+        .enum(['both', 'skills', 'commands'])
+        .optional()
+        .default('both'),
+    workflows: z
+        .array(z.string())
+        .optional(),
+})
+    .passthrough();
+/**
+ * Default configuration values.
+ */
+export const DEFAULT_CONFIG = {
+    featureFlags: {},
+    profile: 'core',
+    delivery: 'both',
+};
+const KNOWN_TOP_LEVEL_KEYS = new Set([...Object.keys(DEFAULT_CONFIG), 'workflows']);
+/**
+ * Validate a config key path for CLI set operations.
+ * Unknown top-level keys are rejected unless explicitly allowed by the caller.
+ */
+export function validateConfigKeyPath(path) {
+    const rawKeys = path.split('.');
+    if (rawKeys.length === 0 || rawKeys.some((key) => key.trim() === '')) {
+        return { valid: false, reason: 'Key path must not be empty' };
+    }
+    const rootKey = rawKeys[0];
+    if (!KNOWN_TOP_LEVEL_KEYS.has(rootKey)) {
+        return { valid: false, reason: `Unknown top-level key "${rootKey}"` };
+    }
+    if (rootKey === 'featureFlags') {
+        if (rawKeys.length > 2) {
+            return { valid: false, reason: 'featureFlags values are booleans and do not support nested keys' };
+        }
+        return { valid: true };
+    }
+    if (rawKeys.length > 1) {
+        return { valid: false, reason: `"${rootKey}" does not support nested keys` };
+    }
+    return { valid: true };
+}
+/**
+ * Get a nested value from an object using dot notation.
+ *
+ * @param obj - The object to access
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns The value at the path, or undefined if not found
+ */
+export function getNestedValue(obj, path) {
+    const keys = path.split('.');
+    let current = obj;
+    for (const key of keys) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[key];
+    }
+    return current;
+}
+/**
+ * Set a nested value in an object using dot notation.
+ * Creates intermediate objects as needed.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @param value - The value to set
+ */
+export function setNestedValue(obj, path, value) {
+    const keys = path.split('.');
+    let current = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (current[key] === undefined || current[key] === null || typeof current[key] !== 'object') {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    const lastKey = keys[keys.length - 1];
+    current[lastKey] = value;
+}
+/**
+ * Delete a nested value from an object using dot notation.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns true if the key existed and was deleted, false otherwise
+ */
+export function deleteNestedValue(obj, path) {
+    const keys = path.split('.');
+    let current = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        if (current[key] === undefined || current[key] === null || typeof current[key] !== 'object') {
+            return false;
+        }
+        current = current[key];
+    }
+    const lastKey = keys[keys.length - 1];
+    if (lastKey in current) {
+        delete current[lastKey];
+        return true;
+    }
+    return false;
+}
+/**
+ * Coerce a string value to its appropriate type.
+ * - "true" / "false" -> boolean
+ * - Numeric strings -> number
+ * - Everything else -> string
+ *
+ * @param value - The string value to coerce
+ * @param forceString - If true, always return the value as a string
+ * @returns The coerced value
+ */
+export function coerceValue(value, forceString = false) {
+    if (forceString) {
+        return value;
+    }
+    // Boolean coercion
+    if (value === 'true') {
+        return true;
+    }
+    if (value === 'false') {
+        return false;
+    }
+    // Number coercion - must be a valid finite number
+    const num = Number(value);
+    if (!isNaN(num) && isFinite(num) && value.trim() !== '') {
+        return num;
+    }
+    return value;
+}
+/**
+ * Format a value for YAML-like display.
+ *
+ * @param value - The value to format
+ * @param indent - Current indentation level
+ * @returns Formatted string
+ */
+export function formatValueYaml(value, indent = 0) {
+    const indentStr = '  '.repeat(indent);
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    if (typeof value === 'boolean' || typeof value === 'number') {
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            return '[]';
+        }
+        return value.map((item) => `${indentStr}- ${formatValueYaml(item, indent + 1)}`).join('\n');
+    }
+    if (typeof value === 'object') {
+        const entries = Object.entries(value);
+        if (entries.length === 0) {
+            return '{}';
+        }
+        return entries
+            .map(([key, val]) => {
+            const formattedVal = formatValueYaml(val, indent + 1);
+            if (typeof val === 'object' && val !== null && Object.keys(val).length > 0) {
+                return `${indentStr}${key}:\n${formattedVal}`;
+            }
+            return `${indentStr}${key}: ${formattedVal}`;
+        })
+            .join('\n');
+    }
+    return String(value);
+}
+/**
+ * Validate a configuration object against the schema.
+ *
+ * @param config - The configuration to validate
+ * @returns Validation result with success status and optional error message
+ */
+export function validateConfig(config) {
+    try {
+        GlobalConfigSchema.parse(config);
+        return { success: true };
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const zodError = error;
+            const messages = zodError.issues.map((e) => `${e.path.join('.')}: ${e.message}`);
+            return { success: false, error: messages.join('; ') };
+        }
+        return { success: false, error: 'Unknown validation error' };
+    }
+}
+//# sourceMappingURL=config-schema.js.map

package/dist/core/config.d.ts

@@ -0,0 +1,19 @@
+export declare const SYNSPEC_DIR_NAME = "synspec";
+export declare const SYNSPEC_MARKERS: {
+    start: string;
+    end: string;
+};
+export interface SynspecConfig {
+    aiTools: string[];
+}
+export interface AIToolOption {
+    name: string;
+    value: string;
+    available: boolean;
+    successLabel?: string;
+    skillsDir?: string;
+    detectionPaths?: string[];
+    hasCommands?: boolean;
+}
+export declare const AI_TOOLS: AIToolOption[];
+//# sourceMappingURL=config.d.ts.map

package/dist/core/config.js

@@ -0,0 +1,38 @@
+export const SYNSPEC_DIR_NAME = 'synspec';
+export const SYNSPEC_MARKERS = {
+    start: '<!-- SYNSPEC:START -->',
+    end: '<!-- SYNSPEC:END -->'
+};
+export const AI_TOOLS = [
+    { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq' },
+    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent' },
+    { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
+    { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob' },
+    { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude', hasCommands: true },
+    { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline' },
+    { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.codex' },
+    { name: 'ForgeCode', value: 'forgecode', available: true, successLabel: 'ForgeCode', skillsDir: '.forge' },
+    { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy' },
+    { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue' },
+    { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec' },
+    { name: 'Crush', value: 'crush', available: true, successLabel: 'Crush', skillsDir: '.crush' },
+    { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor' },
+    { 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'] },
+    { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow' },
+    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie' },
+    { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode' },
+    { name: 'Kimi CLI', value: 'kimi', available: true, successLabel: 'Kimi CLI', skillsDir: '.kimi' },
+    { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro' },
+    { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode', skillsDir: '.opencode', hasCommands: true },
+    { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },
+    { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder' },
+    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma' },
+    { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen' },
+    { name: 'RooCode', value: 'roocode', available: true, successLabel: 'RooCode', skillsDir: '.roo' },
+    { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae' },
+    { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf', skillsDir: '.windsurf' },
+    { name: 'AGENTS.md (works with Amp, VS Code, …)', value: 'agents', available: false, successLabel: 'your AGENTS.md-compatible assistant' }
+];
+//# sourceMappingURL=config.js.map

package/dist/core/converters/json-converter.d.ts

@@ -0,0 +1,6 @@
+export declare class JsonConverter {
+    convertSpecToJson(filePath: string): string;
+    convertChangeToJson(filePath: string): Promise<string>;
+    private extractNameFromPath;
+}
+//# sourceMappingURL=json-converter.d.ts.map

package/dist/core/converters/json-converter.js

@@ -0,0 +1,51 @@
+import { readFileSync } from 'fs';
+import path from 'path';
+import { MarkdownParser } from '../parsers/markdown-parser.js';
+import { ChangeParser } from '../parsers/change-parser.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+export class JsonConverter {
+    convertSpecToJson(filePath) {
+        const content = readFileSync(filePath, 'utf-8');
+        const parser = new MarkdownParser(content);
+        const specName = this.extractNameFromPath(filePath);
+        const spec = parser.parseSpec(specName);
+        const jsonSpec = {
+            ...spec,
+            metadata: {
+                ...spec.metadata,
+                sourcePath: filePath,
+            },
+        };
+        return JSON.stringify(jsonSpec, null, 2);
+    }
+    async convertChangeToJson(filePath) {
+        const content = readFileSync(filePath, 'utf-8');
+        const changeName = this.extractNameFromPath(filePath);
+        const changeDir = path.dirname(filePath);
+        const parser = new ChangeParser(content, changeDir);
+        const change = await parser.parseChangeWithDeltas(changeName);
+        const jsonChange = {
+            ...change,
+            metadata: {
+                ...change.metadata,
+                sourcePath: filePath,
+            },
+        };
+        return JSON.stringify(jsonChange, null, 2);
+    }
+    extractNameFromPath(filePath) {
+        const normalizedPath = FileSystemUtils.toPosixPath(filePath);
+        const parts = normalizedPath.split('/');
+        for (let i = parts.length - 1; i >= 0; i--) {
+            if (parts[i] === 'specs' || parts[i] === 'changes') {
+                if (i < parts.length - 1) {
+                    return parts[i + 1];
+                }
+            }
+        }
+        const fileName = parts[parts.length - 1] ?? '';
+        const dotIndex = fileName.lastIndexOf('.');
+        return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
+    }
+}
+//# sourceMappingURL=json-converter.js.map

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

@@ -0,0 +1,49 @@
+export declare const GLOBAL_CONFIG_DIR_NAME = "synarcx";
+export declare const GLOBAL_CONFIG_FILE_NAME = "config.json";
+export declare const GLOBAL_DATA_DIR_NAME = "synarcx";
+export type Profile = 'core' | 'custom';
+export type Delivery = 'both' | 'skills' | 'commands';
+export interface GlobalConfig {
+    featureFlags?: Record<string, boolean>;
+    profile?: Profile;
+    delivery?: Delivery;
+    workflows?: string[];
+}
+/**
+ * Gets the global configuration directory path following XDG Base Directory Specification.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/synarcx/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/synarcx/
+ * - Windows fallback: %APPDATA%/synarcx/
+ */
+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/synarcx/ if XDG_DATA_HOME is set
+ * - Unix/macOS fallback: ~/.local/share/synarcx/
+ * - Windows fallback: %LOCALAPPDATA%/synarcx/
+ */
+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;
+/**
+ * Saves the global configuration to disk.
+ * Creates the config directory if it doesn't exist.
+ */
+export declare function saveGlobalConfig(config: GlobalConfig): void;
+//# sourceMappingURL=global-config.d.ts.map