gcyphrq 0.12.6

package/docs/assets/main.css

@@ -0,0 +1,416 @@
+/* === Reset & Base === */
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+:root {
+  --color-bg: #ffffff;
+  --color-bg-secondary: #f8f9fb;
+  --color-text: #1a1a2e;
+  --color-text-secondary: #555;
+  --color-accent: #4f46e5;
+  --color-accent-light: #eef2ff;
+  --color-border: #e2e8f0;
+  --color-code-bg: #f4f5f7;
+  --color-code-text: #1f2937;
+  --color-success: #16a34a;
+  --color-warning: #f59e0b;
+  --color-danger: #dc2626;
+  --max-width: 1100px;
+  --header-height: 64px;
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --font-mono: "SF Mono", "Fira Code", "Fira Mono", "Roboto Mono", Consolas, monospace;
+}
+
+html { scroll-behavior: smooth; font-size: 16px; }
+
+body {
+  font-family: var(--font-sans);
+  color: var(--color-text);
+  background: var(--color-bg);
+  line-height: 1.7;
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+a { color: var(--color-accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+
+.container { max-width: var(--max-width); margin: 0 auto; padding: 0 2.5rem; }
+
+@media (max-width: 768px) {
+  .container { padding: 0 1.25rem; }
+}
+
+/* === Header === */
+.site-header {
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  background: rgba(255, 255, 255, 0.92);
+  backdrop-filter: blur(12px);
+  border-bottom: 1px solid var(--color-border);
+  height: var(--header-height);
+}
+
+.site-header .container {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 100%;
+}
+
+.logo {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-weight: 700;
+  font-size: 1.25rem;
+  color: var(--color-text);
+  text-decoration: none;
+}
+
+.logo:hover { text-decoration: none; }
+
+.logo-icon { font-size: 1.5rem; color: var(--color-accent); }
+.logo-text small { font-weight: 400; font-size: 0.75rem; color: var(--color-text-secondary); margin-left: 0.25rem; }
+
+/* === Navigation === */
+.main-nav ul {
+  display: flex;
+  list-style: none;
+  gap: 0.25rem;
+}
+
+.main-nav a {
+  display: block;
+  padding: 0.4rem 0.85rem;
+  border-radius: 6px;
+  font-size: 0.9rem;
+  font-weight: 500;
+  color: var(--color-text-secondary);
+  transition: background 0.15s, color 0.15s;
+}
+
+.main-nav a:hover, .main-nav a.active {
+  background: var(--color-accent-light);
+  color: var(--color-accent);
+  text-decoration: none;
+}
+
+.external-icon { font-size: 0.75rem; opacity: 0.6; }
+
+.nav-toggle { display: none; }
+.nav-toggle-label { display: none; flex-direction: column; gap: 4px; cursor: pointer; padding: 0.5rem; }
+.nav-toggle-label span { display: block; width: 20px; height: 2px; background: var(--color-text); border-radius: 1px; }
+
+@media (max-width: 768px) {
+  .nav-toggle-label { display: flex; }
+  .main-nav ul {
+    display: none;
+    flex-direction: column;
+    position: absolute;
+    top: var(--header-height);
+    left: 0;
+    right: 0;
+    background: var(--color-bg);
+    border-bottom: 1px solid var(--color-border);
+    padding: 0.5rem;
+    gap: 0;
+  }
+  .nav-toggle:checked ~ ul { display: flex; }
+  .main-nav a { padding: 0.6rem 0.85rem; }
+}
+
+/* === Content === */
+.content { flex: 1; padding: 3rem 0; }
+
+.content h1 { font-size: 2.25rem; font-weight: 800; line-height: 1.2; margin-bottom: 0.5rem; }
+.content h2 { font-size: 1.6rem; font-weight: 700; margin-top: 2.5rem; margin-bottom: 0.75rem; padding-bottom: 0.4rem; border-bottom: 1px solid var(--color-border); }
+.content h3 { font-size: 1.25rem; font-weight: 600; margin-top: 2rem; margin-bottom: 0.5rem; }
+.content h4 { font-size: 1.1rem; font-weight: 600; margin-top: 1.5rem; margin-bottom: 0.5rem; }
+
+.content p { margin-bottom: 1.25rem; }
+.content ul, .content ol { margin-bottom: 1.25rem; padding-left: 1.5rem; }
+.content li { margin-bottom: 0.35rem; }
+
+.content strong { font-weight: 600; }
+
+.content table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-bottom: 1.5rem;
+  font-size: 0.9rem;
+}
+
+@media (max-width: 768px) {
+  .content table {
+    display: block;
+    overflow-x: auto;
+  }
+}
+
+.content th {
+  text-align: left;
+  padding: 0.6rem 0.8rem;
+  background: var(--color-bg-secondary);
+  font-weight: 600;
+  border-bottom: 2px solid var(--color-border);
+}
+
+.content td {
+  padding: 0.55rem 0.8rem;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.content tr:hover td { background: var(--color-bg-secondary); }
+
+/* Inline code */
+.content p code, .content li code, .content td code {
+  background: var(--color-accent-light);
+  color: var(--color-accent);
+  padding: 0.15em 0.4em;
+  border-radius: 4px;
+  font-size: 0.88em;
+  font-family: var(--font-mono);
+}
+
+/* Code blocks */
+.highlight, pre.highlight {
+  background: var(--color-code-bg) !important;
+  border-radius: 4px;
+  margin: 1rem 0;
+  overflow-x: auto;
+}
+
+.highlight code, pre.highlight code {
+  color: var(--color-code-text) !important;
+  background: none !important;
+  padding: 0 !important;
+  font-size: 0.84rem;
+  line-height: 1.5;
+}
+
+.highlight { padding: 0.6rem; }
+
+/* Copy button */
+.code-block-wrapper {
+  position: relative;
+  margin: 1rem 0;
+}
+
+.code-block-wrapper .highlight {
+  margin: 0;
+}
+
+.code-copy-btn {
+  position: absolute;
+  top: 0.4rem;
+  right: 0.4rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 26px;
+  height: 26px;
+  padding: 0;
+  background: rgba(0,0,0,0.04);
+  border: 1px solid rgba(0,0,0,0.08);
+  border-radius: 4px;
+  color: rgba(0,0,0,0.35);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.15s, color 0.15s, background 0.15s;
+}
+
+.code-block-wrapper:hover .code-copy-btn {
+  opacity: 1;
+}
+
+/* Always visible on touch devices where :hover doesn't work */
+@media (hover: none) {
+  .code-copy-btn {
+    opacity: 1;
+  }
+}
+
+.code-copy-btn:hover {
+  color: rgba(0,0,0,0.7);
+  background: rgba(0,0,0,0.07);
+}
+
+.code-copy-btn.copied {
+  color: #059669;
+  border-color: rgba(5,150,105,0.3);
+}
+
+/* Cypher keyword highlighting */
+.highlight .cy-kw   { color: #7c3aed; font-weight: 600; }
+.highlight .cy-fn   { color: #2563eb; }
+.highlight .cy-label { color: #d97706; }
+.highlight .cy-rel  { color: #0d9488; font-weight: 600; }
+.highlight .cy-str  { color: #059669; }
+.highlight .cy-num  { color: #d97706; }
+.highlight .cy-cmt  { color: #52525b; font-style: italic; }
+
+/* Rouge syntax highlighting (light theme) */
+.highlight .c, .highlight .c1, .highlight .cm, .highlight .cp { color: #52525b; font-style: italic; }
+.highlight .err { color: #dc2626; }
+.highlight .k, .highlight .kd, .highlight .kn, .highlight .kp, .highlight .kr { color: #7c3aed; }
+.highlight .kt { color: #d97706; }
+.highlight .m, .highlight .mf, .highlight .mh, .highlight .mi { color: #d97706; }
+.highlight .s, .highlight .s1, .highlight .s2, .highlight .sc, .highlight .se, .highlight .sh, .highlight .si, .highlight .sx { color: #059669; }
+.highlight .n, .highlight .nn, .highlight .py { color: #1f2937; }
+.highlight .na, .highlight .nc, .highlight .nd, .highlight .ne, .highlight .nf { color: #2563eb; }
+.highlight .nl, .highlight .nv, .highlight .vc, .highlight .vg, .highlight .vi { color: #dc2626; }
+.highlight .o { color: #0d9488; }
+.highlight .p { color: #6b7280; }
+.highlight .ow { color: #7c3aed; }
+.highlight .e { color: #dc2626; }
+.highlight .gu, .highlight .gd { color: #dc2626; }
+.highlight .gi { color: #059669; }
+
+/* === Hero (home page) === */
+.hero {
+  text-align: center;
+  padding: 3rem 0 2rem;
+}
+
+.hero h1 {
+  font-size: 3rem;
+  font-weight: 800;
+  margin-bottom: 1rem;
+  background: linear-gradient(135deg, var(--color-accent), #7c3aed);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.hero .tagline {
+  font-size: 1.2rem;
+  color: var(--color-text-secondary);
+  max-width: 600px;
+  margin: 0 auto 2rem;
+}
+
+.hero-actions {
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+  flex-wrap: wrap;
+  margin-bottom: 2rem;
+}
+
+.btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.7rem 1.5rem;
+  border-radius: 8px;
+  font-weight: 600;
+  font-size: 0.95rem;
+  transition: transform 0.15s, box-shadow 0.15s;
+}
+
+.btn:hover { transform: translateY(-1px); text-decoration: none; }
+
+.btn-primary {
+  background: var(--color-accent);
+  color: #fff;
+  box-shadow: 0 2px 8px rgba(79, 70, 229, 0.3);
+}
+
+.btn-primary:hover { box-shadow: 0 4px 16px rgba(79, 70, 229, 0.4); }
+
+.btn-secondary {
+  background: var(--color-bg-secondary);
+  color: var(--color-text);
+  border: 1px solid var(--color-border);
+}
+
+.btn-secondary:hover { border-color: var(--color-accent); }
+
+/* === Feature Cards === */
+.feature-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 1.25rem;
+  margin: 2rem 0;
+}
+
+.feature-card {
+  background: var(--color-bg-secondary);
+  border: 1px solid var(--color-border);
+  border-radius: 6px;
+  padding: 1rem 1.15rem;
+  transition: box-shadow 0.2s, border-color 0.2s;
+}
+
+.feature-card:hover {
+  border-color: var(--color-accent);
+  box-shadow: 0 4px 12px rgba(79, 70, 229, 0.08);
+}
+
+.feature-card h3 {
+  margin-top: 0;
+  margin-bottom: 0.5rem;
+  font-size: 1.1rem;
+}
+
+.feature-card p {
+  color: var(--color-text-secondary);
+  font-size: 0.92rem;
+  margin-bottom: 0;
+}
+
+/* === Callout === */
+.callout {
+  border-left: 3px solid var(--color-accent);
+  background: var(--color-accent-light);
+  padding: 0.6rem 0.85rem;
+  border-radius: 0 4px 4px 0;
+  margin: 1.25rem 0;
+}
+
+.callout p { margin-bottom: 0; }
+.callout p + p { margin-top: 0.5rem; }
+
+/* === Breadcrumb === */
+.breadcrumb {
+  font-size: 0.85rem;
+  color: var(--color-text-secondary);
+  margin-bottom: 1rem;
+}
+
+.breadcrumb a { color: var(--color-text-secondary); }
+.breadcrumb a:hover { color: var(--color-accent); }
+.breadcrumb span { margin: 0 0.4rem; }
+
+/* === Status badges === */
+.badge {
+  display: inline-block;
+  padding: 0.15em 0.5em;
+  border-radius: 4px;
+  font-size: 0.8rem;
+  font-weight: 600;
+  vertical-align: middle;
+}
+
+.badge-success { background: #dcfce7; color: var(--color-success); }
+.badge-warning { background: #fef3c7; color: var(--color-warning); }
+.badge-danger { background: #fee2e2; color: var(--color-danger); }
+
+/* === Footer === */
+.site-footer {
+  border-top: 1px solid var(--color-border);
+  padding: 2rem 0;
+  text-align: center;
+  font-size: 0.85rem;
+  color: var(--color-text-secondary);
+}
+
+.site-footer a { color: var(--color-text-secondary); }
+.site-footer a:hover { color: var(--color-accent); }
+
+/* === Scrollbar === */
+.highlight::-webkit-scrollbar { height: 6px; }
+.highlight::-webkit-scrollbar-track { background: transparent; }
+.highlight::-webkit-scrollbar-thumb { background: rgba(0,0,0,0.15); border-radius: 3px; }

package/docs/cli.md

@@ -0,0 +1,115 @@
+---
+layout: default
+title: CLI Reference
+description: Command-line interface reference for gcyphrq.
+---
+
+<div class="breadcrumb">
+  <a href="{{ '/' | relative_url }}">Home</a> <span>›</span> CLI Reference
+</div>
+
+# CLI Reference
+
+The `gcyphrq` CLI executes Cypher graph queries against a JSON graph file and outputs raw JSON results to stdout.
+
+## Usage
+
+```bash
+gcyphrq [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --expr <query>` | Cypher query expression (**required**) |
+| `-g, --graph <file>` | Path to a JSON graph file, or `"-"` to read from stdin (**required**) |
+| `-h, --help` | Show help message |
+
+Both `-e` and `-g` are required. The tool exits with code 1 and prints to stderr if either is missing.
+
+## Loading a Graph
+
+### From a file
+
+```bash
+gcyphrq -g examples/social-graph.json -e 'MATCH (u:User) RETURN u'
+```
+
+### From stdin
+
+```bash
+cat my-graph.json | gcyphrq -g - -e 'MATCH (u:User) RETURN u'
+```
+
+## Output Format
+
+The CLI outputs **raw JSON** — a JSON array of result objects with no prefixes, no markdown, and no extra text. Stdout is pipe-friendly for downstream tools like `jq`:
+
+```bash
+gcyphrq -g examples/social-graph.json -e 'MATCH (u:User) RETURN u.name' | jq '.[0].name'
+```
+
+## Error Handling
+
+All errors are printed to **stderr** with an `Error: ` prefix, and the process exits with code 1:
+
+```
+Error: Invalid graph data: missing "nodes" array
+```
+
+This separation of stdout (results) and stderr (errors) ensures you can safely pipe results without capturing error messages.
+
+## Common Patterns
+
+### Quick inspection
+
+List all nodes of a specific label:
+
+```bash
+gcyphrq -g graph.json -e 'MATCH (s:Service) RETURN s.name'
+```
+
+### Filter with WHERE (on WITH)
+
+```bash
+gcyphrq -g graph.json -e 'MATCH (s:Service) WITH s WHERE s.name CONTAINS "api" RETURN s.name'
+```
+
+### Aggregation
+
+```bash
+gcyphrq -g graph.json -e 'MATCH (n) RETURN count(n) AS totalNodes'
+```
+
+### Top-N with ORDER BY + LIMIT
+
+```bash
+gcyphrq -g graph.json -e 'MATCH (s:Service)-[]->(t) WITH s, count(t) AS outDegree ORDER BY outDegree DESC LIMIT 3 RETURN s.name, outDegree'
+```
+
+### Variable-length paths
+
+```bash
+gcyphrq -g graph.json -e 'MATCH (a:Service {name: "API Gateway"})-[r*1..3]->(b) RETURN a, r, b'
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Query executed successfully |
+| `1` | Error (missing arguments, invalid graph, query parse error, etc.) |
+
+## Running without installing
+
+You can run the tool directly from source using `tsx`:
+
+```bash
+npx tsx src/index.ts -g examples/social-graph.json -e 'MATCH (u:User) RETURN u'
+```
+
+## Next Steps
+
+- **[Query Guide](query-guide)** — Full Cypher syntax reference and query patterns
+- **[Examples](examples)** — Ready-to-run queries against the bundled graph files