@fusedframes/cli 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FusedFrames
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# @fusedframes/cli
+
+Query behavioural patterns captured by [FusedFrames](https://fusedframes.com) from the command line. Designed for AI agents to traverse pattern libraries, follow relationships between patterns and retrieve evidence.
+
+## Install
+
+No installation required. Run directly with `npx`:
+
+```bash
+npx @fusedframes/cli --help
+```
+
+Or install globally:
+
+```bash
+npm install -g @fusedframes/cli
+```
+
+## Setup
+
+Create an API key in your FusedFrames team settings under **Integrations > API keys**, then configure the CLI:
+
+```bash
+echo "ff_your_api_key" | fusedframes config set-key
+```
+
+The key is stored at `~/.config/fusedframes/config.json` with restricted file permissions.
+
+You can also set the key via environment variable:
+
+```bash
+export FUSEDFRAMES_API_KEY=ff_your_api_key
+```
+
+Verify your configuration:
+
+```bash
+fusedframes config show
+```
+
+## Commands
+
+### Browse libraries
+
+List all pattern libraries your API key has access to:
+
+```bash
+fusedframes libraries list
+```
+
+Get detail for a specific library:
+
+```bash
+fusedframes libraries get <library-id>
+```
+
+Discover the vocabulary of a library:
+
+```bash
+fusedframes libraries categories <library-id>
+fusedframes libraries tags <library-id>
+fusedframes libraries applications <library-id>
+```
+
+### Query patterns
+
+List patterns in a library with optional filters:
+
+```bash
+fusedframes patterns list <library-id>
+fusedframes patterns list <library-id> --category "Deployment"
+fusedframes patterns list <library-id> --tag "rollback" --app "Terminal"
+fusedframes patterns list <library-id> --search "failed health check"
+```
+
+Get full detail for a pattern, including its relationships:
+
+```bash
+fusedframes patterns get <pattern-id>
+```
+
+This returns the pattern's behaviour, reasoning, trigger, outcome, category, tags, and all incoming and outgoing edges to other patterns.
+
+Get the evidence actions that support a pattern:
+
+```bash
+fusedframes patterns evidence <pattern-id>
+```
+
+Each evidence action includes the original question, response, and a formatted event timeline showing exactly what happened.
+
+### Traverse the graph
+
+Get the full pattern graph for a library in a single call:
+
+```bash
+fusedframes graph <library-id>
+```
+
+Returns all patterns and all edges. Useful for building a complete picture of a library.
+
+Follow relationships from a specific pattern:
+
+```bash
+fusedframes traverse <pattern-id>
+fusedframes traverse <pattern-id> --depth 2
+fusedframes traverse <pattern-id> --direction outgoing --label "often next"
+fusedframes traverse <pattern-id> --depth 3 --direction both
+```
+
+Depth controls how many levels of connected patterns to follow (1-3). Direction can be `outgoing`, `incoming`, or `both`.
+
+Edge labels describe the relationship between patterns:
+
+| Label | Meaning |
+|---|---|
+| `often next` | What typically happens after |
+| `often previous` | What typically happens before |
+| `variation to` | An alternative approach |
+| `contradicts` | Conflicts with this pattern |
+| `often occurs with` | Usually happening alongside |
+| `exception to` | Edge case where a pattern doesn't apply |
+
+### Search
+
+Search across all accessible libraries:
+
+```bash
+fusedframes search "failed deployment"
+fusedframes search "onboarding" --category "HR"
+fusedframes search "review" --library <library-id>
+```
+
+## Pagination
+
+Commands that return lists support `--page` and `--page-size`:
+
+```bash
+fusedframes patterns list <library-id> --page 2 --page-size 50
+fusedframes patterns evidence <pattern-id> --page 1 --page-size 10
+```
+
+Defaults: page 1, 20 results per page.
+
+## Output
+
+All commands output JSON to stdout. Errors are also JSON:
+
+```json
+{ "error": { "code": "unauthorised", "message": "Invalid or missing API key" } }
+```
+
+Exit codes: `0` for success, `1` for errors, `2` for invalid arguments.
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `FUSEDFRAMES_API_KEY` | API key. Overrides the saved config. |
+| `FUSEDFRAMES_API_URL` | API base URL. Defaults to `https://api.fusedframes.com`. |
+
+## Configuration
+
+The CLI stores its configuration at `~/.config/fusedframes/config.json`. The directory is created with `700` permissions and the file with `600` permissions.
+
+Environment variables take precedence over the config file.
+
+## AI agent usage
+
+This CLI is designed to be called by AI agents (Claude Code, Cursor, Windsurf, Codex) via shell commands. Each command returns structured JSON that the agent can parse and act on.
+
+A typical agent workflow:
+
+1. `fusedframes search "deployment failure"` to find relevant patterns
+2. `fusedframes patterns get <id>` to read the full pattern and its edges
+3. `fusedframes traverse <id> --depth 2` to explore related patterns
+4. `fusedframes patterns evidence <id>` to see the raw actions that support the pattern
+
+The agent uses pattern edges to navigate between related behaviours and build context about how your team works.
+
+## Requirements
+
+- Node.js 18 or later
+- A FusedFrames account with a Pro or Enterprise plan
+- An API key created in your team's integration settings
+
+## Links
+
+- [FusedFrames](https://fusedframes.com)
+- [API reference](https://api.fusedframes.com)

package/dist/index.js

@@ -12,7 +12,7 @@ const program = new Command();
 program
     .name("fusedframes")
     .description("Query FusedFrames behavioural patterns")
-    .version("0.1.0");
+    .version("1.0.0");
 // Register all command groups
 registerConfigCommands(program);
 registerLibraryCommands(program);

package/dist/lib/client.js

@@ -29,7 +29,7 @@ export async function request(path, params) {
         headers: {
             Authorization: `Bearer ${apiKey}`,
             Accept: "application/json",
-            "User-Agent": "@fusedframes/cli/0.1.0",
+            "User-Agent": "@fusedframes/cli/1.0.0",
         },
         signal: AbortSignal.timeout(30_000),
     });

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "@fusedframes/cli",
-  "version": "0.1.0",
-  "description": "CLI for querying FusedFrames behavioural patterns from AI agents",
+  "version": "1.0.0",
+  "description": "CLI for querying FusedFrames",
   "type": "module",
+  "license": "MIT",
+  "author": "FusedFrames <hello@fusedframes.com> (https://fusedframes.com)",
+  "homepage": "https://fusedframes.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fusedframes/fusedframes-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fusedframes/fusedframes-cli/issues"
+  },
   "bin": {
     "fusedframes": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "LICENSE",
+    "README.md"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "build": "tsc && chmod +x dist/index.js",
@@ -18,10 +30,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "commander": "^13.0.0"
+    "commander": "^14.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.9.0",
+    "typescript": "^6.0.0",
     "@types/node": "^22.0.0"
   },
   "keywords": [
@@ -29,6 +41,5 @@
     "cli",
     "patterns",
     "ai-agent"
-  ],
-  "license": "MIT"
+  ]
 }