@niujiajie/freespec 0.0.0-stage → 1.15.0

package/dist/core/global-config.js

@@ -0,0 +1,182 @@
+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 = 'freespec';
+export const GLOBAL_CONFIG_FILE_NAME = 'config.json';
+export const GLOBAL_DATA_DIR_NAME = 'freespec';
+const DEFAULT_CONFIG = {
+    featureFlags: {},
+    profile: 'core',
+    delivery: 'both',
+};
+/**
+ * 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 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);
+}
+// Config paths already warned about. One command reads the config several
+// times (telemetry, the update check, the command itself); warn once.
+const warnedInvalidJsonPaths = new Set();
+/**
+ * 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);
+        // A root that is not a plain object carries no settings, and spreading it
+        // would leak its shape into the result: a string contributes numeric
+        // character keys. Answer with plain defaults, as for a file that did not
+        // parse at all. Same predicate the writers refuse to save over.
+        if (!isConfigRootObject(parsed)) {
+            return { ...DEFAULT_CONFIG };
+        }
+        // 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 && !warnedInvalidJsonPaths.has(configPath)) {
+            warnedInvalidJsonPaths.add(configPath);
+            console.error(`Warning: Invalid JSON in ${configPath}, using defaults`);
+        }
+        return { ...DEFAULT_CONFIG };
+    }
+}
+/**
+ * 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 function isConfigRootObject(parsed) {
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed);
+}
+/**
+ * The one-line, actionable refusal every global-config writer reports when it
+ * declines to overwrite a file it could not read.
+ */
+export function unreadableGlobalConfigMessage(configPath) {
+    return (`Refusing to overwrite ${configPath}: it could not be parsed, so saving would replace every setting in it. ` +
+        'Fix it with "freespec config edit", or reset it with "freespec config reset --all".');
+}
+/**
+ * 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 function isGlobalConfigUnreadable() {
+    const configPath = getGlobalConfigPath();
+    if (!fs.existsSync(configPath)) {
+        return false;
+    }
+    try {
+        return !isConfigRootObject(JSON.parse(fs.readFileSync(configPath, 'utf-8')));
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * 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 function saveGlobalConfig(config, options = {}) {
+    const configDir = getGlobalConfigDir();
+    const configPath = getGlobalConfigPath();
+    if (!options.replaceUnreadable && isGlobalConfigUnreadable()) {
+        throw new Error(unreadableGlobalConfigMessage(configPath));
+    }
+    // Create directory if it doesn't exist
+    if (!fs.existsSync(configDir)) {
+        fs.mkdirSync(configDir, { recursive: true });
+    }
+    fs.writeFileSync(configPath, serializeGlobalConfig(config), 'utf-8');
+}
+/** The bytes `saveGlobalConfig` writes, for a caller that only plans the write. */
+export function serializeGlobalConfig(config) {
+    return JSON.stringify(config, null, 2) + '\n';
+}
+//# 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 FreeSpec 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,57 @@
+/**
+ * Init Command
+ *
+ * Sets up FreeSpec with Agent Skills and /freespec:* slash commands.
+ * This is the unified setup command that replaces both the old init and experimental commands.
+ */
+type InitCommandOptions = {
+    tools?: string;
+    language?: string;
+    force?: boolean;
+    interactive?: boolean;
+    profile?: string;
+    /** Commander's --no-animation flag: false disables the welcome animation. */
+    animation?: boolean;
+};
+export declare class InitCommand {
+    private readonly toolsArg?;
+    private readonly language?;
+    private readonly force;
+    private readonly interactiveOption?;
+    private readonly profileOverride?;
+    private readonly animation;
+    constructor(options?: InitCommandOptions);
+    execute(targetPath: string): Promise<void>;
+    private validate;
+    private canPromptInteractively;
+    private resolveProfileOverride;
+    /**
+     * Resolves the workflows the effective profile installs, so onboarding output
+     * only mentions commands that will actually exist.
+     */
+    private getActiveWorkflows;
+    private getSelectedTools;
+    private resolveToolsArg;
+    private validateTools;
+    private createDirectoryStructure;
+    private writeGitkeepFiles;
+    /**
+     * Generates skill files and slash commands for each selected tool,
+     * honoring the configured delivery mode (skills, commands, or both).
+     *
+     * @param projectPath - Absolute path to the project root
+     * @param tools - Selected tools with their skill directory metadata
+     * @returns Created, refreshed, and failed tools plus removed artifact counts
+     */
+    private generateSkillsAndCommands;
+    private normalizeLanguage;
+    private languageContext;
+    private assertLanguageCanBeApplied;
+    private createConfig;
+    private displaySuccessMessage;
+    private startSpinner;
+    private removeSkillDirs;
+    private removeCommandFiles;
+}
+export {};
+//# sourceMappingURL=init.d.ts.map