@kbdavis07/openspec 1.5.0-nov.1

package/dist/core/file-state.js

@@ -0,0 +1,112 @@
+import * as nodeFs from 'node:fs';
+import * as path from 'node:path';
+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 STALE_LOCK_THRESHOLD_MS = 30_000;
+const LOCK_DEADLINE_MS = 5000;
+const LOCK_POLL_MS = 25;
+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, 'utf-8');
+        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 {
+            return await fs.open(lockPath, 'wx');
+        }
+        catch (error) {
+            if (!isNodeErrorCode(error, 'EEXIST')) {
+                // A permission or filesystem problem, not contention - say so.
+                throw errorFor('create-failed', { lockPath, cause: error });
+            }
+            // A crashed process leaves the lock behind forever; state-file
+            // writes are sub-second, so an old lock is an orphan - steal it.
+            let staleStolen = false;
+            try {
+                const lockStat = await fs.stat(lockPath);
+                if (Date.now() - lockStat.mtimeMs > STALE_LOCK_THRESHOLD_MS) {
+                    await fs.rm(lockPath, { force: true });
+                    staleStolen = true;
+                }
+            }
+            catch {
+                // The holder released between open and stat - retry, but stay
+                // bounded: a persistently failing stat (EPERM, delete-pending)
+                // must hit the deadline instead of spinning forever.
+            }
+            if (!staleStolen) {
+                if (Date.now() >= deadline) {
+                    throw errorFor('timeout', { lockPath });
+                }
+                await sleep(LOCK_POLL_MS);
+            }
+        }
+    }
+}
+export async function releaseFileLock(lock, lockPath) {
+    await lock.close().catch(() => undefined);
+    await fs.rm(lockPath, { force: true }).catch(() => undefined);
+}
+//# sourceMappingURL=file-state.js.map

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

@@ -0,0 +1,51 @@
+export declare const GLOBAL_CONFIG_DIR_NAME = "openspec";
+export declare const GLOBAL_CONFIG_FILE_NAME = "config.json";
+export declare const GLOBAL_DATA_DIR_NAME = "openspec";
+export type Profile = 'core' | 'custom';
+export type Delivery = 'both' | 'skills' | 'commands';
+export interface GlobalConfig {
+    featureFlags?: Record<string, boolean>;
+    profile?: Profile;
+    delivery?: Delivery;
+    workflows?: string[];
+    /** Workset opener rows (slice 7.1); hand-edited, validated on use. */
+    openers?: unknown;
+}
+/**
+ * Gets the global configuration directory path following XDG Base Directory Specification.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/openspec/
+ * - Windows fallback: %APPDATA%/openspec/
+ */
+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/openspec/ if XDG_DATA_HOME is set
+ * - Unix/macOS fallback: ~/.local/share/openspec/
+ * - Windows fallback: %LOCALAPPDATA%/openspec/
+ */
+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

package/dist/core/global-config.js

@@ -0,0 +1,124 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+// Constants
+export const GLOBAL_CONFIG_DIR_NAME = 'openspec';
+export const GLOBAL_CONFIG_FILE_NAME = 'config.json';
+export const GLOBAL_DATA_DIR_NAME = 'openspec';
+const DEFAULT_CONFIG = {
+    featureFlags: {},
+    profile: 'core',
+    delivery: 'both',
+};
+/**
+ * Gets the global configuration directory path following XDG Base Directory Specification.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/openspec/
+ * - Windows fallback: %APPDATA%/openspec/
+ */
+export function getGlobalConfigDir() {
+    // XDG_CONFIG_HOME takes precedence on all platforms when explicitly set
+    const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+    if (xdgConfigHome) {
+        return path.join(xdgConfigHome, GLOBAL_CONFIG_DIR_NAME);
+    }
+    const platform = os.platform();
+    if (platform === 'win32') {
+        // Windows: use %APPDATA%
+        const appData = process.env.APPDATA;
+        if (appData) {
+            return path.join(appData, GLOBAL_CONFIG_DIR_NAME);
+        }
+        // Fallback for Windows if APPDATA is not set
+        return path.join(os.homedir(), 'AppData', 'Roaming', GLOBAL_CONFIG_DIR_NAME);
+    }
+    // Unix/macOS fallback: ~/.config
+    return path.join(os.homedir(), '.config', GLOBAL_CONFIG_DIR_NAME);
+}
+function joinGlobalDataPath(platform, ...segments) {
+    return platform === 'win32'
+        ? path.win32.join(...segments)
+        : path.posix.join(...segments);
+}
+export function getGlobalDataDir(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? os.platform();
+    // XDG_DATA_HOME takes precedence on all platforms when explicitly set
+    const xdgDataHome = env.XDG_DATA_HOME;
+    if (xdgDataHome) {
+        return joinGlobalDataPath(platform, xdgDataHome, GLOBAL_DATA_DIR_NAME);
+    }
+    const homedir = options.homedir ?? os.homedir();
+    if (platform === 'win32') {
+        // Windows: use %LOCALAPPDATA%
+        const localAppData = env.LOCALAPPDATA;
+        if (localAppData) {
+            return joinGlobalDataPath(platform, localAppData, GLOBAL_DATA_DIR_NAME);
+        }
+        // Fallback for Windows if LOCALAPPDATA is not set
+        return joinGlobalDataPath(platform, homedir, 'AppData', 'Local', GLOBAL_DATA_DIR_NAME);
+    }
+    // Unix/macOS fallback: ~/.local/share
+    return joinGlobalDataPath(platform, homedir, '.local', 'share', GLOBAL_DATA_DIR_NAME);
+}
+/**
+ * Gets the path to the global config file.
+ */
+export function getGlobalConfigPath() {
+    return path.join(getGlobalConfigDir(), GLOBAL_CONFIG_FILE_NAME);
+}
+/**
+ * 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 function getGlobalConfig() {
+    const configPath = getGlobalConfigPath();
+    try {
+        if (!fs.existsSync(configPath)) {
+            return { ...DEFAULT_CONFIG };
+        }
+        const content = fs.readFileSync(configPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        // Merge with defaults (loaded values take precedence)
+        const merged = {
+            ...DEFAULT_CONFIG,
+            ...parsed,
+            // Deep merge featureFlags
+            featureFlags: {
+                ...DEFAULT_CONFIG.featureFlags,
+                ...(parsed.featureFlags || {})
+            }
+        };
+        // Schema evolution: apply defaults for new fields if not present in loaded config
+        if (parsed.profile === undefined) {
+            merged.profile = DEFAULT_CONFIG.profile;
+        }
+        if (parsed.delivery === undefined) {
+            merged.delivery = DEFAULT_CONFIG.delivery;
+        }
+        return merged;
+    }
+    catch (error) {
+        // Log warning for parse errors, but not for missing files
+        if (error instanceof SyntaxError) {
+            console.error(`Warning: Invalid JSON in ${configPath}, using defaults`);
+        }
+        return { ...DEFAULT_CONFIG };
+    }
+}
+/**
+ * Saves the global configuration to disk.
+ * Creates the config directory if it doesn't exist.
+ */
+export function saveGlobalConfig(config) {
+    const configDir = getGlobalConfigDir();
+    const configPath = getGlobalConfigPath();
+    // Create directory if it doesn't exist
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
+//# sourceMappingURL=global-config.js.map

package/dist/core/id.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The one kebab id grammar. Store ids, change ids, and legacy initiative ids
+ * all share it.
+ */
+export declare const KEBAB_ID_REGEX: RegExp;
+export declare function isKebabId(value: string): boolean;
+/** Human rendering of the grammar, shared so the wording never forks. */
+export declare const KEBAB_ID_DESCRIPTION = "must be kebab-case with lowercase letters, numbers, and single hyphen separators";
+/** The fix-line twin of KEBAB_ID_DESCRIPTION, shared for the same reason. */
+export declare const KEBAB_ID_FIX = "Use kebab-case with lowercase letters, numbers, and single hyphen separators.";
+/**
+ * The folder-safe-name grammar (store ids layer the kebab grammar on
+ * top of it; workset member labels use it alone). Returns a problem
+ * description, or null when valid.
+ */
+export declare function folderStyleNameProblem(value: string, label: string): string | null;
+//# sourceMappingURL=id.d.ts.map

package/dist/core/id.js

@@ -0,0 +1,30 @@
+/**
+ * The one kebab id grammar. Store ids, change ids, and legacy initiative ids
+ * all share it.
+ */
+export const KEBAB_ID_REGEX = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+export function isKebabId(value) {
+    return KEBAB_ID_REGEX.test(value);
+}
+/** Human rendering of the grammar, shared so the wording never forks. */
+export const KEBAB_ID_DESCRIPTION = 'must be kebab-case with lowercase letters, numbers, and single hyphen separators';
+/** The fix-line twin of KEBAB_ID_DESCRIPTION, shared for the same reason. */
+export const KEBAB_ID_FIX = 'Use kebab-case with lowercase letters, numbers, and single hyphen separators.';
+/**
+ * The folder-safe-name grammar (store ids layer the kebab grammar on
+ * top of it; workset member labels use it alone). Returns a problem
+ * description, or null when valid.
+ */
+export function folderStyleNameProblem(value, label) {
+    if (value.length === 0) {
+        return `${label} must not be empty`;
+    }
+    if (value === '.' || value === '..') {
+        return `${label} must not be '${value}'`;
+    }
+    if (/[\\/]/u.test(value)) {
+        return `${label} must not contain path separators`;
+    }
+    return null;
+}
+//# sourceMappingURL=id.js.map

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, GLOBAL_DATA_DIR_NAME, type GlobalDataDirOptions, type GlobalConfig, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, getGlobalDataDir } from './global-config.js';
+export * from './references.js';
+export * from './store/index.js';
+export * from './planning-home.js';
+export * from './openspec-root.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -0,0 +1,7 @@
+// Core OpenSpec logic will be implemented here
+export { GLOBAL_CONFIG_DIR_NAME, GLOBAL_CONFIG_FILE_NAME, GLOBAL_DATA_DIR_NAME, getGlobalConfigDir, getGlobalConfigPath, getGlobalConfig, saveGlobalConfig, getGlobalDataDir } from './global-config.js';
+export * from './references.js';
+export * from './store/index.js';
+export * from './planning-home.js';
+export * from './openspec-root.js';
+//# sourceMappingURL=index.js.map

package/dist/core/init.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Init Command
+ *
+ * Sets up OpenSpec with Agent Skills and /opsx:* slash commands.
+ * This is the unified setup command that replaces both the old init and experimental commands.
+ */
+type InitCommandOptions = {
+    tools?: string;
+    force?: boolean;
+    interactive?: boolean;
+    profile?: string;
+};
+export declare class InitCommand {
+    private readonly toolsArg?;
+    private readonly force;
+    private readonly interactiveOption?;
+    private readonly profileOverride?;
+    constructor(options?: InitCommandOptions);
+    execute(targetPath: string): Promise<void>;
+    private validate;
+    private canPromptInteractively;
+    private resolveProfileOverride;
+    private handleLegacyCleanup;
+    private performLegacyCleanup;
+    private getSelectedTools;
+    private resolveToolsArg;
+    private validateTools;
+    private createDirectoryStructure;
+    private generateSkillsAndCommands;
+    private createConfig;
+    private displaySuccessMessage;
+    private startSpinner;
+    private removeSkillDirs;
+    private removeCommandFiles;
+}
+export {};
+//# sourceMappingURL=init.d.ts.map