From 0dc89badfb3ec8c859ef08c16d5b9b2070bec569 Mon Sep 17 00:00:00 2001
From: Dan Lynch <pyramation@gmail.com>
Date: Tue, 27 Jan 2026 03:14:15 +0000
Subject: [PATCH] feat: add cnc-execution-engine skill for GraphQL API
 execution

Adds skill documentation for the cnc CLI execution engine:
- Context management (create, list, use, current, delete)
- Authentication (set-token, status, logout)
- Query execution (--query, --file, --variables)

Similar to kubectl contexts - manages endpoint + credentials configurations.
---
 skills/cnc-execution-engine.zip      | Bin 0 -> 2676 bytes
 skills/cnc-execution-engine/SKILL.md | 301 +++++++++++++++++++++++++++
 2 files changed, 301 insertions(+)
 create mode 100644 skills/cnc-execution-engine.zip
 create mode 100644 skills/cnc-execution-engine/SKILL.md

diff --git a/skills/cnc-execution-engine.zip b/skills/cnc-execution-engine.zip
new file mode 100644
index 0000000000000000000000000000000000000000..975b0e552e4e23e3c6b9ab444648264118704b57
GIT binary patch
literal 2676
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

literal 0
HcmV?d00001

diff --git a/skills/cnc-execution-engine/SKILL.md b/skills/cnc-execution-engine/SKILL.md
new file mode 100644
index 0000000..a3f9dda
--- /dev/null
+++ b/skills/cnc-execution-engine/SKILL.md
@@ -0,0 +1,301 @@
+---
+name: cnc-execution-engine
+description: Execute GraphQL queries against Constructive APIs using the cnc CLI. Use when asked to "run a query", "execute GraphQL", "set up API context", "configure API token", "manage API endpoints", or when working with Constructive GraphQL APIs.
+compatibility: Node.js 18+, cnc CLI (constructive-io/constructive)
+metadata:
+  author: constructive-io
+  version: "1.0.0"
+---
+
+# CNC Execution Engine
+
+Execute raw GraphQL queries against Constructive APIs using the `cnc` CLI. Manage multiple API contexts (endpoint + credentials) similar to kubectl contexts.
+
+## When to Apply
+
+Use this skill when:
+- Executing GraphQL queries against Constructive APIs
+- Setting up API endpoint configurations
+- Managing API tokens for authentication
+- Switching between multiple API environments (dev, staging, prod)
+- Testing GraphQL queries from the command line
+
+## Quick Start
+
+```bash
+# Create a context with an endpoint
+cnc context create my-api --endpoint https://api.example.com/graphql
+
+# Set your API token (input is masked)
+cnc auth set-token
+
+# Execute a query
+cnc execute --query 'query { __typename }'
+```
+
+## Context Management
+
+Contexts store endpoint URLs and are similar to kubectl contexts. They are stored in `~/.cnc/config/contexts/`.
+
+### Create a Context
+
+```bash
+# Interactive mode
+cnc context create
+
+# With flags
+cnc context create my-api --endpoint https://api.example.com/graphql
+```
+
+### List Contexts
+
+```bash
+cnc context list
+```
+
+Output shows all contexts with authentication status:
+
+```
+Contexts:
+
+* my-api [authenticated]
+    Endpoint: https://api.example.com/graphql
+
+  staging [no token]
+    Endpoint: https://staging.example.com/graphql
+```
+
+### Switch Context
+
+```bash
+cnc context use staging
+```
+
+### Show Current Context
+
+```bash
+cnc context current
+```
+
+### Delete a Context
+
+```bash
+cnc context delete old-api
+```
+
+## Authentication
+
+Tokens are stored securely in `~/.cnc/config/credentials.json` with restricted file permissions (0o600).
+
+### Set Token
+
+```bash
+# Interactive (input masked with asterisks)
+cnc auth set-token
+
+# With token as argument
+cnc auth set-token eyJhbGciOiJIUzI1NiIs...
+
+# For a specific context
+cnc auth set-token --context staging
+
+# With expiration
+cnc auth set-token --expires 2024-12-31T23:59:59Z
+```
+
+### Check Auth Status
+
+```bash
+cnc auth status
+```
+
+Output:
+
+```
+Authentication Status:
+
+* my-api
+    Status: Authenticated
+    Token:  eyJhbG...s5Nw
+    Expires: 2024-12-31T23:59:59Z
+
+  staging
+    Status: Not authenticated
+```
+
+### Logout
+
+```bash
+cnc auth logout
+cnc auth logout --context staging
+```
+
+## Executing Queries
+
+### Inline Query
+
+```bash
+cnc execute --query 'query { databases { nodes { id name } } }'
+```
+
+### From File
+
+```bash
+cnc execute --file query.graphql
+```
+
+### With Variables
+
+```bash
+cnc execute --query 'query($id: UUID!) { database(id: $id) { name } }' \
+  --variables '{"id":"550e8400-e29b-41d4-a716-446655440000"}'
+```
+
+### Using a Specific Context
+
+```bash
+cnc execute --query 'query { __typename }' --context staging
+```
+
+## Output Format
+
+Successful queries return JSON:
+
+```
+Context: my-api
+Endpoint: https://api.example.com/graphql
+
+Success!
+
+{
+  "databases": {
+    "nodes": [
+      { "id": "...", "name": "my-database" }
+    ]
+  }
+}
+```
+
+Failed queries show errors:
+
+```
+Failed!
+
+  - Field "nonexistent" not found
+    Path: query.nonexistent
+```
+
+## Common Workflows
+
+### Setting Up a New Environment
+
+```bash
+# Create context for production
+cnc context create prod --endpoint https://api.constructive.io/graphql
+
+# Set the API token
+cnc auth set-token
+
+# Verify connection
+cnc execute --query 'query { __typename }'
+```
+
+### Working with Multiple Environments
+
+```bash
+# Create contexts for each environment
+cnc context create dev --endpoint https://dev-api.example.com/graphql
+cnc context create staging --endpoint https://staging-api.example.com/graphql
+cnc context create prod --endpoint https://api.example.com/graphql
+
+# Set tokens for each
+cnc auth set-token --context dev
+cnc auth set-token --context staging
+cnc auth set-token --context prod
+
+# Switch between environments
+cnc context use dev
+cnc execute --query 'query { databases { nodes { id } } }'
+
+cnc context use prod
+cnc execute --query 'query { databases { nodes { id } } }'
+```
+
+### Scripting with CNC
+
+```bash
+#!/bin/bash
+# Example: Query all databases and save to file
+
+cnc context use prod
+cnc execute --query 'query { databases { nodes { id name createdAt } } }' > databases.json
+```
+
+## CLI Reference
+
+### cnc context
+
+| Command | Description |
+|---------|-------------|
+| `cnc context create <name>` | Create a new context |
+| `cnc context list` | List all contexts |
+| `cnc context use <name>` | Switch to a context |
+| `cnc context current` | Show current context details |
+| `cnc context delete <name>` | Delete a context |
+
+**Create Options:**
+- `--endpoint <url>` - GraphQL endpoint URL
+
+### cnc auth
+
+| Command | Description |
+|---------|-------------|
+| `cnc auth set-token [token]` | Set API token (masked input if no token provided) |
+| `cnc auth status` | Show authentication status for all contexts |
+| `cnc auth logout` | Remove credentials for current context |
+
+**Options:**
+- `--context <name>` - Target a specific context
+- `--expires <date>` - Token expiration date (ISO format)
+
+### cnc execute
+
+| Option | Description |
+|--------|-------------|
+| `--query <graphql>` | GraphQL query/mutation string |
+| `--file <path>` | Path to file containing GraphQL query |
+| `--variables <json>` | Variables as JSON string |
+| `--context <name>` | Context to use (defaults to current) |
+
+## File Locations
+
+| Path | Purpose |
+|------|---------|
+| `~/.cnc/config/contexts/` | Context configuration files |
+| `~/.cnc/config/settings.json` | Global settings (current context) |
+| `~/.cnc/config/credentials.json` | API tokens (mode 0o600) |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "No active context" | Run `cnc context create` or `cnc context use` |
+| "No valid credentials" | Run `cnc auth set-token` |
+| "Context not found" | Check `cnc context list` for available contexts |
+| Token expired | Run `cnc auth set-token` to set a new token |
+| Connection refused | Verify endpoint URL with `cnc context current` |
+
+## Environment Variables
+
+The CLI respects standard environment variables but stored context/credentials take precedence:
+
+| Variable | Description |
+|----------|-------------|
+| `CNC_ENDPOINT` | Override endpoint URL |
+| `CNC_TOKEN` | Override API token |
+
+## References
+
+- CLI source: `packages/cli/` in constructive-io/constructive
+- Config management uses `appstash` for directory resolution
+- Related skill: `constructive-graphql-codegen` for generating typed hooks/ORM