@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/config/gitignore.js

@@ -0,0 +1,156 @@
+/**
+ * Gitignore Helper
+ *
+ * Shared module for checking and updating .gitignore files with recommended
+ * AIWG runtime and provider directory patterns.
+ *
+ * @implements #553
+ * @module src/config/gitignore
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+// ===========================
+// Recommended Patterns
+// ===========================
+/**
+ * AIWG runtime subdirectories that should be gitignored.
+ * NOTE: .aiwg/ itself is intentionally NOT included — it contains
+ * project artifacts (requirements, architecture, etc.) that should be versioned.
+ * Only the high-churn runtime subdirectories are ignored.
+ */
+export const AIWG_RUNTIME_PATTERNS = [
+    '.aiwg/working/',
+    // .aiwg/.index/ is the artifact graph index (JSON nodes/edges + checksum
+    // manifest). It is a pure build artifact, fully regenerable from corpus
+    // content via `aiwg index build --all`, so it is ignored rather than committed.
+    '.aiwg/.index/',
+    '.aiwg/ralph/',
+    '.aiwg/ralph-external/',
+    '.aiwg/security-engineering/reviews/disclosures/',
+];
+/**
+ * Provider conventional directories for non-native deployments.
+ * These are generated by `aiwg use` and should not be version-controlled.
+ * Claude Code native dirs (.claude/agents/, .claude/skills/, etc.) are intentionally
+ * excluded from this list — they are authored artifacts worth versioning.
+ */
+export const PROVIDER_CONVENTIONAL_PATTERNS = [
+    '.codex/',
+    '.cursor/agents/',
+    '.cursor/commands/',
+    '.cursor/skills/',
+    '.factory/skills/',
+    '.factory/rules/',
+    '.warp/',
+    '.windsurf/agents/',
+    '.windsurf/skills/',
+    '.windsurf/rules/',
+];
+/**
+ * Claude Code session state patterns (machine-local, should not be versioned).
+ */
+export const CLAUDE_SESSION_PATTERNS = [
+    '.claude/settings.local.json',
+];
+/** All recommended patterns combined */
+export const ALL_RECOMMENDED_PATTERNS = [
+    ...AIWG_RUNTIME_PATTERNS,
+    ...CLAUDE_SESSION_PATTERNS,
+    ...PROVIDER_CONVENTIONAL_PATTERNS,
+];
+// ===========================
+// Core Functions
+// ===========================
+/**
+ * Check which recommended patterns are missing from the project's .gitignore.
+ */
+export async function checkGitignore(projectRoot) {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    let content = '';
+    let exists = false;
+    try {
+        content = await fs.readFile(gitignorePath, 'utf-8');
+        exists = true;
+    }
+    catch {
+        // File doesn't exist — all patterns are missing
+    }
+    const lines = content.split('\n').map(l => l.trim());
+    const isCovered = (pattern) => {
+        // Exact match
+        if (lines.includes(pattern))
+            return true;
+        // Pattern without trailing slash is also sufficient
+        if (lines.includes(pattern.replace(/\/$/, '')))
+            return true;
+        // Parent directory is ignored (covers all children)
+        const parts = pattern.split('/').filter(Boolean);
+        for (let i = 1; i < parts.length; i++) {
+            const parent = parts.slice(0, i).join('/') + '/';
+            if (lines.includes(parent) || lines.includes(parent.replace(/\/$/, ''))) {
+                return true;
+            }
+        }
+        return false;
+    };
+    const missingRuntime = AIWG_RUNTIME_PATTERNS.filter(p => !isCovered(p));
+    const missingSession = CLAUDE_SESSION_PATTERNS.filter(p => !isCovered(p));
+    const missingProvider = PROVIDER_CONVENTIONAL_PATTERNS.filter(p => !isCovered(p));
+    const missing = [...missingRuntime, ...missingSession, ...missingProvider];
+    return { exists, missing, missingRuntime, missingSession, missingProvider };
+}
+/**
+ * Append missing patterns to .gitignore, creating the file if it doesn't exist.
+ * Patterns are grouped with comments.
+ */
+export async function appendGitignore(projectRoot, patterns) {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    let existing = '';
+    let fileExists = false;
+    try {
+        existing = await fs.readFile(gitignorePath, 'utf-8');
+        fileExists = true;
+    }
+    catch {
+        // File doesn't exist, will create
+    }
+    const existingLines = existing.split('\n').map(l => l.trim());
+    const toAdd = [];
+    const alreadyPresent = [];
+    for (const pattern of patterns) {
+        if (existingLines.includes(pattern) || existingLines.includes(pattern.replace(/\/$/, ''))) {
+            alreadyPresent.push(pattern);
+        }
+        else {
+            toAdd.push(pattern);
+        }
+    }
+    if (toAdd.length > 0) {
+        const runtimeToAdd = toAdd.filter(p => AIWG_RUNTIME_PATTERNS.includes(p));
+        const sessionToAdd = toAdd.filter(p => CLAUDE_SESSION_PATTERNS.includes(p));
+        const providerToAdd = toAdd.filter(p => PROVIDER_CONVENTIONAL_PATTERNS.includes(p));
+        let block = '';
+        if (runtimeToAdd.length > 0) {
+            block += '\n# AIWG — ignore only high-churn runtime subdirs, NOT .aiwg/ itself\n';
+            block += runtimeToAdd.join('\n') + '\n';
+        }
+        if (sessionToAdd.length > 0) {
+            block += '\n# Claude Code local session state\n';
+            block += sessionToAdd.join('\n') + '\n';
+        }
+        if (providerToAdd.length > 0) {
+            block += '\n# Agentic provider conventional dirs (generated by aiwg use, not authored)\n';
+            block += providerToAdd.join('\n') + '\n';
+        }
+        const newContent = existing.endsWith('\n') || existing === ''
+            ? existing + block
+            : existing + '\n' + block;
+        await fs.writeFile(gitignorePath, newContent, 'utf-8');
+    }
+    return {
+        added: toAdd,
+        alreadyPresent,
+        created: !fileExists && toAdd.length > 0,
+    };
+}
+//# sourceMappingURL=gitignore.js.map

package/dist/src/config/project-artifacts.js

@@ -0,0 +1,76 @@
+/**
+ * Project AIWG artifact directory resolution.
+ *
+ * The public contract has long documented `AIWG_ARTIFACTS_PATH` as the
+ * override for the project-local `.aiwg/` artifact root. Keep that contract
+ * centralized so callers do not hardcode `<project>/.aiwg`.
+ */
+import { homedir } from 'os';
+import { existsSync, readFileSync } from 'fs';
+import { isAbsolute, join, resolve } from 'path';
+export const DEFAULT_PROJECT_AIWG_DIR = '.aiwg';
+export const AIWG_ARTIFACTS_PATH_ENV = 'AIWG_ARTIFACTS_PATH';
+export const PROJECT_AIWG_LOCATION_FILE = '.aiwg-location';
+const ARTIFACT_PATH_ENV_ALIASES = [
+    AIWG_ARTIFACTS_PATH_ENV,
+    'AIWG_PROJECT_ARTIFACTS_PATH',
+    'AIWG_PROJECT_AIWG_DIR',
+];
+export function expandProjectArtifactPath(pathValue, projectDir) {
+    const trimmed = pathValue.trim();
+    if (trimmed === '~')
+        return homedir();
+    if (trimmed.startsWith('~/'))
+        return resolve(homedir(), trimmed.slice(2));
+    if (isAbsolute(trimmed))
+        return trimmed;
+    return resolve(projectDir, trimmed);
+}
+export function parseProjectArtifactLocation(contents) {
+    for (const rawLine of contents.split(/\r?\n/)) {
+        let line = rawLine.trim();
+        if (line.length === 0 || line.startsWith('#'))
+            continue;
+        if (line.startsWith('export '))
+            line = line.slice('export '.length).trim();
+        const assignment = line.match(/^AIWG_ARTIFACTS_PATH\s*=\s*(.+)$/);
+        if (assignment)
+            line = assignment[1].trim();
+        if ((line.startsWith('"') && line.endsWith('"')) ||
+            (line.startsWith("'") && line.endsWith("'"))) {
+            line = line.slice(1, -1);
+        }
+        return line.length > 0 ? line : null;
+    }
+    return null;
+}
+export function readProjectArtifactLocation(projectDir) {
+    const pointerPath = resolve(projectDir, PROJECT_AIWG_LOCATION_FILE);
+    if (!existsSync(pointerPath))
+        return null;
+    return parseProjectArtifactLocation(readFileSync(pointerPath, 'utf-8'));
+}
+/**
+ * Resolve the directory that contains AIWG project artifacts.
+ *
+ * Defaults to `<projectDir>/.aiwg`. When `AIWG_ARTIFACTS_PATH` is set, the
+ * override may be absolute, project-relative, or `~/`-relative. The override
+ * intentionally points at the artifact directory itself, not its parent, so
+ * callers can rename `.aiwg` or place it outside the checkout.
+ */
+export function resolveProjectAiwgDir(projectDir, env = process.env) {
+    for (const key of ARTIFACT_PATH_ENV_ALIASES) {
+        const value = env[key];
+        if (typeof value === 'string' && value.trim().length > 0) {
+            return expandProjectArtifactPath(value, projectDir);
+        }
+    }
+    const configuredLocation = readProjectArtifactLocation(projectDir);
+    if (configuredLocation)
+        return expandProjectArtifactPath(configuredLocation, projectDir);
+    return resolve(projectDir, DEFAULT_PROJECT_AIWG_DIR);
+}
+export function projectAiwgPath(projectDir, ...segments) {
+    return join(resolveProjectAiwgDir(projectDir), ...segments);
+}
+//# sourceMappingURL=project-artifacts.js.map

package/dist/src/config/user-config.js

@@ -0,0 +1,428 @@
+/**
+ * User-Level Configuration Manager
+ *
+ * Manages the ~/.aiwg/ (or ~/.config/aiwg/) user configuration directory.
+ * Provides get/set/list/validate/reset/path operations for all config files.
+ *
+ * Resolution order:
+ *   1. AIWG_CONFIG env var (explicit override)
+ *   2. --config-dir CLI flag (explicit override)
+ *   3. ~/.aiwg (primary — simple, discoverable)
+ *   4. ~/.config/aiwg (fallback — XDG-compliant)
+ *
+ * New config files are created in whichever path already exists,
+ * defaulting to ~/.aiwg if neither exists.
+ *
+ * @implements #545
+ */
+import { readFile, writeFile, mkdir, access } from 'fs/promises';
+import { resolve } from 'path';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+/**
+ * Known config files in the user config directory
+ */
+export const KNOWN_CONFIG_FILES = [
+    { filename: 'config.yaml', description: 'Global AIWG user preferences' },
+    { filename: 'models.json', description: 'Model tier and provider overrides' },
+    { filename: 'ops.json', description: 'Ops workspace registry' },
+    { filename: 'mcp-servers.json', description: 'MCP server registry (single source of truth)' },
+    { filename: 'packages.yaml', description: 'Installed remote packages (aiwg install)' },
+];
+/**
+ * Default user config values
+ */
+export const DEFAULT_USER_CONFIG = {
+    apiVersion: 'aiwg.io/v1',
+    kind: 'UserConfig',
+    defaults: {
+        provider: 'claude',
+        verbosity: 'normal',
+    },
+    telemetry: {
+        enabled: false,
+    },
+    updates: {
+        channel: 'stable',
+        checkOnStartup: true,
+    },
+    community: {
+        nudges: true,
+    },
+};
+/**
+ * Resolve the active user config directory
+ *
+ * Resolution order:
+ *   1. Explicit override (AIWG_CONFIG env or --config-dir)
+ *   2. ~/.aiwg (primary)
+ *   3. ~/.config/aiwg (fallback)
+ *   4. ~/.aiwg (default if neither exists)
+ */
+export function resolveConfigDir(overridePath) {
+    // 1. Explicit override from env or CLI flag
+    const envOverride = process.env.AIWG_CONFIG;
+    if (overridePath) {
+        return resolve(overridePath);
+    }
+    if (envOverride) {
+        return resolve(envOverride);
+    }
+    // 2. Check primary path: ~/.aiwg
+    const primaryPath = resolve(homedir(), '.aiwg');
+    if (existsSync(primaryPath)) {
+        return primaryPath;
+    }
+    // 3. Check fallback path: ~/.config/aiwg
+    const fallbackPath = resolve(homedir(), '.config/aiwg');
+    if (existsSync(fallbackPath)) {
+        return fallbackPath;
+    }
+    // 4. Default to primary if neither exists
+    return primaryPath;
+}
+/**
+ * User-level configuration manager
+ */
+export class UserConfig {
+    configDir;
+    configCache = null;
+    constructor(overridePath) {
+        this.configDir = resolveConfigDir(overridePath);
+    }
+    /**
+     * Get the resolved config directory path
+     */
+    getPath() {
+        return this.configDir;
+    }
+    /**
+     * Ensure the config directory exists
+     */
+    async ensureDir() {
+        await mkdir(this.configDir, { recursive: true });
+    }
+    /**
+     * Get a config value by dot-notation key
+     *
+     * Supports keys like:
+     *   - "defaults.provider"
+     *   - "telemetry.enabled"
+     *   - "updates.channel"
+     */
+    async get(key) {
+        const config = await this.loadConfig();
+        return getNestedValue(config, key);
+    }
+    /**
+     * Set a config value by dot-notation key
+     */
+    async set(key, value) {
+        const config = await this.loadConfig();
+        const parsed = parseValue(value);
+        setNestedValue(config, key, parsed);
+        await this.saveConfig(config);
+        this.configCache = config;
+    }
+    /**
+     * List all config values (merged view across all files)
+     */
+    async list() {
+        const result = {};
+        // Load config.yaml (or defaults)
+        const config = await this.loadConfig();
+        result['config.yaml'] = config;
+        // Check for other known files
+        for (const spec of KNOWN_CONFIG_FILES) {
+            if (spec.filename === 'config.yaml')
+                continue;
+            const filePath = resolve(this.configDir, spec.filename);
+            try {
+                await access(filePath);
+                const content = await readFile(filePath, 'utf-8');
+                if (spec.filename.endsWith('.json')) {
+                    result[spec.filename] = JSON.parse(content);
+                }
+                else {
+                    result[spec.filename] = content;
+                }
+            }
+            catch {
+                // File doesn't exist, skip
+            }
+        }
+        return result;
+    }
+    /**
+     * Validate all config files
+     *
+     * Returns array of validation issues (empty = all valid)
+     */
+    async validate() {
+        const issues = [];
+        // Check config directory exists
+        if (!existsSync(this.configDir)) {
+            issues.push({
+                file: this.configDir,
+                severity: 'info',
+                message: 'Config directory does not exist (will be created on first use)',
+            });
+            return issues;
+        }
+        // Validate config.yaml
+        const configPath = resolve(this.configDir, 'config.yaml');
+        if (existsSync(configPath)) {
+            try {
+                const content = await readFile(configPath, 'utf-8');
+                const parsed = parseYamlSimple(content);
+                if (!parsed.apiVersion) {
+                    issues.push({
+                        file: 'config.yaml',
+                        severity: 'warning',
+                        message: 'Missing apiVersion field',
+                    });
+                }
+                if (!parsed.kind) {
+                    issues.push({
+                        file: 'config.yaml',
+                        severity: 'warning',
+                        message: 'Missing kind field',
+                    });
+                }
+            }
+            catch (err) {
+                issues.push({
+                    file: 'config.yaml',
+                    severity: 'error',
+                    message: `Failed to parse: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+        // Validate models.json
+        const modelsPath = resolve(this.configDir, 'models.json');
+        if (existsSync(modelsPath)) {
+            try {
+                const content = await readFile(modelsPath, 'utf-8');
+                JSON.parse(content);
+            }
+            catch (err) {
+                issues.push({
+                    file: 'models.json',
+                    severity: 'error',
+                    message: `Invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+        // Validate ops.json if present
+        const opsPath = resolve(this.configDir, 'ops.json');
+        if (existsSync(opsPath)) {
+            try {
+                const content = await readFile(opsPath, 'utf-8');
+                const parsed = JSON.parse(content);
+                if (parsed.apiVersion && parsed.apiVersion !== 'aiwg.io/v1') {
+                    issues.push({
+                        file: 'ops.json',
+                        severity: 'warning',
+                        message: `Unknown apiVersion: ${parsed.apiVersion}`,
+                    });
+                }
+            }
+            catch (err) {
+                issues.push({
+                    file: 'ops.json',
+                    severity: 'error',
+                    message: `Failed to parse: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+        return issues;
+    }
+    /**
+     * Reset a key to its default value, or reset all config
+     */
+    async reset(key) {
+        if (!key) {
+            // Reset entire config to defaults
+            await this.saveConfig({ ...DEFAULT_USER_CONFIG });
+            this.configCache = null;
+            return;
+        }
+        // Reset specific key
+        const config = await this.loadConfig();
+        const defaultValue = getNestedValue(DEFAULT_USER_CONFIG, key);
+        if (defaultValue !== undefined) {
+            setNestedValue(config, key, defaultValue);
+            await this.saveConfig(config);
+            this.configCache = config;
+        }
+    }
+    /**
+     * Load config.yaml, creating defaults if it doesn't exist
+     */
+    async loadConfig() {
+        if (this.configCache) {
+            return this.configCache;
+        }
+        const configPath = resolve(this.configDir, 'config.yaml');
+        try {
+            const content = await readFile(configPath, 'utf-8');
+            const parsed = parseYamlSimple(content);
+            this.configCache = {
+                ...DEFAULT_USER_CONFIG,
+                ...parsed,
+                defaults: { ...DEFAULT_USER_CONFIG.defaults, ...parsed.defaults },
+                telemetry: { ...DEFAULT_USER_CONFIG.telemetry, ...parsed.telemetry },
+                updates: { ...DEFAULT_USER_CONFIG.updates, ...parsed.updates },
+                community: { ...DEFAULT_USER_CONFIG.community, ...parsed.community },
+            };
+            return this.configCache;
+        }
+        catch {
+            // File doesn't exist — return defaults (don't create file yet)
+            this.configCache = {
+                ...DEFAULT_USER_CONFIG,
+                defaults: { ...DEFAULT_USER_CONFIG.defaults },
+                telemetry: { ...DEFAULT_USER_CONFIG.telemetry },
+                updates: { ...DEFAULT_USER_CONFIG.updates },
+                community: { ...DEFAULT_USER_CONFIG.community },
+            };
+            return this.configCache;
+        }
+    }
+    /**
+     * Save config.yaml
+     */
+    async saveConfig(config) {
+        await this.ensureDir();
+        const configPath = resolve(this.configDir, 'config.yaml');
+        const yaml = serializeYamlSimple(config);
+        await writeFile(configPath, yaml, 'utf-8');
+    }
+}
+// ============================================
+// Simple YAML helpers (no dependency needed for flat configs)
+// ============================================
+/**
+ * Minimal YAML parser for flat/nested config files.
+ * Handles the subset we use: scalars, nested objects (2 levels).
+ * For complex YAML, users should use a full parser.
+ */
+export function parseYamlSimple(content) {
+    const result = {};
+    let currentSection = null;
+    for (const line of content.split('\n')) {
+        // Skip comments and empty lines
+        if (line.trim().startsWith('#') || line.trim() === '')
+            continue;
+        const indent = line.length - line.trimStart().length;
+        const trimmed = line.trim();
+        // Key: value pair
+        const match = trimmed.match(/^([^:]+):\s*(.*)$/);
+        if (!match)
+            continue;
+        const key = match[1].trim();
+        const rawValue = match[2].trim();
+        if (indent === 0) {
+            if (rawValue === '' || rawValue === undefined) {
+                // Section header
+                currentSection = key;
+                if (!(key in result)) {
+                    result[key] = {};
+                }
+            }
+            else {
+                // Top-level key-value
+                currentSection = null;
+                result[key] = parseScalar(rawValue);
+            }
+        }
+        else if (currentSection && indent >= 2) {
+            // Nested key under current section
+            const section = result[currentSection];
+            section[key] = parseScalar(rawValue);
+        }
+    }
+    return result;
+}
+function parseScalar(value) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (value === 'null' || value === '~')
+        return null;
+    if (/^-?\d+$/.test(value))
+        return parseInt(value, 10);
+    if (/^-?\d+\.\d+$/.test(value))
+        return parseFloat(value);
+    // Strip quotes
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Minimal YAML serializer for our config format
+ */
+export function serializeYamlSimple(obj, indent = 0) {
+    const lines = [];
+    const pad = ' '.repeat(indent);
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined) {
+            lines.push(`${pad}${key}:`);
+        }
+        else if (typeof value === 'object' && !Array.isArray(value)) {
+            lines.push(`${pad}${key}:`);
+            lines.push(serializeYamlSimple(value, indent + 2));
+        }
+        else if (typeof value === 'string') {
+            // Quote strings that could be misinterpreted
+            const needsQuote = /[:#{}[\],&*?|>!%@`]/.test(value) || value === '';
+            lines.push(`${pad}${key}: ${needsQuote ? `"${value}"` : value}`);
+        }
+        else {
+            lines.push(`${pad}${key}: ${String(value)}`);
+        }
+    }
+    return lines.join('\n');
+}
+// ============================================
+// Dot-notation helpers
+// ============================================
+function getNestedValue(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+function setNestedValue(obj, path, value) {
+    const parts = path.split('.');
+    let current = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+function parseValue(value) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    if (value === 'null')
+        return null;
+    if (/^-?\d+$/.test(value))
+        return parseInt(value, 10);
+    if (/^-?\d+\.\d+$/.test(value))
+        return parseFloat(value);
+    return value;
+}
+//# sourceMappingURL=user-config.js.map