@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/cli/skill-usage.js

@@ -0,0 +1,616 @@
+import { mkdir, readFile, rename, stat, writeFile, appendFile, readdir } 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 maybeAppendSkillUsage(input) {
+    const env = input.env ?? process.env;
+    const resolved = await resolveSkillUsageSettings(input.cwd, env);
+    if (!resolved.enabled || resolved.scopes.length === 0)
+        return;
+    const identity = classifyCliUsage(input.command, input.args);
+    const version = await readAiwgVersion(input.frameworkRoot);
+    const context = await resolvePathContext(input.cwd);
+    for (const scope of resolved.scopes) {
+        const filePath = resolveUsagePath(scope, context.projectRoot, env);
+        if (!filePath)
+            continue;
+        const event = buildUsageEvent({
+            env,
+            source: 'cli',
+            provider: env.AIWG_PROVIDER || env.CLAUDE_CODE_ENTRYPOINT || undefined,
+            artifact: {
+                kind: identity.kind,
+                id: identity.id,
+            },
+            action: identity.action,
+            outcome: input.exitStatus === 0 ? 'ok' : 'failed',
+            durationMs: Math.max(0, Math.round(input.durationMs)),
+            version,
+            cwd: input.cwd,
+            context,
+            scope,
+        });
+        await appendBoundedJsonl(filePath, event, resolved.maxBytes);
+    }
+}
+export async function ingestSkillUsageTranscript(options) {
+    const env = options.env ?? process.env;
+    const contextCwd = options.projectRoot ?? options.cwd;
+    const resolved = await resolveSkillUsageSettings(contextCwd, env);
+    if (!resolved.enabled || resolved.scopes.length === 0) {
+        return { events: [], appended: 0, skipped: 0, paths: [] };
+    }
+    const raw = await readFile(options.transcriptPath, 'utf8');
+    const lines = raw.split('\n').map(line => line.trim()).filter(Boolean);
+    const version = await readAiwgVersion(options.frameworkRoot);
+    const context = await resolvePathContext(contextCwd);
+    const extracted = [];
+    let skipped = 0;
+    for (const line of lines) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            skipped += 1;
+            continue;
+        }
+        const events = extractClaudeCodeUsage(parsed);
+        if (events.length === 0) {
+            skipped += 1;
+        }
+        else {
+            extracted.push(...events);
+        }
+    }
+    const persisted = [];
+    const paths = resolved.scopes
+        .map(scope => resolveUsagePath(scope, context.projectRoot, env))
+        .filter((p) => Boolean(p));
+    for (const scope of resolved.scopes) {
+        const filePath = resolveUsagePath(scope, context.projectRoot, env);
+        if (!filePath)
+            continue;
+        for (const item of extracted) {
+            const event = buildUsageEvent({
+                env,
+                source: 'transcript',
+                provider: normalizeProvider(options.provider),
+                artifact: item.artifact,
+                action: item.action,
+                outcome: 'unknown',
+                version,
+                cwd: context.projectRoot ?? contextCwd,
+                context,
+                scope,
+            });
+            persisted.push(event);
+            if (!options.dryRun) {
+                await appendBoundedJsonl(filePath, event, resolved.maxBytes);
+            }
+        }
+    }
+    return {
+        events: persisted,
+        appended: options.dryRun ? 0 : persisted.length,
+        skipped,
+        paths,
+    };
+}
+export async function readSkillUsageReport(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 => resolveUsagePath(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);
+    const inventory = await discoverSkillInventory(options.frameworkRoot);
+    const heatmap = buildHeatmap(events, options.now ?? new Date());
+    const coldSpots = buildColdSpots(inventory, events).slice(0, 20);
+    return {
+        events: limited,
+        summary: summarizeEvents(events),
+        heatmap,
+        cold_spots: coldSpots,
+        suggestions: buildSuggestions({
+            inventory,
+            events,
+            query: options.suggestFor,
+            limit: 5,
+        }),
+        paths,
+    };
+}
+export async function printSkillUsageReport(options) {
+    const report = await readSkillUsageReport(options);
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log('AIWG skill usage');
+    console.log(`Events: ${report.summary.total}`);
+    if (report.paths.length > 0) {
+        console.log(`Stores: ${report.paths.join(', ')}`);
+    }
+    const artifacts = Object.entries(report.summary.by_artifact)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10);
+    if (artifacts.length > 0) {
+        console.log('');
+        console.log('Top artifacts');
+        for (const [artifact, count] of artifacts) {
+            const failures = report.summary.failures_by_artifact[artifact] ?? 0;
+            const failureText = failures > 0 ? `, ${failures} failed` : '';
+            console.log(`  ${artifact}: ${count}${failureText}`);
+        }
+    }
+    if (report.events.length > 0) {
+        console.log('');
+        console.log('Recent usage');
+        for (const event of report.events) {
+            const status = event.outcome ?? 'unknown';
+            const rel = event.project?.relative_path ? ` path=${event.project.relative_path}` : '';
+            const artifact = `${event.artifact.kind}:${event.artifact.id}`;
+            const duration = event.duration_ms === undefined ? '' : ` ${event.duration_ms}ms`;
+            console.log(`  ${event.timestamp} ${event.scope} ${event.action} ${artifact} ${status}${duration}${rel}`);
+        }
+    }
+    if (report.heatmap.length > 0) {
+        console.log('');
+        console.log('Heatmap');
+        for (const entry of report.heatmap.slice(0, 10)) {
+            console.log(`  ${entry.artifact}: ${entry.frequency_bucket} frequency, ${entry.recency_bucket} recency (${entry.count})`);
+        }
+    }
+    if (report.cold_spots.length > 0) {
+        console.log('');
+        console.log('Cold spots');
+        for (const entry of report.cold_spots.slice(0, 10)) {
+            console.log(`  skill:${entry.id}`);
+        }
+    }
+    if (report.suggestions.length > 0) {
+        console.log('');
+        console.log('Suggestions');
+        for (const suggestion of report.suggestions) {
+            console.log(`  ${suggestion.artifact}: ${suggestion.reason}`);
+        }
+    }
+}
+function classifyCliUsage(command, args) {
+    if (command === 'run' && args[0] === 'skill' && isIdentifier(args[1])) {
+        return { kind: 'skill', id: args[1], action: 'invoke' };
+    }
+    if (command === 'run' && args[0] === 'agent' && isIdentifier(args[1])) {
+        return { kind: 'agent', id: args[1], action: 'delegate' };
+    }
+    if (command === 'show' && isArtifactKind(args[0]) && isIdentifier(args[1])) {
+        return { kind: args[0], id: args[1], action: 'show' };
+    }
+    if (command === 'discover') {
+        return { kind: 'command', id: 'discover', action: 'discover' };
+    }
+    return { kind: 'command', id: command, action: 'invoke' };
+}
+function buildUsageEvent(input) {
+    const event = {
+        schema_version: 1,
+        event_type: 'aiwg.skill_usage',
+        timestamp: new Date().toISOString(),
+        invocation_id: input.env.AIWG_INVOCATION_ID,
+        source: input.source,
+        provider: input.provider,
+        artifact: input.artifact,
+        action: input.action,
+        outcome: input.outcome,
+        aiwg_version: input.version,
+        cwd_hash: hashPath(input.cwd),
+        scope: input.scope,
+    };
+    if (input.durationMs !== undefined) {
+        event.duration_ms = input.durationMs;
+    }
+    if (input.context.projectRoot) {
+        event.project = {
+            root_hash: hashPath(input.context.projectRoot),
+            relative_path: input.context.relativePath,
+        };
+    }
+    return event;
+}
+function extractClaudeCodeUsage(value) {
+    const toolUses = collectToolUses(value);
+    const events = [];
+    for (const toolUse of toolUses) {
+        const name = typeof toolUse.name === 'string' ? toolUse.name : '';
+        const input = isRecord(toolUse.input) ? toolUse.input : {};
+        if (name === 'Skill') {
+            const id = firstString(input, ['skill', 'skill_name', 'name', 'id']);
+            if (id)
+                events.push({ artifact: { kind: 'skill', id }, action: 'invoke' });
+            continue;
+        }
+        if (name === 'Task') {
+            const id = firstString(input, ['subagent_type', 'agent', 'agent_name', 'name']);
+            if (id)
+                events.push({ artifact: { kind: 'agent', id }, action: 'delegate' });
+            continue;
+        }
+        if (name === 'SlashCommand') {
+            const id = firstString(input, ['command', 'name', 'id']);
+            if (id)
+                events.push({ artifact: { kind: 'command', id: id.replace(/^\//, '') }, action: 'invoke' });
+        }
+    }
+    return events;
+}
+function collectToolUses(value) {
+    const found = [];
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        if (!isRecord(node))
+            return;
+        if (node['type'] === 'tool_use' && typeof node['name'] === 'string') {
+            found.push(node);
+        }
+        for (const child of Object.values(node)) {
+            if (typeof child === 'object' && child !== null)
+                visit(child);
+        }
+    };
+    visit(value);
+    return found;
+}
+function firstString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeProvider(value) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'claude' || normalized === 'claude_code')
+        return 'claude-code';
+    return normalized || 'unknown';
+}
+function isArtifactKind(value) {
+    return value === 'skill' ||
+        value === 'agent' ||
+        value === 'rule' ||
+        value === 'framework' ||
+        value === 'addon' ||
+        value === 'extension' ||
+        value === 'command';
+}
+function isIdentifier(value) {
+    return typeof value === 'string' && value.length > 0 && !value.startsWith('-');
+}
+async function resolveSkillUsageSettings(cwd, env) {
+    const envSetting = env.AIWG_SKILL_USAGE?.trim().toLowerCase();
+    const envMax = parsePositiveInt(env.AIWG_SKILL_USAGE_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 skillUsage = config?.telemetry?.skill_usage;
+    if (skillUsage?.enabled) {
+        return settingsFromConfig(skillUsage, envMax);
+    }
+    const commandLog = config?.command_log;
+    if (commandLog?.enabled) {
+        return settingsFromConfig(commandLog, envMax);
+    }
+    return { enabled: false, scopes: [], maxBytes: envMax ?? DEFAULT_MAX_BYTES };
+}
+function settingsFromConfig(config, envMax) {
+    return {
+        enabled: true,
+        scopes: normalizeScopes(config.scopes ?? ['project']),
+        maxBytes: config.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 resolveUsagePath(scope, projectRoot, env) {
+    if (scope === 'project') {
+        if (!projectRoot)
+            return null;
+        return projectAiwgPath(projectRoot, 'telemetry', 'skill-usage.jsonl');
+    }
+    const stateHome = env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state');
+    return path.join(stateHome, 'aiwg', 'skill-usage.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_artifact = {};
+    const by_kind = {};
+    const by_action = {};
+    const failures_by_artifact = {};
+    const by_scope = {};
+    for (const event of events) {
+        const artifact = `${event.artifact.kind}:${event.artifact.id}`;
+        by_artifact[artifact] = (by_artifact[artifact] ?? 0) + 1;
+        by_kind[event.artifact.kind] = (by_kind[event.artifact.kind] ?? 0) + 1;
+        by_action[event.action] = (by_action[event.action] ?? 0) + 1;
+        by_scope[event.scope] = (by_scope[event.scope] ?? 0) + 1;
+        if (event.outcome === 'failed') {
+            failures_by_artifact[artifact] = (failures_by_artifact[artifact] ?? 0) + 1;
+        }
+    }
+    return {
+        total: events.length,
+        by_artifact,
+        by_kind,
+        by_action,
+        failures_by_artifact,
+        by_scope,
+    };
+}
+function buildHeatmap(events, now) {
+    const byArtifact = new Map();
+    for (const event of events) {
+        const key = `${event.artifact.kind}:${event.artifact.id}`;
+        const existing = byArtifact.get(key);
+        if (!existing) {
+            byArtifact.set(key, { event, count: 1, last: event.timestamp });
+            continue;
+        }
+        existing.count += 1;
+        if (event.timestamp > existing.last)
+            existing.last = event.timestamp;
+    }
+    return [...byArtifact.entries()]
+        .map(([artifact, item]) => ({
+        artifact,
+        kind: item.event.artifact.kind,
+        id: item.event.artifact.id,
+        count: item.count,
+        last_used_at: item.last,
+        recency_bucket: recencyBucket(item.last, now),
+        frequency_bucket: frequencyBucket(item.count),
+    }))
+        .sort((a, b) => b.count - a.count || b.last_used_at.localeCompare(a.last_used_at) || a.artifact.localeCompare(b.artifact));
+}
+function buildColdSpots(inventory, events) {
+    const used = new Set(events
+        .filter(event => event.artifact.kind === 'skill')
+        .map(event => event.artifact.id));
+    return inventory
+        .filter(item => !used.has(item.id))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+function buildSuggestions(input) {
+    const queryTerms = tokenize(input.query ?? '');
+    if (queryTerms.length === 0)
+        return [];
+    const counts = new Map();
+    for (const event of input.events) {
+        if (event.artifact.kind !== 'skill')
+            continue;
+        counts.set(event.artifact.id, (counts.get(event.artifact.id) ?? 0) + 1);
+    }
+    return input.inventory
+        .map(item => {
+        const haystack = tokenize(`${item.id} ${item.description ?? ''}`);
+        const relevance = queryTerms.reduce((score, term) => score + (haystack.includes(term) ? 1 : 0), 0);
+        const usageCount = counts.get(item.id) ?? 0;
+        const underUsedBoost = usageCount === 0 ? 2 : usageCount === 1 ? 1 : 0;
+        return { item, relevance, usageCount, score: relevance * 10 + underUsedBoost };
+    })
+        .filter(candidate => candidate.relevance > 0 && candidate.usageCount <= 1)
+        .sort((a, b) => b.score - a.score || a.usageCount - b.usageCount || a.item.id.localeCompare(b.item.id))
+        .slice(0, input.limit)
+        .map(candidate => ({
+        artifact: `skill:${candidate.item.id}`,
+        kind: 'skill',
+        id: candidate.item.id,
+        reason: candidate.usageCount === 0
+            ? 'Matches the query and has no local usage events.'
+            : 'Matches the query and has only one local usage event.',
+        score: candidate.score,
+    }));
+}
+async function discoverSkillInventory(frameworkRoot) {
+    const root = path.join(frameworkRoot, 'agentic', 'code');
+    const entries = [];
+    await collectSkillFiles(root, entries);
+    const byId = new Map();
+    for (const entry of entries) {
+        const existing = byId.get(entry.id);
+        if (!existing || entry.path < existing.path)
+            byId.set(entry.id, entry);
+    }
+    return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+async function collectSkillFiles(dir, out) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    if (entries.some(entry => entry.isFile() && entry.name === 'SKILL.md')) {
+        const skillPath = path.join(dir, 'SKILL.md');
+        const id = path.basename(dir);
+        out.push({
+            kind: 'skill',
+            id,
+            description: await readSkillDescription(skillPath),
+            path: normalizeRelativePath(skillPath),
+        });
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name === 'node_modules' || entry.name.startsWith('.'))
+            continue;
+        await collectSkillFiles(path.join(dir, entry.name), out);
+    }
+}
+async function readSkillDescription(skillPath) {
+    try {
+        const raw = await readFile(skillPath, 'utf8');
+        const match = raw.match(/^description:\s*(.+)$/m);
+        return match?.[1]?.trim().replace(/^['"]|['"]$/g, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+function recencyBucket(timestamp, now) {
+    const ageMs = now.getTime() - new Date(timestamp).getTime();
+    const ageDays = ageMs / 86_400_000;
+    if (ageDays <= 1)
+        return 'today';
+    if (ageDays <= 7)
+        return '7d';
+    if (ageDays <= 30)
+        return '30d';
+    return 'stale';
+}
+function frequencyBucket(count) {
+    if (count >= 10)
+        return 'high';
+    if (count >= 3)
+        return 'medium';
+    return 'low';
+}
+function tokenize(value) {
+    return [...new Set(value
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter(term => term.length >= 2))];
+}
+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=skill-usage.js.map