@grafema/cli 0.2.4-beta → 0.2.6-beta

package/dist/utils/spinner.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Simple terminal spinner for slow operations.
+ *
+ * Features:
+ * - TTY detection: silent in non-TTY environments (CI, pipes)
+ * - Delayed display: spinner only appears after 100ms to avoid flicker
+ * - Elapsed time: shows seconds for long operations
+ *
+ * Usage:
+ *   const spinner = new Spinner('Querying graph...');
+ *   spinner.start();
+ *   await slowOperation();
+ *   spinner.stop();
+ *
+ * IMPORTANT: Always call stop() BEFORE any console.log output.
+ */
+export declare class Spinner {
+    private message;
+    private frames;
+    private interval;
+    private displayTimer;
+    private frameIndex;
+    private startTime;
+    private displayDelay;
+    private isSpinning;
+    constructor(message: string, displayDelay?: number);
+    /**
+     * Start the spinner. Spinner appears only after displayDelay ms.
+     * In non-TTY environments (CI, pipes), this is a no-op.
+     */
+    start(): void;
+    private render;
+    /**
+     * Stop the spinner and clear the line.
+     * Safe to call multiple times or if spinner never started.
+     */
+    stop(): void;
+}
+//# sourceMappingURL=spinner.d.ts.map

package/dist/utils/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/utils/spinner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAsD;IACpE,OAAO,CAAC,QAAQ,CAA+C;IAC/D,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,MAAM,EAAE,YAAY,SAAM;IAK/C;;;OAGG;IACH,KAAK,IAAI,IAAI;IAqBb,OAAO,CAAC,MAAM;IAYd;;;OAGG;IACH,IAAI,IAAI,IAAI;CAqBb"}

package/dist/utils/spinner.js

@@ -0,0 +1,84 @@
+/**
+ * Simple terminal spinner for slow operations.
+ *
+ * Features:
+ * - TTY detection: silent in non-TTY environments (CI, pipes)
+ * - Delayed display: spinner only appears after 100ms to avoid flicker
+ * - Elapsed time: shows seconds for long operations
+ *
+ * Usage:
+ *   const spinner = new Spinner('Querying graph...');
+ *   spinner.start();
+ *   await slowOperation();
+ *   spinner.stop();
+ *
+ * IMPORTANT: Always call stop() BEFORE any console.log output.
+ */
+export class Spinner {
+    message;
+    frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    interval = null;
+    displayTimer = null;
+    frameIndex = 0;
+    startTime = 0;
+    displayDelay;
+    isSpinning = false;
+    constructor(message, displayDelay = 100) {
+        this.message = message;
+        this.displayDelay = displayDelay;
+    }
+    /**
+     * Start the spinner. Spinner appears only after displayDelay ms.
+     * In non-TTY environments (CI, pipes), this is a no-op.
+     */
+    start() {
+        // TTY check - ora pattern
+        if (!process.stdout.isTTY) {
+            return;
+        }
+        this.startTime = Date.now();
+        // Defer display to avoid flicker on fast queries
+        this.displayTimer = setTimeout(() => {
+            this.isSpinning = true;
+            this.render();
+            // Animate frames at 80ms interval
+            this.interval = setInterval(() => {
+                this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+                this.render();
+            }, 80);
+        }, this.displayDelay);
+    }
+    render() {
+        if (!this.isSpinning)
+            return;
+        const frame = this.frames[this.frameIndex];
+        const elapsed = Math.floor((Date.now() - this.startTime) / 1000);
+        const timeStr = elapsed > 0 ? ` (${elapsed}s)` : '';
+        process.stdout.clearLine(0);
+        process.stdout.cursorTo(0);
+        process.stdout.write(`${frame} ${this.message}${timeStr}`);
+    }
+    /**
+     * Stop the spinner and clear the line.
+     * Safe to call multiple times or if spinner never started.
+     */
+    stop() {
+        // Clear deferred display timer
+        if (this.displayTimer) {
+            clearTimeout(this.displayTimer);
+            this.displayTimer = null;
+        }
+        // Stop animation
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        // Clear line if we were displaying
+        if (this.isSpinning && process.stdout.isTTY) {
+            process.stdout.clearLine(0);
+            process.stdout.cursorTo(0);
+        }
+        this.isSpinning = false;
+    }
+}
+//# sourceMappingURL=spinner.js.map

package/dist/utils/spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.js","sourceRoot":"","sources":["../../src/utils/spinner.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafema/cli",
-  "version": "0.2.4-beta",
+  "version": "0.2.6-beta",
   "description": "CLI for Grafema code analysis toolkit",
   "type": "module",
   "main": "./dist/cli.js",
@@ -16,7 +16,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills"
   ],
   "keywords": [
     "grafema",
@@ -28,25 +29,23 @@
   "author": "Vadim Reshetnikov",
   "repository": {
     "type": "git",
-    "url": "https://github.com/grafema/grafema.git",
+    "url": "https://github.com/Disentinel/grafema.git",
     "directory": "packages/cli"
   },
   "dependencies": {
     "commander": "^13.0.0",
-    "ink": "^6.6.0",
-    "ink-text-input": "^6.0.0",
-    "react": "^19.2.3",
     "yaml": "^2.8.2",
-    "@grafema/core": "0.2.4-beta",
-    "@grafema/types": "0.2.4-beta"
+    "@grafema/core": "0.2.6-beta",
+    "@grafema/types": "0.2.6-beta",
+    "@grafema/api": "0.2.6-beta"
   },
   "devDependencies": {
     "@types/node": "^25.0.8",
-    "@types/react": "^19.2.9",
     "typescript": "^5.9.3"
   },
   "scripts": {
     "build": "tsc",
+    "postbuild": "mkdir -p dist/plugins && cp src/plugins/pluginResolver.js dist/plugins/",
     "clean": "rm -rf dist",
     "start": "node dist/cli.js",
     "test": "node --import tsx --test test/*.test.ts"

package/skills/grafema-codebase-analysis/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: grafema-codebase-analysis
+description: >
+  Analyze codebases using a graph database instead of reading source files.
+  Use when understanding code architecture, finding functions or call patterns,
+  tracing data flow, checking dependencies, or answering "where is X used?"
+  questions. Grafema builds a queryable code graph from static analysis —
+  prefer querying the graph over reading files manually.
+license: Apache-2.0
+compatibility: Requires Grafema MCP server configured (grafema or @grafema/mcp package)
+metadata:
+  author: Grafema
+  version: "0.2.5"
+---
+
+# Grafema: Graph-Based Codebase Analysis
+
+## Core Principle
+
+**Query the graph, not read code.**
+
+Grafema builds a graph database from your codebase via static analysis.
+Instead of reading dozens of files to understand how code connects,
+query the graph to get structured, complete answers instantly.
+
+```
+BAD:  Read 20 files hoping to find all callers of a function
+GOOD: find_calls({ name: "processPayment" }) -> get all callers in one query
+
+BAD:  Grep for variable name across files, miss aliased references
+GOOD: trace_dataflow({ source: "userInput", direction: "forward" }) -> complete data flow
+
+BAD:  Read file by file to understand module dependencies
+GOOD: get_file_overview({ file: "src/api.ts" }) -> structured imports, exports, classes, functions
+```
+
+### When to Use Grafema
+
+- Finding where functions/methods are called
+- Understanding module dependencies and imports
+- Tracing data flow (forward or backward)
+- Getting function details (signature, callers, callees)
+- Checking code invariants with Datalog rules
+- Exploring file structure and entity relationships
+
+### When NOT to Use Grafema
+
+- Reading a single specific file (use your editor/Read tool — faster)
+- Editing code (Grafema is read-only analysis)
+- Runtime behavior questions (Grafema is static analysis)
+- Files not yet analyzed (run `analyze_project` first)
+
+## Essential Tools (Tier 1)
+
+These 5 tools handle ~80% of queries. Start here.
+
+### find_nodes — Find entities by type, name, or file
+
+```json
+find_nodes({ type: "FUNCTION", name: "validateUser" })
+find_nodes({ type: "CLASS", file: "src/auth.ts" })
+find_nodes({ type: "http:request" })
+find_nodes({ type: "MODULE" })
+```
+
+**Use when:** "Find all X", "What functions are in file Y", "List all routes"
+
+**Node types:** MODULE, FUNCTION, METHOD, CLASS, VARIABLE, PARAMETER,
+CALL, PROPERTY_ACCESS, METHOD_CALL, CALL_SITE,
+http:route, http:request, db:query, socketio:emit, socketio:on
+
+### find_calls — Find function/method call sites
+
+```json
+find_calls({ name: "processPayment" })
+find_calls({ name: "query", className: "Database" })
+```
+
+**Use when:** "Where is X called?", "Who calls this function?", "Find all usages"
+
+Returns call sites with file locations and whether the target is resolved.
+
+### get_function_details — Complete function info
+
+```json
+get_function_details({ name: "handleRequest" })
+get_function_details({ name: "validate", file: "src/auth.ts" })
+get_function_details({ name: "processOrder", transitive: true })
+```
+
+**Use when:** "What does function X do?", "What does it call?", "Who calls it?"
+
+Returns: signature, parameters, what it calls, who calls it.
+Use `transitive: true` to follow call chains (A calls B calls C, max depth 5).
+
+### get_context — Deep context for any node
+
+```json
+get_context({ semanticId: "src/api.ts:handleRequest#fn" })
+get_context({ semanticId: "src/db.ts:Database#class", edgeType: "CALLS" })
+```
+
+**Use when:** "Tell me everything about this entity", "Show me its relationships"
+
+Returns: node info, source code, ALL incoming/outgoing edges with code context.
+Use after `find_nodes` to deep-dive into a specific result.
+
+### trace_dataflow — Trace data flow
+
+```json
+trace_dataflow({ source: "userInput", file: "src/handler.ts", direction: "forward" })
+trace_dataflow({ source: "dbResult", file: "src/query.ts", direction: "backward" })
+trace_dataflow({ source: "config", direction: "both", max_depth: 5 })
+```
+
+**Use when:** "Where does this value end up?", "Where does this data come from?",
+"Is user input reaching the database unsanitized?"
+
+Directions: `forward` (where does it go?), `backward` (where did it come from?), `both`.
+
+## Decision Tree
+
+```
+START: What do you need?
+|
+|-- "Find entities (functions, classes, routes)"
+|   -> find_nodes({ type, name, file })
+|
+|-- "Find who calls function X"
+|   -> find_calls({ name: "X" })
+|   -> For full details: get_function_details({ name: "X" })
+|
+|-- "Understand a specific entity deeply"
+|   -> First: find_nodes to get its semantic ID
+|   -> Then: get_context({ semanticId: "..." })
+|
+|-- "Trace data flow"
+|   -> trace_dataflow({ source, file, direction })
+|
+|-- "Understand a file's structure"
+|   -> get_file_overview({ file: "path/to/file.ts" })
+|
+|-- "Trace an alias/re-export chain"
+|   -> trace_alias({ variableName: "alias", file: "path.ts" })
+|
+|-- "Check a code rule/invariant"
+|   -> check_invariant({ rule: "violation(X) :- ..." })
+|
+|-- "Custom complex query"
+|   -> query_graph({ query: "violation(X) :- ..." })
+|   -> See references/query-patterns.md for Datalog syntax
+|
+|-- "Explore unknown codebase"
+|   -> get_stats() for high-level overview
+|   -> get_schema() for available node/edge types
+|   -> find_nodes({ type: "MODULE" }) for module list
+|   -> get_file_overview for specific files
+```
+
+## Common Workflows
+
+### 1. Impact Analysis: "What breaks if I change function X?"
+
+```
+get_function_details({ name: "X", transitive: true })
+-> Check calledBy array for all callers (direct + transitive)
+-> For critical callers: get_context({ semanticId }) for full picture
+```
+
+### 2. Security Audit: "Does user input reach the database?"
+
+```
+find_nodes({ type: "http:request" })
+-> For each route, trace_dataflow({ source: requestParam, direction: "forward" })
+-> Check if flow reaches db:query nodes
+-> Use find_guards to check for sanitization
+```
+
+### 3. Onboarding: "How is this codebase structured?"
+
+```
+get_stats()                              -> Node/edge counts by type
+find_nodes({ type: "MODULE" })           -> All modules
+get_file_overview({ file: "src/index.ts" })  -> Entry point structure
+find_nodes({ type: "http:request" })     -> All API endpoints
+```
+
+### 4. Dependency Analysis: "What does module X depend on?"
+
+```
+get_file_overview({ file: "src/service.ts" })
+-> Check imports section for dependencies
+-> For each import: get_context for deeper relationships
+```
+
+### 5. Find Dead Code: "What functions have no callers?"
+
+```
+query_graph({
+  query: 'violation(X) :- node(X, "FUNCTION"), \\+ edge(_, X, "CALLS").'
+})
+```
+
+## Anti-Patterns
+
+**Don't read files to find call sites.** Use `find_calls` — it finds ALL callers across
+the entire codebase, including indirect references you'd miss by grepping.
+
+**Don't use `query_graph` for simple lookups.** `find_nodes`, `find_calls`, and
+`get_function_details` are optimized for common queries. Reserve Datalog for
+complex patterns (joins, transitive closure, invariant checks).
+
+**Don't skip analysis status.** If you just ran `analyze_project`, check
+`get_analysis_status` before querying — partial results are misleading.
+
+**Don't request excessive depth.** `get_context` with no filters returns everything.
+Use `edgeType` filter to focus on specific relationships (e.g., `"CALLS,ASSIGNED_FROM"`).
+
+**Don't use Grafema for single-file questions.** If you only need to read one file,
+use your editor. Grafema shines for cross-file relationships.
+
+## Advanced Tools (Tier 2)
+
+### query_graph — Custom Datalog queries
+
+For complex patterns not covered by high-level tools.
+See [references/query-patterns.md](references/query-patterns.md) for syntax and examples.
+
+```json
+query_graph({
+  query: "violation(X) :- node(X, \"CALL\"), attr(X, \"name\", \"eval\").",
+  explain: true
+})
+```
+
+Available predicates: `node(Id, Type)`, `edge(Src, Dst, Type)`, `attr(Id, Name, Value)`.
+Must define `violation/1` predicate for results. Use `explain: true` to debug empty results.
+
+### get_file_overview — File-level structure
+
+Structured overview of imports, exports, classes, functions, variables with relationships.
+Recommended first step when exploring a specific file before using `get_context`.
+
+### trace_alias — Resolve alias chains
+
+For code like `const alias = obj.method; alias()` — traces "alias" back to "obj.method".
+
+### get_schema — Available types
+
+Returns all node and edge types in the graph. Use when you need exact type names.
+
+### check_invariant — Code rule checking
+
+Check if a Datalog rule has violations. For persistent rules, use `create_guarantee`.
+
+## Specialized Tools (Tier 3)
+
+| Tool | Purpose |
+|------|---------|
+| get_stats | Graph statistics (node/edge counts by type) |
+| get_coverage | Analysis coverage for a path |
+| find_guards | Conditional guards protecting a node |
+| create_guarantee | Create persistent code invariant |
+| list_guarantees | List all guarantees |
+| check_guarantees | Check guarantee violations |
+| delete_guarantee | Remove a guarantee |
+| discover_services | Discover services without full analysis |
+| analyze_project | Run/re-run analysis |
+| get_analysis_status | Check analysis progress |
+| read_project_structure | Directory tree |
+| write_config | Update .grafema/config.yaml |
+| get_documentation | Grafema usage docs |
+| report_issue | Report bugs |
+
+## Troubleshooting
+
+**Query returns nothing?**
+1. Check analysis ran: `get_analysis_status`
+2. Check type names: `get_schema` for available types
+3. Use `explain: true` in `query_graph` to debug
+4. Check file paths match (relative to project root)
+
+**Need help with Datalog syntax?**
+- See [references/query-patterns.md](references/query-patterns.md)
+- Use `get_documentation({ topic: "queries" })` for inline help
+
+**Graph seems incomplete?**
+- Run `get_coverage({ path: "src/" })` to check coverage
+- Re-analyze with `analyze_project({ force: true })`
+- Check `.grafema/config.yaml` for include/exclude patterns
+
+## References
+
+- [Node and Edge Types](references/node-edge-types.md) — Complete graph schema
+- [Query Patterns](references/query-patterns.md) — Datalog cookbook with examples

package/skills/grafema-codebase-analysis/references/node-edge-types.md

@@ -0,0 +1,123 @@
+# Grafema Graph Schema: Node and Edge Types
+
+## Node Types
+
+### Core Entities
+
+| Type | Description | Key Attributes |
+|------|-------------|----------------|
+| `MODULE` | A source file/module | name, file |
+| `FUNCTION` | Function declaration | name, file, line, async |
+| `METHOD` | Class method | name, file, line, className |
+| `CLASS` | Class declaration | name, file, line |
+| `VARIABLE` | Variable declaration | name, file, line, kind (const/let/var) |
+| `PARAMETER` | Function parameter | name, file, line, index |
+
+### Call & Access Nodes
+
+| Type | Description | Key Attributes |
+|------|-------------|----------------|
+| `CALL` | Function call expression | name, file, line, resolved |
+| `METHOD_CALL` | Method call expression | name, file, line, object, resolved |
+| `CALL_SITE` | Call site context | file, line |
+| `PROPERTY_ACCESS` | Property access (obj.prop) | name, object, file, line |
+
+### Domain-Specific Nodes
+
+| Type | Description | Key Attributes |
+|------|-------------|----------------|
+| `http:route` | HTTP route definition | path, method |
+| `http:request` | HTTP request handler | path, method, file, line |
+| `db:query` | Database query | file, line |
+| `socketio:emit` | Socket.IO emit call | event, file, line |
+| `socketio:on` | Socket.IO event listener | event, file, line |
+
+### Structural Nodes
+
+| Type | Description |
+|------|-------------|
+| `SCOPE` | Code scope (function body, if block, loop) |
+| `OBJECT_LITERAL` | Object literal expression |
+| `ARRAY_LITERAL` | Array literal expression |
+| `LITERAL` | Primitive literal value |
+| `IMPORT` | Import declaration |
+| `EXPORT` | Export declaration |
+
+## Edge Types
+
+| Type | Direction | Description |
+|------|-----------|-------------|
+| `CONTAINS` | Parent -> Child | Structural containment (module contains function) |
+| `CALLS` | Caller -> Callee | Function/method call relationship |
+| `DEPENDS_ON` | Module -> Module | Module dependency (import) |
+| `ASSIGNED_FROM` | Variable -> Source | Value assignment source |
+| `INSTANCE_OF` | Instance -> Class | Class instantiation |
+| `PASSES_ARGUMENT` | Call -> Value | Argument passing at call site |
+| `HAS_SCOPE` | Function -> Scope | Function's scope chain |
+| `EXTENDS` | Class -> Class | Class inheritance |
+| `IMPLEMENTS` | Class -> Interface | Interface implementation |
+| `RETURNS` | Function -> Type | Return type relationship |
+| `DATAFLOW` | Source -> Sink | Data flow edge |
+| `GUARDED_BY` | Node -> Scope | Conditional guard relationship |
+
+## Common Attribute Names
+
+These can be used with `attr(Id, Name, Value)` in Datalog queries:
+
+| Attribute | Types | Description |
+|-----------|-------|-------------|
+| `name` | All named nodes | Entity name |
+| `file` | All nodes | Source file path (relative) |
+| `line` | All located nodes | Line number |
+| `column` | All located nodes | Column number |
+| `type` | All nodes | Node type (via `node(Id, Type)`) |
+| `async` | FUNCTION, METHOD | Is async function |
+| `kind` | VARIABLE | const, let, or var |
+| `method` | http:request | HTTP method (GET, POST, etc.) |
+| `path` | http:request, http:route | URL path pattern |
+| `resolved` | CALL, METHOD_CALL | Whether call target is resolved |
+| `object` | METHOD_CALL, PROPERTY_ACCESS | Receiver object name |
+| `className` | METHOD | Owning class name |
+| `event` | socketio:emit, socketio:on | Socket.IO event name |
+
+## Quick Reference: Finding Common Patterns
+
+### Find all functions
+```
+node(X, "FUNCTION")
+```
+
+### Find all classes
+```
+node(X, "CLASS")
+```
+
+### Find all HTTP endpoints
+```
+node(X, "http:request")
+```
+
+### Find calls to a specific function
+```
+node(X, "CALL"), attr(X, "name", "targetFunction")
+```
+
+### Find all methods of a class
+```
+node(C, "CLASS"), attr(C, "name", "MyClass"), edge(C, M, "CONTAINS"), node(M, "METHOD")
+```
+
+### Find module dependencies
+```
+edge(A, B, "DEPENDS_ON"), node(A, "MODULE"), node(B, "MODULE")
+```
+
+### Find data flow from a variable
+```
+node(X, "VARIABLE"), attr(X, "name", "myVar"), edge(X, Y, "DATAFLOW")
+```
+
+### Find unresolved calls
+```
+node(X, "CALL"), attr(X, "resolved", "false")
+```