@bahulam/code 0.1.13 → 0.1.15

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

@@ -0,0 +1,465 @@
+/**
+ * Static requirements analyzer for an installed pi ingredient.
+ *
+ * Walks the package's source files and detects the failure-mode signals
+ * a composed pack will hit at first tool call: shell binaries the pi
+ * package spawns, env vars / API keys it reads, workspace-scoping of
+ * paths, and per-tool schema constraints already surfaced by the probe.
+ *
+ * Emits `<pi-dir>/.bahulam-requirements.json` alongside the tool cache.
+ * Runs after `discoverPiTools` during pull/install so the CLI can print
+ * findings before the user commits to using the pack.
+ *
+ * Explicitly not-an-LLM: uses regex + JSON reads + Markdown section
+ * matching. Fast (< 500ms for a big package), safe, no network. If a
+ * requirement slips past the static heuristics, the user pastes the
+ * error into Bahulam and the main agent reasons about it.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+
+export const REQUIREMENTS_FILE = '.bahulam-requirements.json';
+
+// Known binary → install hint DB. Extend as we learn new pi packages.
+// Keep it small and honest: unknown binaries just report the name.
+const INSTALL_HINTS = {
+  ffmpeg:      { darwin: 'brew install ffmpeg',         linux: 'apt install -y ffmpeg' },
+  ffprobe:     { darwin: 'brew install ffmpeg',         linux: 'apt install -y ffmpeg' },
+  imagemagick: { darwin: 'brew install imagemagick',    linux: 'apt install -y imagemagick' },
+  convert:     { darwin: 'brew install imagemagick',    linux: 'apt install -y imagemagick' },
+  magick:      { darwin: 'brew install imagemagick',    linux: 'apt install -y imagemagick' },
+  docker:      { darwin: 'brew install --cask docker',  linux: 'https://docs.docker.com/engine/install/' },
+  git:         { darwin: 'brew install git',            linux: 'apt install -y git' },
+  python:      { darwin: 'brew install python',         linux: 'apt install -y python3' },
+  python3:     { darwin: 'brew install python',         linux: 'apt install -y python3' },
+  node:        { darwin: 'brew install node',           linux: 'apt install -y nodejs' },
+  yt_dlp:      { darwin: 'brew install yt-dlp',         linux: 'pip install yt-dlp' },
+  'yt-dlp':    { darwin: 'brew install yt-dlp',         linux: 'pip install yt-dlp' },
+  pandoc:      { darwin: 'brew install pandoc',         linux: 'apt install -y pandoc' },
+  tesseract:   { darwin: 'brew install tesseract',      linux: 'apt install -y tesseract-ocr' },
+};
+
+// Shell keywords that mean "the arg after me is the binary" when
+// child_process is invoked with a shell wrapper like `sh -c '...'`.
+const SHELL_WRAPPERS = new Set(['sh', 'bash', 'zsh', 'cmd', 'cmd.exe', 'powershell', 'pwsh']);
+
+// Env var names we treat as "credential-ish" by heuristic. Not exhaustive —
+// falls back to any UPPER_SNAKE ending in these tokens.
+const CREDENTIAL_SUFFIXES = ['_KEY', '_TOKEN', '_SECRET', '_PASSWORD', '_APIKEY', '_API_KEY', '_ACCESS_KEY', '_ACCESS_TOKEN'];
+
+// Files we scan. .ts/.mjs/.js/.cjs — pi packages sometimes ship pure TS.
+const SOURCE_EXT_RE = /\.(ts|tsx|mts|cts|mjs|cjs|js)$/;
+
+// Directories we skip (bloat + third-party code we don't want to attribute
+// as pi's requirements).
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', 'coverage', 'tests', '__tests__', 'test']);
+
+// Cap the scan so an accidentally-huge package doesn't hang.
+const MAX_FILES = 400;
+const MAX_FILE_BYTES = 512 * 1024; // skip anything > 512KB (minified bundles)
+
+function walkSources(dir, out, budget) {
+  if (out.length >= MAX_FILES) return;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; }
+  for (const entry of entries) {
+    if (out.length >= MAX_FILES) return;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+      walkSources(full, out, budget);
+    } else if (entry.isFile() && SOURCE_EXT_RE.test(entry.name)) {
+      try {
+        const stat = fs.statSync(full);
+        if (stat.size > MAX_FILE_BYTES) continue;
+        out.push(full);
+      } catch { /* skip */ }
+    }
+  }
+}
+
+function readTextSafe(p) {
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return ''; }
+}
+
+/**
+ * Extract the binary name from a spawn/exec/execFile call. Handles:
+ *   spawn('ffmpeg', ...)         → ffmpeg
+ *   spawn("bash", ["-c", "ff"])  → ffmpeg (peek shell args)
+ *   exec('ffprobe -v error ...') → ffprobe
+ *   execFile("./bin/foo", ...)   → foo (skip — local script, not a system dep)
+ *   spawn(cmd, ...)              → skipped (variable, we can't infer)
+ */
+function extractBinaryFromCall(callKind, argText) {
+  const trimmed = argText.trim();
+  const m = trimmed.match(/^(['"`])(.+?)\1/);
+  if (!m) return null;
+  let first = m[2].trim();
+
+  if (callKind === 'exec' || callKind === 'execSync') {
+    // First token of a shell command line.
+    const token = first.split(/\s+/)[0] || '';
+    const clean = token.replace(/^['"]|['"]$/g, '');
+    const base = path.basename(clean).replace(/\.(exe|bat|cmd)$/i, '');
+    if (!base || base.startsWith('/') || base.startsWith('.') || base.startsWith('$')) return null;
+    if (!/^[a-zA-Z0-9_.+-]+$/.test(base)) return null;
+    return base;
+  }
+  if (callKind === 'spawn' || callKind === 'spawnSync' || callKind === 'execFile' || callKind === 'execFileSync') {
+    const base = path.basename(first).replace(/\.(exe|bat|cmd)$/i, '');
+    if (!base || first.startsWith('./') || first.startsWith('../') || first.startsWith('/')) {
+      // Local path — a bundled script, not a system requirement
+      return null;
+    }
+    if (!/^[a-zA-Z0-9_.+-]+$/.test(base)) return null;
+    // Special-case shell wrappers: peek the args array for the real binary
+    if (SHELL_WRAPPERS.has(base)) {
+      const argsMatch = trimmed.match(/,\s*\[(.*?)\]/s);
+      if (argsMatch) {
+        const argsText = argsMatch[1];
+        // Look for the first quoted arg after a "-c" flag
+        const cMatch = argsText.match(/['"`]-c['"`]\s*,\s*['"`]([^'"`]+)['"`]/);
+        if (cMatch) {
+          const innerBin = cMatch[1].trim().split(/\s+/)[0] || '';
+          const innerBase = path.basename(innerBin).replace(/\.(exe|bat|cmd)$/i, '');
+          if (innerBase && /^[a-zA-Z0-9_.+-]+$/.test(innerBase)) return innerBase;
+        }
+      }
+      return null;
+    }
+    return base;
+  }
+  return null;
+}
+
+/**
+ * Scan a single source file for shell/env/path signals. Purely textual —
+ * we skip AST parsing to keep the analyzer dependency-free and fast.
+ * False positives are acceptable; the alternative (missing a real dep)
+ * is worse. Users see a list they can eyeball.
+ */
+// Binary names we recognize in string literals or env var infixes when
+// direct spawn arg detection misses (spawn(variable, ...) is common).
+const KNOWN_BINARY_TOKENS = ['ffmpeg', 'ffprobe', 'imagemagick', 'convert', 'magick', 'docker', 'git', 'python', 'python3', 'node', 'yt-dlp', 'ytdlp', 'pandoc', 'tesseract', 'sox', 'gs', 'ghostscript', 'poppler', 'pdftotext', 'pdfinfo', 'lame', 'oggenc', 'flac', 'curl', 'wget', 'rsync', 'jq', 'yq', 'awk', 'sed'];
+
+function analyzeFile(text, rel, findings) {
+  // Shell binary calls: spawn/spawnSync/exec/execSync/execFile/execFileSync
+  const shellRe = /\b(spawn|spawnSync|exec|execSync|execFile|execFileSync)\s*\(\s*([^)]{0,300})\)/g;
+  let m;
+  let sawChildProcess = /\bfrom\s*['"]node:child_process['"]|require\(\s*['"]node:child_process['"]/.test(text)
+    || /\bfrom\s*['"]child_process['"]|require\(\s*['"]child_process['"]/.test(text);
+  while ((m = shellRe.exec(text)) !== null) {
+    sawChildProcess = true;
+    const kind = m[1];
+    const bin = extractBinaryFromCall(kind, m[2]);
+    if (!bin) continue;
+    const existing = findings.systemBinaries.get(bin) || { name: bin, seen_in: new Set() };
+    existing.seen_in.add(rel);
+    findings.systemBinaries.set(bin, existing);
+  }
+
+  // Env vars: process.env.XXX or process.env['XXX']
+  const envRe = /\bprocess\.env\s*(?:\.([A-Z][A-Z0-9_]{2,})|\[\s*['"`]([A-Z][A-Z0-9_]{2,})['"`]\s*\])/g;
+  while ((m = envRe.exec(text)) !== null) {
+    const name = m[1] || m[2];
+    if (!name) continue;
+    // Ignore Node.js / OS-level env vars users don't set for a plugin.
+    if (['NODE_ENV', 'PATH', 'HOME', 'USER', 'PWD', 'SHELL', 'TERM', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR', 'TMP', 'TEMP'].includes(name)) continue;
+    const existing = findings.envVars.get(name) || { name, seen_in: new Set(), credential: false };
+    existing.seen_in.add(rel);
+    if (CREDENTIAL_SUFFIXES.some(s => name.endsWith(s))) existing.credential = true;
+    findings.envVars.set(name, existing);
+
+    // If an env var name contains a known binary token (e.g. PI_MEDIA_FFMPEG_BINARY,
+    // FFPROBE_PATH, IMAGEMAGICK_HOME), the package is almost certainly
+    // shelling out to that binary — even when the actual spawn() takes a
+    // variable, not a literal. This catches the common override-your-binary
+    // pattern many pi packages use.
+    const lower = name.toLowerCase();
+    for (const tok of KNOWN_BINARY_TOKENS) {
+      if (lower.includes(tok.replace('-', '_'))) {
+        const existing2 = findings.systemBinaries.get(tok) || { name: tok, seen_in: new Set() };
+        existing2.seen_in.add(`inferred from env var ${name}`);
+        findings.systemBinaries.set(tok, existing2);
+      }
+    }
+  }
+
+  // Fallback: if child_process is imported but spawn args are variables
+  // (spawn(cmd, ...)) rather than literals, look for known binary names as
+  // string literals anywhere in the file. False-positive risk (a comment or
+  // an error message could mention 'ffmpeg'), but the alternative is
+  // missing the requirement entirely — users can review the findings list.
+  if (sawChildProcess && findings.systemBinaries.size === 0) {
+    for (const tok of KNOWN_BINARY_TOKENS) {
+      const litRe = new RegExp(`['"\`]${tok.replace(/[-]/g, '\\-')}['"\`]`, 'i');
+      if (litRe.test(text)) {
+        const existing = findings.systemBinaries.get(tok) || { name: tok, seen_in: new Set() };
+        existing.seen_in.add(`literal in ${rel}`);
+        findings.systemBinaries.set(tok, existing);
+      }
+    }
+  }
+
+  // Workspace-scoping heuristic: the pi convention is `ctx.cwd` used in a
+  // path resolve/join, followed by a throw about "outside" or "workspace".
+  if (!findings.workspaceScopedPaths) {
+    if (/ctx\s*\.\s*cwd/.test(text) && /(outside|not.*inside|workspace)/i.test(text) && /throw\b/.test(text)) {
+      findings.workspaceScopedPaths = true;
+    }
+  }
+}
+
+function analyzePackageJson(pkg, findings) {
+  // Author-declared runtime hints.
+  const opt = pkg.optionalDependencies || {};
+  for (const name of Object.keys(opt)) {
+    // Heuristic: optionalDependencies named after known binaries.
+    if (INSTALL_HINTS[name]) {
+      const existing = findings.systemBinaries.get(name) || { name, seen_in: new Set(['package.json:optionalDependencies']) };
+      findings.systemBinaries.set(name, existing);
+    }
+  }
+  // engines / os could add platform hints — record but don't overweight.
+  if (pkg.engines) findings.enginesRequirement = pkg.engines;
+  if (pkg.os) findings.osRequirement = pkg.os;
+  if (pkg.cpu) findings.cpuRequirement = pkg.cpu;
+}
+
+function extractReadmeSections(readmeText) {
+  if (!readmeText) return [];
+  const sections = [];
+  const wanted = /^\s*#{1,3}\s+(requirements?|prerequisites?|installation|setup|dependencies|before you begin)\b/i;
+  const lines = readmeText.split('\n');
+  let inSection = false;
+  let title = '';
+  let body = [];
+  const flush = () => {
+    if (inSection) {
+      const text = body.join('\n').trim();
+      if (text) sections.push({ title: title.trim(), body: text.slice(0, 2000) });
+    }
+    inSection = false; title = ''; body = [];
+  };
+  for (const line of lines) {
+    if (wanted.test(line)) {
+      flush();
+      inSection = true;
+      title = line.replace(/^\s*#+\s*/, '');
+      continue;
+    }
+    if (inSection && /^\s*#{1,3}\s/.test(line)) { flush(); continue; }
+    if (inSection) body.push(line);
+  }
+  flush();
+  return sections;
+}
+
+function extractSkillsFiles(pluginDir) {
+  const skills = [];
+  const dirs = ['skills', 'SKILLS'];
+  for (const d of dirs) {
+    const full = path.join(pluginDir, d);
+    try {
+      const stat = fs.statSync(full);
+      if (!stat.isDirectory()) continue;
+      for (const f of fs.readdirSync(full)) {
+        if (/\.(md|markdown|mdx)$/i.test(f)) skills.push(path.join(d, f));
+      }
+    } catch { /* skip */ }
+  }
+  // Root-level SKILL.md
+  for (const name of ['SKILL.md', 'skill.md', 'AGENTS.md']) {
+    if (fs.existsSync(path.join(pluginDir, name))) skills.push(name);
+  }
+  return skills;
+}
+
+function extractToolConstraints(discoveredTools) {
+  const out = {};
+  for (const tool of discoveredTools || []) {
+    const s = tool.input_schema || {};
+    const props = s.properties || {};
+    const required = new Set(s.required || []);
+    const perParam = {};
+    for (const [name, def] of Object.entries(props)) {
+      const c = {};
+      if (def.pattern) c.regex = def.pattern;
+      if (typeof def.minLength === 'number') c.min_length = def.minLength;
+      if (typeof def.maxLength === 'number') c.max_length = def.maxLength;
+      if (typeof def.minimum === 'number') c.min = def.minimum;
+      if (typeof def.maximum === 'number') c.max = def.maximum;
+      if (Array.isArray(def.enum)) c.enum = def.enum;
+      if (required.has(name)) c.required = true;
+      if (Object.keys(c).length) perParam[name] = c;
+    }
+    if (Object.keys(perParam).length) out[tool.name] = perParam;
+  }
+  return out;
+}
+
+/**
+ * Analyze an installed pi ingredient. Returns the requirements object
+ * AND writes it to `<pluginDir>/.bahulam-requirements.json`.
+ *
+ * @param {string} pluginDir — absolute path to the ingredient dir
+ * @param {Object} [opts]
+ * @param {Object} [opts.discoveredTools] — parsed .bahulam-tools.json, if
+ *   the caller already has it. Otherwise skips tool-constraint extraction.
+ */
+export function analyzeRequirements(pluginDir, { discoveredTools = null } = {}) {
+  const findings = {
+    systemBinaries: new Map(),
+    envVars: new Map(),
+    workspaceScopedPaths: false,
+    enginesRequirement: null,
+    osRequirement: null,
+    cpuRequirement: null,
+  };
+
+  // Package.json hints
+  const pkgPath = path.join(pluginDir, 'package.json');
+  let pkg = {};
+  try { pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')); } catch { /* skip */ }
+  analyzePackageJson(pkg, findings);
+
+  // Walk sources
+  const files = [];
+  walkSources(pluginDir, files, MAX_FILES);
+  for (const abs of files) {
+    const rel = path.relative(pluginDir, abs);
+    analyzeFile(readTextSafe(abs), rel, findings);
+  }
+
+  // README requirements
+  const readmeCandidates = ['README.md', 'readme.md', 'README', 'readme.markdown'];
+  let readmeText = '';
+  for (const r of readmeCandidates) {
+    const full = path.join(pluginDir, r);
+    if (fs.existsSync(full)) { readmeText = readTextSafe(full); break; }
+  }
+  const readmeSections = extractReadmeSections(readmeText);
+
+  // Skills discovery
+  const skills = extractSkillsFiles(pluginDir);
+
+  // Tool constraints from probed schemas (caller supplies)
+  const toolConstraints = discoveredTools ? extractToolConstraints(discoveredTools.tools || []) : {};
+
+  // Assemble the sidecar
+  const shape = {
+    version: 1,
+    analyzed_at: new Date().toISOString(),
+    files_scanned: files.length,
+    truncated: files.length >= MAX_FILES,
+    system_binaries: [...findings.systemBinaries.values()]
+      .map(v => ({
+        name: v.name,
+        install_hints: INSTALL_HINTS[v.name] || null,
+        seen_in: [...v.seen_in].slice(0, 5),
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name)),
+    env_vars: [...findings.envVars.values()]
+      .map(v => ({
+        name: v.name,
+        credential: v.credential,
+        seen_in: [...v.seen_in].slice(0, 5),
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name)),
+    workspace_scoped_paths: findings.workspaceScopedPaths,
+    engines: findings.enginesRequirement,
+    os: findings.osRequirement,
+    cpu: findings.cpuRequirement,
+    readme_sections: readmeSections,
+    skills_available: skills,
+    tool_constraints: toolConstraints,
+  };
+
+  try {
+    fs.writeFileSync(path.join(pluginDir, REQUIREMENTS_FILE), JSON.stringify(shape, null, 2));
+  } catch { /* non-fatal; findings still returned to caller */ }
+
+  return shape;
+}
+
+/**
+ * Format a requirements report for terminal output. Compact, actionable,
+ * no color codes (caller adds ANSI wrappers around specific tokens).
+ * Returns an array of {level, text} lines: level ∈ 'info' | 'warn' | 'ok'.
+ */
+export function formatRequirementsReport(reqs, { verbose = false } = {}) {
+  const lines = [];
+  if (!reqs) return lines;
+
+  if (reqs.system_binaries?.length) {
+    lines.push({ level: 'warn', text: `system binaries required: ${reqs.system_binaries.map(b => b.name).join(', ')}` });
+    if (verbose) {
+      for (const b of reqs.system_binaries) {
+        const hint = b.install_hints?.darwin || b.install_hints?.linux;
+        lines.push({ level: 'info', text: `   ${b.name}${hint ? ` — install: ${hint}` : ''}` });
+      }
+    }
+  }
+  if (reqs.env_vars?.length) {
+    const creds = reqs.env_vars.filter(v => v.credential);
+    const other = reqs.env_vars.filter(v => !v.credential);
+    if (creds.length) lines.push({ level: 'warn', text: `API keys / credentials: ${creds.map(v => v.name).join(', ')}` });
+    if (other.length && verbose) lines.push({ level: 'info', text: `other env vars: ${other.map(v => v.name).join(', ')}` });
+  }
+  if (reqs.workspace_scoped_paths) {
+    lines.push({ level: 'info', text: 'paths must be workspace-relative (relative to cwd)' });
+  }
+  if (reqs.readme_sections?.length) {
+    lines.push({ level: 'info', text: `README notes ${reqs.readme_sections.length} section(s): ${reqs.readme_sections.map(s => s.title).join(', ')}` });
+  }
+  if (reqs.skills_available?.length) {
+    lines.push({ level: 'info', text: `skills available: ${reqs.skills_available.join(', ')}` });
+  }
+  if (!lines.length) {
+    lines.push({ level: 'ok', text: 'no external requirements detected — pure JS/TS + npm deps' });
+  }
+  return lines;
+}
+
+/**
+ * Check requirements against the host environment. Used by `plugin doctor`.
+ * Returns per-item results — caller prints and decides exit code.
+ */
+export function checkRequirementsAgainstHost(reqs) {
+  const results = { binaries: [], env_vars: [] };
+
+  const isWin = process.platform === 'win32';
+  const whichCmd = isWin ? 'where' : 'command -v';
+  for (const b of reqs?.system_binaries || []) {
+    let found = false, resolvedPath = null, version = null;
+    try {
+      const out = execSync(`${whichCmd} ${b.name}`, {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        shell: isWin ? undefined : '/bin/sh',
+      }).trim();
+      resolvedPath = out.split(/\r?\n/)[0] || null;
+      found = Boolean(resolvedPath);
+    } catch { found = false; }
+    if (found) {
+      try {
+        version = execSync(`${b.name} --version`, {
+          encoding: 'utf-8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        }).split(/\r?\n/)[0].trim();
+      } catch { /* skip */ }
+    }
+    results.binaries.push({ name: b.name, found, path: resolvedPath, version, install_hints: b.install_hints });
+  }
+
+  for (const v of reqs?.env_vars || []) {
+    const value = process.env[v.name];
+    results.env_vars.push({ name: v.name, credential: v.credential, set: Boolean(value && value.length) });
+  }
+
+  return results;
+}
+

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

@@ -24,20 +24,24 @@ import * as path from 'node:path';
 import { COMPOSED_TOOL_SEPARATOR } from '../pi-compose.mjs';
 
 /**
- * Derive a pack slug from a pi package name.
- *   pi-web-access → web-access-studio
- *   pi-redmine    → redmine-studio
- *   @ffmpeg/transitions → transitions-studio
- *   plain-name    → plain-name-studio
+ * Derive a pack slug from a source package name. No forced suffix — a
+ * pack can be anything (studio, analyzer, connector, worker, …), and
+ * pinning a semantic to the slug guesses wrong most of the time. The
+ * default is the source name, sanitized. Author overrides with --slug.
+ *
+ *   pi-web-access        → pi-web-access
+ *   pi-redmine           → pi-redmine
+ *   @ffmpeg/transitions  → transitions        (scope stripped)
+ *   filesystem-mcp       → filesystem-mcp
+ *   plain-name           → plain-name
  */
 export function deriveSlug(packageName) {
   let base = String(packageName || '').trim();
   const scoped = base.match(/^@[^/]+\/(.+)$/);
   if (scoped) base = scoped[1];
-  base = base.replace(/^pi-/, '');
   base = base.replace(/[^a-z0-9-]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase();
-  if (!base) base = 'pi-pack';
-  return `${base}-studio`;
+  if (!base) base = 'pack';
+  return base;
 }
 
 /**
@@ -77,13 +81,75 @@ function truncate(s, n) {
   return str.slice(0, n - 1) + '…';
 }
 
+/**
+ * Compose the "Requirements & constraints" block from the analyzer's
+ * findings. Injected into the generated agent's system prompt so the
+ * sub-agent knows what its composed tools need — no user teaching
+ * required. Falls back to an empty list if requirements is absent (fresh
+ * install where the analyzer didn't run, etc.).
+ */
+function requirementsPromptLines(requirements, namespace) {
+  if (!requirements) return [];
+  const lines = ['', 'Requirements & constraints (from ingredient analysis):'];
+  const bins = requirements.system_binaries || [];
+  if (bins.length) {
+    const names = bins.map(b => b.name).join(', ');
+    lines.push(
+      `- System binaries required: ${names}. If a tool errors with "ENOENT" or "spawn ${bins[0].name}", tell the user to install them (macOS: \`${bins[0].install_hints?.darwin || 'via brew'}\`; Linux: \`${bins[0].install_hints?.linux || 'via package manager'}\`).`,
+    );
+  }
+  const creds = (requirements.env_vars || []).filter(v => v.credential);
+  if (creds.length) {
+    lines.push(
+      `- API keys / credentials expected: ${creds.map(v => v.name).join(', ')}. If a tool fails with an auth error, ask the user to set the missing env var.`,
+    );
+  }
+  if (requirements.workspace_scoped_paths) {
+    lines.push(
+      '- Paths passed to composed tools MUST be workspace-relative (relative to the current working directory). Absolute paths outside cwd are rejected with "Path is outside the workspace". If the user references an absolute path, ask them to `cd` closer to it or copy the file into the workspace.',
+    );
+  }
+  // Per-tool schema constraints the agent must respect. Emit BOTH required
+  // fields AND regex/range constraints — the underlying pi tools throw
+  // opaque path/type errors when a required param is missing, and the
+  // agent's default reasoning tends to skip params whose descriptions
+  // sound "optional" even when the schema marks them required.
+  const tc = requirements.tool_constraints || {};
+  const toolsWithConstraints = Object.keys(tc).filter(t => Object.keys(tc[t]).length);
+  if (toolsWithConstraints.length) {
+    lines.push('- Strict input schemas — supply EVERY required field and respect all constraints. Missing a required field usually throws an opaque error like `paths[1] argument must be of type string`:');
+    for (const t of toolsWithConstraints) {
+      const params = tc[t];
+      const required = Object.keys(params).filter(p => params[p].required);
+      const regexed = Object.entries(params).filter(([, c]) => c.regex);
+      const ranged = Object.entries(params).filter(([, c]) => c.min != null || c.max != null || c.enum);
+      if (required.length) {
+        lines.push(`    - \`${namespace}${COMPOSED_TOOL_SEPARATOR}${t}\` requires: ${required.map(p => `\`${p}\``).join(', ')}`);
+      }
+      for (const [param, c] of regexed) {
+        lines.push(`        · \`${param}\` must match \`${c.regex}\``);
+      }
+      for (const [param, c] of ranged) {
+        const parts = [];
+        if (c.min != null) parts.push(`min ${c.min}`);
+        if (c.max != null) parts.push(`max ${c.max}`);
+        if (c.enum) parts.push(`one of ${JSON.stringify(c.enum)}`);
+        lines.push(`        · \`${param}\` ${parts.join(', ')}`);
+      }
+    }
+  }
+  // If we detected no external requirements at all, keep the block out so
+  // the prompt stays clean.
+  return lines.length > 1 ? lines : [];
+}
+
 /**
  * Compose an agent system prompt from the pi package + its tools.
  * Focused on WHAT the agent should do, not step-by-step recipes — the
  * generic template can't know the pack's domain. Users are expected to
  * edit the prompt after generation.
  */
-function generatePrompt(packageName, namespace, toolNames, hasState) {
+function generatePrompt(packageName, namespace, toolNames, hasState, requirements = null) {
   const composed = toolNames.map(t => `${namespace}${COMPOSED_TOOL_SEPARATOR}${t}`);
   const stateLines = hasState
     ? [
@@ -103,6 +169,7 @@ function generatePrompt(packageName, namespace, toolNames, hasState) {
     'Available composed tools:',
     ...composed.map(t => `- \`${t}\``),
     ...stateLines,
+    ...requirementsPromptLines(requirements, namespace),
     '',
     'Rules:',
     '- Use the composed tools directly — do not describe what you would do, DO it.',
@@ -453,7 +520,16 @@ export function scaffoldPiPack({
     `Specialist agent for ${packageName}. Composes ${toolNames.length} tool${toolNames.length === 1 ? '' : 's'} exposed as ${namespace}${COMPOSED_TOOL_SEPARATOR}*.`,
     240,
   );
-  const systemPrompt = generatePrompt(packageName, namespace, toolNames, state);
+
+  // Pull the requirements sidecar the analyzer wrote at install time
+  // (may be absent if user is scaffolding manually with an older ingredient).
+  let requirements = null;
+  const reqSidecar = path.join(piDir, '.bahulam-requirements.json');
+  if (fs.existsSync(reqSidecar)) {
+    try { requirements = JSON.parse(fs.readFileSync(reqSidecar, 'utf-8')); } catch { /* skip */ }
+  }
+
+  const systemPrompt = generatePrompt(packageName, namespace, toolNames, state, requirements);
 
   const manifest = renderManifest({
     slug,

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

@@ -130,5 +130,33 @@ export function createPiShim({ pluginName = 'pi', captured }) {
     },
   };
 
-  return pi;
+  // 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/preflight.mjs

@@ -39,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',

package/src/terminal/main.mjs

@@ -27,6 +27,7 @@ const PLUGIN_MANAGEMENT_COMMANDS = new Set([
   'validate', 'check', 'lint',
   'list', 'ls', 'remove', 'rm', 'uninstall',
   'enable', 'disable', 'info', 'update', 'upgrade',
+  'doctor',
 ]);
 
 function parsePluginArgs(argv) {
@@ -69,7 +70,7 @@ function parsePluginArgs(argv) {
       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 {
@@ -296,7 +297,7 @@ async function main() {
       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 install ${rest.join(' ')}\x1b[0m   (pack — registry, scaffolds around pi:, git/tarball/local)\n`);
       process.stderr.write(`    \x1b[36mbahulam pull ${rest.join(' ')}\x1b[0m      (ingredient only — pi: sources)\n`);
       process.exit(2);
     }
@@ -355,6 +356,8 @@ async function main() {
   \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 <name>         Install from awesome-bahulam-plugins
+    bahulam install bahulam:<name> Explicit awesome-bahulam-plugins lookup
     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