botinabox 2.5.0 → 2.5.2

package/dist/core/orchestrator/workflow-engine.js

@@ -0,0 +1,204 @@
+import { detectCycle } from './dependency-resolver.js';
+import { interpolate } from './template-interpolate.js';
+export class WorkflowEngine {
+    db;
+    hooks;
+    taskQueue;
+    constructor(db, hooks, taskQueue) {
+        this.db = db;
+        this.hooks = hooks;
+        this.taskQueue = taskQueue;
+        // Subscribe to task.completed to advance workflow steps
+        this.hooks.register('task.completed', async (ctx) => {
+            const taskId = ctx['taskId'];
+            const output = ctx['output'] ?? '';
+            if (taskId) {
+                await this.onStepCompleted(taskId, output);
+            }
+        });
+    }
+    /**
+     * Define/register a workflow.
+     */
+    async define(slug, def) {
+        // Validate: no duplicate step IDs
+        const ids = def.steps.map((s) => s.id);
+        const unique = new Set(ids);
+        if (unique.size !== ids.length) {
+            throw new Error('Workflow has duplicate step IDs');
+        }
+        // Validate: no invalid dependsOn references
+        for (const step of def.steps) {
+            for (const dep of step.dependsOn ?? []) {
+                if (!unique.has(dep)) {
+                    throw new Error(`Step "${step.id}" depends on unknown step "${dep}"`);
+                }
+            }
+        }
+        // Validate: no cycles
+        if (detectCycle(def.steps)) {
+            throw new Error('Workflow has cyclic step dependencies');
+        }
+        // Store in workflows table
+        const existing = await this.db.query('workflows', { where: { slug } });
+        if (existing.length > 0) {
+            await this.db.update('workflows', { slug }, {
+                name: def.name,
+                description: def.description,
+                definition: JSON.stringify(def),
+                updated_at: new Date().toISOString(),
+            });
+        }
+        else {
+            await this.db.insert('workflows', {
+                slug,
+                name: def.name,
+                description: def.description,
+                definition: JSON.stringify(def),
+            });
+        }
+    }
+    /**
+     * Start a workflow run.
+     */
+    async start(workflowSlug, context) {
+        const workflows = await this.db.query('workflows', { where: { slug: workflowSlug } });
+        if (workflows.length === 0) {
+            throw new Error(`Workflow not found: ${workflowSlug}`);
+        }
+        const workflow = workflows[0];
+        const def = JSON.parse(workflow['definition']);
+        // Create workflow_run record
+        const runRow = await this.db.insert('workflow_runs', {
+            workflow_id: workflow['id'],
+            status: 'running',
+            step_results: JSON.stringify({}),
+            context: JSON.stringify(context),
+        });
+        const workflowRunId = runRow['id'];
+        // Find initial steps (no dependsOn or empty dependsOn)
+        const initialSteps = def.steps.filter((s) => !s.dependsOn || s.dependsOn.length === 0);
+        for (const step of initialSteps) {
+            await this._createStepTask(step, workflowRunId, workflow['id'], context);
+        }
+        return workflowRunId;
+    }
+    /**
+     * Called when a task with workflow_run_id completes.
+     */
+    async onStepCompleted(taskId, output) {
+        const task = await this.db.get('tasks', { id: taskId });
+        if (!task || !task['workflow_run_id'])
+            return;
+        const workflowRunId = task['workflow_run_id'];
+        const stepId = task['workflow_step_id'];
+        const run = await this.db.get('workflow_runs', { id: workflowRunId });
+        if (!run || run['status'] !== 'running')
+            return;
+        // Update step_results
+        const stepResults = JSON.parse(run['step_results'] ?? '{}');
+        if (stepId) {
+            stepResults[stepId] = { output, taskId };
+        }
+        await this.db.update('workflow_runs', { id: workflowRunId }, {
+            step_results: JSON.stringify(stepResults),
+            current_step: stepId,
+        });
+        // Find workflow definition
+        const workflow = await this.db.get('workflows', { id: run['workflow_id'] });
+        if (!workflow)
+            return;
+        const def = JSON.parse(workflow['definition']);
+        // Build context with step outputs
+        const runContext = JSON.parse(run['context'] ?? '{}');
+        const stepsContext = {};
+        for (const [sid, result] of Object.entries(stepResults)) {
+            stepsContext[sid] = result;
+        }
+        const fullContext = { ...runContext, steps: stepsContext };
+        // Find completed step IDs (all tasks for this run that succeeded)
+        const allRunTasks = await this.db.query('tasks', { where: { workflow_run_id: workflowRunId } });
+        const completedStepIds = new Set(allRunTasks
+            .filter((t) => t['status'] === 'done' || t['id'] === taskId)
+            .map((t) => t['workflow_step_id'])
+            .filter(Boolean));
+        // Mark current task's step as complete
+        if (stepId)
+            completedStepIds.add(stepId);
+        // Find next steps whose all dependsOn are satisfied and haven't been started
+        const startedStepIds = new Set(allRunTasks.map((t) => t['workflow_step_id']).filter(Boolean));
+        const nextSteps = def.steps.filter((s) => {
+            if (startedStepIds.has(s.id) && s.id !== stepId)
+                return false;
+            if (s.id === stepId)
+                return false; // Current step
+            if (!s.dependsOn || s.dependsOn.length === 0)
+                return false; // Already started as initial
+            return s.dependsOn.every((dep) => completedStepIds.has(dep));
+        });
+        if (nextSteps.length === 0) {
+            // Check if all steps are done
+            const allStepIds = new Set(def.steps.map((s) => s.id));
+            const allDone = [...allStepIds].every((id) => completedStepIds.has(id));
+            if (allDone) {
+                await this.db.update('workflow_runs', { id: workflowRunId }, {
+                    status: 'completed',
+                    completed_at: new Date().toISOString(),
+                });
+                await this.hooks.emit('workflow.completed', { workflowRunId });
+            }
+            return;
+        }
+        for (const step of nextSteps) {
+            await this._createStepTask(step, workflowRunId, workflow['id'], fullContext);
+        }
+    }
+    /**
+     * Mark a workflow run as failed.
+     */
+    async onStepFailed(taskId, error) {
+        const task = await this.db.get('tasks', { id: taskId });
+        if (!task || !task['workflow_run_id'])
+            return;
+        const workflowRunId = task['workflow_run_id'];
+        const stepId = task['workflow_step_id'];
+        const run = await this.db.get('workflow_runs', { id: workflowRunId });
+        if (!run || run['status'] !== 'running')
+            return;
+        // Find workflow definition to check onFail behavior
+        const workflow = await this.db.get('workflows', { id: run['workflow_id'] });
+        if (!workflow)
+            return;
+        const def = JSON.parse(workflow['definition']);
+        const step = stepId ? def.steps.find((s) => s.id === stepId) : undefined;
+        if (!step || step.onFail === 'abort' || !step.onFail) {
+            await this.db.update('workflow_runs', { id: workflowRunId }, {
+                status: 'failed',
+                error,
+                completed_at: new Date().toISOString(),
+            });
+            await this.hooks.emit('workflow.failed', { workflowRunId, error });
+        }
+        // skip/retry handled by retry policy in run-manager
+    }
+    async _createStepTask(step, workflowRunId, workflowId, context) {
+        // Find agent id by slug if agentSlug provided
+        let assigneeId;
+        if (step.agentSlug) {
+            const agents = await this.db.query('agents', { where: { slug: step.agentSlug } });
+            if (agents.length > 0) {
+                assigneeId = agents[0]['id'];
+            }
+        }
+        const title = interpolate(step.taskTemplate.title, context);
+        const description = interpolate(step.taskTemplate.description, context);
+        const taskId = await this.taskQueue.create({
+            title,
+            description,
+            assignee_id: assigneeId,
+            workflow_run_id: workflowRunId,
+            workflow_step_id: step.id,
+        });
+        return taskId;
+    }
+}

package/dist/core/security/audit.d.ts

@@ -0,0 +1,20 @@
+import type { HookBus } from '../hooks/hook-bus.js';
+import type { AuditEvent } from './types.js';
+interface AuditEmitterOptions {
+    auditTables?: string[];
+}
+/**
+ * Emits audit events via the HookBus for tracked tables.
+ *
+ * - auditTables defaults to [] (nothing audited)
+ * - '*' wildcard audits all tables
+ * - emit is fire-and-forget — errors are swallowed, no awaiting
+ */
+export declare class AuditEmitter {
+    private readonly hooks;
+    private readonly auditTables;
+    constructor(hooks: HookBus, opts?: AuditEmitterOptions);
+    shouldAudit(table: string): boolean;
+    emit(event: AuditEvent): void;
+}
+export {};

package/dist/core/security/audit.js

@@ -0,0 +1,33 @@
+/**
+ * Emits audit events via the HookBus for tracked tables.
+ *
+ * - auditTables defaults to [] (nothing audited)
+ * - '*' wildcard audits all tables
+ * - emit is fire-and-forget — errors are swallowed, no awaiting
+ */
+export class AuditEmitter {
+    hooks;
+    auditTables;
+    constructor(hooks, opts) {
+        this.hooks = hooks;
+        this.auditTables = opts?.auditTables ?? [];
+    }
+    shouldAudit(table) {
+        return this.auditTables.includes('*') || this.auditTables.includes(table);
+    }
+    emit(event) {
+        // Fire and forget — never throw, never await
+        try {
+            const context = event;
+            if (typeof this.hooks.emitSync === 'function') {
+                this.hooks.emitSync('audit', context);
+            }
+            else {
+                void this.hooks.emit('audit', context);
+            }
+        }
+        catch {
+            // Swallow errors — audit must never break normal operation
+        }
+    }
+}

package/dist/core/security/column-validator.d.ts

@@ -0,0 +1,20 @@
+import type { DataStore } from '../data/data-store.js';
+export interface ColumnValidator {
+    validateWrite(table: string, row: Record<string, unknown>): Record<string, unknown>;
+    validateRead(table: string, columns: string[]): void;
+    invalidateCache(table: string): void;
+}
+/**
+ * Validates column names against the live SQLite schema.
+ *
+ * - validateWrite: strips unknown columns silently
+ * - validateRead: throws on unknown columns
+ */
+export declare class ColumnValidatorImpl implements ColumnValidator {
+    private readonly db;
+    constructor(db: DataStore);
+    private getValidColumns;
+    validateWrite(table: string, row: Record<string, unknown>): Record<string, unknown>;
+    validateRead(table: string, columns: string[]): void;
+    invalidateCache(_table: string): void;
+}

package/dist/core/security/column-validator.js

@@ -0,0 +1,37 @@
+/**
+ * Validates column names against the live SQLite schema.
+ *
+ * - validateWrite: strips unknown columns silently
+ * - validateRead: throws on unknown columns
+ */
+export class ColumnValidatorImpl {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    getValidColumns(table) {
+        const rows = this.db.tableInfo(table);
+        return new Set(rows.map(r => r.name));
+    }
+    validateWrite(table, row) {
+        const valid = this.getValidColumns(table);
+        const result = {};
+        for (const [col, val] of Object.entries(row)) {
+            if (valid.has(col)) {
+                result[col] = val;
+            }
+        }
+        return result;
+    }
+    validateRead(table, columns) {
+        const valid = this.getValidColumns(table);
+        for (const col of columns) {
+            if (!valid.has(col)) {
+                throw new Error(`Unknown column: ${col} in table ${table}`);
+            }
+        }
+    }
+    invalidateCache(_table) {
+        // No-op: DataStore.tableInfo() queries SQLite directly each time (no cache)
+    }
+}

package/dist/core/security/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './sanitizer.js';
+export * from './column-validator.js';
+export * from './audit.js';
+export * from './process-env.js';

package/dist/core/security/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './sanitizer.js';
+export * from './column-validator.js';
+export * from './audit.js';
+export * from './process-env.js';

package/dist/core/security/process-env.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Build a clean environment for spawned subprocesses.
+ * Strips secrets and passes only safe system variables.
+ * Used by the CLI execution adapter when spawning agent processes.
+ */
+/**
+ * Build a filtered environment for subprocess execution.
+ * Only passes explicitly allowed variables — all secrets are stripped.
+ *
+ * @param allowedKeys - Additional keys to allow beyond the defaults
+ * @param inject - Extra key-value pairs to inject into the env
+ */
+export declare function buildProcessEnv(allowedKeys?: string[], inject?: Record<string, string>): Record<string, string>;

package/dist/core/security/process-env.js

@@ -0,0 +1,49 @@
+/**
+ * Build a clean environment for spawned subprocesses.
+ * Strips secrets and passes only safe system variables.
+ * Used by the CLI execution adapter when spawning agent processes.
+ */
+const DEFAULT_ALLOWED_KEYS = 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",
+]);
+/**
+ * Build a filtered environment for subprocess execution.
+ * Only passes explicitly allowed variables — all secrets are stripped.
+ *
+ * @param allowedKeys - Additional keys to allow beyond the defaults
+ * @param inject - Extra key-value pairs to inject into the env
+ */
+export 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 !== undefined) {
+            env[key] = value;
+        }
+    }
+    if (inject) {
+        Object.assign(env, inject);
+    }
+    return env;
+}

package/dist/core/security/sanitizer.d.ts

@@ -0,0 +1,11 @@
+import type { SanitizerOptions } from './types.js';
+/**
+ * Sanitizes a row object by:
+ * 1. Stripping null bytes from string values
+ * 2. Stripping control characters (preserving \n, \r, \t)
+ * 3. Truncating fields that exceed their byte length limit
+ *
+ * Non-string values pass through unchanged.
+ * Returns a new object — input is never mutated.
+ */
+export declare function sanitize(row: Record<string, unknown>, opts?: SanitizerOptions): Record<string, unknown>;

package/dist/core/security/sanitizer.js

@@ -0,0 +1,39 @@
+import { Buffer } from 'node:buffer';
+const DEFAULT_FIELD_LIMIT = 65535;
+const DEFAULT_SUFFIX = '[truncated]';
+/**
+ * Sanitizes a row object by:
+ * 1. Stripping null bytes from string values
+ * 2. Stripping control characters (preserving \n, \r, \t)
+ * 3. Truncating fields that exceed their byte length limit
+ *
+ * Non-string values pass through unchanged.
+ * Returns a new object — input is never mutated.
+ */
+export function sanitize(row, opts) {
+    const limits = opts?.fieldLengthLimits ?? {};
+    const suffix = opts?.truncateSuffix ?? DEFAULT_SUFFIX;
+    const result = {};
+    for (const [col, val] of Object.entries(row)) {
+        if (typeof val !== 'string') {
+            result[col] = val;
+            continue;
+        }
+        // 1. Strip null bytes
+        let s = val.replace(/\x00/g, '');
+        // 2. Strip control chars, preserving \n (0x0a), \r (0x0d), \t (0x09)
+        s = s.replace(/[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+        // 3. Enforce field length limit
+        const limit = limits[col] ?? DEFAULT_FIELD_LIMIT;
+        if (Buffer.byteLength(s) > limit) {
+            // Truncate to fit within limit bytes (accounting for suffix)
+            const suffixBytes = Buffer.byteLength(suffix);
+            const maxContentBytes = limit - suffixBytes;
+            // Slice the string to fit within maxContentBytes
+            const buf = Buffer.from(s);
+            s = buf.slice(0, maxContentBytes).toString() + suffix;
+        }
+        result[col] = s;
+    }
+    return result;
+}

package/dist/core/security/types.d.ts

@@ -0,0 +1,11 @@
+export interface SanitizerOptions {
+    fieldLengthLimits?: Record<string, number>;
+    truncateSuffix?: string;
+}
+export interface AuditEvent {
+    table: string;
+    operation: 'insert' | 'update' | 'delete';
+    pk: unknown;
+    timestamp: number;
+    changedColumns?: string[];
+}

package/dist/core/security/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/update/auto-update.d.ts

@@ -0,0 +1,21 @@
+interface UpdateResult {
+    updated: boolean;
+    packages: Array<{
+        name: string;
+        from: string;
+        to: string;
+    }>;
+    restartRequired: boolean;
+}
+/**
+ * Check npm for newer versions of framework packages and install them.
+ * Returns what was updated. Safe to call on every startup — skips if
+ * already on latest.
+ *
+ * @param packages - Package names to check (default: botinabox + latticesql)
+ * @param opts.quiet - Suppress console output (default: false)
+ */
+export declare function autoUpdate(packages?: string[], opts?: {
+    quiet?: boolean;
+}): Promise<UpdateResult>;
+export {};

package/dist/core/update/auto-update.js

@@ -0,0 +1,102 @@
+/**
+ * Auto-update — checks npm for newer versions of botinabox and its
+ * dependencies, installs them if outdated. Call at app startup before
+ * initializing the framework.
+ *
+ * Usage:
+ *   import { autoUpdate } from 'botinabox';
+ *   await autoUpdate();  // checks + installs if needed
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Strict semver pattern — rejects anything that isn't a clean version string */
+const SEMVER_RE = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+/**
+ * Get the installed version of a package from node_modules.
+ */
+function getInstalledVersion(pkgName) {
+    try {
+        const pkgPath = join(process.cwd(), "node_modules", pkgName, "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return pkg.version;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get the latest version from the npm registry.
+ */
+async function getLatestVersion(pkgName) {
+    try {
+        const res = await fetch(`https://registry.npmjs.org/${pkgName}/latest`, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return data.version;
+    }
+    catch {
+        return null;
+    }
+}
+function isNewer(latest, current) {
+    const a = latest.split(".").map(Number);
+    const b = current.split(".").map(Number);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        if ((a[i] ?? 0) > (b[i] ?? 0))
+            return true;
+        if ((a[i] ?? 0) < (b[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+/**
+ * Check npm for newer versions of framework packages and install them.
+ * Returns what was updated. Safe to call on every startup — skips if
+ * already on latest.
+ *
+ * @param packages - Package names to check (default: botinabox + latticesql)
+ * @param opts.quiet - Suppress console output (default: false)
+ */
+export async function autoUpdate(packages = ["botinabox", "latticesql"], opts) {
+    const log = opts?.quiet ? () => { } : console.log;
+    const result = { updated: false, packages: [], restartRequired: false };
+    const toInstall = [];
+    for (const pkg of packages) {
+        const installed = getInstalledVersion(pkg);
+        if (!installed)
+            continue;
+        const latest = await getLatestVersion(pkg);
+        if (!latest)
+            continue;
+        if (isNewer(latest, installed)) {
+            if (!SEMVER_RE.test(latest)) {
+                console.error(`[autoUpdate] Rejecting invalid version "${latest}" for ${pkg}`);
+                continue;
+            }
+            toInstall.push(`${pkg}@${latest}`);
+            result.packages.push({ name: pkg, from: installed, to: latest });
+        }
+    }
+    if (toInstall.length === 0)
+        return result;
+    log(`[autoUpdate] Updating: ${toInstall.join(", ")}`);
+    try {
+        execFileSync("npm", ["install", ...toInstall], {
+            cwd: process.cwd(),
+            stdio: opts?.quiet ? "ignore" : "inherit",
+            timeout: 60_000,
+        });
+        result.updated = true;
+        result.restartRequired = true;
+        log(`[autoUpdate] Updated successfully. Restart required for changes to take effect.`);
+    }
+    catch (err) {
+        console.error("[autoUpdate] Failed to install updates:", err);
+    }
+    return result;
+}

package/dist/core/update/backup-manager.d.ts

@@ -0,0 +1,7 @@
+export declare class BackupManager {
+    private projectRoot;
+    constructor(projectRoot: string);
+    backup(): Promise<string>;
+    restore(backupPath: string): Promise<void>;
+    cleanup(backupPath: string): Promise<void>;
+}

package/dist/core/update/backup-manager.js

@@ -0,0 +1,24 @@
+import { copyFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { rmSync } from 'fs';
+export class BackupManager {
+    projectRoot;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+    }
+    async backup() {
+        const backupDir = join(this.projectRoot, '.botinabox-backup');
+        mkdirSync(backupDir, { recursive: true });
+        const src = join(this.projectRoot, 'pnpm-lock.yaml');
+        const dest = join(backupDir, 'pnpm-lock.yaml.bak');
+        copyFileSync(src, dest);
+        return dest;
+    }
+    async restore(backupPath) {
+        const dest = join(this.projectRoot, 'pnpm-lock.yaml');
+        copyFileSync(backupPath, dest);
+    }
+    async cleanup(backupPath) {
+        rmSync(backupPath, { force: true });
+    }
+}

package/dist/core/update/index.d.ts

@@ -0,0 +1,8 @@
+export type { PackageUpdate, UpdateManifest } from './types.js';
+export { parseVersion, compareVersions, classifyUpdate } from './version-utils.js';
+export { UpdateChecker } from './update-checker.js';
+export { BackupManager } from './backup-manager.js';
+export { UpdateManager } from './update-manager.js';
+export { runPackageMigrations } from './migration-hooks.js';
+export type { PackageMigration } from './migration-hooks.js';
+export { autoUpdate } from './auto-update.js';

package/dist/core/update/index.js

@@ -0,0 +1,6 @@
+export { parseVersion, compareVersions, classifyUpdate } from './version-utils.js';
+export { UpdateChecker } from './update-checker.js';
+export { BackupManager } from './backup-manager.js';
+export { UpdateManager } from './update-manager.js';
+export { runPackageMigrations } from './migration-hooks.js';
+export { autoUpdate } from './auto-update.js';

package/dist/core/update/migration-hooks.d.ts

@@ -0,0 +1,11 @@
+import type { DataStore } from '../data/data-store.js';
+export interface PackageMigration {
+    version: string;
+    package: string;
+    sql: string;
+}
+/**
+ * Runs package migrations using the __lattice_migrations table for tracking.
+ * Each migration is keyed by "{package}:{version}" to ensure idempotency.
+ */
+export declare function runPackageMigrations(db: DataStore, migrations: PackageMigration[]): Promise<void>;

package/dist/core/update/migration-hooks.js

@@ -0,0 +1,10 @@
+/**
+ * Runs package migrations using the __lattice_migrations table for tracking.
+ * Each migration is keyed by "{package}:{version}" to ensure idempotency.
+ */
+export async function runPackageMigrations(db, migrations) {
+    await db.migrate(migrations.map((m) => ({
+        version: `${m.package}:${m.version}`,
+        sql: m.sql,
+    })));
+}