@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/features/catalog.js

@@ -0,0 +1,88 @@
+/**
+ * Optional Features Catalog
+ *
+ * AIWG ships several runtime-optional features whose dependencies may
+ * be installed separately. This catalog is the canonical mapping
+ * between **feature names** (operator vocabulary) and the **npm
+ * packages** that enable them.
+ *
+ * Consumed by:
+ *   - `aiwg features` command (status / info / install / remove)
+ *   - `aiwg doctor` (Optional Features section)
+ *   - Runtime error messages (when a dynamic import fails, point at
+ *     `aiwg features install <name>`)
+ *
+ * @implements #1219
+ */
+export const FEATURE_CATALOG = [
+    {
+        name: 'embeddings',
+        description: 'Vector embeddings for `aiwg discover` (semantic search beyond the keyword scorer)',
+        packages: ['@xenova/transformers', 'hnswlib-node'],
+        packageSpecs: {
+            '@xenova/transformers': '2.17.2',
+            'hnswlib-node': '3.0.0',
+        },
+        scriptPackages: ['hnswlib-node'],
+        enables: [
+            'higher hit@K on natural-language queries that don\'t match trigger phrases',
+            'optional dense-rerank layer when sparse top-1 is ambiguous',
+        ],
+        cost: '~150 MB — transformers runtime + libvips native binary, one-time download',
+    },
+    {
+        name: 'sqlite',
+        description: 'SQLite storage backend for memory / activity-log / kb subsystems',
+        packages: ['better-sqlite3'],
+        packageSpecs: { 'better-sqlite3': '12.8.0' },
+        scriptPackages: ['better-sqlite3'],
+        enables: [
+            'storage.config: backend=sqlite for any subsystem',
+            'transactional reads/writes against `.aiwg/storage/`',
+        ],
+        cost: '~5 MB — native compile via node-gyp',
+    },
+    {
+        name: 'pty',
+        description: 'PTY bridge for daemon — pass-through interactive TUIs (Claude Code, Codex, etc.)',
+        packages: ['node-pty'],
+        packageSpecs: { 'node-pty': '1.1.0' },
+        scriptPackages: ['node-pty'],
+        enables: [
+            'aiwg daemon pty start / list / stop',
+            'daemon web UI for interactive Claude/Codex/etc sessions over WebSocket',
+        ],
+        cost: '~2 MB — native compile via node-gyp',
+    },
+    {
+        name: 'webserver',
+        description: 'HTTP/WebSocket server for the daemon web UI and ralph-external bridge',
+        packages: ['hono', '@hono/node-server', 'ws'],
+        packageSpecs: {
+            hono: '4.12.18',
+            '@hono/node-server': '1.19.14',
+            ws: '8.20.0',
+        },
+        enables: [
+            'aiwg daemon serve',
+            'browser-based daemon UI',
+            'ralph-external WebSocket dispatch',
+        ],
+        cost: '~3 MB — pure JS, no native deps',
+    },
+];
+/** Native packages require a successful runtime load, not just package files. */
+export const NATIVE_FEATURE_PACKAGES = new Set(FEATURE_CATALOG.flatMap(feature => feature.scriptPackages ?? []));
+/** Quick lookup by feature name. */
+export function getFeature(name) {
+    return FEATURE_CATALOG.find(f => f.name === name) ?? null;
+}
+/** All feature names — useful for `--all` flags and CLI completion. */
+export function listFeatureNames() {
+    return FEATURE_CATALOG.map(f => f.name);
+}
+/** Reverse lookup: given a package name, which feature does it belong to? */
+export function featureForPackage(pkg) {
+    return FEATURE_CATALOG.find(f => f.packages.includes(pkg)) ?? null;
+}
+//# sourceMappingURL=catalog.js.map

package/dist/src/features/cli.js

@@ -0,0 +1,197 @@
+/**
+ * `aiwg features` CLI subcommands
+ *
+ * Native packages are installed into a user-owned feature root. Its generated
+ * package manifest contains exact package-level allowScripts approvals, so the
+ * operator does not need to weaken npm policy globally.
+ */
+import { FEATURE_CATALOG } from './catalog.js';
+import { getFeatureStatus, getAllFeatureStatuses, formatStatusLine } from './status.js';
+import { installFeature } from './installer.js';
+export async function main(args) {
+    // If the first arg is a flag (e.g. `--json`), treat the implicit
+    // subcommand as `status` and pass everything through. This makes
+    // `aiwg features --json` Just Work.
+    const firstIsFlag = args[0]?.startsWith('--');
+    const subcommand = firstIsFlag ? 'status' : (args[0] ?? 'status');
+    const subArgs = firstIsFlag ? args : args.slice(1);
+    switch (subcommand) {
+        case 'status':
+        case 'list':
+            await handleStatus(subArgs);
+            break;
+        case 'info':
+            await handleInfo(subArgs);
+            break;
+        case 'install':
+            await handleInstall(subArgs);
+            break;
+        case 'remove':
+            console.error(`Error: \`aiwg features ${subcommand}\` not yet implemented (#1219 Cycle 3).`);
+            console.error('');
+            console.error('To install manually for now:');
+            console.error('  cd <aiwg install root>');
+            console.error('  npm install <packages>     # see `aiwg features info <name>` for the package list');
+            process.exit(1);
+            break;
+        case 'help':
+        case '--help':
+        case '-h':
+            printHelp();
+            break;
+        default:
+            console.error(`Error: unknown subcommand '${subcommand}'`);
+            console.error('');
+            printHelp();
+            process.exit(1);
+    }
+}
+function printHelp() {
+    console.log('Usage: aiwg features [subcommand] [options]');
+    console.log('');
+    console.log('Subcommands:');
+    console.log('  status        Show install status of every optional feature (default)');
+    console.log('  info <name>   Show detailed info on one feature');
+    console.log('  install <name> Install a feature with scoped lifecycle-script approval');
+    console.log('  remove        Not yet implemented (#1219 Cycle 3)');
+    console.log('  help          Show this help');
+    console.log('');
+    console.log('Options:');
+    console.log('  --json        Emit machine-readable output');
+    console.log('');
+    console.log('Examples:');
+    console.log('  aiwg features                       # status table');
+    console.log('  aiwg features --json                # JSON status');
+    console.log('  aiwg features info embeddings       # what does this feature enable');
+    console.log('  aiwg features install pty            # explicitly build node-pty');
+    console.log('');
+    console.log('Available features:');
+    for (const f of FEATURE_CATALOG) {
+        console.log(`  ${f.name.padEnd(12)} — ${f.description}`);
+    }
+}
+async function handleStatus(args) {
+    const json = args.includes('--json');
+    const statuses = await getAllFeatureStatuses();
+    if (json) {
+        console.log(JSON.stringify({
+            features: statuses.map(s => ({
+                name: s.feature.name,
+                available: s.available,
+                missing: s.missing,
+                packages: s.packages.map(p => ({
+                    name: p.name,
+                    installed: p.installed,
+                    version: p.version,
+                    loadable: p.loadable,
+                    error: p.error,
+                })),
+            })),
+            total: statuses.length,
+            available: statuses.filter(s => s.available).length,
+            missing: statuses.filter(s => !s.available).length,
+        }, null, 2));
+        return;
+    }
+    console.log('AIWG Optional Features');
+    console.log('======================');
+    console.log('');
+    for (const status of statuses) {
+        console.log(formatStatusLine(status));
+    }
+    console.log('');
+    const available = statuses.filter(s => s.available).length;
+    console.log(`Total: ${statuses.length}  Available: ${available}  Missing: ${statuses.length - available}`);
+    console.log('');
+    console.log('Run `aiwg features info <name>` for details on any feature.');
+}
+async function handleInfo(args) {
+    const json = args.includes('--json');
+    const positional = args.filter(a => !a.startsWith('--'));
+    const name = positional[0];
+    if (!name) {
+        console.error('Error: feature name required.');
+        console.error('');
+        console.error('Available features:');
+        for (const f of FEATURE_CATALOG) {
+            console.error(`  ${f.name}`);
+        }
+        process.exit(1);
+    }
+    const status = await getFeatureStatus(name);
+    if (!status) {
+        console.error(`Error: unknown feature '${name}'.`);
+        console.error('');
+        console.error('Available features:');
+        for (const f of FEATURE_CATALOG) {
+            console.error(`  ${f.name}`);
+        }
+        process.exit(1);
+    }
+    if (json) {
+        console.log(JSON.stringify({
+            name: status.feature.name,
+            description: status.feature.description,
+            enables: status.feature.enables,
+            cost: status.feature.cost,
+            available: status.available,
+            missing: status.missing,
+            packages: status.packages.map(p => ({
+                name: p.name,
+                installed: p.installed,
+                version: p.version,
+                loadable: p.loadable,
+                error: p.error,
+            })),
+        }, null, 2));
+        return;
+    }
+    printFeatureInfo(status);
+}
+function printFeatureInfo(status) {
+    const f = status.feature;
+    console.log(`Feature: ${f.name}`);
+    console.log(`Status:  ${status.available ? 'INSTALLED' : 'NOT INSTALLED'}`);
+    console.log('');
+    console.log(`Description: ${f.description}`);
+    console.log('');
+    console.log('Enables:');
+    for (const cap of f.enables) {
+        console.log(`  - ${cap}`);
+    }
+    console.log('');
+    console.log(`Install cost: ${f.cost}`);
+    console.log('');
+    console.log('Packages:');
+    for (const p of status.packages) {
+        const mark = p.installed && p.loadable ? 'OK' : (p.installed ? '!' : '-');
+        const version = p.version ? ` ${p.version}` : '';
+        const error = p.error ? ` — ${p.error}` : '';
+        console.log(`  ${mark} ${p.name}${version}${error}`);
+    }
+    console.log('');
+    if (!status.available) {
+        console.log('To install:');
+        console.log(`  aiwg features install ${f.name}`);
+    }
+}
+async function handleInstall(args) {
+    const name = args.find(arg => !arg.startsWith('--'));
+    if (!name)
+        throw new Error('Feature name required. Run `aiwg features` to list features.');
+    const feature = FEATURE_CATALOG.find(candidate => candidate.name === name);
+    if (!feature)
+        throw new Error(`Unknown feature '${name}'.`);
+    console.log(`Installing optional feature: ${name}`);
+    if ((feature.scriptPackages?.length ?? 0) > 0) {
+        console.log(`Approved lifecycle scripts: ${feature.scriptPackages.join(', ')}`);
+        console.log('Approval is stored only in the AIWG user feature manifest.');
+    }
+    const root = await installFeature(name);
+    const status = await getFeatureStatus(name);
+    if (!status?.available) {
+        throw new Error(`Feature ${name} was installed but failed its runtime load check. Run \`aiwg doctor\` for details.`);
+    }
+    console.log(`Feature ${name} is ready (${root}).`);
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/features/installer.js

@@ -0,0 +1,57 @@
+import { spawnSync } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { FEATURE_CATALOG, getFeature } from './catalog.js';
+import { getFeaturesRoot } from './paths.js';
+export async function prepareFeatureManifest(feature, root = getFeaturesRoot()) {
+    await fs.mkdir(root, { recursive: true });
+    const manifestPath = path.join(root, 'package.json');
+    let current = {};
+    try {
+        current = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+    }
+    catch {
+        // First install, or an invalid partial file left by an interrupted write.
+    }
+    const knownSpecs = Object.assign({}, ...FEATURE_CATALOG.map(candidate => candidate.packageSpecs));
+    const priorDependencies = Object.fromEntries(Object.entries(current.dependencies ?? {}).filter(([name]) => name in knownSpecs));
+    const dependencies = {
+        ...priorDependencies,
+        ...feature.packageSpecs,
+    };
+    const allowScripts = {};
+    for (const candidate of FEATURE_CATALOG) {
+        for (const packageName of candidate.scriptPackages ?? []) {
+            if (packageName in dependencies)
+                allowScripts[packageName] = true;
+        }
+    }
+    const manifest = {
+        name: 'aiwg-optional-features',
+        private: true,
+        version: '1.0.0',
+        description: 'User-owned optional runtime packages managed by aiwg features',
+        dependencies,
+        allowScripts,
+    };
+    const tempPath = `${manifestPath}.tmp-${process.pid}`;
+    await fs.writeFile(tempPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+    await fs.rename(tempPath, manifestPath);
+    return manifest;
+}
+export async function installFeature(name, options = {}) {
+    const feature = getFeature(name);
+    if (!feature)
+        throw new Error(`Unknown optional feature: ${name}`);
+    const root = options.root ?? getFeaturesRoot();
+    await prepareFeatureManifest(feature, root);
+    const npmCommand = options.npmCommand ?? (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    const result = spawnSync(npmCommand, ['install', '--prefix', root, '--no-audit', '--no-fund'], { stdio: 'inherit', env: process.env });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        throw new Error(`npm exited with status ${result.status ?? 'unknown'} while installing ${name}`);
+    }
+    return root;
+}
+//# sourceMappingURL=installer.js.map

package/dist/src/features/paths.js

@@ -0,0 +1,14 @@
+import os from 'node:os';
+import path from 'node:path';
+/** User-owned root for optional runtime packages. */
+export function getFeaturesRoot() {
+    if (process.env.AIWG_FEATURES_HOME)
+        return process.env.AIWG_FEATURES_HOME;
+    if (process.platform === 'win32') {
+        const dataHome = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+        return path.join(dataHome, 'aiwg', 'features');
+    }
+    const dataHome = process.env.XDG_DATA_HOME ?? path.join(os.homedir(), '.local', 'share');
+    return path.join(dataHome, 'aiwg', 'features');
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/features/runtime.js

@@ -0,0 +1,21 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getFeaturesRoot } from './paths.js';
+/** Load an optional package from the user feature root, then the base install. */
+export async function loadFeaturePackage(name) {
+    const featureRequire = createRequire(path.join(getFeaturesRoot(), 'package.json'));
+    try {
+        const resolved = featureRequire.resolve(name);
+        return await import(pathToFileURL(resolved).href);
+    }
+    catch (featureError) {
+        try {
+            return await (new Function('m', 'return import(m)'))(name);
+        }
+        catch {
+            throw featureError;
+        }
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/features/status.js

@@ -0,0 +1,134 @@
+/**
+ * Optional Features — Installation Status Probe
+ *
+ * Resolves whether each feature in the catalog is currently available
+ * by attempting to read its packages from the AIWG install's
+ * `node_modules`. Pure best-effort — never throws on missing packages,
+ * just reports them as not installed.
+ *
+ * @implements #1219
+ */
+import { promises as fs } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { FEATURE_CATALOG, NATIVE_FEATURE_PACKAGES } from './catalog.js';
+import { getFeaturesRoot } from './paths.js';
+/**
+ * Resolve the AIWG install root for package probing. Tries:
+ *   1. AIWG_ROOT env var
+ *   2. The directory that contains this module's compiled output
+ *      (walks up to find package.json with name "aiwg")
+ *   3. process.cwd() as a last resort
+ */
+async function resolveAiwgRoot() {
+    if (process.env.AIWG_ROOT)
+        return process.env.AIWG_ROOT;
+    // Walk up from this module's URL.
+    // dist layout: dist/src/features/status.js → walk up to package.json
+    let cur = path.dirname(new URL(import.meta.url).pathname);
+    for (let i = 0; i < 10; i++) {
+        try {
+            const pkgPath = path.join(cur, 'package.json');
+            const stat = await fs.stat(pkgPath).catch(() => null);
+            if (stat?.isFile()) {
+                const pkg = JSON.parse(await fs.readFile(pkgPath, 'utf8'));
+                if (pkg?.name === 'aiwg')
+                    return cur;
+            }
+        }
+        catch { /* keep walking */ }
+        const parent = path.dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    return process.cwd();
+}
+/**
+ * Probe a single package by reading its package.json from
+ * `<aiwgRoot>/node_modules/<name>/package.json`.
+ */
+async function probePackage(aiwgRoot, name) {
+    const roots = [getFeaturesRoot(), aiwgRoot];
+    for (const root of roots) {
+        const candidate = path.join(root, 'node_modules', name, 'package.json');
+        try {
+            const raw = await fs.readFile(candidate, 'utf8');
+            const meta = JSON.parse(raw);
+            let loadable = true;
+            let error = null;
+            if (NATIVE_FEATURE_PACKAGES.has(name)) {
+                try {
+                    createRequire(candidate)(name);
+                }
+                catch (cause) {
+                    loadable = false;
+                    const message = cause instanceof Error ? cause.message : String(cause);
+                    error = message.split('\n')[0] || 'native module could not be loaded';
+                }
+            }
+            return {
+                name,
+                installed: true,
+                version: meta.version ?? null,
+                path: candidate,
+                loadable,
+                error,
+            };
+        }
+        catch {
+            // Try the base AIWG install after the user feature root.
+        }
+    }
+    return { name, installed: false, version: null, path: null, loadable: false, error: null };
+}
+/** Status of a single named feature. Returns null if the name is unknown. */
+export async function getFeatureStatus(name) {
+    const feature = FEATURE_CATALOG.find(f => f.name === name);
+    if (!feature)
+        return null;
+    const aiwgRoot = await resolveAiwgRoot();
+    const pkgStatuses = await Promise.all(feature.packages.map(p => probePackage(aiwgRoot, p)));
+    const missing = pkgStatuses.filter(p => !p.installed || !p.loadable).map(p => p.name);
+    return {
+        feature,
+        packages: pkgStatuses,
+        available: missing.length === 0,
+        missing,
+    };
+}
+/** Status of every feature in the catalog. */
+export async function getAllFeatureStatuses() {
+    const aiwgRoot = await resolveAiwgRoot();
+    return Promise.all(FEATURE_CATALOG.map(async (feature) => {
+        const pkgStatuses = await Promise.all(feature.packages.map(p => probePackage(aiwgRoot, p)));
+        const missing = pkgStatuses.filter(p => !p.installed || !p.loadable).map(p => p.name);
+        return {
+            feature,
+            packages: pkgStatuses,
+            available: missing.length === 0,
+            missing,
+        };
+    }));
+}
+/**
+ * Format a single feature status as a one-line "doctor row":
+ *   ✓ embeddings   installed (@xenova/transformers 2.17.2, hnswlib-node 3.0.0)
+ *   ○ pty          not installed — `aiwg features install pty` to enable
+ */
+export function formatStatusLine(status, indent = '  ') {
+    const name = status.feature.name.padEnd(11);
+    if (status.available) {
+        const versions = status.packages
+            .map(p => `${p.name} ${p.version ?? '?'}`)
+            .join(', ');
+        return `${indent}OK ${name} installed (${versions})`;
+    }
+    const broken = status.packages.filter(p => p.installed && !p.loadable);
+    if (broken.length > 0) {
+        return `${indent}!  ${name} installed but native build is unusable (${broken.map(p => p.name).join(', ')}) — ` +
+            `run \`aiwg features install ${status.feature.name}\` to rebuild with scoped script approval`;
+    }
+    return `${indent}-  ${name} not installed — \`aiwg features install ${status.feature.name}\` to enable`;
+}
+//# sourceMappingURL=status.js.map