@bahulam/code 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahulam/code",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Bahulam Code — abundance, in your terminal. CLI-first, reliability-first, sub-agents, 65.6% SWE-bench Verified.",
   "type": "module",
   "bin": {

package/src/auth/tarang-auth.mjs

@@ -0,0 +1,313 @@
+/**
+ * Bahulam Code Authentication — GitHub OAuth + config management.
+ * Reads/writes ~/.bahulam/config.json (fallback: ~/.kepler/config.json for
+ * legacy installs — see src/core/paths.mjs for the resolver).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as http from 'node:http';
+import { getLoginSuccessHTML } from '../ui/banner.mjs';
+import { resolveBackendUrl } from '../core/backend-url.mjs';
+import { bahulamHome } from '../core/paths.mjs';
+
+// Note: computed via a function (not a constant) so that BAHULAM_HOME /
+// KEPLER_HOME env-var swaps mid-process still work.
+function configDir() { return bahulamHome(); }
+function configPath() { return path.join(configDir(), 'config.json'); }
+
+// Legacy exports kept for backwards compat with any tests/scripts that
+// still import CONFIG_DIR / CONFIG_PATH by name.
+const CONFIG_DIR = configDir();
+const CONFIG_PATH = configPath();
+
+let _tokenEnvNoticeShown = false;
+function readTokenFromEnv() {
+    if (process.env.B0_TOKEN) return process.env.B0_TOKEN;
+    if (process.env.KEPLER_TOKEN) {
+        if (!_tokenEnvNoticeShown && process.env.B0_QUIET_MIGRATION !== '1') {
+            _tokenEnvNoticeShown = true;
+            try {
+                process.stderr.write(
+                    '  \x1b[2mnote: KEPLER_TOKEN is deprecated; set B0_TOKEN instead.\x1b[0m\n'
+                );
+            } catch {}
+        }
+        return process.env.KEPLER_TOKEN;
+    }
+    return null;
+}
+
+export class TarangAuth {
+    constructor() {
+        this._config = null;
+    }
+
+    /** Ensure ~/.bahulam/ (or legacy ~/.kepler/) exists with secure permissions. */
+    _ensureConfigDir() {
+        const dir = configDir();
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+    }
+
+    /** Load credentials and settings from config.json. */
+    loadCredentials() {
+        const cfgPath = configPath();
+        try {
+            if (fs.existsSync(cfgPath)) {
+                const raw = fs.readFileSync(cfgPath, 'utf-8');
+                this._config = JSON.parse(raw);
+            } else {
+                this._config = {};
+            }
+        } catch {
+            this._config = {};
+        }
+        return {
+            token: readTokenFromEnv() || this._config.token || null,
+            openRouterKey: this._config.openrouter_key || process.env.OPENROUTER_API_KEY || null,
+            anthropicKey: this._config.anthropic_api_key || process.env.ANTHROPIC_API_KEY || null,
+            openaiKey: this._config.openai_api_key || process.env.OPENAI_API_KEY || null,
+            googleKey: this._config.google_api_key || process.env.GOOGLE_API_KEY || null,
+            backendUrl: resolveBackendUrl(),
+            mode: this._config.mode || 'auto',
+            gatewayType: this._config.gateway_type || 'openrouter',
+            models: this._config.models || {},
+            configuredProviders: this._config.configured_providers || [],
+            gatewayConfig: this._config.gateway_config || {},
+            // PRD-076 W7: persisted /model picks. `modelConfig` mirrors the
+            // Python-side key read_local_model_config() looks for; keep the
+            // snake_case JSON key so the runtime picks it up unchanged.
+            modelConfig: this._config.model_config || {},
+            modelMode: this._config.model_mode || null,
+            routePreference: this._config.route_preference || null,
+        };
+    }
+
+    /** Get the raw config object. */
+    getRawConfig() {
+        if (!this._config) this.loadCredentials();
+        return this._config || {};
+    }
+
+    /** Clear credentials — remove token and keys from config. */
+    logout() {
+        try {
+            const cfgPath = configPath();
+            if (fs.existsSync(cfgPath)) {
+                fs.unlinkSync(cfgPath);
+            }
+            this._config = null;
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /** Save credentials atomically (temp-file + rename). */
+    saveCredentials(updates) {
+        this._ensureConfigDir();
+        const current = this._config || {};
+        const merged = { ...current, ...updates };
+        const cfgPath = configPath();
+        const tmpPath = `${cfgPath}.tmp.${process.pid}`;
+        fs.writeFileSync(tmpPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+        fs.renameSync(tmpPath, cfgPath);
+        this._config = merged;
+    }
+
+    /** Check if user has a valid auth token. */
+    isAuthenticated() {
+        const creds = this.loadCredentials();
+        return !!creds.token;
+    }
+
+    /** Check if OpenRouter key is configured. */
+    hasOpenRouterKey() {
+        const creds = this.loadCredentials();
+        return !!creds.openRouterKey;
+    }
+
+    /** Save an API key by provider name. */
+    saveProviderKey(provider, key) {
+        const keyMap = {
+            openrouter: 'openrouter_key',
+            anthropic: 'anthropic_api_key',
+            openai: 'openai_api_key',
+            googleai: 'google_api_key',
+            azureopenai: 'azure_api_key',
+            bedrock: 'aws_access_key',
+            databricks: 'databricks_token',
+        };
+        const field = keyMap[provider];
+        if (!field) throw new Error(`Unknown provider: ${provider}`);
+        this.saveCredentials({ [field]: key });
+    }
+
+    /** Save OpenRouter API key. */
+    saveOpenRouterKey(key) {
+        this.saveProviderKey('openrouter', key);
+    }
+
+    /** Save Anthropic API key. */
+    saveAnthropicKey(key) {
+        this.saveProviderKey('anthropic', key);
+    }
+
+    /** Save OpenAI API key. */
+    saveOpenAIKey(key) {
+        this.saveProviderKey('openai', key);
+    }
+
+    /** Save Google AI API key. */
+    saveGoogleKey(key) {
+        this.saveProviderKey('googleai', key);
+    }
+
+    /** Sync settings from web backend and save locally. */
+    async syncSettings() {
+        const { fetchRemoteSettings, mergeRemoteSettings } = await import('../core/settings-sync.mjs');
+        const creds = this.loadCredentials();
+        if (!creds.token) throw new Error('Not logged in. Run `bahulam-code login` first.');
+
+        const remote = await fetchRemoteSettings(creds.token);
+        if (!remote) throw new Error('Failed to fetch settings from server.');
+
+        const merged = mergeRemoteSettings(this.getRawConfig(), remote);
+        this.saveCredentials(merged);
+        return remote;
+    }
+
+    /** Set default mode. */
+    setMode(mode) {
+        const valid = ['local', 'remote', 'auto'];
+        if (!valid.includes(mode)) {
+            throw new Error(`Invalid mode: ${mode}. Must be one of: ${valid.join(', ')}`);
+        }
+        this.saveCredentials({ mode });
+    }
+
+    /** Display config (styled). */
+    printConfig() {
+        const creds = this.loadCredentials();
+        const GREEN = '\x1b[32m', RED = '\x1b[31m', DIM = '\x1b[2m', BOLD = '\x1b[1m', CYAN = '\x1b[36m', RESET = '\x1b[0m';
+        const check = `${GREEN}\u2713${RESET}`;
+        const cross = `${RED}\u2717${RESET}`;
+
+        const env = process.env.TARANG_ENV || process.env.NODE_ENV || 'production';
+
+        process.stderr.write(`\n${BOLD}Bahulam Code Configuration${RESET}\n`);
+        process.stderr.write(`${'─'.repeat(50)}\n`);
+        process.stderr.write(`  Auth:           ${creds.token ? `${check} logged in` : `${cross} not logged in ${DIM}(/login)${RESET}`}\n`);
+        process.stderr.write(`  Environment:    ${DIM}${env}${RESET}\n`);
+        process.stderr.write(`  Backend:        ${DIM}${creds.backendUrl}${RESET}\n`);
+        process.stderr.write(`  Mode:           ${DIM}${creds.mode || 'auto'}${RESET}\n`);
+        process.stderr.write(`  Gateway:        ${DIM}${creds.gatewayType}${RESET}\n`);
+
+        const models = creds.models || {};
+        const planningModel = models.planning || models.orchestrator;
+        if (planningModel || models.reasoning || models.local) {
+            process.stderr.write(`\n${BOLD}  Models${RESET}\n`);
+            if (planningModel)       process.stderr.write(`  Planning:       ${DIM}${planningModel}${RESET}\n`);
+            if (models.reasoning)    process.stderr.write(`  Coding:         ${DIM}${models.reasoning}${RESET}\n`);
+            if (models.local)        process.stderr.write(`  Local:          ${DIM}${models.local}${RESET}\n`);
+        }
+
+        const providers = creds.configuredProviders || [];
+        if (providers.length > 0) {
+            process.stderr.write(`  Providers:      ${DIM}${providers.join(', ')}${RESET}\n`);
+        }
+
+        const raw = this.getRawConfig();
+        if (raw.last_synced_at) {
+            process.stderr.write(`  Last synced:    ${DIM}${new Date(raw.last_synced_at).toLocaleString()}${RESET}\n`);
+        }
+
+        process.stderr.write(`\n  ${DIM}Run ${RESET}${CYAN}bahulam-code sync${RESET}${DIM} to sync settings from web.${RESET}\n`);
+        process.stderr.write(`  ${DIM}Run ${RESET}${CYAN}bahulam-code configure${RESET}${DIM} to open settings in browser.${RESET}\n`);
+        process.stderr.write('\n');
+    }
+
+    /**
+     * Run login flow via web app.
+     *
+     * Flow:
+     *   1. CLI starts local HTTP server on random port
+     *   2. Opens browser to web /auth/cli?callback=http://127.0.0.1:{port}/callback
+     *   3. Web checks Supabase session (if none → GitHub OAuth → Supabase)
+     *   4. Web generates CLI token via /api/cli/token
+     *   5. Web redirects browser to CLI callback with token
+     *   6. CLI receives token, saves to ~/.bahulam/config.json
+     */
+    async login() {
+        const { resolveWebUrl } = await import('../core/backend-url.mjs');
+        const webUrl = resolveWebUrl();
+
+        return new Promise((resolve, reject) => {
+            const server = http.createServer(async (req, res) => {
+                const url = new URL(req.url, `http://localhost`);
+
+                // The web app redirects here with ?token=<cli_token>
+                const token = url.searchParams.get('token');
+
+                if (!token) {
+                    // Maybe an error or missing token
+                    const error = url.searchParams.get('error');
+                    if (error) {
+                        res.writeHead(200, { 'Content-Type': 'text/html' });
+                        res.end(`<html><body><h2>Login failed</h2><p>${error}</p></body></html>`);
+                        server.close();
+                        reject(new Error(error));
+                        return;
+                    }
+                    // Ignore other requests (favicon, etc.)
+                    res.writeHead(200);
+                    res.end('');
+                    return;
+                }
+
+                // Save the CLI token
+                this.saveCredentials({ token });
+
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(getLoginSuccessHTML());
+
+                server.close();
+                resolve(true);
+            });
+
+            server.listen(0, '127.0.0.1', () => {
+                const port = server.address().port;
+                const callbackUrl = `http://127.0.0.1:${port}/callback`;
+                const authUrl = `${webUrl}/auth/cli?callback=${encodeURIComponent(callbackUrl)}`;
+
+                process.stderr.write(`\n\x1b[36mOpening browser for login...\x1b[0m\n`);
+                process.stderr.write(`\x1b[2mIf browser doesn't open, visit:\x1b[0m\n  \x1b[4m${authUrl}\x1b[0m\n\n`);
+
+                // Open browser
+                const openCmd = process.platform === 'darwin' ? 'open' :
+                                process.platform === 'win32' ? 'start' : 'xdg-open';
+                import('node:child_process').then(({ exec }) => {
+                    exec(`${openCmd} "${authUrl}"`, () => {});
+                });
+            });
+
+            // Timeout after 120s
+            setTimeout(() => {
+                server.close();
+                reject(new Error('Login timed out after 120s'));
+            }, 120_000);
+        });
+    }
+
+    /**
+     * Ensure user is authenticated, prompt login if not.
+     */
+    async ensureAuth() {
+        if (!this.isAuthenticated()) {
+            process.stderr.write('\x1b[33mNot logged in.\x1b[0m Starting login flow...\n');
+            await this.login();
+        }
+    }
+}

package/src/commands/agent.mjs

@@ -1,5 +1,5 @@
 /**
- * Agent CLI Commands — list, get, sync user-defined agents.
+ * Agent CLI Commands — list, get, sync backend-published user-defined agents.
  *
  * Commands:
  *   bahulam-code agent list
@@ -47,9 +47,9 @@ export async function handleAgentCommand(args) {
 
 function printAgentUsage() {
     process.stderr.write(`${BOLD}AGENT COMMANDS${RESET}\n`);
-    process.stderr.write(`  ${CYAN}bahulam-code agent list${RESET}                           List user-defined agents\n`);
-    process.stderr.write(`  ${CYAN}bahulam-code agent get <slug>${RESET}                     Show agent details\n`);
-    process.stderr.write(`  ${CYAN}bahulam-code agent sync [--dir <path>]${RESET}            Sync agent YAML files\n`);
+    process.stderr.write(`  ${CYAN}bahulam-code agent list${RESET}                           List backend-published agents\n`);
+    process.stderr.write(`  ${CYAN}bahulam-code agent get <slug>${RESET}                     Show backend-published agent details\n`);
+    process.stderr.write(`  ${CYAN}bahulam-code agent sync [--dir <path>]${RESET}            Publish local agent YAML files for account/cloud reuse\n`);
     process.stderr.write('\n');
 }
 
@@ -110,11 +110,11 @@ async function handleList(args) {
 
     const agents = result.agents || [];
     if (agents.length === 0) {
-        process.stderr.write(`${DIM}No user-defined agents found.${RESET}\n`);
+        process.stderr.write(`${DIM}No backend-published agents found. Local .bahulam/agents files can still be delegated in their workspace.${RESET}\n`);
         process.exit(0);
     }
 
-    process.stderr.write(`${BOLD}User-defined Agents:${RESET}\n`);
+    process.stderr.write(`${BOLD}Backend-published Agents:${RESET}\n`);
     for (const a of agents) {
         const source = a.source === 'platform' ? `${DIM}(platform)${RESET}` : `${DIM}(user)${RESET}`;
         process.stderr.write(`  ${CYAN}${a.slug}${RESET}  ${a.name || a.slug} ${source}\n`);
@@ -184,7 +184,7 @@ async function handleSync(args) {
             agents: selected,
         });
         const synced = result.synced ?? selected.length;
-        process.stderr.write(`${GREEN}✓ Synced ${synced} agent${synced === 1 ? '' : 's'} to Supabase.${RESET}\n`);
+        process.stderr.write(`${GREEN}✓ Synced ${synced} agent${synced === 1 ? '' : 's'} to the backend for account/cloud reuse.${RESET}\n`);
         process.stdout.write(JSON.stringify({ synced, agents: result.agents || [] }, null, 2) + '\n');
     } catch (err) {
         process.stderr.write(`${RED}✗ Agent sync failed: ${err.message}${RESET}\n`);

package/src/commands/install.mjs

@@ -0,0 +1,295 @@
+/**
+ * Top-level `bahulam pull` and `bahulam install` commands.
+ *
+ *   bahulam pull <src>     — install an ingredient (currently pi:<name>).
+ *                            No pack scaffolding; the raw package lands in
+ *                            ~/.bahulam/plugins-pi/ and is only useful when
+ *                            referenced by a pack's spec.composes:.
+ *
+ *   bahulam install <src>  — install a full pack.
+ *                            For pi:<name>: pulls the ingredient AND
+ *                            scaffolds a Bahulam pack around it (composes +
+ *                            native state layer + agent + workspace panel),
+ *                            then installs the pack via preflight.
+ *                            For git URL / tarball URL / local path: installs
+ *                            as a hand-authored pack (delegates to the
+ *                            existing plugin-manage install path).
+ *
+ * The split lets users pull pi ingredients they only need as compose targets
+ * without generating a full pack, while giving one-command installs for
+ * users who want an agent-ready surface from a pi package.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  classifySource,
+  installFromGit,
+  installFromTarball,
+  installFromLocal,
+  installFromPi,
+  pluginTargetDir,
+  resolveComposeDependencies,
+} from './plugin-manage.mjs';
+import { preflightPlugin, existingInstalledNames } from '../plugins/preflight.mjs';
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+
+function parseArgs(argv) {
+  const parsed = {
+    source: null,
+    force: false,
+    global: true,
+    ref: null,
+    json: false,
+    help: false,
+    slug: null,
+    state: true,
+    workspace: true,
+  };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--help': case '-h': parsed.help = true; break;
+      case '--force': case '-f': parsed.force = true; break;
+      case '--project': parsed.global = false; break;
+      case '--global': parsed.global = true; break;
+      case '--ref': case '--tag': case '--branch': parsed.ref = argv[++i]; break;
+      case '--json': parsed.json = true; break;
+      case '--slug': case '--name': parsed.slug = argv[++i]; break;
+      case '--no-state': parsed.state = false; break;
+      case '--no-workspace': parsed.workspace = false; break;
+      default:
+        if (!arg.startsWith('-')) positional.push(arg);
+        break;
+    }
+  }
+  parsed.source = positional.shift() || null;
+  return parsed;
+}
+
+/**
+ * `bahulam pull <src>` — ingredient only. Currently pi: sources only.
+ */
+export async function handlePullCommand(argv, { cwd = process.cwd() } = {}) {
+  const args = parseArgs(argv);
+  if (args.help || !args.source) {
+    process.stderr.write(`
+  ${BOLD}bahulam pull <source>${RESET}
+
+  Pull an ingredient (pi package) into ~/.bahulam/plugins-pi/. The
+  ingredient is composable but not directly runnable — reference it from
+  a pack's ${CYAN}spec.composes:${RESET} block, or use ${CYAN}bahulam install pi:<name>${RESET}
+  to auto-scaffold a full pack around it.
+
+  Sources:
+    pi:<npm-package>[@<version>]     Pull a pi package (e.g. pi:pi-web-access@^0.27.0)
+
+  Flags:
+    --force, -f            Overwrite an existing ingredient at the same path
+    --json                 Machine-readable output
+
+`);
+    if (!args.source) process.exit(1);
+    return;
+  }
+
+  const classified = classifySource(args.source);
+  if (classified.kind !== 'pi') {
+    if (classified.kind === 'invalid') {
+      throw new Error(`invalid pi source: ${args.source}`);
+    }
+    throw new Error(
+      `pull only accepts pi: sources. For ${classified.kind} sources use \`bahulam install ${args.source}\`.`,
+    );
+  }
+
+  try {
+    const dest = await installFromPi({
+      packageName: classified.package_name,
+      versionRange: classified.version_range,
+      force: args.force,
+    });
+    if (args.json) {
+      process.stdout.write(JSON.stringify({
+        ok: true,
+        kind: 'pi',
+        package_name: classified.package_name,
+        version_range: classified.version_range,
+        directory: dest,
+      }, null, 2) + '\n');
+      return;
+    }
+    process.stderr.write(`\n${GREEN}✓${RESET} Pulled pi package ${BOLD}${classified.package_name}${RESET}\n`);
+    process.stderr.write(`  ${DIM}location${RESET}  ${dest}\n`);
+    process.stderr.write(`  ${YELLOW}!${RESET} Pi packages run with your full system permissions. Bahulam does not audit pi packages.\n`);
+    process.stderr.write(`  ${DIM}Wrap in a pack:${RESET}  ${CYAN}bahulam install pi:${classified.package_name}${RESET}\n`);
+    process.stderr.write(`  ${DIM}Compose in yours:${RESET} ${CYAN}spec.composes: [{source: pi:${classified.package_name}, expose: [...]}]${RESET}\n\n`);
+  } catch (err) {
+    process.stderr.write(`\x1b[31m✗\x1b[0m ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+/**
+ * `bahulam install <src>` — full pack install.
+ *   pi:<name>  → pull ingredient + scaffold pack + preflight-install
+ *   git URL    → clone + preflight-install
+ *   tarball    → download + preflight-install
+ *   local path → copy + preflight-install
+ */
+export async function handleInstallCommand(argv, { cwd = process.cwd() } = {}) {
+  const args = parseArgs(argv);
+  if (args.help || !args.source) {
+    process.stderr.write(`
+  ${BOLD}bahulam install <source>${RESET}
+
+  Install a pack. For pi sources, pulls the ingredient and scaffolds a
+  full Bahulam pack (composition + state layer + workspace + agent), then
+  installs it. For git/tarball/local sources, installs the existing pack.
+
+  Sources:
+    pi:<npm-package>[@<version>]     Scaffold + install from a pi package
+    <git-url>[.git]                  Clone a hand-authored pack
+    <tarball-url>                    Download + install a pack tarball
+    <local-path>                     Copy + install a local pack directory
+
+  Flags:
+    --force, -f            Overwrite an existing pack at the same target
+    --slug <name>          Override the scaffolded pack slug (pi sources only)
+    --no-state             Skip the persistent state layer (pi sources only)
+    --no-workspace         Skip the reactive workspace panel (pi sources only)
+    --project              Install into ./.bahulam/plugins/ instead of ~/.bahulam/plugins/
+    --ref <ref>            Git branch/tag/commit (git sources only)
+    --json                 Machine-readable output
+
+`);
+    if (!args.source) process.exit(1);
+    return;
+  }
+
+  const classified = classifySource(args.source);
+  const targetDir = pluginTargetDir({ global: args.global, cwd });
+
+  try {
+    if (classified.kind === 'pi') {
+      await installPiWithScaffolding({ classified, targetDir, cwd, args });
+      return;
+    }
+    if (classified.kind === 'invalid') {
+      throw new Error(`unrecognized source: ${args.source}`);
+    }
+
+    // Non-pi paths reuse the plugin-manage install machinery.
+    let dest;
+    if (classified.kind === 'git') {
+      dest = await installFromGit({ url: classified.url, targetDir, ref: args.ref, force: args.force });
+    } else if (classified.kind === 'tarball') {
+      dest = await installFromTarball({ url: classified.url, targetDir, force: args.force });
+    } else if (classified.kind === 'local') {
+      dest = await installFromLocal({ src: classified.path, targetDir, force: args.force });
+    } else if (classified.kind === 'name') {
+      throw new Error(`registry lookup for bare names is not yet wired into \`bahulam install\`. Provide a git URL, tarball URL, local path, or pi: source.`);
+    } else {
+      throw new Error(`could not resolve source: ${args.source}`);
+    }
+
+    await preflightAndReport({ dest, args, cwd });
+  } catch (err) {
+    process.stderr.write(`\x1b[31m✗\x1b[0m ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+async function installPiWithScaffolding({ classified, targetDir, cwd, args }) {
+  const { bahulamHome } = await import('../core/paths.mjs');
+  const { discoverPiTools } = await import('../plugins/pi-compat/probe.mjs');
+  const { scaffoldPiPack } = await import('../plugins/pi-compat/scaffold.mjs');
+
+  const piBaseDir = path.join(bahulamHome(), 'plugins-pi');
+  const safeName = classified.package_name.replace(/[/@]/g, '_');
+  const piDir = path.join(piBaseDir, safeName);
+
+  // Step 1: pull the ingredient if we haven't already.
+  if (!fs.existsSync(piDir)) {
+    process.stderr.write(`${DIM}pulling ${classified.package_name}…${RESET}\n`);
+    await installFromPi({
+      packageName: classified.package_name,
+      versionRange: classified.version_range,
+      force: false,
+    });
+  } else {
+    process.stderr.write(`${DIM}reusing existing ingredient at ${piDir}${RESET}\n`);
+  }
+
+  // Step 2: ensure the tools cache is present.
+  const discovered = await discoverPiTools(piDir, { pluginName: classified.package_name });
+
+  // Step 3: generate the pack directory (composes + state + agent + panel).
+  process.stderr.write(`${DIM}scaffolding pack…${RESET}\n`);
+  const { dest, slug, namespace, exposeTools, agentSlug } = scaffoldPiPack({
+    packageName: classified.package_name,
+    versionRange: classified.version_range,
+    piDir,
+    targetDir,
+    discoveredTools: discovered,
+    state: args.state,
+    workspace: args.workspace,
+    slug: args.slug,
+    force: args.force,
+  });
+
+  // Step 4: preflight the generated pack. Same rules as any other pack.
+  await preflightAndReport({ dest, args, cwd, meta: { slug, namespace, exposeTools, agentSlug, packageName: classified.package_name } });
+}
+
+async function preflightAndReport({ dest, args, cwd, meta = null }) {
+  const preflight = await preflightPlugin(dest, {
+    existingPluginNames: () => existingInstalledNames(cwd),
+  });
+  if (!preflight.ok) {
+    fs.rmSync(dest, { recursive: true, force: true });
+    const detail = preflight.errors.map(e => `    · ${e}`).join('\n');
+    throw new Error(`preflight failed — rolled back ${dest}:\n${detail}`);
+  }
+  if (preflight.warnings.length) {
+    for (const w of preflight.warnings) process.stderr.write(`${YELLOW}!${RESET} ${w}\n`);
+  }
+  const m = preflight.manifest;
+
+  // A hand-authored pack may compose pi packages we haven't pulled yet.
+  // Do it in one command; the scaffolder path already has the pi ingredient.
+  await resolveComposeDependencies(m, { targetDir: path.dirname(dest) });
+
+  if (args.json) {
+    process.stdout.write(JSON.stringify({
+      ok: true,
+      name: m.metadata.name,
+      version: m.metadata.version,
+      directory: dest,
+      scaffolded: Boolean(meta),
+      ...(meta ? { pi_package: meta.packageName, namespace: meta.namespace, composed_tools: meta.exposeTools, agent: meta.agentSlug } : {}),
+    }, null, 2) + '\n');
+    return;
+  }
+
+  process.stderr.write(`\n${GREEN}✓${RESET} Installed ${BOLD}${m.metadata.name}${RESET} v${m.metadata.version}\n`);
+  process.stderr.write(`  ${DIM}location${RESET}  ${dest}\n`);
+  const nativeTools = (m.spec.tools || []).map(t => t.name);
+  const composedCount = (m.spec.composes || []).reduce((n, c) => n + ((c.expose || []).length || 0), 0);
+  process.stderr.write(`  ${DIM}tools${RESET}     ${nativeTools.length ? nativeTools.join(', ') : '(none)'}${composedCount ? ` ${DIM}+ ${composedCount} composed${RESET}` : ''}\n`);
+  process.stderr.write(`  ${DIM}agents${RESET}    ${(m.spec.agents || []).map(a => a.slug).join(', ') || '(none)'}\n`);
+  const views = m.spec.workspace?.views || [];
+  process.stderr.write(`  ${DIM}views${RESET}     ${views.length ? views.map(v => v.name).join(', ') : '(none)'}\n`);
+  if (meta) {
+    process.stderr.write(`  ${DIM}scaffolded${RESET} from ${CYAN}pi:${meta.packageName}${RESET} (namespace ${CYAN}${meta.namespace}${RESET}, ${meta.exposeTools.length} composed tool${meta.exposeTools.length === 1 ? '' : 's'})\n`);
+    process.stderr.write(`  ${DIM}Edit the pack under ${dest} to customize.${RESET}\n`);
+  }
+  process.stderr.write(`\n  ${DIM}Open with:${RESET} ${CYAN}bahulam plugin ${m.metadata.name}${RESET}\n\n`);
+}