apigrip 0.1.0

package/README.md

@@ -0,0 +1,240 @@
+# Apigrip
+
+A spec-first, read-only OpenAPI client for developers who generate their API specs from code.
+
+The spec file on disk is the only source of truth. It is never imported, copied, or converted. When it changes (because you regenerated it, switched branches, or pulled), the tool reflects the changes immediately.
+
+![Apigrip demo](docs/apigrip-demo.gif)
+
+## Quick start
+
+```bash
+npm install
+npm start -- --project /path/to/your/api
+```
+
+Open `http://127.0.0.1:3000` in your browser.
+
+## Requirements
+
+- Node.js 20+
+- curl 7.70+ (for `--write-out` JSON format)
+
+## Features
+
+- Browse endpoints from any OpenAPI 2.0, 3.0.x, or 3.1.x spec
+- Send requests via curl subprocess with full `curl -v` level detail
+- Live reload on spec changes, git branch switches, and `$ref` dependency updates
+- Parameter persistence across restarts (auto-saved per project, per endpoint)
+- Named environments with `{{ variable }}` syntax resolved at send time
+- Git status bar showing branch, commit, and dirty/clean state
+- `Ctrl+P` command palette with fuzzy search across projects and endpoints
+- Response schema validation against the spec
+- Dracula dark theme by default, light mode available
+- MCP server for AI coding assistants
+
+## CLI
+
+```bash
+# Start the web UI
+apigrip serve                                    # default port 3000
+apigrip serve --port 8080 --open                 # custom port, open browser
+
+# Send requests from the terminal
+apigrip send GET /users                          # basic request
+apigrip send POST /users -d '{"name": "John"}'   # with body
+apigrip send GET /users/{id} --pathParam id=42   # path param
+apigrip send GET /users -e Staging --verbose     # use named environment
+apigrip send GET /users --dry-run                # print without sending
+apigrip send GET /users --curl                   # print curl command only
+
+# Generate curl command (shorthand for send --curl)
+apigrip curl GET /users -e Production
+
+# List endpoints
+apigrip list                                     # grouped by tag
+apigrip list --search "auth" --json              # fuzzy search, JSON output
+
+# Manage projects
+apigrip projects                                 # list bookmarks
+apigrip projects add ./my-api                    # bookmark a directory
+apigrip projects remove my-api                   # remove bookmark
+
+# Manage environments
+apigrip env                                      # list environments
+apigrip env show Staging                         # show variables
+apigrip env set Staging api_key "sk-123"         # set a variable
+apigrip env delete Staging api_key               # delete a variable
+apigrip env import envs.json                     # import from JSON file
+apigrip env import staging.json --import-name Staging  # into named env
+
+# View last cached response
+apigrip last                                     # list all cached endpoints
+apigrip last GET /users                          # show last response body
+apigrip last GET /users --json                   # full JSON output
+
+# MCP server (for AI assistants)
+apigrip mcp --project /path/to/api
+```
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success (HTTP 4xx/5xx responses are still exit 0) |
+| 1 | Network error (DNS, connection refused, timeout) |
+| 2 | Spec parse error |
+| 3 | Endpoint not found |
+
+### Project context
+
+CLI commands auto-detect the project from the current working directory:
+
+1. If `--project` or `--spec` is passed, use that
+2. If cwd is inside a bookmarked project, use it
+3. If cwd contains an OpenAPI spec file, use it directly
+4. Otherwise, error
+
+## Web UI
+
+Two-panel layout: request on the left, response on the right.
+
+**Left panel** -- endpoint browser (tag view or path tree view), server selector, parameter inputs, request body editor, send button.
+
+**Right panel** -- status badge, timing, response body (pretty-printed), headers, verbose `curl -v` output, copyable curl command.
+
+**Keyboard shortcuts**: `Ctrl+P` (command palette), `Ctrl+O` (open project), `Ctrl+E` (environment editor), `Ctrl+Enter` (send request).
+
+## Environments
+
+Environments are named sets of key-value pairs stored per project in the config directory (never in your project).
+
+```
+Base Environment     ->  base_url=http://localhost:8080, api_version=v1
+  + Staging          ->  base_url=https://staging.example.com, auth_token=sk-...
+  + Production       ->  base_url=https://api.example.com, auth_token=pk-...
+```
+
+Reference variables anywhere: server URL, parameters, headers, request body. They resolve at send time.
+
+Reserved keys: `timeout` (integer, seconds -- default 30), `insecure` (boolean -- passes `--insecure` to curl).
+
+## Library API
+
+Use apigrip programmatically in your own scripts and tools:
+
+```js
+// ESM
+import { loadSpec, send, validateBody } from 'apigrip';
+
+// CommonJS
+const { loadSpec, send } = await require('apigrip');
+```
+
+### Quick examples
+
+```js
+// Load and inspect a spec
+const { spec, endpoints } = await loadSpec('./my-api/');
+console.log(`${endpoints.length} endpoints found`);
+
+// Send a request with full validation
+const res = await send('./my-api/', 'GET', '/users', {
+  params: { query: { limit: '10' } },
+  env: 'staging',
+  projectDir: './my-api/',
+});
+console.log(res.status, res.validation);
+
+// Retrieve last cached response
+import { loadLastResponse } from 'apigrip';
+const cached = loadLastResponse('./my-api/', 'GET', '/users');
+```
+
+### All exports
+
+| Category | Functions |
+|----------|-----------|
+| **Spec** | `discoverSpec`, `parseSpec`, `extractEndpoints`, `getEndpointDetails`, `getRefDeps` |
+| **Request** | `buildUrl`, `buildCurlArgs`, `executeCurl`, `cancelRequest`, `checkCurl`, `shellQuote` |
+| **Environment** | `loadEnvironments`, `saveEnvironments`, `resolveEnvironment`, `resolveVariables`, `resolveAllParams`, `getConfigDir`, `getProjectHash` |
+| **Validation** | `validateBody`, `validateResponse` |
+| **Storage** | `loadParams`, `saveParams`, `saveLastResponse`, `loadLastResponse`, `loadProjects`, `addProject`, `removeProject`, `loadPreferences`, `savePreferences`, `getGitInfo` |
+| **Convenience** | `loadSpec`, `send` |
+
+Direct core module access is also available: `import { parseSpec } from 'apigrip/core/spec-parser.js'`
+
+## MCP server
+
+Expose the spec to AI coding assistants via the Model Context Protocol:
+
+```json
+{
+  "mcpServers": {
+    "api": {
+      "command": "apigrip",
+      "args": ["mcp", "--project", "/path/to/api"]
+    }
+  }
+}
+```
+
+**Tools:** `list_endpoints`, `get_endpoint`, `get_schema`, `validate_request_body`, `send_request`, `get_last_response`, `list_environments`, `get_environment`, `get_project_path`, `get_spec_path`
+
+**Resources:** `spec://parsed`, `project://info`
+
+## Project structure
+
+```
+apigrip/
+├── cli/              CLI entry point and commands
+│   ├── index.js      Yargs command registration
+│   ├── output.js     CLI formatting (table, JSON, color)
+│   ├── resolve-project.js  Shared project context resolution
+│   └── commands/     serve, send, curl, list, projects, env, last, mcp
+├── core/             Shared logic (spec parsing, curl, environments, persistence)
+│   ├── spec-discovery.js    Find OpenAPI spec in a directory
+│   ├── spec-parser.js       Parse/dereference specs (2.0, 3.0, 3.1)
+│   ├── curl-builder.js      Build curl args array
+│   ├── curl-executor.js     Execute curl subprocess
+│   ├── env-resolver.js      Load/merge environments, resolve {{ variables }}
+│   ├── git-info.js          Git status via CLI
+│   ├── params-store.js      Per-endpoint parameter persistence
+│   ├── response-store.js    Per-endpoint response caching
+│   ├── projects-store.js    Project bookmark CRUD
+│   ├── preferences-store.js Global + per-project preferences
+│   └── schema-validator.js  JSON Schema validation (ajv)
+├── lib/              Programmatic library API
+│   ├── index.js      ESM entrypoint (re-exports + loadSpec, send)
+│   └── index.cjs     CJS compatibility wrapper
+├── mcp/              MCP server wiring
+│   └── server.js     Tools + resources -> core modules
+├── server/           Express server, routes, SSE, file watcher
+│   ├── index.js      Server factory, route mounting
+│   ├── spec-watcher.js  Chokidar watchers (spec, $ref deps, .git/)
+│   └── routes/       REST endpoint handlers
+├── client/           React frontend (Vite build)
+│   ├── components/   TopBar, EndpointList, RequestPanel, ResponsePanel, ...
+│   ├── lib/          api.js (HTTP client), sse.js (SSE client)
+│   └── styles/       CSS variables (Dracula palette), layout, components
+└── test/             Node.js built-in test runner
+    ├── core/         Unit tests for all core modules
+    ├── cli/          CLI command tests
+    ├── server/       Route + SSE integration tests
+    ├── mcp/          MCP server tests
+    └── fixtures/     Test specs (apigrip-openapi.yaml, petstore-2.0.json)
+```
+
+Config is stored at `$XDG_CONFIG_HOME/apigrip/` (or `~/.config/apigrip/`). Project directories are never written to.
+
+## Testing
+
+```bash
+npm test
+```
+
+Runs 282 tests across 17 test files using Node's built-in test runner (`node --test`). The test suite uses the tool's own OpenAPI spec as a fixture (self-referential testing).
+
+## License
+
+ISC

package/cli/commands/curl.js

@@ -0,0 +1,11 @@
+// cli/commands/curl.js — Generate curl command for an API endpoint
+
+/**
+ * Curl command handler. Delegates to send with --curl flag.
+ * @param {object} argv - Parsed CLI arguments
+ */
+export async function curlCommand(argv) {
+  argv.curl = true;
+  const { sendCommand } = await import('./send.js');
+  return sendCommand(argv);
+}

package/cli/commands/env.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadEnvironments, saveEnvironments, resolveEnvironment } from '../../core/env-resolver.js';
+import { resolveProjectContext } from '../resolve-project.js';
+
+export async function envCommand(argv) {
+  const { projectDir } = await resolveProjectContext(argv);
+  const action = argv.action;
+
+  if (!action) {
+    // List environments
+    const data = loadEnvironments(projectDir);
+    const names = Object.keys(data.environments);
+    if (names.length === 0 && Object.keys(data.base).length === 0) {
+      console.log('No environments configured.');
+      return;
+    }
+    console.log(`Active: ${data.active || '(none)'}`);
+    console.log(`Base: ${JSON.stringify(data.base)}`);
+    for (const name of names) {
+      const marker = name === data.active ? ' *' : '';
+      console.log(`${name}${marker}: ${JSON.stringify(data.environments[name])}`);
+    }
+    return;
+  }
+
+  if (action === 'show') {
+    const name = argv.name;
+    const data = loadEnvironments(projectDir);
+    if (!name) {
+      // Show resolved environment
+      const resolved = resolveEnvironment(data);
+      console.log(JSON.stringify(resolved, null, 2));
+      return;
+    }
+    const env = data.environments[name];
+    if (!env) {
+      console.error(`Environment not found: ${name}`);
+      process.exit(1);
+    }
+    console.log(JSON.stringify(env, null, 2));
+    return;
+  }
+
+  if (action === 'set') {
+    const { name, key, value } = argv;
+    if (!name || !key || value === undefined) {
+      console.error('Usage: apigrip env set <name> <key> <value>');
+      process.exit(1);
+    }
+    const data = loadEnvironments(projectDir);
+    if (name === 'base') {
+      data.base[key] = value;
+    } else {
+      if (!data.environments[name]) {
+        data.environments[name] = {};
+      }
+      data.environments[name][key] = value;
+    }
+    saveEnvironments(projectDir, data);
+    console.log(`Set ${name}.${key} = ${value}`);
+    return;
+  }
+
+  if (action === 'import') {
+    const file = argv.name; // first positional after action
+    if (!file) {
+      console.error('Usage: apigrip env import <file> [--name <env>] [--merge]');
+      process.exit(1);
+    }
+
+    const filePath = path.resolve(file);
+    if (!fs.existsSync(filePath)) {
+      console.error(`File not found: ${filePath}`);
+      process.exit(1);
+    }
+
+    let json;
+    try {
+      json = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    } catch (err) {
+      console.error(`Invalid JSON: ${err.message}`);
+      process.exit(1);
+    }
+
+    if (typeof json !== 'object' || json === null || Array.isArray(json)) {
+      console.error('JSON must be an object');
+      process.exit(1);
+    }
+
+    const data = loadEnvironments(projectDir);
+    const targetName = argv.importName;
+    const merge = argv.merge || false;
+
+    if (targetName) {
+      // Import as a named environment (or base)
+      if (targetName === 'base') {
+        data.base = merge ? { ...data.base, ...json } : json;
+        saveEnvironments(projectDir, data);
+        console.log(`Imported ${Object.keys(json).length} variable(s) into base`);
+      } else {
+        const existing = data.environments[targetName] || {};
+        data.environments[targetName] = merge ? { ...existing, ...json } : json;
+        saveEnvironments(projectDir, data);
+        console.log(`Imported ${Object.keys(json).length} variable(s) into ${targetName}`);
+      }
+    } else {
+      // Auto-detect: full config vs flat key-value
+      const isFullConfig = json.base !== undefined || json.environments !== undefined;
+      if (isFullConfig) {
+        if (merge) {
+          if (json.base) data.base = { ...data.base, ...json.base };
+          if (json.environments) {
+            for (const [name, vars] of Object.entries(json.environments)) {
+              data.environments[name] = { ...(data.environments[name] || {}), ...vars };
+            }
+          }
+          if (json.active !== undefined) data.active = json.active;
+        } else {
+          if (json.base) data.base = json.base;
+          if (json.environments) data.environments = json.environments;
+          if (json.active !== undefined) data.active = json.active;
+        }
+        saveEnvironments(projectDir, data);
+        const envCount = json.environments ? Object.keys(json.environments).length : 0;
+        console.log(`Imported full config (${envCount} environment(s))`);
+      } else {
+        // Flat key-value: import into base
+        data.base = merge ? { ...data.base, ...json } : json;
+        saveEnvironments(projectDir, data);
+        console.log(`Imported ${Object.keys(json).length} variable(s) into base`);
+      }
+    }
+    return;
+  }
+
+  if (action === 'delete') {
+    const { name, key } = argv;
+    if (!name) {
+      console.error('Usage: apigrip env delete <name> [key]');
+      process.exit(1);
+    }
+    const data = loadEnvironments(projectDir);
+    if (!key) {
+      // Delete entire environment
+      if (name === 'base') {
+        console.error('Cannot delete base environment');
+        process.exit(1);
+      }
+      if (!data.environments[name]) {
+        console.error(`Environment not found: ${name}`);
+        process.exit(1);
+      }
+      delete data.environments[name];
+      if (data.active === name) {
+        data.active = null;
+      }
+      saveEnvironments(projectDir, data);
+      console.log(`Deleted environment: ${name}`);
+    } else {
+      // Delete a key
+      if (name === 'base') {
+        delete data.base[key];
+      } else if (data.environments[name]) {
+        delete data.environments[name][key];
+      } else {
+        console.error(`Environment not found: ${name}`);
+        process.exit(1);
+      }
+      saveEnvironments(projectDir, data);
+      console.log(`Deleted ${name}.${key}`);
+    }
+  }
+}

package/cli/commands/last.js

@@ -0,0 +1,63 @@
+// cli/commands/last.js — Show the last cached response for an endpoint
+
+import { loadLastResponse, loadAllResponses } from '../../core/response-store.js';
+import { formatResponse } from '../output.js';
+import { resolveProjectContext } from '../resolve-project.js';
+
+/**
+ * Last command handler.
+ * @param {object} argv - Parsed CLI arguments
+ */
+export async function lastCommand(argv) {
+  const { projectDir } = await resolveProjectContext(argv);
+
+  // No method/path: list all cached endpoints
+  if (!argv.method) {
+    const all = loadAllResponses(projectDir);
+    const keys = Object.keys(all);
+    if (keys.length === 0) {
+      console.log('No cached responses.');
+      return;
+    }
+    for (const key of keys) {
+      const r = all[key];
+      const age = r.saved_at ? timeSince(r.saved_at) : 'unknown';
+      console.log(`${key}  ${r.status}  ${age}`);
+    }
+    return;
+  }
+
+  const method = argv.method.toUpperCase();
+  const pathArg = argv.path;
+  if (!pathArg) {
+    console.error('Usage: apigrip last <method> <path>');
+    process.exit(1);
+  }
+  const apiPath = pathArg.startsWith('/') ? pathArg : '/' + pathArg;
+
+  const cached = loadLastResponse(projectDir, method, apiPath);
+  if (!cached) {
+    console.error(`No cached response for ${method} ${apiPath}`);
+    process.exit(1);
+  }
+
+  if (argv.json) {
+    console.log(JSON.stringify(cached, null, 2));
+    return;
+  }
+
+  // Reuse the same formatter as send
+  console.log(formatResponse(cached, { verbose: argv.verbose, headers: argv.headers }));
+}
+
+function timeSince(isoString) {
+  const diff = Date.now() - new Date(isoString).getTime();
+  const seconds = Math.floor(diff / 1000);
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}

package/cli/commands/list.js

@@ -0,0 +1,35 @@
+// cli/commands/list.js — List endpoints from an OpenAPI spec
+
+import { parseSpec, extractEndpoints } from '../../core/spec-parser.js';
+import { formatEndpointList } from '../output.js';
+import { resolveProjectContext } from '../resolve-project.js';
+
+/**
+ * List command handler.
+ * @param {object} argv - Parsed CLI arguments
+ */
+export async function listCommand(argv) {
+  const { specPath } = await resolveProjectContext(argv);
+  if (!specPath) {
+    console.error('No spec file found');
+    process.exit(2);
+  }
+  try {
+    const spec = await parseSpec(specPath);
+    let endpoints = extractEndpoints(spec);
+    if (argv.tag) {
+      endpoints = endpoints.filter(e => e.tags.includes(argv.tag));
+    }
+    if (argv.search) {
+      const search = argv.search.toLowerCase();
+      endpoints = endpoints.filter(e =>
+        e.path.toLowerCase().includes(search) ||
+        (e.summary || '').toLowerCase().includes(search)
+      );
+    }
+    console.log(formatEndpointList(endpoints, { json: argv.json }));
+  } catch (err) {
+    console.error(`Spec parse error: ${err.message}`);
+    process.exit(2);
+  }
+}

package/cli/commands/mcp.js

@@ -0,0 +1,25 @@
+import { parseSpec } from '../../core/spec-parser.js';
+import { createMcpServer } from '../../mcp/server.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { resolveProjectContext } from '../resolve-project.js';
+
+export async function mcpCommand(argv) {
+  const { projectDir, specPath } = await resolveProjectContext(argv);
+
+  if (!specPath) {
+    console.error('No spec file found');
+    process.exit(2);
+  }
+
+  let spec;
+  try {
+    spec = await parseSpec(specPath);
+  } catch (err) {
+    console.error(`Spec parse error: ${err.message}`);
+    process.exit(2);
+  }
+
+  const server = await createMcpServer({ projectDir, specPath, spec });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/cli/commands/projects.js

@@ -0,0 +1,50 @@
+import { loadProjects, addProject, removeProject } from '../../core/projects-store.js';
+import path from 'node:path';
+
+export async function projectsCommand(argv) {
+  const action = argv.action;
+
+  if (!action) {
+    // List projects
+    const projects = loadProjects();
+    if (projects.length === 0) {
+      console.log('No bookmarked projects.');
+      return;
+    }
+    for (const p of projects) {
+      console.log(`${p.name}  ${p.path}${p.spec ? '  (' + p.spec + ')' : ''}`);
+    }
+    return;
+  }
+
+  if (action === 'add') {
+    const dir = argv.dir ? path.resolve(argv.dir) : process.cwd();
+    try {
+      const project = addProject(dir);
+      console.log(`Added: ${project.name} (${project.path})`);
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  if (action === 'remove') {
+    if (!argv.dir) {
+      console.error('Usage: apigrip projects remove <name-or-path>');
+      process.exit(1);
+    }
+    try {
+      const removed = removeProject(argv.dir);
+      if (removed) {
+        console.log(`Removed: ${argv.dir}`);
+      } else {
+        console.error(`Not found: ${argv.dir}`);
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  }
+}