gcyphrq 0.12.6

package/docs/query-guide.md

@@ -0,0 +1,302 @@
+---
+layout: default
+title: Query Guide
+description: Full Cypher syntax reference, supported features, and query patterns for gcyphrq.
+---
+
+<div class="breadcrumb">
+  <a href="{{ '/' | relative_url }}">Home</a> <span>›</span> Query Guide
+</div>
+
+# Query Guide
+
+This guide covers all supported Cypher syntax and query patterns available in the `gcyphrq` engine.
+
+---
+
+## Supported Features
+
+See the [Home page](/) for the full feature support table.
+
+<div class="callout">
+  <p><strong>Single MATCH per stage:</strong> The engine processes one MATCH clause at a time. Chained MATCHes within the same stage are not supported — use multiple stages separated by <code>WITH</code> instead.</p>
+</div>
+
+---
+
+## MATCH
+
+### Basic node match
+
+```cypher
+MATCH (u:User) RETURN u
+```
+
+### Match with property filter
+
+```cypher
+MATCH (u:User {name: 'Alice'}) RETURN u
+```
+
+### Match with relationships
+
+```cypher
+MATCH (u:User)-[:FRIEND]->(f:User) RETURN u, f
+```
+
+### Variable-length paths
+
+```cypher
+MATCH (u:User)-[r:FRIEND*1..3]-(f:User) RETURN u, r, f
+```
+
+The `*min..max` syntax specifies the minimum and maximum path length. Use `*1..3` for 1 to 3 hops, `*2..2` for exactly 2 hops, etc.
+
+### Directional edges
+
+| Syntax | Meaning |
+|---|---|
+| `-[:TYPE]->` | Outbound only (from source to target) |
+| `<-[:TYPE]-` | Inbound only (from target to source) |
+| `-[:TYPE]-` | Undirected (either direction) |
+
+```cypher
+// Outbound only
+MATCH (u:User {name: 'Alice'})-[r:FRIEND]->(f:User) RETURN f
+
+// Inbound only
+MATCH (u:User {name: 'Alice'})<-[r:FRIEND]-(f:User) RETURN f
+
+// Any direction
+MATCH (u:User {name: 'Alice'})-[r:FRIEND]-(f:User) RETURN f
+```
+
+---
+
+## OPTIONAL MATCH
+
+Performs a left outer join — returns results even when no matching path exists (with nulls for unmatched variables):
+
+```cypher
+MATCH (u:User)
+OPTIONAL MATCH (u)-[r:HAS_CARD]->(c:Card)
+RETURN u, c
+```
+
+---
+
+## RETURN
+
+### Return full nodes
+
+```cypher
+MATCH (u:User) RETURN u
+```
+
+### Return specific properties
+
+```cypher
+MATCH (u:User) RETURN u.name, u.age
+```
+
+### Return with aliases
+
+```cypher
+MATCH (u:User) RETURN u.name AS userName, u.age AS userAge
+```
+
+---
+
+## WITH + Implicit Grouping
+
+Use `WITH` to pipe results through intermediate stages. When you include both aggregated and non-aggregated variables, implicit grouping occurs:
+
+```cypher
+MATCH (u:User)-[:FRIEND]->(f)
+WITH u, count(f) AS friendCount
+WHERE friendCount > 1
+RETURN u.name, friendCount
+```
+
+### Supported aggregations
+
+| Function | Description |
+|---|---|
+| `count(x)` | Count non-null values |
+| `sum(x.prop)` | Sum numeric values |
+| `avg(x.prop)` | Average of numeric values (null if no values) |
+| `min(x.prop)` | Minimum numeric value (null if no values) |
+| `max(x.prop)` | Maximum numeric value (null if no values) |
+
+---
+
+## WHERE (on WITH)
+
+Filter results after a `WITH` clause:
+
+```cypher
+MATCH (s:Service)-[]->(t)
+WITH s, count(t) AS outDegree
+WHERE outDegree > 2
+RETURN s.name, outDegree
+```
+
+### Supported operators
+
+| Operator | Example |
+|---|---|
+| `=` | `WHERE count = 5` |
+| `>` | `WHERE count > 5` |
+| `<` | `WHERE count < 5` |
+| `CONTAINS` | `WHERE name CONTAINS "api"` |
+
+---
+
+## ORDER BY
+
+Sort results by one or more properties. Default direction is `ASC` (ascending).
+
+```cypher
+// Single column, ascending (default)
+MATCH (u:User) RETURN u.name ORDER BY u.name
+
+// Single column, descending
+MATCH (u:User) RETURN u.name, u.age ORDER BY u.age DESC
+
+// Multiple columns
+MATCH (u:User) RETURN u.name, u.age ORDER BY u.age ASC, u.name DESC
+```
+
+---
+
+## LIMIT
+
+Return only the first N results:
+
+```cypher
+MATCH (u:User) RETURN u.name LIMIT 5
+
+// Combined with ORDER BY for top-N
+MATCH (u:User) RETURN u.name, u.age ORDER BY u.age DESC LIMIT 3
+```
+
+---
+
+## SKIP
+
+Skip the first N results:
+
+```cypher
+MATCH (u:User) RETURN u.name SKIP 5
+
+// Pagination: page 2 with 10 results per page
+MATCH (u:User) RETURN u.name ORDER BY u.name ASC SKIP 10 LIMIT 10
+```
+
+---
+
+## Mutations
+
+### CREATE
+
+Create a new node:
+
+```cypher
+CREATE (l:Log {timestamp: 12345})
+RETURN l
+```
+
+### SET
+
+Update a node property:
+
+```cypher
+MATCH (u:User {name: 'Alice'})
+SET u.age = 31
+RETURN u
+```
+
+### DELETE
+
+Remove a node from the graph:
+
+```cypher
+MATCH (f:User {name: 'Bob'})
+DELETE f
+```
+
+---
+
+## Query Patterns
+
+### Blast radius analysis
+
+Find all nodes affected by a failure (up to N hops):
+
+```cypher
+MATCH (kafka:Infrastructure {name: "Kafka Cluster"})-[r*1..2]-(affected)
+RETURN kafka, r, affected
+```
+
+### Dependency chain
+
+Trace the full request path from entry point to databases:
+
+```cypher
+MATCH (api:Service {name: "API Gateway"})-[r*2..4]->(db:Database)
+RETURN api, r, db
+```
+
+### Collaborative filtering
+
+Find items recommended based on what "friends of friends" bought:
+
+```cypher
+MATCH (u:User {id: 'usr_abc'})-[:FRIEND*2..2]-(peer:User)-[:BOUGHT]->(item:Product)
+OPTIONAL MATCH (u)-[already_owns:BOUGHT]->(item)
+WITH item, already_owns
+WHERE already_owns IS NULL
+RETURN item
+```
+
+### What-if impact simulation
+
+Inject speculative properties mid-pipeline:
+
+```cypher
+MATCH (s:Server {id: 'srv_A'})-[:DEPENDS_ON*1..3]->(downstream:Application)
+SET s.capacity = 90
+WITH downstream, s
+WHERE downstream.min_required_capacity > s.capacity
+RETURN downstream.name AS at_risk_application, s.capacity AS simulated_capacity
+```
+
+### Top-N by degree
+
+Find the N nodes with the most connections:
+
+```cypher
+MATCH (s:Service)-[]->(target)
+WITH s, count(target) AS outDegree
+ORDER BY outDegree DESC
+LIMIT 3
+RETURN s.name, outDegree
+```
+
+---
+
+## Unsupported Features
+
+The following Cypher features are **not** supported by the engine:
+
+- **Subqueries** — `CALL {}` syntax
+- **APOC procedures** — `CALL apoc.*`
+- **Multiple MATCH in same stage** — use `WITH` to chain stages
+- **MERGE** — use `CREATE` or `MATCH` + `CREATE` instead
+- **FOREACH** — not implemented
+- **UNION** — not implemented
+
+## Next Steps
+
+- **[Library API](library-api)** — Use gcyphrq programmatically in your code
+- **[Examples](examples)** — 18 ready-to-run queries against the bundled cloud infrastructure graph

package/docs/skill.md

@@ -0,0 +1,219 @@
+---
+layout: default
+title: Skill Guide
+description: Install the gcyphrq skill on AI coding agents and use it to query graphs with natural language.
+---
+
+<div class="breadcrumb">
+  <a href="{{ '/' | relative_url }}">Home</a> <span>›</span> Skill Guide
+</div>
+
+# Skill Guide
+
+The **gcyphrq skill** lets AI coding agents execute Cypher queries against JSON graph files using natural language prompts. Install it once, then ask questions like *"What services depend on the API Gateway?"* and get structured JSON results.
+
+## What the Skill Does
+
+When installed, the skill teaches an AI agent to:
+
+- **Translate natural language** into Cypher queries automatically
+- **Run queries** against your JSON graph files using the `gcyphrq` CLI
+- **Interpret results** and present them in a readable format
+- **Chain multiple queries** for complex analysis (blast radius, path tracing, degree analysis)
+
+The skill includes a curated library of query patterns for common infrastructure questions — service dependencies, replication topology, monitoring coverage, and more.
+
+## Installation by Platform
+
+### Pi
+
+Pi auto-discovers skills placed in its skill directories.
+
+```bash
+# Copy the skill globally
+mkdir -p ~/.pi/agent/skills/gcyphrq/references
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
+  -o ~/.pi/agent/skills/gcyphrq/SKILL.md
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/queries.md \
+  -o ~/.pi/agent/skills/gcyphrq/references/queries.md
+
+# Or project-level (available only in this project)
+mkdir -p .pi/skills/gcyphrq/references
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
+  -o .pi/skills/gcyphrq/SKILL.md
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/queries.md \
+  -o .pi/skills/gcyphrq/references/queries.md
+```
+
+Pi will recognize the skill automatically. You can invoke it with `/skill:gcyphrq` or simply describe what you want in natural language — Pi will match the skill to your request.
+
+### Claude (Claude Code / MCP)
+
+Claude Code auto-discovers skills placed in its skill directories.
+
+```bash
+# Copy the skill globally
+mkdir -p ~/.claude/skills/gcyphrq/references
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
+  -o ~/.claude/skills/gcyphrq/SKILL.md
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/queries.md \
+  -o ~/.claude/skills/gcyphrq/references/queries.md
+
+# Or project-level (available only in this project)
+mkdir -p .claude/skills/gcyphrq/references
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
+  -o .claude/skills/gcyphrq/SKILL.md
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/queries.md \
+  -o .claude/skills/gcyphrq/references/queries.md
+```
+
+Claude Code will recognize the skill automatically when you ask graph-related questions.
+
+### OpenCode
+
+OpenCode supports skill files in its configuration directory:
+
+```bash
+# Install gcyphrq CLI globally
+npm install -g gcyphrq
+
+# Copy the skill to OpenCode's skill directory
+mkdir -p ~/.opencode/skills/gcyphrq/references
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md \
+  -o ~/.opencode/skills/gcyphrq/SKILL.md
+curl -sL https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/queries.md \
+  -o ~/.opencode/skills/gcyphrq/references/queries.md
+```
+
+OpenCode will load the skill and use it when your prompts match the skill's description (graph queries, infrastructure topology, service dependencies, etc.).
+
+### Other Agents
+
+For any AI coding agent that supports custom instructions or system prompts:
+
+1. **Install the CLI**: `npm install -g gcyphrq`
+2. **Copy the SKILL.md** from `https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/SKILL.md` into your agent's custom instructions
+3. **Copy the reference file** from `https://raw.githubusercontent.com/plelevier/gcyphrq/main/skills/gcyphrq/references/queries.md` into a `references/` subdirectory alongside SKILL.md
+4. **Point to your graph files** — replace `<graph.json>` in skill examples with paths to your actual graph files
+
+## Prerequisites
+
+- **gcyphrq CLI** installed and on PATH — see [Getting Started](getting-started) for install instructions
+- **A JSON graph file** to query (use the bundled `examples/cloud-infra.json` to get started)
+
+## Example Prompts
+
+Once the skill is installed, you can use natural language prompts. Here are examples that the skill should resolve:
+
+### Service Dependencies
+
+> **Prompt:** "What services does the API Gateway depend on?"
+
+The skill translates this to a Cypher query tracing outgoing connections from the API Gateway node.
+
+> **Prompt:** "Show me all services connected to PostgreSQL."
+
+Returns all services with TCP connections to the PostgreSQL Primary database.
+
+### Blast Radius Analysis
+
+> **Prompt:** "If Kafka goes down, what breaks?"
+
+Traces all nodes reachable from the Kafka Cluster within 2 hops to show the impact radius.
+
+> **Prompt:** "What's the blast radius if the API Gateway fails?"
+
+Maps all downstream services and infrastructure affected by the API Gateway being unavailable.
+
+### Path Tracing
+
+> **Prompt:** "Show me the path from the CDN to the database."
+
+Finds the connection path between the CDN and database nodes, showing intermediate services.
+
+> **Prompt:** "How does a request flow from the API Gateway to the user database?"
+
+Traces the request path through authentication, RPC services, and database connections.
+
+### Infrastructure Topology
+
+> **Prompt:** "How are the message queues connected?"
+
+Lists all message queue infrastructure and their producer/consumer relationships.
+
+> **Prompt:** "What's the replication setup for the databases?"
+
+Shows primary-replica relationships and replication edge types.
+
+### Degree Analysis
+
+> **Prompt:** "Which service has the most outgoing connections?"
+
+Computes out-degree for all services and returns the most connected one.
+
+> **Prompt:** "Find services with more than 2 outgoing connections."
+
+Filters services by out-degree threshold using aggregation and WHERE.
+
+### Monitoring Coverage
+
+> **Prompt:** "What services are being monitored?"
+
+Finds all services connected to monitoring infrastructure (Prometheus, Grafana, etc.).
+
+> **Prompt:** "Which services don't have monitoring?"
+
+Uses OPTIONAL MATCH to find services without monitoring connections.
+
+### External Dependencies
+
+> **Prompt:** "Which services call external APIs?"
+
+Traces RPC services through 1-3 hops to find external API dependencies.
+
+> **Prompt:** "List all external integrations."
+
+Returns all nodes with the External label and their upstream callers.
+
+### Pagination
+
+> **Prompt:** "Show me page 2 of services, 10 per page, sorted alphabetically."
+
+Uses ORDER BY, SKIP, and LIMIT to paginate through service results.
+
+### Graph Mutations
+
+> **Prompt:** "Add a new monitoring service called 'Datadog'."
+
+Uses CREATE to add a new node to the graph.
+
+> **Prompt:** "Set the status of the API Gateway to 'deprecated'."
+
+Uses SET to update a node property.
+
+## Skill Reference
+
+The skill file (`SKILL.md`) includes:
+
+- **CLI usage** — command syntax, options, stdin piping
+- **Graph file format** — node and edge structure
+- **Supported Cypher features** — full feature matrix with status
+- **Query patterns** — pre-built queries for the cloud-infra example graph
+- **Output format** — raw JSON output specification
+- **Limitations** — known constraints (single MATCH per stage, no subqueries, etc.)
+
+## Troubleshooting
+
+| Issue | Solution |
+|---|---|
+| `gcyphrq: command not found` | Run `npm install -g gcyphrq` or `npm link` |
+| Skill not detected by agent | Verify the `SKILL.md` is in the correct skill directory for your platform |
+| Query returns empty results | Check that node labels and property names match your graph file exactly |
+| "Single MATCH per stage" error | Split chained MATCHes into separate queries or use WITH pipelining |
+
+## Next Steps
+
+- **[Getting Started](getting-started)** — Install gcyphrq and run your first query
+- **[Query Guide](query-guide)** — Full Cypher syntax reference
+- **[Examples](examples)** — 18 ready-to-run queries against the cloud infrastructure graph
+- **[Library API](library-api)** — Use gcyphrq programmatically in Node.js / TypeScript

package/examples/README.md

@@ -0,0 +1,187 @@
+# Example Graphs
+
+This directory contains example graph files you can use with `gcyphrq`.
+
+Each file uses a simple JSON format:
+
+```json
+{
+  "nodes": [
+    { "id": "<node-id>", "label": "<label>", "<property>": "<value>", ... }
+  ],
+  "edges": [
+    { "source": "<source-id>", "target": "<target-id>", "type": "<edge-type>", ... }
+  ]
+}
+```
+
+## Available examples
+
+| File | Description |
+|---|---|
+| `social-graph.json` | A small social network with three users connected by `FRIEND` relationships |
+| `cloud-infra.json` | A full startup cloud infrastructure — 52 nodes, 110 edges — with RPC services, message queues, databases, workers, monitoring, and external APIs |
+
+## Usage
+
+```bash
+# Load a graph from file
+gcyphrq -g examples/social-graph.json -e 'MATCH (u:User) RETURN u'
+
+# Pipe a graph from stdin
+cat examples/social-graph.json | gcyphrq -g - -e 'MATCH (u:User) RETURN u'
+```
+
+---
+
+## `cloud-infra.json` — Query Examples
+
+This graph models an entire startup's cloud service infrastructure. Use it to explore real-world queries like impact analysis, dependency chains, and service topology.
+
+### 1. List all RPC services
+
+Find every service of type `RPC` running in the infrastructure:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service {type: "RPC"}) RETURN s'
+```
+
+### 2. Trace the full request path from the public API to databases
+
+Follow the call chain from the API Gateway, 2–4 hops deep, to see which databases a request can reach:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (api:Service {name: "API Gateway"})-[r*2..4]->(db:Database) RETURN api, r, db'
+```
+
+### 3. Find all services that depend on a specific database
+
+Discover every service that has a direct connection to the PostgreSQL primary:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[:TCP]->(db:Database {name: "PostgreSQL Primary"}) RETURN s'
+```
+
+### 4. Count how many services each message queue feeds into
+
+Group by message queue and count the downstream consumers:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (mq:Infrastructure {type: "MessageQueue"})-[:TCP]->(w:Service) WITH mq, count(w) AS consumerCount RETURN mq, consumerCount'
+```
+
+### 5. Find the blast radius of a service failure
+
+If the Kafka cluster goes down, which services are directly or indirectly affected (up to 2 hops)?
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (kafka:Infrastructure {name: "Kafka Cluster"})-[r*1..2]-(affected) RETURN kafka, r, affected'
+```
+
+### 6. List all external dependencies per service
+
+For each RPC service, find which external APIs it calls (directly or through intermediaries, up to 3 hops):
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service {type: "RPC"})-[r*1..3]->(ext:External) RETURN s, ext'
+```
+
+### 7. Find which services call Stripe
+
+Trace from any service through up to 3 hops to find which ones reach the Stripe API:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[r*1..3]->(stripe:External {name: "Stripe API"}) RETURN s, stripe'
+```
+
+### 8. Map the replication topology
+
+Find all replication relationships between databases:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (primary:Database)-[r:Replication]->(replica:Database) RETURN primary, r, replica'
+```
+
+### 9. Find the longest dependency chain
+
+Trace paths from the CDN (edge) down through the infrastructure to storage or databases (up to 6 hops):
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (cdn:Service {name: "CloudFront CDN"})-[r*1..6]->(leaf:Database) RETURN cdn, r, leaf'
+```
+
+### 10. List all services hosted on the primary EKS cluster
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (eks:Infrastructure {name: "EKS Cluster"})-[:Hosts]->(s:Service) RETURN s'
+```
+
+### 11. Find which services talk to Vault for secrets
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[:HTTPS]->(v:Security {name: "Vault"}) RETURN s'
+```
+
+### 12. Count outgoing connections per service
+
+Rank services by how many direct dependencies they have:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[]->(target) WITH s, count(target) AS outDegree WHERE outDegree > 2 RETURN s, outDegree'
+```
+
+### 13. Sort services by name (ORDER BY)
+
+Return all services sorted alphabetically by name:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service) RETURN s.name ORDER BY s.name ASC'
+```
+
+### 14. Top-N services by connection count (ORDER BY + LIMIT)
+
+Find the 3 services with the most outgoing connections:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[]->(target) WITH s, count(target) AS outDegree ORDER BY outDegree DESC LIMIT 3 RETURN s.name, outDegree'
+```
+
+### 15. Limit results to first N (LIMIT)
+
+Return only the first 5 databases in the infrastructure:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (d:Database) RETURN d.name LIMIT 5'
+```
+
+### 16. Sort by multiple columns
+
+Sort services first by type (ascending), then by name (descending):
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service) RETURN s.type, s.name ORDER BY s.type ASC, s.name DESC'
+```
+
+### 17. Skip first N results (SKIP)
+
+Skip the first 5 services when listing all services:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service) RETURN s.name SKIP 5'
+```
+
+### 18. Pagination with ORDER BY + SKIP + LIMIT
+
+Get page 2 of services sorted by name (10 per page):
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service) RETURN s.name ORDER BY s.name ASC SKIP 10 LIMIT 10'
+```
+
+### 19. Average, min, max aggregations
+
+Compute average, minimum, and maximum across all users:
+
+```bash
+gcyphrq -g examples/social-graph.json -e 'MATCH (u:User) RETURN avg(u.age) AS avgAge, min(u.age) AS minAge, max(u.age) AS maxAge'
+```