@bahulam/code 0.1.12 → 0.1.13

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}$/;
@@ -86,6 +87,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 +103,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 +136,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 +191,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,7 +24,7 @@ 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',
 ]);
@@ -63,8 +63,7 @@ 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;
@@ -279,7 +278,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 +352,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]';
+}

package/src/terminal/repl.mjs

@@ -71,6 +71,7 @@ import { PluginRegistry } from '../plugins/registry.mjs';
 import { SessionManager } from '../core/session-manager.mjs';
 import { parseArgs } from '../config/cli-args.mjs';
 import { pickModelOverridesForm } from './repl-model-form.mjs';
+import { isRawMultilinePasteChunk, normalizePastedText, pastedTextLabel } from './paste-input.mjs';
 import {
   MODEL_CATEGORY_ORDER,
   formatCategoryBadge,
@@ -4857,6 +4858,9 @@ export async function startTerminalRepl() {
   let _bracketedPasteStartLine = '';
   let _bracketedPasteStartCursor = 0;
   let _promptHasInsertedPaste = false;
+  let _suppressRawPasteLines = false;
+  let _pastedInputValue = '';
+  let _pastedInputLabel = '';
   const _pasteEndListeners = new Set();
   function onBracketedPasteEnd(cb) { _pasteEndListeners.add(cb); return () => _pasteEndListeners.delete(cb); }
   function isInBracketedPaste() { return _inBracketedPaste; }
@@ -4876,7 +4880,25 @@ export async function startTerminalRepl() {
       while (i < s.length) {
         if (!_inBracketedPaste) {
           const start = s.indexOf(PASTE_BEGIN, i);
-          if (start === -1) return;
+          if (start === -1) {
+            if (isRawMultilinePasteChunk(s)) {
+              _suppressRawPasteLines = true;
+              const baseLine = String(rl?.line || '');
+              const baseCursor = typeof rl?.cursor === 'number' ? rl.cursor : baseLine.length;
+              setImmediate(() => {
+                try {
+                  insertPromptText(normalizePastedText(s), {
+                    baseLine,
+                    baseCursor,
+                    fromPaste: true,
+                  });
+                } finally {
+                  _suppressRawPasteLines = false;
+                }
+              });
+            }
+            return;
+          }
           _inBracketedPaste = true;
           _bracketedPasteBuffer = '';
           _suppressBracketedPasteLines = true;
@@ -5138,7 +5160,11 @@ export async function startTerminalRepl() {
     const line = String(baseLine || '');
     const cursor = typeof baseCursor === 'number' ? Math.max(0, Math.min(line.length, baseCursor)) : line.length;
     const next = `${line.slice(0, cursor)}${payload}${line.slice(cursor)}`;
-    if (fromPaste) _promptHasInsertedPaste = true;
+    if (fromPaste) {
+      _promptHasInsertedPaste = true;
+      _pastedInputValue = next;
+      _pastedInputLabel = pastedTextLabel(payload);
+    }
     replaceReadlineLine(next, cursor + payload.length);
     renderIdleDockInput();
   }
@@ -5178,15 +5204,28 @@ export async function startTerminalRepl() {
 
   function renderIdleDockInput() {
     if (!isInputDockMounted()) return false;
+    const line = rl.line || '';
+    let displayLine = line;
+    let displayCursor = typeof rl.cursor === 'number' ? rl.cursor : null;
+    let fixedRows = null;
+    if (_pastedInputValue && line === _pastedInputValue) {
+      displayLine = _pastedInputLabel;
+      displayCursor = _pastedInputLabel.length;
+      fixedRows = 1;
+    } else if (_pastedInputValue) {
+      _pastedInputValue = '';
+      _pastedInputLabel = '';
+    }
     // rl.cursor is readline's byte offset within rl.line. Threading it
     // through to focusDockInput makes arrow-key navigation visually move
     // the terminal cursor within the buffer instead of always landing at
     // the end of the string.
-    return renderDockInput(userPrompt(), rl.line || '', {
+    return renderDockInput(userPrompt(), displayLine, {
       context: buildContextStrip(),
       meta: buildDockMeta(),
       tips: idleInputTips(),
-      cursor: typeof rl.cursor === 'number' ? rl.cursor : null,
+      cursor: displayCursor,
+      fixedRows,
     });
   }
 
@@ -5232,7 +5271,7 @@ export async function startTerminalRepl() {
     readline.emitKeypressEvents(process.stdin, rl);
     process.stdin.on('keypress', (_str, key = {}) => {
       if (!inputActive) return;
-      if (_inBracketedPaste || _suppressBracketedPasteLines) return;
+      if (_inBracketedPaste || _suppressBracketedPasteLines || _suppressRawPasteLines) return;
       if (key.name === 'return' || key.name === 'enter') return;
       if (key.name === 'f2') {
         clearSlashHint();
@@ -5243,7 +5282,7 @@ export async function startTerminalRepl() {
       }
       setImmediate(() => {
         if (!inputActive) return;
-        if (_inBracketedPaste || _suppressBracketedPasteLines) return;
+        if (_inBracketedPaste || _suppressBracketedPasteLines || _suppressRawPasteLines) return;
         if (slashHintVisible && key.name === 'tab' && acceptSlashHint()) return;
         if (slashHintVisible && key.name === 'down' && moveSlashHintSelection(1)) return;
         if (slashHintVisible && key.name === 'up' && moveSlashHintSelection(-1)) return;
@@ -5305,12 +5344,16 @@ export async function startTerminalRepl() {
     if (pastedLines.length > 1 || trailing) {
       const text = [...pastedLines, trailing].join('\n');
       _promptHasInsertedPaste = true;
+      _pastedInputValue = text;
+      _pastedInputLabel = pastedTextLabel(text);
       replaceReadlineLine(text);
       renderIdleDockInput();
       return;
     }
     const line = pastedLines.join('\n');
     _promptHasInsertedPaste = false;
+    _pastedInputValue = '';
+    _pastedInputLabel = '';
     queueOrRunLine(line);
   }
 
@@ -5320,7 +5363,7 @@ export async function startTerminalRepl() {
   // or the user pressed Enter normally), the debounce falls back to old
   // behavior — a single Enter flushes almost instantly.
   rl.on('line', async (line) => {
-    if (_suppressBracketedPasteLines) {
+    if (_suppressBracketedPasteLines || _suppressRawPasteLines) {
       _pasteLines = [];
       if (_pasteFlushTimer) {
         clearTimeout(_pasteFlushTimer);
@@ -5369,6 +5412,8 @@ export async function startTerminalRepl() {
     let input = line.trim();
     const selectedSlashCommand = selectedSlashCommandFor(input);
     inputActive = false;
+    _pastedInputValue = '';
+    _pastedInputLabel = '';
     clearSlashHint();
     if (selectedSlashCommand) input = selectedSlashCommand;
     if (!input) {

package/src/tools/registry.mjs

@@ -122,6 +122,25 @@ export function createToolRegistry({
             const name = String(toolDef.name || '').trim();
             if (!name || tools.has(name)) continue;
             const pluginName = toolDef._plugin_name || toolDef.plugin_name || null;
+            if (toolDef._composed?.kind === 'pi') {
+                tools.set(name, {
+                    name,
+                    description: toolDef.description || '',
+                    inputSchema: toolDef.input_schema || toolDef.parameters || { type: 'object', properties: {} },
+                    validateInput() { return []; },
+                    async call() {
+                        return {
+                            success: false,
+                            output: `Composed pi tool '${name}' is registered but pi runtime execution is not wired yet`,
+                            _tool: name,
+                            _plugin: pluginName,
+                            _composed: toolDef._composed,
+                            _blocked: true,
+                        };
+                    },
+                });
+                continue;
+            }
             tools.set(name, {
                 name,
                 description: toolDef.description || '',

package/src/ui/input-dock.mjs

@@ -672,10 +672,13 @@ export function clearInputPrompt() {
   return true;
 }
 
-export function renderDockInput(prefix, value, { context = '', tips = '', meta = '', cursor = null } = {}) {
+export function renderDockInput(prefix, value, { context = '', tips = '', meta = '', cursor = null, fixedRows = null } = {}) {
   if (!mounted) return false;
   contentTrackingActive = false;
-  setInputRowsTo(computeInputRowsForBuffer(prefix, value));
+  const requestedRows = fixedRows == null
+    ? computeInputRowsForBuffer(prefix, value)
+    : Math.max(MIN_INPUT_ROWS, Math.min(inputRowsMax, Math.floor(Number(fixedRows) || MIN_INPUT_ROWS)));
+  setInputRowsTo(requestedRows);
   renderFrame({ context, tips, meta, prefix, value, cursor, overlayLines: null });
   const layout = layoutInput(prefix, value);
   drawInputLines(layout.lines);