@backburner/cli 0.1.0

package/dist/src/journal/renderer.js

@@ -0,0 +1,50 @@
+const SEVERITY_PREFIX = {
+    info: "  ",
+    warning: "! ",
+    error: "✗ "
+};
+export function renderJournalEntries(entries, opts = {}) {
+    if (opts.json) {
+        return JSON.stringify(entries, null, 2) + "\n";
+    }
+    if (entries.length === 0) {
+        return "No journal entries found.\n";
+    }
+    return (entries
+        .map((e) => {
+        const prefix = SEVERITY_PREFIX[e.severity] ?? "  ";
+        const ts = e.timestamp.replace("T", " ").replace(/\.\d+Z$/, "Z");
+        const scope = e.repoId ? `[${e.repoId}]` : `[${e.scope}:${e.scopeId.slice(0, 8)}]`;
+        const base = `${ts} ${prefix}${scope} ${e.summary}`;
+        if (!opts.verbose) {
+            return base;
+        }
+        const lines = [base];
+        lines.push(`    category: ${e.category}`);
+        if (e.cycleId)
+            lines.push(`    cycle:    ${e.cycleId}`);
+        if (e.workstreamId)
+            lines.push(`    ws:       ${e.workstreamId}`);
+        if (e.executionId)
+            lines.push(`    exec:     ${e.executionId}`);
+        if (e.noActionReason)
+            lines.push(`    reason:   ${e.noActionReason}`);
+        if (e.expectedNextAction)
+            lines.push(`    next:     ${e.expectedNextAction}`);
+        if (e.stateTransition) {
+            lines.push(`    from:     ${e.stateTransition.from}`);
+            lines.push(`    to:       ${e.stateTransition.to}`);
+            if (e.stateTransition.trigger) {
+                lines.push(`    trigger:  ${e.stateTransition.trigger}`);
+            }
+        }
+        if (e.observedState) {
+            lines.push(`    observed: ${JSON.stringify(e.observedState)}`);
+        }
+        if (e.derivedState) {
+            lines.push(`    derived:  ${JSON.stringify(e.derivedState)}`);
+        }
+        return lines.join("\n");
+    })
+        .join("\n") + "\n");
+}

package/dist/src/journal/service.js

@@ -0,0 +1,72 @@
+import { JournalWriter } from "./writer.js";
+import { JournalReader } from "./reader.js";
+export class JournalService {
+    writer;
+    reader;
+    constructor(journalDir) {
+        this.writer = new JournalWriter(journalDir);
+        this.reader = new JournalReader(journalDir);
+    }
+    async write(entry) {
+        return this.writer.write(entry);
+    }
+    async query(q = {}) {
+        return this.reader.query(q);
+    }
+    async recordNoAction(opts) {
+        return this.write({
+            ...(opts.cycleId !== undefined ? { cycleId: opts.cycleId } : {}),
+            scope: opts.scope,
+            scopeId: opts.scopeId,
+            ...(opts.repoId !== undefined ? { repoId: opts.repoId } : {}),
+            ...(opts.workstreamId !== undefined ? { workstreamId: opts.workstreamId } : {}),
+            ...(opts.issueNumber !== undefined ? { issueNumber: opts.issueNumber } : {}),
+            ...(opts.prNumber !== undefined ? { prNumber: opts.prNumber } : {}),
+            category: "no_action",
+            severity: "info",
+            summary: opts.reason,
+            noActionReason: opts.reason,
+            ...(opts.observedState !== undefined ? { observedState: opts.observedState } : {}),
+            ...(opts.derivedState !== undefined ? { derivedState: opts.derivedState } : {})
+        });
+    }
+    async recordStateTransition(opts) {
+        return this.write({
+            ...(opts.cycleId !== undefined ? { cycleId: opts.cycleId } : {}),
+            scope: opts.scope,
+            scopeId: opts.scopeId,
+            ...(opts.repoId !== undefined ? { repoId: opts.repoId } : {}),
+            ...(opts.workstreamId !== undefined ? { workstreamId: opts.workstreamId } : {}),
+            ...(opts.issueNumber !== undefined ? { issueNumber: opts.issueNumber } : {}),
+            ...(opts.prNumber !== undefined ? { prNumber: opts.prNumber } : {}),
+            category: "state_transition",
+            severity: "info",
+            summary: opts.summary,
+            stateTransition: {
+                from: opts.from,
+                to: opts.to,
+                ...(opts.trigger !== undefined ? { trigger: opts.trigger } : {})
+            },
+            ...(opts.observedState !== undefined ? { observedState: opts.observedState } : {}),
+            ...(opts.derivedState !== undefined ? { derivedState: opts.derivedState } : {}),
+            ...(opts.expectedNextAction !== undefined ? { expectedNextAction: opts.expectedNextAction } : {})
+        });
+    }
+    async recordBlocked(opts) {
+        return this.write({
+            ...(opts.cycleId !== undefined ? { cycleId: opts.cycleId } : {}),
+            scope: opts.scope,
+            scopeId: opts.scopeId,
+            ...(opts.repoId !== undefined ? { repoId: opts.repoId } : {}),
+            ...(opts.workstreamId !== undefined ? { workstreamId: opts.workstreamId } : {}),
+            ...(opts.issueNumber !== undefined ? { issueNumber: opts.issueNumber } : {}),
+            ...(opts.prNumber !== undefined ? { prNumber: opts.prNumber } : {}),
+            category: "blocked",
+            severity: "warning",
+            summary: opts.reason,
+            noActionReason: opts.reason,
+            ...(opts.observedState !== undefined ? { observedState: opts.observedState } : {}),
+            ...(opts.derivedState !== undefined ? { derivedState: opts.derivedState } : {})
+        });
+    }
+}

package/dist/src/journal/types.js

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

package/dist/src/journal/writer.js

@@ -0,0 +1,19 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+export class JournalWriter {
+    journalPath;
+    constructor(journalDir) {
+        this.journalPath = path.join(journalDir, "journal.jsonl");
+    }
+    async write(entry) {
+        const full = {
+            id: randomUUID(),
+            timestamp: new Date().toISOString(),
+            ...entry
+        };
+        await mkdir(path.dirname(this.journalPath), { recursive: true });
+        await appendFile(this.journalPath, JSON.stringify(full) + "\n", "utf8");
+        return full;
+    }
+}

package/dist/src/mcps/bridge.js

@@ -0,0 +1,166 @@
+import Smithery from "@smithery/api";
+export class SmitheryConnectionToolsClient {
+    input;
+    constructor(input) {
+        this.input = input;
+    }
+    async listTools() {
+        const response = await this.input.client.connections.tools.list(this.input.connectionId, { namespace: this.input.namespace });
+        return response.tools.map((tool) => toBrokerTool(tool));
+    }
+    async getTool(name) {
+        try {
+            return toBrokerTool(await this.input.client.connections.tools.get(name, {
+                namespace: this.input.namespace,
+                connectionId: this.input.connectionId
+            }));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async callTool(name, rawArguments) {
+        try {
+            const body = normalizeToolArguments(rawArguments);
+            const result = await this.input.client.connections.tools.call(name, {
+                namespace: this.input.namespace,
+                connectionId: this.input.connectionId,
+                body
+            });
+            return {
+                ok: true,
+                tool: name,
+                result,
+                summary: `Smithery MCP tool "${name}" succeeded.`
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                tool: name,
+                error: {
+                    code: "smithery_tool_call_failed",
+                    message: err instanceof Error ? err.message : String(err)
+                }
+            };
+        }
+    }
+}
+function toBrokerTool(tool) {
+    return {
+        name: tool.name,
+        title: tool.title ?? tool.name,
+        description: tool.description ?? `Smithery MCP tool ${tool.name}`,
+        inputSchema: tool.inputSchema ?? { type: "object", properties: {} }
+    };
+}
+export class ReadyMcpBridgeService {
+    handle;
+    client;
+    namespace;
+    cachedTools;
+    constructor(handle, client, allowedPublicToolNames) {
+        this.handle = handle;
+        this.client = client;
+        this.namespace = handle;
+        this.allowedLocalToolNames = allowedPublicToolNames
+            ? new Set(allowedPublicToolNames
+                .filter((name) => name.startsWith(`${handle}.`))
+                .filter((name) => !name.endsWith(".*"))
+                .map((name) => name.slice(handle.length + 1)))
+            : undefined;
+    }
+    allowedLocalToolNames;
+    listTools() {
+        return (this.cachedTools ?? [])
+            .filter((tool) => this.isToolAllowed(tool.name))
+            .map((tool) => ({
+            ...tool,
+            name: tool.name
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name));
+    }
+    async initialize() {
+        try {
+            this.cachedTools = await this.client.listTools();
+        }
+        catch (err) {
+            if (this.allowedLocalToolNames === undefined || this.client.getTool === undefined) {
+                throw err;
+            }
+            const tools = [];
+            for (const toolName of [...this.allowedLocalToolNames].sort((left, right) => left.localeCompare(right))) {
+                const tool = await this.client.getTool(toolName);
+                if (tool) {
+                    tools.push(tool);
+                }
+            }
+            if (tools.length === 0) {
+                throw err;
+            }
+            this.cachedTools = tools;
+        }
+    }
+    async callTool(name, rawArguments) {
+        if (!this.isToolAllowed(name)) {
+            return {
+                ok: false,
+                tool: name,
+                error: {
+                    code: "tool_not_found",
+                    message: `MCP bridge tool "${this.handle}.${name}" is not enabled for this run`
+                }
+            };
+        }
+        return await this.client.callTool(name, rawArguments);
+    }
+    isToolAllowed(localToolName) {
+        return (this.allowedLocalToolNames === undefined ||
+            this.allowedLocalToolNames.has(localToolName));
+    }
+}
+export function createReadyMcpBridgeService(input) {
+    if (input.status.status !== "ready") {
+        return undefined;
+    }
+    return new ReadyMcpBridgeService(input.status.handle, input.client, input.allowedPublicToolNames);
+}
+export function createReadyMcpBridgeServices(inputs) {
+    return [...inputs]
+        .sort((left, right) => left.status.handle.localeCompare(right.status.handle))
+        .map((input) => createReadyMcpBridgeService(input))
+        .filter((service) => service !== undefined);
+}
+export async function createSmitheryMcpBridgeServicesFromStatuses(statuses, runtimeConfig, client, allowedPublicToolNames) {
+    if (!runtimeConfig.apiKey && !client) {
+        return [];
+    }
+    const sdkClient = client ?? new Smithery({ apiKey: runtimeConfig.apiKey });
+    const services = [];
+    for (const status of [...statuses].sort((left, right) => left.handle.localeCompare(right.handle))) {
+        if (status.status !== "ready") {
+            continue;
+        }
+        const namespace = status.connection?.namespace;
+        const connectionId = status.connection?.providerConnectionId;
+        if (!namespace || !connectionId) {
+            continue;
+        }
+        const service = new ReadyMcpBridgeService(status.handle, new SmitheryConnectionToolsClient({ namespace, connectionId, client: sdkClient }), allowedPublicToolNames);
+        await service.initialize();
+        services.push(service);
+    }
+    return services;
+}
+export function projectReadyMcpBridge(service, status) {
+    return {
+        handle: status.handle,
+        tools: service.listTools().map((tool) => tool.name)
+    };
+}
+function normalizeToolArguments(rawArguments) {
+    if (rawArguments && typeof rawArguments === "object" && !Array.isArray(rawArguments)) {
+        return rawArguments;
+    }
+    return {};
+}

package/dist/src/mcps/index.js

@@ -0,0 +1,5 @@
+export { SmitheryMcpResolver } from "./smithery.js";
+export { createSmitheryMcpResolverFromEnv } from "./smithery.js";
+export { SmitherySdkClient } from "./smithery-client.js";
+export { ReadyMcpBridgeService, createReadyMcpBridgeService, createReadyMcpBridgeServices, createSmitheryMcpBridgeServicesFromStatuses, SmitheryConnectionToolsClient, projectReadyMcpBridge } from "./bridge.js";
+export { reconcileMcpStatus } from "./reconcile.js";

package/dist/src/mcps/reconcile.js

@@ -0,0 +1,113 @@
+export function reconcileMcpStatus(dependencies, previous, resolverResults, now) {
+    const previousByHandle = new Map(previous.map((r) => [r.handle, r]));
+    const currentHandles = new Set(dependencies.map((d) => d.handle));
+    const resultByHandle = new Map(resolverResults.map((r) => [r.handle, r]));
+    const added = [];
+    const updated = [];
+    const unchanged = [];
+    const removed = [];
+    // Drop records for handles no longer in dependencies.
+    for (const prev of previous) {
+        if (!currentHandles.has(prev.handle)) {
+            removed.push(prev.handle);
+        }
+    }
+    const records = [];
+    for (const dep of dependencies) {
+        const resolved = resultByHandle.get(dep.handle);
+        const prev = previousByHandle.get(dep.handle);
+        if (!resolved) {
+            // No resolver result for this handle — carry forward previous if any.
+            if (prev) {
+                records.push(prev);
+                unchanged.push(dep.handle);
+            }
+            continue;
+        }
+        const next = resolvedMcpToStatusRecord(resolved, now);
+        if (!prev) {
+            added.push(dep.handle);
+        }
+        else if (prev.status === next.status &&
+            prev.actionRequired?.reason === next.actionRequired?.reason &&
+            prev.connection?.providerConnectionId === next.connection?.providerConnectionId &&
+            prev.connection?.readinessProof === next.connection?.readinessProof) {
+            // Status, action_required reason, and connection identity/proof are unchanged — still update lastCheckedAt and message.
+            unchanged.push(dep.handle);
+            records.push({ ...next });
+            continue;
+        }
+        else {
+            updated.push(dep.handle);
+        }
+        records.push(next);
+    }
+    // Sort deterministically by handle.
+    records.sort((a, b) => a.handle.localeCompare(b.handle));
+    return { records, added, updated, unchanged, removed };
+}
+function resolvedMcpToStatusRecord(resolved, now) {
+    const record = {
+        handle: resolved.handle,
+        providerId: resolved.provider,
+        providerMcpId: resolved.providerMcpId,
+        status: resolved.status,
+        lastCheckedAt: now,
+    };
+    if (resolved.message) {
+        record.message = resolved.message;
+    }
+    if (resolved.actionRequired) {
+        // Only persist the reason, user-visible message, safe fields list.
+        // Do NOT persist URLs unless they are explicitly safe (non-secret, non-short-lived).
+        // For V1, omit URL persistence to stay conservative.
+        record.actionRequired = {
+            reason: resolved.actionRequired.reason,
+            ...(resolved.actionRequired.message
+                ? { message: resolved.actionRequired.message }
+                : {}),
+            ...(resolved.actionRequired.fields?.length
+                ? { fields: [...resolved.actionRequired.fields] }
+                : {}),
+        };
+    }
+    if (resolved.connection) {
+        // Only persist non-secret connection metadata.
+        // mcpUrl is intentionally omitted: Smithery bundleUrl/deploymentUrl may embed
+        // short-lived auth tokens. transport (e.g. "http", "streamable-http") is safe.
+        record.connection = {
+            ...(resolved.connection.localConnectionIdentity
+                ? { localConnectionIdentity: resolved.connection.localConnectionIdentity }
+                : {}),
+            ...(resolved.connection.providerConnectionId
+                ? { providerConnectionId: resolved.connection.providerConnectionId }
+                : {}),
+            ...(resolved.connection.namespace
+                ? { namespace: resolved.connection.namespace }
+                : {}),
+            ...(resolved.connection.transport
+                ? { transport: resolved.connection.transport }
+                : {}),
+            ...(resolved.status === "ready" && resolved.connection.readiness === "connected"
+                ? { readinessProof: "connected", readinessCheckedAt: now }
+                : {}),
+        };
+    }
+    if (resolved.discovered) {
+        // Store discovery summary (counts) rather than full tool lists for now.
+        // Full projection is out of scope for this issue.
+        record.discovered = {
+            ...(resolved.discovered.name ? { name: resolved.discovered.name } : {}),
+            ...(resolved.discovered.tools?.length !== undefined
+                ? { toolCount: resolved.discovered.tools?.length ?? 0 }
+                : {}),
+            ...(resolved.discovered.resources?.length !== undefined
+                ? { resourceCount: resolved.discovered.resources?.length ?? 0 }
+                : {}),
+            ...(resolved.discovered.prompts?.length !== undefined
+                ? { promptCount: resolved.discovered.prompts?.length ?? 0 }
+                : {}),
+        };
+    }
+    return record;
+}

package/dist/src/mcps/smithery-client.js

@@ -0,0 +1,186 @@
+import Smithery from "@smithery/api";
+function isSmitherySdkClientShape(candidate) {
+    if (!candidate || typeof candidate !== "object") {
+        return false;
+    }
+    const maybe = candidate;
+    return typeof maybe.servers?.get === "function" && typeof maybe.connections?.get === "function" && typeof maybe.connections?.set === "function";
+}
+export class SmitherySdkClient {
+    runtimeConfig;
+    fetchFn;
+    sdkClient;
+    constructor(runtimeConfig, clientOrFetch, sdkClient) {
+        this.runtimeConfig = runtimeConfig;
+        this.fetchFn = typeof clientOrFetch === "function" ? clientOrFetch : fetch;
+        if (isSmitherySdkClientShape(clientOrFetch)) {
+            this.sdkClient = clientOrFetch;
+        }
+        else if (sdkClient) {
+            this.sdkClient = sdkClient;
+        }
+    }
+    async getServerByExactId(smitheryId) {
+        if (!this.runtimeConfig.apiKey) {
+            return {
+                status: "error",
+                message: "Missing Smithery API key.",
+            };
+        }
+        try {
+            const server = await this.getClient().servers.get(smitheryId);
+            // Check for required configuration
+            const configProperties = new Set();
+            if (Array.isArray(server.connections)) {
+                for (const conn of server.connections) {
+                    if (conn.configSchema?.properties) {
+                        for (const key of Object.keys(conn.configSchema.properties)) {
+                            configProperties.add(key);
+                        }
+                    }
+                }
+            }
+            const actionRequired = configProperties.size > 0
+                ? {
+                    reason: "config_required",
+                    message: `Configuration required for Smithery server "${smitheryId}".`,
+                    fields: Array.from(configProperties),
+                }
+                : undefined;
+            // Map connection info if available. We prefer hosted HTTP connections.
+            const httpConn = server.connections?.find((c) => c.type === "http");
+            const connection = httpConn
+                ? {
+                    transport: "http",
+                    mcpUrl: httpConn.deploymentUrl ||
+                        httpConn.bundleUrl ||
+                        server.deploymentUrl ||
+                        undefined,
+                    readiness: "unknown",
+                }
+                : undefined;
+            return {
+                status: "found",
+                server: {
+                    name: server.displayName || server.qualifiedName,
+                    tools: server.tools ?? undefined,
+                    resources: server.resources ?? undefined,
+                    prompts: server.prompts ?? undefined,
+                },
+                actionRequired,
+                connection,
+            };
+        }
+        catch (err) {
+            if (err.status === 404) {
+                return {
+                    status: "not_found",
+                    message: `Smithery server "${smitheryId}" not found.`,
+                };
+            }
+            if (err.status === 401 || err.status === 403) {
+                return {
+                    status: "error",
+                    message: `Smithery API key is missing, invalid, or unauthorized (HTTP ${err.status}). Check the SMITHERY_API_KEY runtime configuration.`,
+                };
+            }
+            return {
+                status: "error",
+                message: err.message || String(err),
+            };
+        }
+    }
+    async getConnection(namespace, connectionId) {
+        if (!this.runtimeConfig.apiKey) {
+            return { status: "error", message: "Missing Smithery API key." };
+        }
+        try {
+            const connection = await this.getClient().connections.get(connectionId, { namespace });
+            return this.mapConnectionData(connection);
+        }
+        catch (err) {
+            if (err.status === 404) {
+                return {
+                    status: "not_found",
+                    message: `Connection "${connectionId}" not found in namespace "${namespace}".`,
+                };
+            }
+            if (err.status === 401 || err.status === 403) {
+                return {
+                    status: "error",
+                    message: `Smithery API key is missing, invalid, or unauthorized (HTTP ${err.status}). Check the SMITHERY_API_KEY runtime configuration.`,
+                };
+            }
+            return { status: "error", message: err.message || String(err) };
+        }
+    }
+    async createOrUpdateConnection(input) {
+        if (!this.runtimeConfig.apiKey) {
+            return { status: "error", message: "Missing Smithery API key." };
+        }
+        try {
+            const connection = await this.getClient().connections.set(input.connectionId, {
+                namespace: input.namespace,
+                server: input.smitheryId,
+                name: input.handle,
+                ...(input.transport ? { transport: input.transport } : {}),
+                metadata: {
+                    backburner: "backburner",
+                    backburnerHandle: input.handle,
+                    providerMcpId: input.smitheryId,
+                    localConnectionIdentity: input.connectionId,
+                },
+            });
+            return this.mapConnectionData(connection);
+        }
+        catch (err) {
+            if (err.status === 401 || err.status === 403) {
+                return {
+                    status: "error",
+                    message: `Smithery API key is missing, invalid, or unauthorized (HTTP ${err.status}). Check the SMITHERY_API_KEY runtime configuration.`,
+                };
+            }
+            return { status: "error", message: err.message || String(err) };
+        }
+    }
+    mapConnectionData(data) {
+        const state = data.status?.state;
+        let status = "error";
+        if (state === "connected")
+            status = "connected";
+        else if (state === "auth_required")
+            status = "auth_required";
+        else if (state === "input_required")
+            status = "input_required";
+        else if (state === "disconnected")
+            status = "disconnected";
+        const rawMetadata = data.metadata;
+        const metadata = rawMetadata && typeof rawMetadata === "object" && !Array.isArray(rawMetadata)
+            ? rawMetadata
+            : undefined;
+        return {
+            status,
+            message: data.status?.message,
+            connectionId: data.connectionId,
+            namespace: data.namespace,
+            transport: data.transport ?? undefined,
+            mcpUrl: data.mcpUrl || undefined,
+            setupUrl: data.status?.setupUrl || data.status?.url,
+            fields: data.status?.fields,
+            ...(metadata ? { metadata } : {}),
+        };
+    }
+    getClient() {
+        if (this.sdkClient) {
+            return this.sdkClient;
+        }
+        if (!this.runtimeConfig.apiKey) {
+            throw new Error("Missing Smithery API key.");
+        }
+        this.sdkClient = new Smithery({
+            apiKey: this.runtimeConfig.apiKey,
+            fetch: this.fetchFn,
+        });
+        return this.sdkClient;
+    }
+}