@fusedframes/cli 0.1.0

package/dist/commands/config.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerConfigCommands(program: Command): void;

package/dist/commands/config.js

@@ -0,0 +1,40 @@
+import { readConfig, writeConfig, getConfigInfo } from "../lib/config.js";
+import { outputSuccess, outputError } from "../lib/output.js";
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data.trim()));
+        process.stdin.on("error", reject);
+        // If stdin is a TTY (interactive terminal), prompt the user
+        if (process.stdin.isTTY) {
+            process.stderr.write("Enter API key: ");
+        }
+    });
+}
+export function registerConfigCommands(program) {
+    const config = program.command("config").description("Manage CLI configuration");
+    config
+        .command("set-key [apiKey]")
+        .description("Set the API key (reads from stdin if not provided)")
+        .action(async (apiKey) => {
+        let key = apiKey;
+        // If no argument provided, read from stdin
+        if (!key) {
+            key = await readStdin();
+        }
+        if (!key) {
+            outputError("validation_error", "No API key provided");
+        }
+        const existing = readConfig();
+        writeConfig({ ...existing, apiKey: key });
+        outputSuccess({ success: true, message: "API key saved" });
+    });
+    config
+        .command("show")
+        .description("Show current configuration")
+        .action(() => {
+        outputSuccess(getConfigInfo());
+    });
+}

package/dist/commands/graph.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerGraphCommand(program: Command): void;

package/dist/commands/graph.js

@@ -0,0 +1,11 @@
+import { request } from "../lib/client.js";
+import { outputSuccess } from "../lib/output.js";
+export function registerGraphCommand(program) {
+    program
+        .command("graph <libraryId>")
+        .description("Get the full pattern graph for a library")
+        .action(async (libraryId) => {
+        const data = await request(`/libraries/${libraryId}/graph`);
+        outputSuccess(data);
+    });
+}

package/dist/commands/libraries.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerLibraryCommands(program: Command): void;

package/dist/commands/libraries.js

@@ -0,0 +1,42 @@
+import { request } from "../lib/client.js";
+import { outputSuccess } from "../lib/output.js";
+export function registerLibraryCommands(program) {
+    const libraries = program
+        .command("libraries")
+        .description("Browse pattern libraries");
+    libraries
+        .command("list")
+        .description("List all accessible pattern libraries")
+        .action(async () => {
+        const data = await request("/libraries");
+        outputSuccess(data);
+    });
+    libraries
+        .command("get <id>")
+        .description("Get pattern library detail")
+        .action(async (id) => {
+        const data = await request(`/libraries/${id}`);
+        outputSuccess(data);
+    });
+    libraries
+        .command("categories <id>")
+        .description("List categories with pattern counts")
+        .action(async (id) => {
+        const data = await request(`/libraries/${id}/categories`);
+        outputSuccess(data);
+    });
+    libraries
+        .command("tags <id>")
+        .description("List tags with pattern counts")
+        .action(async (id) => {
+        const data = await request(`/libraries/${id}/tags`);
+        outputSuccess(data);
+    });
+    libraries
+        .command("applications <id>")
+        .description("List applications with pattern counts")
+        .action(async (id) => {
+        const data = await request(`/libraries/${id}/applications`);
+        outputSuccess(data);
+    });
+}

package/dist/commands/patterns.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerPatternCommands(program: Command): void;

package/dist/commands/patterns.js

@@ -0,0 +1,46 @@
+import { request } from "../lib/client.js";
+import { outputSuccess } from "../lib/output.js";
+export function registerPatternCommands(program) {
+    const patterns = program
+        .command("patterns")
+        .description("Query patterns");
+    patterns
+        .command("list <libraryId>")
+        .description("List patterns in a library")
+        .option("--category <value>", "Filter by category")
+        .option("--tag <value>", "Filter by tag")
+        .option("--app <value>", "Filter by application")
+        .option("--search <value>", "Search term")
+        .option("--page <number>", "Page number", "1")
+        .option("--page-size <number>", "Results per page", "20")
+        .action(async (libraryId, opts) => {
+        const data = await request(`/libraries/${libraryId}/patterns`, {
+            category: opts.category,
+            tag: opts.tag,
+            application: opts.app,
+            search: opts.search,
+            page: opts.page,
+            pageSize: opts.pageSize,
+        });
+        outputSuccess(data);
+    });
+    patterns
+        .command("get <id>")
+        .description("Get full pattern detail with inline edges")
+        .action(async (id) => {
+        const data = await request(`/patterns/${id}`);
+        outputSuccess(data);
+    });
+    patterns
+        .command("evidence <id>")
+        .description("Get evidence actions for a pattern")
+        .option("--page <number>", "Page number", "1")
+        .option("--page-size <number>", "Results per page", "20")
+        .action(async (id, opts) => {
+        const data = await request(`/patterns/${id}/evidence`, {
+            page: opts.page,
+            pageSize: opts.pageSize,
+        });
+        outputSuccess(data);
+    });
+}

package/dist/commands/search.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerSearchCommand(program: Command): void;

package/dist/commands/search.js

@@ -0,0 +1,23 @@
+import { request } from "../lib/client.js";
+import { outputSuccess } from "../lib/output.js";
+export function registerSearchCommand(program) {
+    program
+        .command("search <query>")
+        .description("Search patterns across all accessible libraries")
+        .option("--category <value>", "Filter by category")
+        .option("--tag <value>", "Filter by tag")
+        .option("--library <value>", "Filter by library ID")
+        .option("--page <number>", "Page number", "1")
+        .option("--page-size <number>", "Results per page", "20")
+        .action(async (query, opts) => {
+        const data = await request("/search/patterns", {
+            q: query,
+            category: opts.category,
+            tag: opts.tag,
+            libraryId: opts.library,
+            page: opts.page,
+            pageSize: opts.pageSize,
+        });
+        outputSuccess(data);
+    });
+}

package/dist/commands/traverse.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerTraverseCommand(program: Command): void;

package/dist/commands/traverse.js

@@ -0,0 +1,18 @@
+import { request } from "../lib/client.js";
+import { outputSuccess } from "../lib/output.js";
+export function registerTraverseCommand(program) {
+    program
+        .command("traverse <patternId>")
+        .description("Traverse edges from a pattern")
+        .option("--direction <value>", "Traversal direction (outgoing, incoming, both)", "both")
+        .option("--label <value>", "Filter by edge label")
+        .option("--depth <number>", "Traversal depth (1-3)", "1")
+        .action(async (patternId, opts) => {
+        const data = await request(`/patterns/${patternId}/traverse`, {
+            direction: opts.direction,
+            label: opts.label,
+            depth: opts.depth,
+        });
+        outputSuccess(data);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerConfigCommands } from "./commands/config.js";
+import { registerLibraryCommands } from "./commands/libraries.js";
+import { registerPatternCommands } from "./commands/patterns.js";
+import { registerGraphCommand } from "./commands/graph.js";
+import { registerTraverseCommand } from "./commands/traverse.js";
+import { registerSearchCommand } from "./commands/search.js";
+import { outputError } from "./lib/output.js";
+import { FusedFramesError } from "./lib/client.js";
+const program = new Command();
+program
+    .name("fusedframes")
+    .description("Query FusedFrames behavioural patterns")
+    .version("0.1.0");
+// Register all command groups
+registerConfigCommands(program);
+registerLibraryCommands(program);
+registerPatternCommands(program);
+registerGraphCommand(program);
+registerTraverseCommand(program);
+registerSearchCommand(program);
+// Override commander to throw instead of exit, but keep help/version output
+program.exitOverride();
+// Global error handler
+async function main() {
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        if (error instanceof FusedFramesError) {
+            outputError(error.code, error.message);
+        }
+        else if (error instanceof Error) {
+            // Commander exits with code 'commander.helpDisplayed' or 'commander.version'
+            const commanderError = error;
+            if (commanderError.code === "commander.helpDisplayed" ||
+                commanderError.code === "commander.version") {
+                // These are expected — commander already wrote output
+                process.exit(0);
+            }
+            if (commanderError.code === "commander.missingArgument" ||
+                commanderError.code === "commander.unknownCommand" ||
+                commanderError.code === "commander.unknownOption" ||
+                commanderError.code === "commander.missingMandatoryOptionValue") {
+                outputError("validation_error", error.message);
+            }
+            outputError("error", error.message);
+        }
+        else {
+            outputError("error", "An unexpected error occurred");
+        }
+    }
+}
+main();

package/dist/lib/client.d.ts

@@ -0,0 +1,6 @@
+export declare class FusedFramesError extends Error {
+    code: string;
+    status: number;
+    constructor(code: string, message: string, status: number);
+}
+export declare function request<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;

package/dist/lib/client.js

@@ -0,0 +1,47 @@
+import { requireApiKey, getApiUrl } from "./config.js";
+export class FusedFramesError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export async function request(path, params) {
+    const apiKey = requireApiKey();
+    const baseUrl = getApiUrl();
+    // Enforce HTTPS (allow http://localhost for dev)
+    if (!baseUrl.startsWith("https://") && !baseUrl.startsWith("http://localhost")) {
+        throw new FusedFramesError("config_error", "API URL must use HTTPS. API keys cannot be sent over unencrypted connections.", 0);
+    }
+    // Build URL with query params
+    const url = new URL(path, baseUrl);
+    if (params) {
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== "") {
+                url.searchParams.set(key, value);
+            }
+        }
+    }
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            Accept: "application/json",
+            "User-Agent": "@fusedframes/cli/0.1.0",
+        },
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok) {
+        let errorBody;
+        try {
+            errorBody = (await response.json());
+        }
+        catch {
+            throw new FusedFramesError("server_error", `HTTP ${response.status}`, response.status);
+        }
+        throw new FusedFramesError(errorBody.error?.code || "unknown", errorBody.error?.message || `HTTP ${response.status}`, response.status);
+    }
+    return (await response.json());
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,16 @@
+interface Config {
+    apiKey?: string;
+}
+export declare function readConfig(): Config;
+export declare function writeConfig(config: Config): void;
+export declare function getApiKey(): string | undefined;
+export declare function getApiUrl(): string;
+export declare function requireApiKey(): string;
+export declare function getConfigInfo(): {
+    apiKey: string | null;
+    apiKeySource: string;
+    apiUrl: string;
+    apiUrlSource: string;
+    configPath: string;
+};
+export {};

package/dist/lib/config.js

@@ -0,0 +1,58 @@
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function getConfigDir() {
+    return join(homedir(), ".config", "fusedframes");
+}
+function getConfigPath() {
+    return join(getConfigDir(), "config.json");
+}
+export function readConfig() {
+    try {
+        const data = readFileSync(getConfigPath(), "utf-8");
+        return JSON.parse(data);
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfig(config) {
+    const dir = getConfigDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const path = getConfigPath();
+    writeFileSync(path, JSON.stringify(config, null, 2) + "\n", {
+        mode: 0o600,
+    });
+}
+export function getApiKey() {
+    // Env var takes precedence
+    if (process.env.FUSEDFRAMES_API_KEY) {
+        return process.env.FUSEDFRAMES_API_KEY;
+    }
+    return readConfig().apiKey;
+}
+export function getApiUrl() {
+    return process.env.FUSEDFRAMES_API_URL || "https://api.fusedframes.com";
+}
+export function requireApiKey() {
+    const key = getApiKey();
+    if (!key) {
+        throw new Error("API key not configured. Run: fusedframes config set-key <api-key>");
+    }
+    return key;
+}
+export function getConfigInfo() {
+    const envKey = process.env.FUSEDFRAMES_API_KEY;
+    const fileConfig = readConfig();
+    return {
+        apiKey: envKey
+            ? `${envKey.slice(0, 8)}...`
+            : fileConfig.apiKey
+                ? `${fileConfig.apiKey.slice(0, 8)}...`
+                : null,
+        apiKeySource: envKey ? "environment" : fileConfig.apiKey ? "config" : "none",
+        apiUrl: getApiUrl(),
+        apiUrlSource: process.env.FUSEDFRAMES_API_URL ? "environment" : "default",
+        configPath: getConfigPath(),
+    };
+}

package/dist/lib/output.d.ts

@@ -0,0 +1,2 @@
+export declare function outputSuccess(data: unknown): void;
+export declare function outputError(code: string, message: string): never;

package/dist/lib/output.js

@@ -0,0 +1,7 @@
+export function outputSuccess(data) {
+    process.stdout.write(JSON.stringify(data) + "\n");
+}
+export function outputError(code, message) {
+    process.stdout.write(JSON.stringify({ error: { code, message } }) + "\n");
+    process.exit(1);
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,101 @@
+export interface LibrarySummary {
+    id: string;
+    name: string;
+    description: string | null;
+    categories: string[];
+    tags: string[];
+    patternCount: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface LibraryDetail extends LibrarySummary {
+    edgeCount: number;
+}
+export interface CategoryCount {
+    name: string;
+    patternCount: number;
+}
+export interface TagCount {
+    name: string;
+    patternCount: number;
+}
+export interface ApplicationCount {
+    name: string;
+    patternCount: number;
+}
+export interface PatternSummary {
+    id: string;
+    title: string;
+    behaviour: string;
+    reasoning: string;
+    trigger: string;
+    outcome: string;
+    category: string;
+    tags: string[];
+    applications: string | null;
+    actionCount: number;
+    connectionCount: number;
+    firstSeen: string | null;
+    lastSeen: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PatternDetail extends PatternSummary {
+    library: {
+        id: string;
+        name: string;
+    };
+    edges: {
+        outgoing: {
+            id: string;
+            targetPatternId: string;
+            targetPatternTitle: string;
+            label: string;
+            actionCount: number;
+        }[];
+        incoming: {
+            id: string;
+            sourcePatternId: string;
+            sourcePatternTitle: string;
+            label: string;
+            actionCount: number;
+        }[];
+    };
+}
+export interface EvidenceAction {
+    id: string;
+    question: string;
+    response: string | null;
+    createdAt: string;
+    events: string[];
+}
+export interface GraphEdge {
+    id: string;
+    sourcePatternId: string;
+    targetPatternId: string;
+    label: string;
+    actionCount: number;
+}
+export interface TraverseNode {
+    id: string;
+    title: string;
+    behaviour: string;
+    category: string;
+    applications: string | null;
+    actionCount: number;
+    depth: number;
+}
+export interface SearchPattern {
+    id: string;
+    title: string;
+    behaviour: string;
+    category: string;
+    tags: string[];
+    applications: string | null;
+    actionCount: number;
+    connectionCount: number;
+    library: {
+        id: string;
+        name: string;
+    };
+}

package/dist/lib/types.js

@@ -0,0 +1,2 @@
+// Response types from the FusedFrames API
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@fusedframes/cli",
+  "version": "0.1.0",
+  "description": "CLI for querying FusedFrames behavioural patterns from AI agents",
+  "type": "module",
+  "bin": {
+    "fusedframes": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "@types/node": "^22.0.0"
+  },
+  "keywords": [
+    "fusedframes",
+    "cli",
+    "patterns",
+    "ai-agent"
+  ],
+  "license": "MIT"
+}