@gaia-ai/gaia 0.5.4 → 0.6.0

package/bin/gaia

@@ -1,2 +1,5 @@
 #!/usr/bin/env node
-import('@gaia-ai/conductor').then((m) => m.main(process.argv));
+// GAIA-201: the `gaia` entrypoint lives in the meta package now (AC-1). It runs
+// the plugin host, which dynamically mounts the ui/conductor/dropsh command
+// plugins — conductor is no longer the CLI owner.
+import('../dist/src/host.js').then((m) => m.main(process.argv));

package/dist/src/host.d.ts

@@ -0,0 +1,31 @@
+import { type CommandDescriptor } from '@gaia-ai/core';
+import { Command } from 'commander';
+/** The built-in command registry. `$GAIA_COMMANDS` (JSON array of descriptors)
+ *  overrides it wholesale. */
+export declare const DEFAULT_COMMANDS: CommandDescriptor[];
+/** Resolve the registry: `$GAIA_COMMANDS` override else the built-in set. */
+export declare function resolveCommands(): CommandDescriptor[];
+/** The installed CLI version (the meta package version). */
+export declare function resolveCliVersion(): string;
+/** Host bases for ESLint-style sibling resolution: the meta install → cwd. */
+export declare function hostBases(): string[];
+/**
+ * Value-aware argv pre-scan: find the first positional token that names a
+ * registered command. Skips the host's value-taking global (`--conductor <v>`)
+ * and maps `help <name>` → `<name>`. Returns undefined for `--help`, an unknown
+ * first positional, or a bare invocation.
+ */
+export declare function scanTarget(argv: string[], names: string[]): string | undefined;
+/** Build the top-level host program, mounting only the target command (the rest
+ *  are describe-only stubs). */
+export declare function buildHostProgram(argv: string[], opts?: {
+    forceTarget?: string;
+    bases?: string[];
+}): Promise<Command>;
+/** Parse argv against the host program, mapping commander's clean exits. */
+export declare function runHost(argv: string[], opts?: {
+    forceTarget?: string;
+    bases?: string[];
+}): Promise<void>;
+/** The `gaia` entrypoint: drop node + script path, run the host. */
+export declare function main(argv: string[]): Promise<void>;

package/dist/src/host.js

@@ -0,0 +1,218 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { commands as conductorCommands } from '@gaia-ai/conductor/preset';
+import { resolveModuleEslintStyle, } from '@gaia-ai/core';
+import { commands as dropshCommands } from '@gaia-ai/plugin-dropsh/preset';
+import { commands as uiCommands } from '@gaia-ai/ui/preset';
+import { Command } from 'commander';
+import { registerUpgrade } from './upgrade.js';
+// GAIA-201: the `gaia` plugin HOST. The meta package `@gaia-ai/gaia` owns the
+// CLI entrypoint (AC-1); ui / conductor / dropsh are declared, ESLint-style
+// resolved, LAZILY mounted command plugins (AC-2). The host discovers + mounts;
+// it hard-wires nothing. Only the invoked subcommand's module is imported —
+// `gaia --help` lists all three via describe-only stubs and imports none;
+// `gaia conductor …` imports only the conductor module.
+//
+// GAIA-215: the registry is DERIVED from the command surface — the three command
+// addons' preset `commands` accumulators — rather than a hand-written list.
+// Those presets are LIGHT (they import no runtime, only return descriptors), so
+// composing them at boot keeps `gaia --help` import-light. `$GAIA_COMMANDS`
+// still overrides the whole registry.
+/** Compose the built-in command registry from the command addons' presets. The
+ *  accumulators are synchronous descriptor builders (light presets), threaded in
+ *  the conductor → ui → dropsh order. */
+function composeCommandSurface() {
+    const accumulators = [conductorCommands, uiCommands, dropshCommands];
+    let acc = [];
+    for (const fn of accumulators) {
+        if (typeof fn === 'function')
+            acc = fn(acc, undefined);
+    }
+    return acc;
+}
+/** The built-in command registry. `$GAIA_COMMANDS` (JSON array of descriptors)
+ *  overrides it wholesale. */
+export const DEFAULT_COMMANDS = composeCommandSurface();
+/** Resolve the registry: `$GAIA_COMMANDS` override else the built-in set. */
+export function resolveCommands() {
+    const override = process.env.GAIA_COMMANDS;
+    if (override && override.trim() !== '') {
+        const parsed = JSON.parse(override);
+        if (!Array.isArray(parsed)) {
+            throw new Error('$GAIA_COMMANDS must be a JSON array of command descriptors');
+        }
+        return parsed;
+    }
+    return DEFAULT_COMMANDS;
+}
+/** The meta package root (holds package.json), for version + resolveBases. */
+function metaPackageRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        try {
+            readFileSync(join(dir, 'package.json'), 'utf8');
+            return dir;
+        }
+        catch {
+            const parent = dirname(dir);
+            if (parent === dir)
+                return dir;
+            dir = parent;
+        }
+    }
+}
+/** The installed CLI version (the meta package version). */
+export function resolveCliVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(metaPackageRoot(), 'package.json'), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** Host bases for ESLint-style sibling resolution: the meta install → cwd. */
+export function hostBases() {
+    return [import.meta.url, pathToFileURL(`${process.cwd()}/`).href];
+}
+/** Load a command descriptor's `GaiaCommandPlugin` (default export, or the named
+ *  `export`), resolving the module over the host bases. */
+async function loadCommandPlugin(entry, bases) {
+    const resolved = resolveModuleEslintStyle(entry.plugin, bases);
+    if (resolved === undefined) {
+        throw new Error(`gaia: cannot resolve command plugin '${entry.plugin}' (command '${entry.name}')`);
+    }
+    const mod = (await import(pathToFileURL(resolved).href));
+    const factory = entry.export ? mod[entry.export] : mod.default;
+    if (factory === undefined || factory === null) {
+        throw new Error(`gaia: command plugin '${entry.plugin}' has no ${entry.export ?? 'default'} export`);
+    }
+    return factory;
+}
+/**
+ * Value-aware argv pre-scan: find the first positional token that names a
+ * registered command. Skips the host's value-taking global (`--conductor <v>`)
+ * and maps `help <name>` → `<name>`. Returns undefined for `--help`, an unknown
+ * first positional, or a bare invocation.
+ */
+export function scanTarget(argv, names) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--conductor') {
+            i++; // skip its value
+            continue;
+        }
+        if (a === 'help') {
+            const next = argv[i + 1];
+            return next !== undefined && names.includes(next) ? next : undefined;
+        }
+        if (a.startsWith('-'))
+            continue; // any other flag
+        return names.includes(a) ? a : undefined;
+    }
+    return undefined;
+}
+/** Add a describe-only stub for a not-loaded command so `--help` stays complete.
+ *  If it is ever dispatched (a mis-scan), its action self-loads the real plugin
+ *  and re-runs the host forcing that target. */
+function addStub(program, entry, bases, argv) {
+    program
+        .command(entry.name)
+        .description(pluginDescribe(entry))
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .helpOption(false)
+        .action(async () => {
+        await runHost(argv, { forceTarget: entry.name, bases });
+    });
+}
+/** Best-effort describe text for a stub without importing the plugin. GAIA-215:
+ *  the descriptor now carries its own `describe` (from the addon's preset); this
+ *  falls back only for a `$GAIA_COMMANDS` entry that omits it. */
+function pluginDescribe(entry) {
+    if (typeof entry.describe === 'string' && entry.describe.trim() !== '') {
+        return entry.describe;
+    }
+    switch (entry.name) {
+        case 'conductor':
+            return 'node-agent lifecycle + local registry';
+        case 'ui':
+            return 'interactive terminal UI: project dashboard, ticket list, ticket detail';
+        case 'dropsh':
+            return 'JSON:API shell (dropsh) bound to the GAIA connection config';
+        default:
+            return `${entry.name} command`;
+    }
+}
+/** Build the top-level host program, mounting only the target command (the rest
+ *  are describe-only stubs). */
+export async function buildHostProgram(argv, opts = {}) {
+    const bases = opts.bases ?? hostBases();
+    const host = { resolveBases: bases };
+    const commands = resolveCommands();
+    const names = commands.map((c) => c.name);
+    const program = new Command();
+    // exitOverride so commander surfaces help/version/unknown-command as thrown
+    // CommanderErrors (mapped in runHost) instead of calling process.exit —
+    // otherwise an unknown command would kill the host process directly.
+    program.exitOverride();
+    program
+        .name('gaia')
+        .description('GAIA conductor + client CLI')
+        .option('--conductor <name>', 'select a conductor by stem (conductor→conductor.config.js, else <name>.conductor.config.js; env $GAIA_CONDUCTOR)');
+    // The global --conductor flag threads into $GAIA_CONDUCTOR (flag wins over env)
+    // so every command selects the named engine config without per-command wiring.
+    program.hook('preAction', () => {
+        const name = program.opts().conductor;
+        if (typeof name === 'string' && name !== '') {
+            process.env.GAIA_CONDUCTOR = name;
+        }
+    });
+    const cliVersion = resolveCliVersion();
+    program.version(cliVersion); // -V, --version
+    program
+        .command('version')
+        .description('output the gaia CLI version')
+        .action(() => {
+        console.log(cliVersion);
+    });
+    registerUpgrade(program);
+    const target = opts.forceTarget ?? scanTarget(argv, names);
+    for (const entry of commands) {
+        if (entry.name === target) {
+            const plugin = await loadCommandPlugin(entry, bases);
+            await plugin.register(program, host);
+        }
+        else {
+            addStub(program, entry, bases, argv);
+        }
+    }
+    return program;
+}
+/** Parse argv against the host program, mapping commander's clean exits. */
+export async function runHost(argv, opts = {}) {
+    const program = await buildHostProgram(argv, opts);
+    try {
+        await program.parseAsync(argv, { from: 'user' });
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'commander.helpDisplayed' ||
+            e.code === 'commander.version') {
+            return;
+        }
+        if (typeof e.code === 'string' && e.code.startsWith('commander.')) {
+            if (!process.exitCode)
+                process.exitCode = 1;
+            return;
+        }
+        process.stderr.write(`${e.message ?? String(err)}\n`);
+        if (!process.exitCode)
+            process.exitCode = 1;
+    }
+}
+/** The `gaia` entrypoint: drop node + script path, run the host. */
+export async function main(argv) {
+    await runHost(argv.slice(2));
+}

package/dist/src/upgrade.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+/** Register `gaia upgrade` on the host program. */
+export declare function registerUpgrade(program: Command): void;

package/dist/src/upgrade.js

@@ -0,0 +1,24 @@
+import { runUpgrade } from '@gaia-ai/conductor';
+// GAIA-216: the `gaia upgrade` migration/seed routine was hoisted DOWN into the
+// engine (`@gaia-ai/conductor`) so `conductor init` can call it intra-package
+// without a host→engine→host cycle. The host keeps only the thin CLI
+// registration below; the behaviour/output contract is unchanged. See
+// `conductor/engine/src/cli/upgrade.ts` for `runUpgrade` + `UpgradeReport`.
+/** Register `gaia upgrade` on the host program. */
+export function registerUpgrade(program) {
+    program
+        .command('upgrade')
+        .description('migrate this install to the split config model (gaia.config.js connection + conductor.config.js engine; ~/.gaia/machine.config.js)')
+        .option('--dry-run', 'print the migration plan without writing anything', false)
+        .action((opts) => {
+        const report = runUpgrade({ dryRun: opts.dryRun });
+        for (const line of report.actions)
+            console.log(line);
+        if (report.alreadyCurrent)
+            console.log('gaia upgrade: already current');
+        else if (opts.dryRun)
+            console.log('gaia upgrade: dry run (no changes written)');
+        else
+            console.log('gaia upgrade: done');
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gaia-ai/gaia",
-  "version": "0.5.4",
-  "description": "GAIA meta package: installs the conductor CLI + all runtime plugins. Global install target.",
+  "version": "0.6.0",
+  "description": "GAIA meta package: the `gaia` plugin-host CLI + all runtime plugins. Global install target.",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -11,6 +11,7 @@
     "gaia": "./bin/gaia"
   },
   "exports": {
+    "./host": "./dist/src/host.js",
     "./plugins": "./dist/src/plugins-barrel.js",
     "./package.json": "./package.json"
   },
@@ -26,7 +27,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://git.key-tec.de/keytec/gaia.git",
-    "directory": "conductor/packages/gaia"
+    "directory": "conductor/host"
   },
   "keywords": [
     "gaia",
@@ -37,13 +38,17 @@
     "jsonapi"
   ],
   "dependencies": {
-    "@gaia-ai/conductor": "^0.5.4",
-    "@gaia-ai/core": "^0.5.4",
-    "@gaia-ai/plugin-claude": "^0.5.4",
-    "@gaia-ai/plugin-codex": "^0.5.4",
-    "@gaia-ai/plugin-essentials": "^0.5.4",
-    "@gaia-ai/plugin-herdr": "^0.5.4",
-    "@gaia-ai/plugin-kimi": "^0.5.4",
-    "@gaia-ai/plugin-opencode": "^0.5.4"
+    "@gaia-ai/conductor": "^0.6.0",
+    "@gaia-ai/core": "^0.6.0",
+    "@gaia-ai/plugin-claude": "^0.6.0",
+    "@gaia-ai/plugin-codex": "^0.6.0",
+    "@gaia-ai/plugin-dropsh": "^0.6.0",
+    "@gaia-ai/plugin-essentials": "^0.6.0",
+    "@gaia-ai/plugin-gaia-ui": "^0.6.0",
+    "@gaia-ai/plugin-herdr": "^0.6.0",
+    "@gaia-ai/plugin-kimi": "^0.6.0",
+    "@gaia-ai/plugin-opencode": "^0.6.0",
+    "@gaia-ai/ui": "^0.6.0",
+    "commander": "^12.1.0"
   }
 }