@bahulam/code 0.1.12 → 0.1.14

package/src/plugins/pi-compat/shim.mjs

@@ -0,0 +1,162 @@
+/**
+ * Pi runtime shim — the synthetic `pi` module a composed pi package
+ * imports at load time.
+ *
+ * Pi's extension API is imperative: extensions do `import { pi } from
+ * 'pi'` and call `pi.registerTool(name, schema, handler)` /
+ * `pi.registerCommand(cmd, handler)` / `pi.ctx.ui.setWidget(...)`. We
+ * intercept the module resolution via a Node ESM loader hook
+ * (`loader-hook.mjs`) that returns a virtual module which imports THIS
+ * shim and instantiates it against a shared capture object.
+ *
+ * v1 scope:
+ *   - registerTool: captured, exposed to our loop as a pluginToolMap entry
+ *   - registerCommand: captured but not surfaced (no REPL command bridge)
+ *   - pi.events.on/emit: no-op (cross-extension event bus, deferred)
+ *   - pi.ctx.ui.setWidget/custom: no-op with debug warning (TUI widgets
+ *     don't translate to our workspace canvas; author dedicated panels)
+ *   - pi.ctx.log: forwards to stderr with plugin prefix
+ */
+
+export function createPiShim({ pluginName = 'pi', captured }) {
+  if (!captured || typeof captured !== 'object') {
+    throw new Error('createPiShim: captured object is required');
+  }
+  captured.tools ||= [];
+  captured.commands ||= [];
+
+  const pi = {
+    // Pi's canonical shape is registerTool({name, description, parameters,
+    // execute}) — a single descriptor with an `execute` function. Older
+    // examples use registerTool(name, schema, handler) with positional args.
+    // Accept both.
+    registerTool(arg1, arg2, arg3) {
+      if (arg1 && typeof arg1 === 'object' && !Array.isArray(arg1)) {
+        const desc = arg1;
+        const name = desc.name;
+        if (!name || typeof name !== 'string') return;
+        // Descriptor form: pi's canonical `{name, description, parameters,
+        // execute}`. Handler is called as execute(id, params).
+        captured.tools.push({
+          name,
+          description: desc.description || '',
+          schema: desc.parameters || desc.input_schema || desc.schema || { type: 'object', properties: {} },
+          handler: typeof desc.execute === 'function' ? desc.execute
+                 : typeof desc.handler === 'function' ? desc.handler
+                 : typeof desc.call === 'function' ? desc.call
+                 : null,
+          _form: 'descriptor',
+        });
+        return;
+      }
+      // Positional legacy form: (name, schema, handler). Handler is
+      // called as handler(args).
+      if (!arg1 || typeof arg1 !== 'string') return;
+      let name = arg1, schema = arg2, handler = arg3;
+      if (typeof handler !== 'function' && typeof schema === 'function') {
+        handler = schema;
+        schema = { type: 'object', properties: {} };
+      }
+      captured.tools.push({
+        name,
+        description: '',
+        schema: schema || { type: 'object', properties: {} },
+        handler,
+        _form: 'positional',
+      });
+    },
+
+    // registerCommand(cmd, descriptor) in real pi; descriptor has
+    // {description, execute}. Older form: registerCommand(cmd, handler).
+    registerCommand(cmd, arg2) {
+      if (!cmd || typeof cmd !== 'string') return;
+      if (arg2 && typeof arg2 === 'object' && !Array.isArray(arg2)) {
+        const desc = arg2;
+        captured.commands.push({
+          cmd,
+          description: desc.description || '',
+          handler: typeof desc.execute === 'function' ? desc.execute
+                 : typeof desc.handler === 'function' ? desc.handler
+                 : null,
+        });
+      } else if (typeof arg2 === 'function') {
+        captured.commands.push({ cmd, handler: arg2 });
+      }
+    },
+
+    events: {
+      on() { /* no-op in v1 */ },
+      emit() { /* no-op in v1 */ },
+      off() { /* no-op in v1 */ },
+    },
+
+    // Pi packages call pi.on(...) directly for lifecycle events (session
+    // start/end etc.) — no-op them so activation reaches registerTool.
+    // Same treatment for pi.off, pi.emit, pi.once.
+    on() { /* no-op */ },
+    off() { /* no-op */ },
+    emit() { /* no-op */ },
+    once() { /* no-op */ },
+
+    // Additional pi surfaces called at activation-time by real packages
+    // (pi-web-access, etc.). Stub them so activation completes and tools
+    // register; runtime callers that rely on these still throw at call
+    // time, which is the correct signal that a feature isn't supported.
+    registerShortcut() { /* no-op */ },
+    appendEntry() { /* no-op */ },
+    sendMessage() { /* no-op */ },
+    exec() {
+      throw new Error(`[pi:${pluginName}] pi.exec is not supported in Bahulam compat`);
+    },
+    // pi.fetch is pi's authenticated fetch. Delegate to global fetch —
+    // that's what the extension expects: an HTTP client. Auth headers
+    // are typically added by the extension itself using env credentials.
+    fetch(...args) { return globalThis.fetch(...args); },
+
+    ctx: {
+      ui: {
+        setWidget(widget) {
+          if (process.env.DEBUG) {
+            const title = widget?.title || widget?.name || 'untitled';
+            process.stderr.write(`[pi:${pluginName}] widget ignored: ${title}\n`);
+          }
+        },
+        custom() { /* no-op */ },
+        clear() { /* no-op */ },
+      },
+      log(...args) {
+        process.stderr.write(`[pi:${pluginName}] ${args.map(String).join(' ')}\n`);
+      },
+    },
+  };
+
+  // Pi's ExtensionAPI is a moving target — packages call methods we haven't
+  // stubbed yet (registerMessageRenderer, registerRoute, registerHandler,
+  // …). Any unstubbed method call throws, aborting activation before
+  // registerTool ever runs, and the probe reports 0 tools.
+  //
+  // Fall back to a no-op returner for every unknown property so activation
+  // reaches its full extent. A tool's runtime call may still fail if it
+  // needed that surface — that's an accurate signal at execution time,
+  // not a silent black hole at load time.
+  return new Proxy(pi, {
+    get(target, prop, receiver) {
+      if (prop in target) return Reflect.get(target, prop, receiver);
+      if (typeof prop === 'symbol') return undefined;
+      if (process.env.DEBUG) {
+        process.stderr.write(`[pi:${pluginName}] shim: pi.${String(prop)} stubbed (no-op)\n`);
+      }
+      // Return a callable that also has method access (e.g. pi.foo.bar).
+      // Property access on the stub returns another stub, so chains never
+      // throw. Result is undefined so anything that reads a return value
+      // treats it as "not present" (typeof result === 'undefined').
+      const stub = function stub() { return undefined; };
+      return new Proxy(stub, {
+        get(t, p) {
+          if (typeof p === 'symbol') return t[p];
+          return stub;
+        },
+      });
+    },
+  });
+}

package/src/plugins/pi-compose.mjs

@@ -0,0 +1,147 @@
+/**
+ * Pi composition helpers.
+ *
+ * This is the contract layer for PRD-102 §13.6.1b. It deliberately does
+ * not install or execute pi packages yet; it gives manifest/preflight/
+ * registry code one normalized shape to test against.
+ */
+
+export const PI_TOOLS_CACHE = '.bahulam-tools.json';
+
+const TOOL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+const NAMESPACE_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+const NPM_NAME_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/i;
+
+export function parsePiSource(source) {
+  const raw = String(source || '').trim();
+  if (!raw.startsWith('pi:')) return null;
+  const spec = raw.slice(3).trim();
+  if (!spec) return null;
+
+  let packageName = spec;
+  let versionRange = '';
+  if (spec.startsWith('@')) {
+    const slash = spec.indexOf('/');
+    const versionAt = slash >= 0 ? spec.indexOf('@', slash + 1) : -1;
+    if (versionAt > 0) {
+      packageName = spec.slice(0, versionAt);
+      versionRange = spec.slice(versionAt + 1);
+    }
+  } else {
+    const versionAt = spec.lastIndexOf('@');
+    if (versionAt > 0) {
+      packageName = spec.slice(0, versionAt);
+      versionRange = spec.slice(versionAt + 1);
+    }
+  }
+
+  if (!NPM_NAME_RE.test(packageName)) return null;
+  return {
+    kind: 'pi',
+    source: raw,
+    spec,
+    package_name: packageName,
+    packageName,
+    version_range: versionRange || null,
+    versionRange: versionRange || null,
+  };
+}
+
+export function normalizeCompose(composeDef, index = 0) {
+  const source = String(composeDef?.source || '').trim();
+  const parsed = parsePiSource(source);
+  const expose = Array.isArray(composeDef?.expose)
+    ? composeDef.expose.map(item => String(item || '').trim()).filter(Boolean)
+    : [];
+  const namespace = String(composeDef?.as || '').trim();
+
+  return {
+    source,
+    as: namespace || '',
+    expose,
+    verified: composeDef?.verified === true,
+    package_name: parsed?.package_name || '',
+    packageName: parsed?.packageName || '',
+    version_range: parsed?.version_range || null,
+    versionRange: parsed?.versionRange || null,
+    _index: index,
+    _kind: 'pi',
+  };
+}
+
+export function normalizeComposes(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .map((item, index) => normalizeCompose(item, index))
+    .filter(item => item.source || item.expose.length || item.as);
+}
+
+// Anthropic's tool-name regex (`^[a-zA-Z0-9_-]{1,64}$`) forbids dots, and
+// the backend's client-tool sanitizer enforces the same shape. `__` is the
+// convention Claude Code and MCP both use for namespaced tool names, so
+// stay compatible: `namespace__tool`.
+export const COMPOSED_TOOL_SEPARATOR = '__';
+
+export function composedToolName(compose, exposedName) {
+  const name = String(exposedName || '').trim();
+  return compose?.as ? `${compose.as}${COMPOSED_TOOL_SEPARATOR}${name}` : name;
+}
+
+export function validateCompose(compose) {
+  const errors = [];
+  const warnings = [];
+  const label = `Compose #${Number.isInteger(compose?._index) ? compose._index : '?'}`;
+
+  if (!parsePiSource(compose?.source)) {
+    errors.push(`${label}: source must be a pi npm spec, for example pi:@scope/package@^1.0.0`);
+  }
+  if (compose?.as && !NAMESPACE_RE.test(compose.as)) {
+    errors.push(`${label}: as "${compose.as}" must match ${NAMESPACE_RE}`);
+  }
+  if (!Array.isArray(compose?.expose) || compose.expose.length === 0) {
+    errors.push(`${label}: expose must list at least one pi tool`);
+  } else {
+    const seen = new Set();
+    for (const exposed of compose.expose) {
+      if (!TOOL_NAME_RE.test(exposed)) {
+        errors.push(`${label}: expose "${exposed}" must match ${TOOL_NAME_RE}`);
+      }
+      if (seen.has(exposed)) {
+        errors.push(`${label}: duplicate exposed tool "${exposed}"`);
+      }
+      seen.add(exposed);
+    }
+  }
+  if (compose?.verified !== true) {
+    warnings.push(`${label}: ${compose?.source || 'pi package'} is unverified; hosted Studios require verified pi packages`);
+  }
+
+  return { errors, warnings };
+}
+
+export function expandComposedTools(pluginName, pluginDir, composes = []) {
+  const tools = [];
+  for (const compose of composes || []) {
+    for (const exposedName of compose.expose || []) {
+      tools.push({
+        name: composedToolName(compose, exposedName),
+        description: `Composed pi tool ${exposedName} from ${compose.source}`,
+        input_schema: { type: 'object', properties: {} },
+        tool: '',
+        plugin_name: pluginName,
+        _plugin_name: pluginName,
+        _plugin_dir: pluginDir,
+        _composed: {
+          kind: 'pi',
+          source: compose.source,
+          package_name: compose.package_name,
+          version_range: compose.version_range,
+          namespace: compose.as || null,
+          original_name: exposedName,
+          verified: compose.verified === true,
+        },
+      });
+    }
+  }
+  return tools;
+}

package/src/plugins/preflight.mjs

@@ -22,6 +22,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parsePluginManifestFile, validatePluginManifest } from './manifest.mjs';
+import { composedToolName, validateCompose } from './pi-compose.mjs';
 
 const TOOL_NAME_RE = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
 const AGENT_SLUG_RE = /^[a-z][a-z0-9-]{0,63}$/;
@@ -38,6 +39,8 @@ export const RESERVED_TOOL_NAMES = new Set([
   // write
   'write_file', 'write_project', 'edit_file', 'delete_file', 'shell',
   'analyze_image', 'generate_image',
+  // background jobs (PRD-102 §6.2.3) — long-running renders, builds, etc.
+  'job_output', 'job_kill', 'job_status', 'job_list',
   // agent/skill/workflow admin
   'ask_user', 'agent_create', 'agent_sync', 'agents_list',
   'skill_install', 'skill_update', 'skill_remove', 'skill_view', 'skills_list',
@@ -86,6 +89,7 @@ export async function preflightPlugin(pluginDir, opts = {}) {
   const views = manifest.spec?.workspace?.views || [];
   const mcpServers = manifest.spec?.mcpServers || {};
   const mcpServerNames = new Set(Object.keys(mcpServers));
+  const composes = manifest.spec?.composes || [];
 
   // MCP server sanity — every server should have EITHER command (stdio)
   // OR url (remote). Anything else is meaningless config.
@@ -101,6 +105,26 @@ export async function preflightPlugin(pluginDir, opts = {}) {
     }
   }
 
+  // Pi composition sanity. Composed tools become part of the agent-visible
+  // tool namespace, but they are not local files and are not imported here.
+  const composedToolNames = new Set();
+  for (const compose of composes) {
+    const validated = validateCompose(compose);
+    errors.push(...validated.errors);
+    warnings.push(...validated.warnings);
+    if (compose.as && mcpServerNames.has(compose.as)) {
+      errors.push(`Compose #${compose._index}: namespace "${compose.as}" collides with an MCP server name`);
+    }
+    for (const exposedName of compose.expose || []) {
+      const fullName = composedToolName(compose, exposedName);
+      if (composedToolNames.has(fullName)) errors.push(`Composed tool "${fullName}": duplicate name`);
+      if (RESERVED_TOOL_NAMES.has(fullName)) {
+        errors.push(`Composed tool "${fullName}": shadows a built-in tool`);
+      }
+      composedToolNames.add(fullName);
+    }
+  }
+
   // 2 + 3 + 4. Tool checks
   const toolNames = new Set();
   for (const [i, tool] of tools.entries()) {
@@ -114,6 +138,9 @@ export async function preflightPlugin(pluginDir, opts = {}) {
     if (RESERVED_TOOL_NAMES.has(tool.name)) {
       errors.push(`Tool "${t}": shadows a built-in tool — pick a different name (built-ins always win)`);
     }
+    if (composedToolNames.has(tool.name)) {
+      errors.push(`Tool "${t}": collides with a composed pi tool`);
+    }
     if (!tool.description || tool.description.length < 8) {
       warnings.push(`Tool "${t}": description is missing or very short (<8 chars) — the model uses this to decide when to call it`);
     }
@@ -166,12 +193,12 @@ export async function preflightPlugin(pluginDir, opts = {}) {
       // plugin's mcpServers. The <tool> half is discovered live.
       if (toolRef.includes('.')) {
         const serverName = toolRef.split('.', 1)[0];
-        if (!mcpServerNames.has(serverName)) {
+        if (!mcpServerNames.has(serverName) && !composedToolNames.has(toolRef)) {
           errors.push(`Agent "${slug}": tool "${toolRef}" references MCP server "${serverName}" which is not declared in mcpServers`);
         }
         continue;
       }
-      if (!toolNames.has(toolRef) && !RESERVED_TOOL_NAMES.has(toolRef)) {
+      if (!toolNames.has(toolRef) && !composedToolNames.has(toolRef) && !RESERVED_TOOL_NAMES.has(toolRef)) {
         errors.push(`Agent "${slug}": tool "${toolRef}" is not defined by this plugin and is not a built-in`);
       }
     }

package/src/plugins/registry.mjs

@@ -9,6 +9,7 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import { parsePluginManifestFile, validatePluginManifest } from './manifest.mjs';
+import { expandComposedTools } from './pi-compose.mjs';
 
 const DEFAULT_PLUGIN_DIRS = () => [
   path.join(process.cwd(), '.bahulam', 'plugins'),
@@ -159,6 +160,11 @@ export class PluginRegistry {
           _plugin_dir: plugin._dir,
         });
       }
+      tools.push(...expandComposedTools(
+        plugin.metadata?.name || '',
+        plugin._dir,
+        plugin.spec?.composes || [],
+      ));
     }
     return tools;
   }

package/src/terminal/main.mjs

@@ -24,9 +24,10 @@ const subcommand = process.argv[2];
 const subcommandArgs = process.argv.slice(3);
 
 const PLUGIN_MANAGEMENT_COMMANDS = new Set([
-  'install', 'validate', 'check', 'lint',
+  'validate', 'check', 'lint',
   'list', 'ls', 'remove', 'rm', 'uninstall',
   'enable', 'disable', 'info', 'update', 'upgrade',
+  'doctor',
 ]);
 
 function parsePluginArgs(argv) {
@@ -63,14 +64,13 @@ function parsePluginArgs(argv) {
   }
   if (positional.length && PLUGIN_MANAGEMENT_COMMANDS.has(positional[0].toLowerCase())) {
     parsed.action = positional.shift().toLowerCase();
-    if (parsed.action === 'install') parsed.source = positional.shift() || null;
-    else if (['validate', 'check', 'lint'].includes(parsed.action)) {
+    if (['validate', 'check', 'lint'].includes(parsed.action)) {
       // Accepts either a directory path or an installed plugin name.
       const arg = positional.shift() || null;
       if (arg && (arg.includes('/') || fs.existsSync?.(arg))) parsed.source = arg;
       else parsed.pluginName = arg;
     }
-    else if (['info', 'remove', 'rm', 'uninstall', 'enable', 'disable', 'update', 'upgrade'].includes(parsed.action)) {
+    else if (['info', 'remove', 'rm', 'uninstall', 'enable', 'disable', 'update', 'upgrade', 'doctor'].includes(parsed.action)) {
       parsed.pluginName = positional.shift() || null;
     }
   } else {
@@ -279,7 +279,28 @@ async function main() {
     return;
   }
 
+  if (subcommand === 'pull') {
+    const { handlePullCommand } = await import('../commands/install.mjs');
+    await handlePullCommand(subcommandArgs, { cwd: process.cwd() });
+    return;
+  }
+
+  if (subcommand === 'install') {
+    const { handleInstallCommand } = await import('../commands/install.mjs');
+    await handleInstallCommand(subcommandArgs, { cwd: process.cwd() });
+    return;
+  }
+
   if (subcommand === 'plugin' || subcommand === 'plugins') {
+    // `install`/`pull` moved to top-level. Detect the old form and redirect.
+    if (subcommandArgs[0] === 'install' || subcommandArgs[0] === 'pull') {
+      const verb = subcommandArgs[0];
+      const rest = subcommandArgs.slice(1);
+      process.stderr.write(`\x1b[33m!\x1b[0m \`bahulam plugin ${verb}\` moved to top-level. Use:\n`);
+      process.stderr.write(`    \x1b[36mbahulam install ${rest.join(' ')}\x1b[0m   (pack — scaffolds around pi:, installs git/tarball/local)\n`);
+      process.stderr.write(`    \x1b[36mbahulam pull ${rest.join(' ')}\x1b[0m      (ingredient only — pi: sources)\n`);
+      process.exit(2);
+    }
     const args = parsePluginArgs(subcommandArgs);
     if (args.action && args.action !== 'open') {
       const { handlePluginManagementCommand } = await import('../commands/plugin-manage.mjs');
@@ -332,8 +353,14 @@ async function main() {
     bahulam workspace list         List recent local workspace sessions
     bahulam local open [path]      Alias for workspace open
 
-  \x1b[1mPlugins:\x1b[0m
-    bahulam plugin <name> [path]   Open a workspace with a named plugin
+  \x1b[1mPacks & ingredients:\x1b[0m
+    bahulam pull pi:<name>         Pull a pi ingredient (composable, not runnable on its own)
+    bahulam install pi:<name>      Pull ingredient + scaffold a full Bahulam pack around it
+    bahulam install <git-url>      Install a hand-authored pack from git
+    bahulam install <local-path>   Install a hand-authored pack from disk
+    bahulam plugin list            List installed packs and pi ingredients
+    bahulam plugin remove <name>   Remove an installed pack
+    bahulam plugin <name> [path]   Open a workspace with an installed pack
 
   \x1b[1mAnalytics:\x1b[0m
     bahulam sessions               List recent local sessions

package/src/terminal/paste-input.mjs

@@ -0,0 +1,23 @@
+export function isRawMultilinePasteChunk(text) {
+  const value = String(text || '');
+  if (!value) return false;
+  if (!/[\r\n]/.test(value)) return false;
+
+  const withoutLineBreaks = value.replace(/[\r\n]/g, '');
+  if (!withoutLineBreaks.length) return false;
+
+  // A single printable char followed by Enter can be delivered in one chunk
+  // by some terminals; keep that as normal line submission.
+  return withoutLineBreaks.length > 1 || value.split(/\r?\n|\r/).length > 2;
+}
+
+export function normalizePastedText(text) {
+  return String(text || '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+export function pastedTextLabel(text) {
+  const value = normalizePastedText(text);
+  const lines = value ? value.split('\n').length : 0;
+  if (lines > 1) return `[text copied · ${lines} lines]`;
+  return '[text copied]';
+}