botinabox 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,15 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ---
 
+## [0.3.0] — 2026-04-03
+
+### Added
+
+- **Domain tables** — `defineDomainTables(db, options?)` creates standard multi-agent app tables: org, project, client, invoice, repository, file, channel, rule, event + junction tables. Configurable: disable clients, repos, files, channels, rules, or events.
+- **Domain entity contexts** — `defineDomainEntityContexts(db, options?)` renders per-entity context directories for all domain tables. Projects get REPOS.md + RULES.md. Clients get REPOS.md + AGENTS.md + INVOICES.md.
+- **Claude stream parser** — `parseClaudeStream(stdout)` parses Claude CLI NDJSON output into structured results (session, model, cost, tokens, text, errors). Plus `isMaxTurns()`, `isLoginRequired()`, `deactivateLocalImagePaths()`.
+- **Process env builder** — `buildProcessEnv(allowedKeys?, inject?)` creates a clean subprocess environment with only safe variables. Strips all secrets.
+
 ## [0.2.0] — 2026-04-03
 
 ### Added

package/dist/index.js

@@ -1140,7 +1140,10 @@ var DataStore = class {
       protectedFiles: def.protectedFiles,
       protected: def.protected,
       encrypted: def.encrypted,
-      sourceDefaults: { softDelete: true },
+      // Note: sourceDefaults.softDelete NOT set here because junction tables
+      // (agent_project, rule_agent, etc.) don't have deleted_at columns.
+      // Entity context render functions should add softDelete per-source when targeting
+      // tables that support it.
       index: def.indexFile ? {
         outputFile: def.indexFile,
         render: def.indexRender ?? ((rows) => {
@@ -1670,6 +1673,501 @@ ${s.definition}` : null,
   });
 }
 
+// src/core/data/domain-schema.ts
+function defineDomainTables(db, options = {}) {
+  const opts = {
+    clients: true,
+    repositories: true,
+    files: true,
+    channels: true,
+    rules: true,
+    events: true,
+    ...options
+  };
+  db.define("org", {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      name: "TEXT NOT NULL",
+      type: "TEXT NOT NULL DEFAULT 'company'",
+      description: "TEXT",
+      mission: "TEXT",
+      website: "TEXT",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+      updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+      deleted_at: "TEXT"
+    }
+  });
+  db.define("project", {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      org_id: "TEXT NOT NULL",
+      name: "TEXT NOT NULL",
+      status: "TEXT",
+      description: "TEXT",
+      tech_stack: "TEXT",
+      github_repo: "TEXT",
+      deploy_target: "TEXT",
+      production_url: "TEXT",
+      branch_strategy: "TEXT",
+      notes: "TEXT",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+      updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+      deleted_at: "TEXT"
+    }
+  });
+  db.define("agent_project", {
+    columns: {
+      agent_id: "TEXT NOT NULL",
+      project_id: "TEXT NOT NULL",
+      role: "TEXT",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+    },
+    primaryKey: ["agent_id", "project_id"]
+  });
+  db.define("secret_project", {
+    columns: {
+      secret_id: "TEXT NOT NULL",
+      project_id: "TEXT NOT NULL",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+    },
+    primaryKey: ["secret_id", "project_id"]
+  });
+  db.define("secret_org", {
+    columns: {
+      secret_id: "TEXT NOT NULL",
+      org_id: "TEXT NOT NULL",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+    },
+    primaryKey: ["secret_id", "org_id"]
+  });
+  if (opts.clients) {
+    db.define("client", {
+      columns: {
+        id: "TEXT PRIMARY KEY",
+        org_id: "TEXT NOT NULL",
+        name: "TEXT NOT NULL",
+        contact_name: "TEXT",
+        contact_email: "TEXT",
+        phone: "TEXT",
+        status: "TEXT NOT NULL DEFAULT 'active'",
+        notes: "TEXT",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        deleted_at: "TEXT"
+      }
+    });
+    db.define("invoice", {
+      columns: {
+        id: "TEXT PRIMARY KEY",
+        org_id: "TEXT NOT NULL",
+        client_id: "TEXT NOT NULL",
+        number: "TEXT",
+        amount_cents: "INTEGER",
+        currency: "TEXT DEFAULT 'USD'",
+        status: "TEXT NOT NULL DEFAULT 'draft'",
+        description: "TEXT",
+        hours: "REAL",
+        rate_cents: "INTEGER",
+        items_json: "TEXT",
+        issued_at: "TEXT",
+        due_at: "TEXT",
+        paid_at: "TEXT",
+        notes: "TEXT",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        deleted_at: "TEXT"
+      },
+      tableConstraints: [
+        "CREATE INDEX IF NOT EXISTS idx_invoice_client ON invoice(client_id)"
+      ]
+    });
+    db.define("agent_client", {
+      columns: {
+        agent_id: "TEXT NOT NULL",
+        client_id: "TEXT NOT NULL",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+      },
+      primaryKey: ["agent_id", "client_id"]
+    });
+  }
+  if (opts.repositories) {
+    db.define("repository", {
+      columns: {
+        id: "TEXT PRIMARY KEY",
+        org_id: "TEXT NOT NULL",
+        project_id: "TEXT",
+        client_id: "TEXT",
+        name: "TEXT NOT NULL",
+        url: "TEXT",
+        local_path: "TEXT",
+        default_branch: "TEXT DEFAULT 'main'",
+        platform: "TEXT DEFAULT 'github'",
+        status: "TEXT NOT NULL DEFAULT 'active'",
+        notes: "TEXT",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        deleted_at: "TEXT"
+      },
+      tableConstraints: [
+        "CREATE INDEX IF NOT EXISTS idx_repository_project ON repository(project_id)",
+        "CREATE INDEX IF NOT EXISTS idx_repository_client ON repository(client_id)"
+      ]
+    });
+  }
+  if (opts.files) {
+    db.define("file", {
+      columns: {
+        id: "TEXT PRIMARY KEY",
+        org_id: "TEXT",
+        name: "TEXT NOT NULL",
+        file_path: "TEXT",
+        mime_type: "TEXT",
+        size_bytes: "INTEGER",
+        project_id: "TEXT",
+        access_level: "TEXT NOT NULL DEFAULT 'org'",
+        description: "TEXT",
+        notes: "TEXT",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        deleted_at: "TEXT"
+      }
+    });
+  }
+  if (opts.channels) {
+    db.define("channel", {
+      columns: {
+        id: "TEXT PRIMARY KEY",
+        org_id: "TEXT",
+        platform: "TEXT NOT NULL",
+        external_id: "TEXT",
+        name: "TEXT NOT NULL",
+        type: "TEXT NOT NULL DEFAULT 'channel'",
+        instructions: "TEXT",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        deleted_at: "TEXT"
+      }
+    });
+  }
+  if (opts.rules) {
+    db.define("rule", {
+      columns: {
+        id: "TEXT PRIMARY KEY",
+        org_id: "TEXT",
+        title: "TEXT NOT NULL",
+        rule_text: "TEXT NOT NULL",
+        scope: "TEXT NOT NULL DEFAULT 'org'",
+        category: "TEXT NOT NULL DEFAULT 'process'",
+        priority: "INTEGER NOT NULL DEFAULT 50",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        deleted_at: "TEXT"
+      }
+    });
+    db.define("rule_agent", {
+      columns: {
+        rule_id: "TEXT NOT NULL",
+        agent_id: "TEXT NOT NULL",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+      },
+      primaryKey: ["rule_id", "agent_id"]
+    });
+    db.define("rule_project", {
+      columns: {
+        rule_id: "TEXT NOT NULL",
+        project_id: "TEXT NOT NULL",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+      },
+      primaryKey: ["rule_id", "project_id"]
+    });
+    db.define("rule_org", {
+      columns: {
+        rule_id: "TEXT NOT NULL",
+        org_id: "TEXT NOT NULL",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP"
+      },
+      primaryKey: ["rule_id", "org_id"]
+    });
+  }
+  if (opts.events) {
+    db.define("event", {
+      columns: {
+        id: "TEXT PRIMARY KEY",
+        org_id: "TEXT",
+        type: "TEXT NOT NULL",
+        summary: "TEXT NOT NULL",
+        details: "TEXT",
+        severity: "TEXT NOT NULL DEFAULT 'info'",
+        actor_agent_id: "TEXT",
+        actor_user_id: "TEXT",
+        project_id: "TEXT",
+        channel_id: "TEXT",
+        created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+        deleted_at: "TEXT"
+      },
+      tableConstraints: [
+        "CREATE INDEX IF NOT EXISTS idx_event_type ON event(type, created_at)",
+        "CREATE INDEX IF NOT EXISTS idx_event_project ON event(project_id)"
+      ]
+    });
+  }
+}
+
+// src/core/data/domain-entity-contexts.ts
+function defineDomainEntityContexts(db, options = {}) {
+  const opts = {
+    clients: true,
+    repositories: true,
+    files: true,
+    channels: true,
+    rules: true,
+    ...options
+  };
+  db.defineEntityContext("org", {
+    table: "org",
+    directory: "orgs",
+    slugColumn: "name",
+    indexFile: "orgs/ORGS.md",
+    files: {
+      "ORG.md": {
+        source: { type: "self" },
+        render: (rows) => {
+          const o = rows[0];
+          if (!o) return "";
+          return [
+            `# ${o.name}`,
+            "",
+            o.type ? `**Type:** ${o.type}` : null,
+            o.description ? `
+${o.description}` : null,
+            o.mission ? `
+**Mission:** ${o.mission}` : null,
+            o.website ? `**Website:** ${o.website}` : null,
+            ""
+          ].filter(Boolean).join("\n");
+        }
+      }
+    }
+  });
+  db.defineEntityContext("project", {
+    table: "project",
+    directory: "projects",
+    slugColumn: "name",
+    indexFile: "projects/PROJECTS.md",
+    files: {
+      "PROJECT.md": {
+        source: { type: "self" },
+        render: (rows) => {
+          const p = rows[0];
+          if (!p) return "";
+          return [
+            `# ${p.name}`,
+            "",
+            p.status ? `**Status:** ${p.status}` : null,
+            p.description ? `
+${p.description}` : null,
+            p.tech_stack ? `
+**Tech Stack:** ${p.tech_stack}` : null,
+            p.production_url ? `**URL:** ${p.production_url}` : null,
+            p.github_repo ? `**GitHub:** ${p.github_repo}` : null,
+            p.deploy_target ? `**Deploy:** ${p.deploy_target}` : null,
+            p.branch_strategy ? `**Branch Strategy:** ${p.branch_strategy}` : null,
+            p.notes ? `
+**Notes:**
+${p.notes}` : null,
+            ""
+          ].filter(Boolean).join("\n");
+        }
+      },
+      ...opts.repositories ? {
+        "REPOS.md": {
+          source: {
+            type: "hasMany",
+            table: "repository",
+            foreignKey: "project_id"
+          },
+          render: (rows) => {
+            if (!rows.length) return "";
+            const lines = rows.map(
+              (r) => `- **${r.name}** \u2014 ${r.url ?? ""}`
+            );
+            return `# Repositories
+
+${lines.join("\n")}
+`;
+          },
+          omitIfEmpty: true
+        }
+      } : {},
+      ...opts.rules ? {
+        "RULES.md": {
+          source: {
+            type: "manyToMany",
+            junctionTable: "rule_project",
+            localKey: "project_id",
+            remoteKey: "rule_id",
+            remoteTable: "rule",
+            softDelete: true,
+            orderBy: "priority"
+          },
+          render: (rows) => {
+            if (!rows.length) return "";
+            const lines = rows.map(
+              (r) => `### ${r.title}
+${r.rule_text}`
+            );
+            return `# Project Rules
+
+${lines.join("\n\n")}
+`;
+          },
+          omitIfEmpty: true
+        }
+      } : {}
+    }
+  });
+  if (opts.clients) {
+    db.defineEntityContext("client", {
+      table: "client",
+      directory: "clients",
+      slugColumn: "name",
+      indexFile: "clients/CLIENTS.md",
+      files: {
+        "CLIENT.md": {
+          source: { type: "self" },
+          render: (rows) => {
+            const c = rows[0];
+            if (!c) return "";
+            return [
+              `# ${c.name}`,
+              "",
+              c.contact_name ? `**Contact:** ${c.contact_name}` : null,
+              c.contact_email ? `**Email:** ${c.contact_email}` : null,
+              c.phone ? `**Phone:** ${c.phone}` : null,
+              c.status ? `**Status:** ${c.status}` : null,
+              c.notes ? `
+${c.notes}` : null,
+              ""
+            ].filter(Boolean).join("\n");
+          }
+        },
+        ...opts.repositories ? {
+          "REPOS.md": {
+            source: {
+              type: "hasMany",
+              table: "repository",
+              foreignKey: "client_id"
+            },
+            render: (rows) => {
+              if (!rows.length) return "";
+              const lines = rows.map(
+                (r) => `- **${r.name}** \u2014 ${r.url ?? ""}`
+              );
+              return `# Repositories
+
+${lines.join("\n")}
+`;
+            },
+            omitIfEmpty: true
+          }
+        } : {},
+        AGENTS: {
+          source: {
+            type: "manyToMany",
+            junctionTable: "agent_client",
+            localKey: "client_id",
+            remoteKey: "agent_id",
+            remoteTable: "agents"
+          },
+          render: (rows) => {
+            if (!rows.length) return "";
+            const lines = rows.map(
+              (r) => `- **${r.name}** (${r.role ?? "agent"})`
+            );
+            return `# Assigned Agents
+
+${lines.join("\n")}
+`;
+          },
+          omitIfEmpty: true
+        },
+        "INVOICES.md": {
+          source: {
+            type: "hasMany",
+            table: "invoice",
+            foreignKey: "client_id"
+          },
+          render: (rows) => {
+            if (!rows.length) return "";
+            const lines = rows.map((r) => {
+              const amt = r.amount_cents ? `$${(r.amount_cents / 100).toFixed(2)}` : "TBD";
+              return `- **${r.number ?? "Draft"}** \u2014 ${amt} (${r.status})${r.description ? ": " + r.description : ""}`;
+            });
+            return `# Invoices
+
+${lines.join("\n")}
+`;
+          },
+          omitIfEmpty: true
+        }
+      }
+    });
+  }
+  if (opts.files) {
+    db.defineEntityContext("file", {
+      table: "file",
+      directory: "files",
+      slugColumn: "name",
+      indexFile: "files/FILES.md",
+      files: {
+        "FILE.md": {
+          source: { type: "self" },
+          render: (rows) => {
+            const f = rows[0];
+            if (!f) return "";
+            return [
+              `# ${f.name}`,
+              "",
+              f.mime_type ? `**Type:** ${f.mime_type}` : null,
+              f.access_level ? `**Access:** ${f.access_level}` : null,
+              f.file_path ? `**Path:** ${f.file_path}` : null,
+              f.description ? `
+${f.description}` : null,
+              ""
+            ].filter(Boolean).join("\n");
+          }
+        }
+      }
+    });
+  }
+  if (opts.channels) {
+    db.defineEntityContext("channel", {
+      table: "channel",
+      directory: "channels",
+      slugColumn: "name",
+      indexFile: "channels/CHANNELS.md",
+      files: {
+        "CHANNEL.md": {
+          source: { type: "self" },
+          render: (rows) => {
+            const c = rows[0];
+            if (!c) return "";
+            return [
+              `# ${c.name}`,
+              "",
+              c.platform ? `**Platform:** ${c.platform}` : null,
+              c.type ? `**Type:** ${c.type}` : null,
+              c.instructions ? `
+${c.instructions}` : null,
+              ""
+            ].filter(Boolean).join("\n");
+          }
+        }
+      }
+    });
+  }
+}
+
 // src/core/security/sanitizer.ts
 import { Buffer as Buffer2 } from "buffer";
 var DEFAULT_FIELD_LIMIT = 65535;
@@ -1753,6 +2251,44 @@ var AuditEmitter = class {
   }
 };
 
+// src/core/security/process-env.ts
+var DEFAULT_ALLOWED_KEYS = /* @__PURE__ */ new Set([
+  "PATH",
+  "HOME",
+  "USER",
+  "SHELL",
+  "LANG",
+  "TERM",
+  "TMPDIR",
+  "XDG_RUNTIME_DIR",
+  "NODE_ENV",
+  // Git
+  "GIT_AUTHOR_NAME",
+  "GIT_AUTHOR_EMAIL",
+  "GIT_COMMITTER_NAME",
+  "GIT_COMMITTER_EMAIL",
+  // Homebrew / system
+  "HOMEBREW_PREFIX",
+  "HOMEBREW_CELLAR",
+  "HOMEBREW_REPOSITORY"
+]);
+function buildProcessEnv(allowedKeys, inject) {
+  const allowed = new Set(DEFAULT_ALLOWED_KEYS);
+  if (allowedKeys) {
+    for (const k of allowedKeys) allowed.add(k);
+  }
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (allowed.has(key) && value !== void 0) {
+      env[key] = value;
+    }
+  }
+  if (inject) {
+    Object.assign(env, inject);
+  }
+  return env;
+}
+
 // src/core/update/version-utils.ts
 function parseVersion(v) {
   const cleaned = v.replace(/^v/, "").split("-")[0] ?? v;
@@ -3230,6 +3766,92 @@ var SecretStore = class {
     };
   }
 };
+
+// src/core/orchestrator/claude-stream-parser.ts
+function parseClaudeStream(stdout) {
+  let sessionId = null;
+  let model = null;
+  let costUsd = null;
+  let usage = null;
+  let isError = false;
+  let errorMessage = null;
+  let stopReason = null;
+  const textBlocks = [];
+  for (const line of stdout.split("\n")) {
+    if (!line.trim()) continue;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const type = event.type;
+    if (type === "system" && event.subtype === "init") {
+      sessionId = event.session_id ?? null;
+      model = event.model ?? null;
+    }
+    if (type === "assistant") {
+      const msg = event.message;
+      const content = msg?.content ?? event.content;
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (block.type === "text" && block.text) {
+            textBlocks.push(block.text);
+          }
+        }
+      }
+    }
+    if (type === "result") {
+      isError = !!event.is_error;
+      stopReason = event.stop_reason ?? null;
+      costUsd = typeof event.total_cost_usd === "number" ? event.total_cost_usd : null;
+      const u = event.usage;
+      if (u) {
+        usage = {
+          inputTokens: u.input_tokens ?? 0,
+          cachedInputTokens: u.cache_read_input_tokens ?? 0,
+          outputTokens: u.output_tokens ?? 0
+        };
+      }
+      if (isError) {
+        errorMessage = event.error ?? event.result ?? "Unknown error";
+      }
+      const resultContent = event.result;
+      if (typeof resultContent === "string" && resultContent) {
+        textBlocks.push(resultContent);
+      }
+    }
+  }
+  return {
+    sessionId,
+    model,
+    costUsd,
+    usage,
+    summary: textBlocks.join("\n"),
+    isError,
+    errorMessage,
+    stopReason
+  };
+}
+function isMaxTurns(parsed) {
+  return parsed.stopReason === "max_turns" || parsed.stopReason === "tool_use";
+}
+function isLoginRequired(stdout) {
+  const patterns = [
+    "not logged in",
+    "login required",
+    "authentication required",
+    "please log in"
+  ];
+  const lower = stdout.toLowerCase();
+  return patterns.some((p) => lower.includes(p));
+}
+function deactivateLocalImagePaths(prompt) {
+  return prompt.replace(
+    /(?<=\s|^)(\/[\w./-]+\.(?:png|jpg|jpeg|gif|webp|svg))(?=\s|$)/gi,
+    "[image-path:$1]"
+  );
+}
 export {
   AGENT_STATUSES,
   AgentRegistry,
@@ -3272,6 +3894,7 @@ export {
   areDependenciesMet,
   buildAgentBindings,
   buildChainOrigin,
+  buildProcessEnv,
   checkAllowlist,
   checkChainDepth,
   checkMentionGate,
@@ -3279,8 +3902,11 @@ export {
   classifyUpdate,
   compareVersions,
   createConfigRevision,
+  deactivateLocalImagePaths,
   defineCoreEntityContexts,
   defineCoreTables,
+  defineDomainEntityContexts,
+  defineDomainTables,
   detectCycle,
   discoverChannels,
   discoverProviders,
@@ -3289,7 +3915,10 @@ export {
   initConfig,
   interpolate,
   interpolateEnv,
+  isLoginRequired,
+  isMaxTurns,
   loadConfig,
+  parseClaudeStream,
   parseVersion,
   runPackageMigrations,
   sanitize,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botinabox",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Bot in a Box — framework for building multi-agent bots",
   "type": "module",
   "main": "./dist/index.js",