@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/cli/cli-extension-loader.js

@@ -0,0 +1,245 @@
+/**
+ * CLI Extension Loader
+ *
+ * Resolves addon-contributed CLI commands via `.aiwg/cli-extensions.json`.
+ * When an addon declares `cli_commands` in its manifest, `aiwg use <addon>`
+ * registers the namespace here. The router falls through to this loader
+ * when no built-in command matches.
+ *
+ * @implements #478
+ * @architecture Addon manifests → cli-extensions.json → dynamic import → execute
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import * as ui from './ui.js';
+import { projectAiwgPath, resolveProjectAiwgDir } from '../config/project-artifacts.js';
+/**
+ * Read the cli-extensions registry from the current project
+ */
+async function readRegistry(cwd) {
+    const registryPath = projectAiwgPath(cwd, 'cli-extensions.json');
+    try {
+        const content = await fs.readFile(registryPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the cli-extensions registry to the current project
+ */
+export async function writeRegistry(cwd, registry) {
+    const dir = resolveProjectAiwgDir(cwd);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'cli-extensions.json'), JSON.stringify(registry, null, 2) + '\n');
+}
+/**
+ * Register an addon's CLI commands into the project's cli-extensions.json
+ *
+ * Called by `aiwg use <addon>` after reading the addon manifest.
+ */
+export async function registerCliCommands(cwd, namespace, description, source, subcommands) {
+    const existing = await readRegistry(cwd) ?? {};
+    existing[namespace] = { source, description, subcommands };
+    await writeRegistry(cwd, existing);
+}
+/**
+ * Try to execute an addon-contributed CLI command
+ *
+ * Returns null if the namespace is not registered (caller should show "unknown command").
+ * Returns a CliCommandResult if the namespace is found.
+ */
+export async function tryExecuteCliExtension(rawCommand, commandArgs, cwd, frameworkRoot) {
+    const registry = await readRegistry(cwd);
+    if (!registry || !registry[rawCommand]) {
+        return null;
+    }
+    const ns = registry[rawCommand];
+    const subcommand = commandArgs[0];
+    // `aiwg <addon> --help` or `aiwg <addon>` with no subcommand
+    if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+        printNamespaceHelp(rawCommand, ns);
+        return { exitCode: 0 };
+    }
+    // Look up subcommand
+    const sub = ns.subcommands[subcommand];
+    if (!sub) {
+        ui.error(`Unknown subcommand: ${rawCommand} ${subcommand}`);
+        printNamespaceHelp(rawCommand, ns);
+        return { exitCode: 1 };
+    }
+    // Resolve the mjs file path
+    const mjsPath = path.resolve(ns.source, path.basename(sub.file));
+    try {
+        await fs.access(mjsPath);
+    }
+    catch {
+        ui.error(`CLI extension file not found: ${mjsPath}`);
+        return { exitCode: 1, message: `Missing: ${mjsPath}` };
+    }
+    // Dynamic import the mjs module
+    const moduleUrl = pathToFileURL(mjsPath).href;
+    const mod = await import(moduleUrl);
+    if (typeof mod.default !== 'function') {
+        ui.error(`CLI extension ${sub.file} does not export a default function`);
+        return { exitCode: 1 };
+    }
+    // Build context
+    const ctx = {
+        cwd,
+        frameworkRoot,
+        namespace: rawCommand,
+        subcommand,
+    };
+    // Execute
+    const result = await mod.default(commandArgs.slice(1), ctx);
+    // Normalize result
+    if (typeof result === 'object' && result !== null) {
+        return {
+            exitCode: result.exitCode ?? 0,
+            message: result.message,
+        };
+    }
+    return { exitCode: 0 };
+}
+/**
+ * Hook events that should be auto-registered.
+ * FeatureComplete is excluded — it's a deliberate user action, not a background event.
+ */
+const AUTO_HOOK_EVENTS = new Set(['Stop', 'SessionStart', 'SessionEnd', 'PreToolUse', 'PostToolUse']);
+/**
+ * Migrate legacy array-shaped hooks to the object form Claude Code expects.
+ * See #107.
+ */
+function normalizeClaudeHooks(raw) {
+    if (Array.isArray(raw)) {
+        const out = {};
+        for (const m of raw) {
+            if (!m || typeof m.matcher !== 'string' || !Array.isArray(m.hooks))
+                continue;
+            if (!out[m.matcher])
+                out[m.matcher] = [];
+            out[m.matcher].push({ hooks: m.hooks });
+        }
+        return out;
+    }
+    if (raw && typeof raw === 'object')
+        return raw;
+    return {};
+}
+/**
+ * Register Claude Code hooks from addon manifest hook_event annotations.
+ *
+ * Reads .claude/settings.json, merges hook entries for subcommands that
+ * declare hook_event, and writes back. Idempotent — duplicate entries
+ * are skipped. Only registers events in AUTO_HOOK_EVENTS.
+ *
+ * Schema: writes the object-keyed form Claude Code requires (#107). If
+ * an existing settings.json has a legacy array-shaped `hooks` field, it
+ * is migrated to the object shape during this write.
+ *
+ * @implements #480
+ */
+export async function registerHooks(cwd, namespace, subcommands) {
+    const settingsPath = path.join(cwd, '.claude', 'settings.json');
+    let settings;
+    try {
+        const content = await fs.readFile(settingsPath, 'utf-8');
+        settings = JSON.parse(content);
+    }
+    catch {
+        // No settings file yet — start fresh
+        settings = {};
+    }
+    const wasLegacy = Array.isArray(settings.hooks);
+    const hooksObj = normalizeClaudeHooks(settings.hooks);
+    settings.hooks = hooksObj;
+    const registered = [];
+    for (const [name, sub] of Object.entries(subcommands)) {
+        if (!sub.hook_event || !AUTO_HOOK_EVENTS.has(sub.hook_event)) {
+            continue;
+        }
+        const command = `aiwg ${namespace} ${name}`;
+        const event = sub.hook_event;
+        if (!hooksObj[event])
+            hooksObj[event] = [];
+        const groups = hooksObj[event];
+        // Skip if any existing group already has this command
+        const exists = groups.some((g) => Array.isArray(g.hooks) && g.hooks.some((h) => h.command === command));
+        if (exists)
+            continue;
+        groups.push({ hooks: [{ type: 'command', command }] });
+        registered.push(`${event} → ${command}`);
+    }
+    // Write if we registered anything OR migrated an existing legacy field.
+    if (registered.length > 0 || wasLegacy) {
+        await fs.mkdir(path.join(cwd, '.claude'), { recursive: true });
+        await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    }
+    return registered;
+}
+/**
+ * Remove Claude Code hooks for a given namespace.
+ *
+ * Strips hook entries whose command matches `aiwg <namespace> *`.
+ * Removes empty groups. Writes back only if changes were made.
+ *
+ * Migrates legacy array-shaped `hooks` fields to object form on write
+ * (#107).
+ */
+export async function unregisterHooks(cwd, namespace) {
+    const settingsPath = path.join(cwd, '.claude', 'settings.json');
+    let settings;
+    try {
+        const content = await fs.readFile(settingsPath, 'utf-8');
+        settings = JSON.parse(content);
+    }
+    catch {
+        return 0;
+    }
+    if (!settings.hooks)
+        return 0;
+    const wasLegacy = Array.isArray(settings.hooks);
+    const hooksObj = normalizeClaudeHooks(settings.hooks);
+    settings.hooks = hooksObj;
+    const prefix = `aiwg ${namespace} `;
+    let removed = 0;
+    for (const event of Object.keys(hooksObj)) {
+        const groups = hooksObj[event];
+        for (const group of groups) {
+            const before = group.hooks.length;
+            group.hooks = group.hooks.filter((h) => !h.command.startsWith(prefix));
+            removed += before - group.hooks.length;
+        }
+        // Drop empty groups
+        hooksObj[event] = groups.filter((g) => g.hooks.length > 0);
+        // Drop the event entirely if no groups remain
+        if (hooksObj[event].length === 0)
+            delete hooksObj[event];
+    }
+    if (removed > 0 || wasLegacy) {
+        await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    }
+    return removed;
+}
+/**
+ * Print help for a CLI extension namespace
+ */
+function printNamespaceHelp(namespace, ns) {
+    ui.blank();
+    console.log(`  ${ui.bold(`aiwg ${namespace}`)} — ${ns.description}`);
+    ui.blank();
+    console.log('  Subcommands:');
+    ui.blank();
+    const entries = Object.entries(ns.subcommands);
+    const maxLen = Math.max(...entries.map(([name]) => name.length));
+    for (const [name, sub] of entries) {
+        console.log(`    ${name.padEnd(maxLen + 2)} ${sub.description}`);
+    }
+    ui.blank();
+    console.log(`  Usage: aiwg ${namespace} <subcommand> [args]`);
+    ui.blank();
+}
+//# sourceMappingURL=cli-extension-loader.js.map

package/dist/src/cli/command-log.js

@@ -0,0 +1,275 @@
+import { mkdir, readFile, rename, stat, writeFile, appendFile } from 'fs/promises';
+import { existsSync } from 'fs';
+import { createHash } from 'crypto';
+import path from 'path';
+import os from 'os';
+import { readAiwgConfig } from '../config/aiwg-config.js';
+import { PROJECT_AIWG_LOCATION_FILE, projectAiwgPath } from '../config/project-artifacts.js';
+const DEFAULT_MAX_BYTES = 1_048_576;
+const DEFAULT_REPORT_LIMIT = 20;
+export async function maybeAppendCommandLog(input) {
+    const env = input.env ?? process.env;
+    const resolved = await resolveCommandLogSettings(input.cwd, env);
+    if (!resolved.enabled || resolved.scopes.length === 0)
+        return;
+    const version = await readAiwgVersion(input.frameworkRoot);
+    const context = await resolvePathContext(input.cwd);
+    const shape = summarizeArgs(input.args);
+    for (const scope of resolved.scopes) {
+        const filePath = resolveLogPath(scope, context.projectRoot, env);
+        if (!filePath)
+            continue;
+        const event = {
+            schema_version: 1,
+            timestamp: new Date().toISOString(),
+            invocation_id: env.AIWG_INVOCATION_ID,
+            command: input.command,
+            flags: shape.flags,
+            positional_count: shape.positionalCount,
+            duration_ms: Math.max(0, Math.round(input.durationMs)),
+            exit_status: input.exitStatus,
+            aiwg_version: version,
+            provider: env.AIWG_PROVIDER || env.CLAUDE_CODE_ENTRYPOINT || undefined,
+            cwd_hash: hashPath(input.cwd),
+            scope,
+        };
+        if (context.projectRoot) {
+            event.project = {
+                root_hash: hashPath(context.projectRoot),
+                relative_path: context.relativePath,
+            };
+        }
+        await appendBoundedJsonl(filePath, event, resolved.maxBytes);
+    }
+}
+export async function readCommandLogReport(options) {
+    const env = options.env ?? process.env;
+    const context = await resolvePathContext(options.cwd);
+    const scope = options.scope ?? 'all';
+    const scopes = scope === 'all' ? ['project', 'global'] : [scope];
+    const paths = scopes
+        .map(s => resolveLogPath(s, context.projectRoot, env))
+        .filter((p) => Boolean(p));
+    const events = [];
+    for (const filePath of paths) {
+        events.push(...await readJsonlEvents(filePath));
+    }
+    events.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    const limited = events.slice(0, options.limit ?? DEFAULT_REPORT_LIMIT);
+    return {
+        events: limited,
+        summary: summarizeEvents(events),
+        paths,
+    };
+}
+export async function printCommandLogReport(options) {
+    const report = await readCommandLogReport(options);
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log('AIWG command log');
+    console.log(`Events: ${report.summary.total}`);
+    if (report.paths.length > 0) {
+        console.log(`Stores: ${report.paths.join(', ')}`);
+    }
+    const commands = Object.entries(report.summary.by_command)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10);
+    if (commands.length > 0) {
+        console.log('');
+        console.log('Top commands');
+        for (const [command, count] of commands) {
+            const failures = report.summary.failures_by_command[command] ?? 0;
+            const failureText = failures > 0 ? `, ${failures} failed` : '';
+            console.log(`  ${command}: ${count}${failureText}`);
+        }
+    }
+    if (report.events.length > 0) {
+        console.log('');
+        console.log('Recent invocations');
+        for (const event of report.events) {
+            const status = event.exit_status === 0 ? 'ok' : `exit ${event.exit_status}`;
+            const rel = event.project?.relative_path ? ` path=${event.project.relative_path}` : '';
+            console.log(`  ${event.timestamp} ${event.scope} ${event.command} ${status} ${event.duration_ms}ms${rel}`);
+        }
+    }
+}
+async function resolveCommandLogSettings(cwd, env) {
+    const envSetting = env.AIWG_COMMAND_LOG?.trim().toLowerCase();
+    const envMax = parsePositiveInt(env.AIWG_COMMAND_LOG_MAX_BYTES);
+    if (envSetting) {
+        const scopes = scopesFromString(envSetting);
+        return {
+            enabled: scopes.length > 0,
+            scopes,
+            maxBytes: envMax ?? DEFAULT_MAX_BYTES,
+        };
+    }
+    const config = await readNearestProjectConfig(cwd);
+    const commandLog = config?.command_log;
+    if (!commandLog?.enabled) {
+        return { enabled: false, scopes: [], maxBytes: envMax ?? DEFAULT_MAX_BYTES };
+    }
+    return {
+        enabled: true,
+        scopes: normalizeScopes(commandLog.scopes ?? ['project']),
+        maxBytes: commandLog.max_bytes ?? envMax ?? DEFAULT_MAX_BYTES,
+    };
+}
+function scopesFromString(value) {
+    if (['0', 'false', 'off', 'none', 'disabled'].includes(value))
+        return [];
+    if (['1', 'true', 'on', 'project'].includes(value))
+        return ['project'];
+    if (value === 'global')
+        return ['global'];
+    if (['both', 'all'].includes(value))
+        return ['project', 'global'];
+    return normalizeScopes(value.split(','));
+}
+function normalizeScopes(values) {
+    const scopes = [];
+    for (const value of values) {
+        if (value === 'project' || value === 'global')
+            scopes.push(value);
+    }
+    return [...new Set(scopes)];
+}
+async function readNearestProjectConfig(cwd) {
+    const projectRoot = await findProjectRoot(cwd);
+    if (!projectRoot)
+        return null;
+    return readAiwgConfig(projectRoot);
+}
+async function resolvePathContext(cwd) {
+    const projectRoot = await findProjectRoot(cwd);
+    if (!projectRoot)
+        return { projectRoot: null, relativePath: '(no-project)' };
+    const rel = path.relative(projectRoot, cwd);
+    return {
+        projectRoot,
+        relativePath: rel === '' ? '.' : normalizeRelativePath(rel),
+    };
+}
+async function findProjectRoot(startDir) {
+    let current = path.resolve(startDir);
+    while (current !== path.dirname(current)) {
+        if (existsSync(path.join(current, '.aiwg')) ||
+            existsSync(path.join(current, PROJECT_AIWG_LOCATION_FILE)) ||
+            existsSync(projectAiwgPath(current, 'aiwg.config'))) {
+            return current;
+        }
+        current = path.dirname(current);
+    }
+    return null;
+}
+function resolveLogPath(scope, projectRoot, env) {
+    if (scope === 'project') {
+        if (!projectRoot)
+            return null;
+        return projectAiwgPath(projectRoot, 'telemetry', 'cli-commands.jsonl');
+    }
+    const stateHome = env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
+    return path.join(stateHome, 'aiwg', 'cli-commands.jsonl');
+}
+async function appendBoundedJsonl(filePath, event, maxBytes) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await rotateIfNeeded(filePath, maxBytes);
+    await appendFile(filePath, JSON.stringify(event) + '\n', 'utf8');
+}
+async function rotateIfNeeded(filePath, maxBytes) {
+    if (maxBytes <= 0)
+        return;
+    try {
+        const current = await stat(filePath);
+        if (current.size <= maxBytes)
+            return;
+        const rotated = `${filePath}.1`;
+        if (existsSync(rotated)) {
+            await writeFile(rotated, '', 'utf8');
+        }
+        await rename(filePath, rotated);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+async function readJsonlEvents(filePath) {
+    try {
+        const raw = await readFile(filePath, 'utf8');
+        return raw
+            .split('\n')
+            .map(line => line.trim())
+            .filter(Boolean)
+            .map(line => JSON.parse(line));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+function summarizeEvents(events) {
+    const by_command = {};
+    const failures_by_command = {};
+    const by_scope = {};
+    for (const event of events) {
+        by_command[event.command] = (by_command[event.command] ?? 0) + 1;
+        by_scope[event.scope] = (by_scope[event.scope] ?? 0) + 1;
+        if (event.exit_status !== 0) {
+            failures_by_command[event.command] = (failures_by_command[event.command] ?? 0) + 1;
+        }
+    }
+    return {
+        total: events.length,
+        by_command,
+        failures_by_command,
+        by_scope,
+    };
+}
+function summarizeArgs(args) {
+    const flags = new Set();
+    let positionalCount = 0;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--') {
+            positionalCount += Math.max(0, args.length - i - 1);
+            break;
+        }
+        if (arg.startsWith('--')) {
+            flags.add(arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg);
+            continue;
+        }
+        if (arg.startsWith('-') && arg.length > 1) {
+            flags.add(arg);
+            continue;
+        }
+        positionalCount += 1;
+    }
+    return { flags: [...flags].sort(), positionalCount };
+}
+async function readAiwgVersion(frameworkRoot) {
+    try {
+        const raw = await readFile(path.join(frameworkRoot, 'package.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        return typeof parsed.version === 'string' ? parsed.version : '(unknown)';
+    }
+    catch {
+        return '(unknown)';
+    }
+}
+function hashPath(value) {
+    return createHash('sha256').update(path.resolve(value)).digest('hex').slice(0, 16);
+}
+function normalizeRelativePath(value) {
+    return value.split(path.sep).filter(Boolean).join('/');
+}
+function parsePositiveInt(value) {
+    if (!value)
+        return undefined;
+    const n = Number(value);
+    return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+//# sourceMappingURL=command-log.js.map