@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/cli/handlers/best-practices-audit.js

@@ -0,0 +1,280 @@
+/**
+ * Best-Practices Audit Handler
+ *
+ * Launches `/best-practices-audit` — a research-grounded validation of a
+ * target (file, directory, or topic) against current external best practices
+ * with citation guardrails. The actual research is performed by the agent
+ * following the slash command skill in research-complete; this handler is
+ * a thin shim that parses flags, validates the target, computes the output
+ * path, and either spawns the configured provider or prints guidance for
+ * IDE-integrated providers.
+ *
+ * Pattern matches src/cli/handlers/sdlc-accelerate.ts — same agent-spawn
+ * conventions, same provider gating, same --params / --dangerous handling.
+ *
+ * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
+ * @issue #943
+ */
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { parseAgentSpawnFlags, buildAgentArgs, getProviderConfig, isSpawnableProvider, dangerousWarning, spawnableProviders, } from '../agent-spawn.js';
+/**
+ * Best-practices audit positional + flag parser. Distinct from
+ * `parseAgentSpawnFlags` because most of the flags are forwarded to the
+ * skill. We extract only the ones we need to validate locally; the rest
+ * survive in `remaining` and get appended to the slash-command prompt.
+ */
+function parseAuditFlags(args) {
+    const audit = {};
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const next = () => args[++i];
+        switch (a) {
+            case '--focus':
+                audit.focus = next();
+                rest.push(a, audit.focus ?? '');
+                break;
+            case '--framework':
+                audit.framework = next();
+                rest.push(a, audit.framework ?? '');
+                break;
+            case '--standard':
+                audit.standard = next();
+                rest.push(a, audit.standard ?? '');
+                break;
+            case '--recency':
+                audit.recency = next();
+                rest.push(a, audit.recency ?? '');
+                break;
+            case '--depth': {
+                const v = next();
+                if (v && (v === 'quick' || v === 'standard' || v === 'deep')) {
+                    audit.depth = v;
+                }
+                rest.push(a, v ?? '');
+                break;
+            }
+            case '--sources':
+                audit.sources = next();
+                rest.push(a, audit.sources ?? '');
+                break;
+            case '--exclude':
+                audit.exclude = next();
+                rest.push(a, audit.exclude ?? '');
+                break;
+            case '--cite-threshold': {
+                const v = next();
+                const n = v ? Number(v) : NaN;
+                if (Number.isInteger(n) && n > 0)
+                    audit.citeThreshold = n;
+                rest.push(a, v ?? '');
+                break;
+            }
+            case '--dissent':
+                audit.dissent = true;
+                rest.push(a);
+                break;
+            case '--validate':
+                audit.validateMode = true;
+                rest.push(a);
+                break;
+            case '--output':
+                audit.output = next();
+                // Don't forward --output to the slash command; the handler
+                // computes/normalizes the absolute output path separately.
+                break;
+            default:
+                rest.push(a);
+        }
+    }
+    return { audit, rest };
+}
+/**
+ * Compute the default output path. Naming convention from #929 §5:
+ *
+ *   .aiwg/reports/best-practices-audit-<target-slug>-<YYYY-MM-DD>.md
+ *
+ * The slug is derived from a path basename, freeform topic words, or 'audit'
+ * if neither produces something usable.
+ */
+function computeOutputPath(target, override, projectRoot) {
+    if (override) {
+        return path.isAbsolute(override) ? override : path.resolve(projectRoot, override);
+    }
+    const date = new Date().toISOString().slice(0, 10);
+    const slugSource = existsSync(target) ? path.basename(target).replace(/\.[^.]+$/, '') : target;
+    const slug = slugSource
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60) || 'audit';
+    return projectAiwgPath(projectRoot, 'reports', `best-practices-audit-${slug}-${date}.md`);
+}
+export class BestPracticesAuditHandler {
+    id = 'best-practices-audit';
+    name = 'Best-Practices Audit';
+    description = 'Research-grounded validation of a target against current external best practices';
+    category = 'orchestration';
+    aliases = ['best-practices-audit'];
+    async execute(ctx) {
+        if (ctx.args.includes('--help') || ctx.args.includes('-h')) {
+            return { exitCode: 0, message: this.getHelpText() };
+        }
+        // Spawn flags peeled first (--provider, --dangerous, --params).
+        const { opts: spawnOpts, remaining } = parseAgentSpawnFlags(ctx.args);
+        // Audit-specific flags peeled next; the rest carries the target +
+        // forwarded flags into the slash-command prompt.
+        const { audit, rest } = parseAuditFlags(remaining);
+        // Target must be the first positional argument. Without one, this is
+        // a usage error — the audit command requires a target.
+        const positionals = rest.filter(a => !a.startsWith('-'));
+        if (positionals.length === 0) {
+            return {
+                exitCode: 1,
+                message: 'best-practices-audit: missing <target>. Pass a file path, directory, or freeform topic.\n' +
+                    'Run: aiwg best-practices-audit --help',
+            };
+        }
+        const target = positionals[0];
+        const outputPath = computeOutputPath(target, audit.output, ctx.cwd ?? process.cwd());
+        const provider = spawnOpts.provider ?? 'claude';
+        const config = getProviderConfig(provider);
+        const prompt = this.buildPrompt(target, rest, outputPath);
+        if (!isSpawnableProvider(provider)) {
+            return {
+                exitCode: 0,
+                message: [
+                    `Provider '${config.name}' is not spawnable from the CLI.`,
+                    config.guidanceMessage ?? '',
+                    '',
+                    `Run this in your IDE or agent panel:`,
+                    `  ${prompt}`,
+                    '',
+                    `Output will be written to: ${outputPath}`,
+                ].join('\n'),
+            };
+        }
+        const warn = dangerousWarning(provider);
+        if (spawnOpts.dangerous && warn) {
+            console.warn(`Warning: ${warn}`);
+        }
+        const agentArgs = buildAgentArgs(prompt, spawnOpts);
+        return this.spawnAgent(config.binary, agentArgs, prompt, outputPath);
+    }
+    /**
+     * Compose the slash-command invocation. The agent skill receives the
+     * target and forwarded flags verbatim, plus an explicit `--output`
+     * pointing at the absolute output path so the skill writes to the
+     * handler-computed location regardless of how it interprets cwd.
+     */
+    buildPrompt(target, rest, outputPath) {
+        const flagsAfterTarget = rest.slice(rest.indexOf(target) + 1).join(' ');
+        const targetStr = target.includes(' ') ? `"${target}"` : target;
+        const flagsPart = flagsAfterTarget ? ` ${flagsAfterTarget}` : '';
+        return `/best-practices-audit ${targetStr}${flagsPart} --output "${outputPath}"`;
+    }
+    spawnAgent(binary, args, prompt, outputPath) {
+        return new Promise(resolve => {
+            try {
+                const child = spawn(binary, args, { stdio: 'inherit', env: process.env });
+                child.on('close', code => resolve({ exitCode: code ?? 0 }));
+                child.on('error', err => {
+                    if (err.code === 'ENOENT') {
+                        resolve({
+                            exitCode: 1,
+                            message: this.getNotFoundMessage(binary, prompt, outputPath),
+                        });
+                    }
+                    else {
+                        resolve({
+                            exitCode: 1,
+                            message: `Failed to launch ${binary}: ${err.message}\n\n${this.getNotFoundMessage(binary, prompt, outputPath)}`,
+                            error: err,
+                        });
+                    }
+                });
+            }
+            catch (err) {
+                resolve({
+                    exitCode: 1,
+                    message: `Failed to start best-practices-audit: ${err instanceof Error ? err.message : String(err)}\n\n${this.getNotFoundMessage(binary, prompt, outputPath)}`,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                });
+            }
+        });
+    }
+    getNotFoundMessage(binary, prompt, outputPath) {
+        return [
+            `'${binary}' not found. Install the provider CLI and try again.`,
+            `To run manually, open the agent and run:`,
+            `  ${prompt}`,
+            ``,
+            `Output will be written to: ${outputPath}`,
+        ].join('\n');
+    }
+    getHelpText() {
+        const spawnable = spawnableProviders().join(', ');
+        return `
+Best-Practices Audit — Research-grounded validation against current practice
+
+USAGE:
+  aiwg best-practices-audit <target> [options]
+  aiwg best-practices-audit ".aiwg/architecture/SAD.md" --focus security
+  aiwg best-practices-audit "FastAPI dependency injection" --depth deep
+
+ARGUMENTS:
+  <target>                File path, directory, freeform topic, or issue ref
+
+FOCUS / SCOPE:
+  --focus <area>          security, performance, accessibility, licensing,
+                          api-design, testing, docs, ops, compliance, ...
+  --framework <name>      Bias toward a named stack (React, Kubernetes, ...)
+  --standard <name>       Align to a standard (OWASP, SOC2, WCAG 2.2, ...)
+
+RESEARCH BUDGET:
+  --recency <window>      Default 18m. Tighten for fast-moving domains.
+  --depth quick|standard|deep   Research effort budget (default: standard)
+  --sources <list>        Restrict to: vendor-docs, standards-bodies,
+                          practitioner-blogs, conference-talks, academic,
+                          github-discussions
+  --exclude <list>        e.g. exclude SEO-spam domains
+  --cite-threshold <N>    Minimum distinct sources before a finding is reported (default: 2)
+
+REPORTING:
+  --dissent               Surface practitioner disagreement, not just consensus
+  --validate              Re-validate existing claims in the target rather than
+                          generating new ones
+  --output <path>         Default: .aiwg/reports/best-practices-audit-<slug>-<date>.md
+
+AGENT OPTIONS:
+  --provider <name>       Agent system to use (default: claude)
+                          Spawnable: ${spawnable}
+                          IDE-integrated (guidance only): copilot, cursor, factory, warp, windsurf
+  --dangerous             Enable unrestricted mode (passes provider's native flag).
+  --params "<args>"       Pass arbitrary args verbatim to the agent binary.
+
+ANTI-HALLUCINATION GUARDRAILS:
+  - No fabricated citations, DOIs, URLs, or quotes (Citation Policy enforced).
+  - Findings need >= --cite-threshold distinct, retrievable sources or are
+    downgraded.
+  - Conflicting sources surface as labeled disagreements, not silent picks.
+  - Sparse-signal honesty: confidence is downgraded rather than filled with priors.
+
+EXAMPLES:
+  aiwg best-practices-audit ".aiwg/architecture/SAD.md"
+  aiwg best-practices-audit ".aiwg/architecture/SAD.md" --focus security --standard OWASP
+  aiwg best-practices-audit "src/auth/" --focus security --depth deep --dissent
+  aiwg best-practices-audit "FastAPI request validation patterns" --recency 6m
+  aiwg best-practices-audit ".aiwg/architecture/" --validate
+`;
+    }
+}
+export const bestPracticesAuditHandler = new BestPracticesAuditHandler();
+/**
+ * Internal exports for testing only. Not part of the public CLI surface.
+ */
+export const __test__ = { parseAuditFlags, computeOutputPath };
+//# sourceMappingURL=best-practices-audit.js.map

package/dist/src/cli/handlers/cockpit.js

@@ -0,0 +1,137 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+export const COCKPIT_PACKAGE_NAME = '@aiwg/cockpit';
+export function cockpitHome() {
+    return process.env.AIWG_COCKPIT_HOME || path.join(homedir(), '.aiwg', 'cockpit', 'package');
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function coreVersion(frameworkRoot) {
+    const pkg = await readJson(path.join(frameworkRoot, 'package.json'));
+    return typeof pkg?.version === 'string' && pkg.version.length > 0 ? pkg.version : 'latest';
+}
+function packageRoot(home = cockpitHome()) {
+    return path.join(home, 'node_modules', '@aiwg', 'cockpit');
+}
+export async function resolveCockpitInstall(home = cockpitHome()) {
+    const root = packageRoot(home);
+    const pkg = await readJson(path.join(root, 'package.json'));
+    if (!pkg)
+        return { installed: false, packageRoot: root };
+    const bin = typeof pkg.bin === 'string'
+        ? pkg.bin
+        : typeof pkg.bin?.['aiwg-cockpit'] === 'string'
+            ? pkg.bin['aiwg-cockpit']
+            : 'bridge/src/server.mjs';
+    const entrypoint = path.join(root, bin);
+    return {
+        installed: existsSync(entrypoint),
+        version: typeof pkg.version === 'string' ? pkg.version : undefined,
+        packageRoot: root,
+        entrypoint,
+    };
+}
+function runProcess(cmd, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: 'inherit',
+        });
+        child.once('error', reject);
+        child.once('close', (code) => resolve(code ?? 1));
+    });
+}
+export async function installCockpit(ctx, args = ctx.args) {
+    const version = await coreVersion(ctx.frameworkRoot);
+    const home = cockpitHome();
+    const spec = version === 'latest' ? COCKPIT_PACKAGE_NAME : `${COCKPIT_PACKAGE_NAME}@${version}`;
+    const dryRun = args.includes('--dry-run');
+    if (dryRun) {
+        return {
+            exitCode: 0,
+            message: [
+                `Would install ${spec}`,
+                `Target: ${home}`,
+                'Run without --dry-run to acquire the opt-in Cockpit package.',
+            ].join('\n'),
+        };
+    }
+    await mkdir(home, { recursive: true });
+    const code = await runProcess('npm', ['install', '--prefix', home, '--no-audit', '--fund=false', spec], {
+        cwd: ctx.cwd,
+    });
+    if (code !== 0) {
+        return { exitCode: code, message: `Failed to install ${spec}` };
+    }
+    const install = await resolveCockpitInstall(home);
+    if (!install.installed) {
+        return { exitCode: 1, message: `${COCKPIT_PACKAGE_NAME} installed, but no aiwg-cockpit entrypoint was found.` };
+    }
+    if (version !== 'latest' && install.version !== version) {
+        return {
+            exitCode: 1,
+            message: `Installed ${COCKPIT_PACKAGE_NAME}@${install.version ?? 'unknown'}, expected ${version}.`,
+        };
+    }
+    return { exitCode: 0, message: `Installed ${COCKPIT_PACKAGE_NAME}@${install.version} in ${home}` };
+}
+export const cockpitHandler = {
+    id: 'cockpit',
+    name: 'Cockpit',
+    description: 'Launch the opt-in AIWG Cockpit control plane',
+    category: 'utility',
+    aliases: [],
+    async execute(ctx) {
+        const install = await resolveCockpitInstall();
+        const version = await coreVersion(ctx.frameworkRoot);
+        const autoInstall = ctx.args.includes('--install') || ctx.args.includes('--yes') || ctx.args.includes('-y');
+        if (ctx.args.includes('--status')) {
+            return {
+                exitCode: 0,
+                message: install.installed
+                    ? `${COCKPIT_PACKAGE_NAME}@${install.version ?? 'unknown'} installed at ${install.packageRoot}`
+                    : `${COCKPIT_PACKAGE_NAME} not installed. Run: aiwg use cockpit`,
+            };
+        }
+        if (!install.installed) {
+            if (autoInstall) {
+                const result = await installCockpit(ctx, ctx.args);
+                if (result.exitCode !== 0)
+                    return result;
+                return this.execute({ ...ctx, args: ctx.args.filter((arg) => arg !== '--install' && arg !== '--yes' && arg !== '-y') });
+            }
+            return {
+                exitCode: 1,
+                message: [
+                    'AIWG Cockpit is not installed.',
+                    `Install the opt-in package with: aiwg use cockpit`,
+                    `Expected package: ${COCKPIT_PACKAGE_NAME}@${version}`,
+                    'No Cockpit dependency is required for the base aiwg CLI.',
+                ].join('\n'),
+            };
+        }
+        if (version !== 'latest' && install.version !== version) {
+            return {
+                exitCode: 1,
+                message: [
+                    `AIWG Cockpit version mismatch: installed ${install.version ?? 'unknown'}, core ${version}.`,
+                    'Refresh the opt-in package with: aiwg use cockpit',
+                ].join('\n'),
+            };
+        }
+        const passthrough = ctx.args.filter((arg) => arg !== '--status');
+        const code = await runProcess(process.execPath, [install.entrypoint, ...passthrough], { cwd: ctx.cwd });
+        return { exitCode: code };
+    },
+};
+//# sourceMappingURL=cockpit.js.map

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

@@ -0,0 +1,37 @@
+import { printCommandLogReport } from '../command-log.js';
+export const commandLogHandler = {
+    id: 'command-log',
+    name: 'Command Log',
+    description: 'Report opt-in local CLI command invocation logs',
+    category: 'utility',
+    aliases: [],
+    async execute(ctx) {
+        const json = ctx.args.includes('--json');
+        const limit = readNumberFlag(ctx.args, '--limit') ?? 20;
+        const scope = readScopeFlag(ctx.args);
+        await printCommandLogReport({
+            cwd: ctx.cwd,
+            frameworkRoot: ctx.frameworkRoot,
+            json,
+            limit,
+            scope,
+        });
+        return { exitCode: 0 };
+    },
+};
+function readNumberFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1)
+        return undefined;
+    const raw = args[idx + 1];
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+function readScopeFlag(args) {
+    const idx = args.indexOf('--scope');
+    const raw = idx === -1 ? 'all' : args[idx + 1];
+    if (raw === 'project' || raw === 'global' || raw === 'all')
+        return raw;
+    return 'all';
+}
+//# sourceMappingURL=command-log.js.map

package/dist/src/cli/handlers/daemon.js

@@ -0,0 +1,59 @@
+/**
+ * Daemon Command Handlers
+ *
+ * Handlers for daemon-related CLI commands (behavior management, daemon init).
+ * Each handler delegates to existing scripts in tools/.
+ *
+ * @tests @test/unit/cli/handlers/coverage.test.ts
+ */
+import { createScriptRunner } from './script-runner.js';
+import { getFrameworkRoot } from '../../channel/manager.mjs';
+/**
+ * Base class for daemon handlers that delegate to scripts
+ */
+class DaemonHandler {
+    category = 'daemon';
+    get aliases() {
+        return [this.id];
+    }
+    async execute(ctx) {
+        const frameworkRoot = await getFrameworkRoot();
+        const runner = createScriptRunner(frameworkRoot);
+        return runner.run(this.scriptPath, ctx.args);
+    }
+}
+/**
+ * Behavior Handler
+ *
+ * Manages behavior YAML bundles that bind directives and toolsets to agent types.
+ */
+class BehaviorHandler extends DaemonHandler {
+    id = 'behavior';
+    name = 'Behavior';
+    description = 'Manage behavior YAML bundles that bind directives and toolsets to agent types';
+    scriptPath = 'tools/daemon/behavior.mjs';
+}
+/**
+ * Daemon Init Handler
+ *
+ * Initialize daemon config from a profile template.
+ */
+class DaemonInitHandler extends DaemonHandler {
+    id = 'daemon-init';
+    name = 'Daemon Init';
+    description = 'Initialize daemon config from a profile template (default: manager)';
+    scriptPath = 'tools/daemon/init-profile.mjs';
+}
+/**
+ * Exported handler instances
+ */
+export const behaviorHandler = new BehaviorHandler();
+export const daemonInitHandler = new DaemonInitHandler();
+/**
+ * All daemon handlers for registration
+ */
+export const daemonHandlers = [
+    behaviorHandler,
+    daemonInitHandler,
+];
+//# sourceMappingURL=daemon.js.map