@yiaany/ghostapi 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to GhostAPI will be documented in this file.
 
 The format follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses semantic versioning once public releases begin.
 
+## 0.1.7 - 2026-07-18
+
+### Changed
+
+- Set npm package `homepage` link to the landing repository `yiaany/ghostweb` so npm cards point to the public site instead of repository code.
+
+## 0.1.6 - 2026-07-18
+
+### Fixed
+
+- Updated npm package repository, bugs, and homepage URLs to point to `yiaany/ghostapi` instead of broken legacy links.
+- Replaced custom CI badge with live GitHub Actions workflow status badge (`yiaany/ghostapi/actions/workflows/ci.yml/badge.svg`).
+
 ## 0.1.5 - 2026-07-18
 
 ### Fixed

package/README.md

@@ -1,33 +1,92 @@
-# GhostAPI
-
-**The local internet for AI coding agents.**
-
-GhostAPI runs a local API sandbox on `http://127.0.0.1:8080` so coding agents can build and test Stripe, OpenAI, Twilio, Resend, GitHub, Discord, and REST integrations without touching production.
+<p align="center">
+  <img src="docs/assets/ghostapi-avatar.png" alt="GhostAPI" width="104" height="104">
+</p>
+
+<h1 align="center">GhostAPI</h1>
+
+<p align="center">
+  <strong>The local internet for AI coding agents.</strong>
+</p>
+
+<p align="center">
+  A local API sandbox, dashboard, and MCP control plane for building third-party integrations without touching production.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@yiaany/ghostapi"><img alt="npm" src="https://img.shields.io/npm/v/@yiaany/ghostapi?color=0f172a&label=npm"></a>
+  <a href="https://github.com/yiaany/ghostapi/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-0f172a"></a>
+  <a href="https://github.com/yiaany/ghostapi/actions/workflows/ci.yml"><img alt="ci" src="https://github.com/yiaany/ghostapi/actions/workflows/ci.yml/badge.svg"></a>
+  <img alt="node" src="https://img.shields.io/badge/node-%3E%3D20-0f172a">
+  <img alt="mcp" src="https://img.shields.io/badge/MCP-enabled-0f172a">
+</p>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> ·
+  <a href="#mcp-setup">MCP Setup</a> ·
+  <a href="#how-it-works">How It Works</a> ·
+  <a href="#sdk-recipes">SDK Recipes</a> ·
+  <a href="#contributing">Contributing</a>
+</p>
 
 ```bash
 npx @yiaany/ghostapi start --open
 ```
 
-```text
-Your app or agent -> http://127.0.0.1:8080 -> GhostAPI -> dashboard, local state, scenarios, MCP tools
-```
+<p align="center">
+  <img src="docs/assets/dashboard.png" alt="GhostAPI dashboard showing local API traffic">
+</p>
+
+## The Problem
+
+AI coding agents are now strong enough to write Stripe checkouts, OpenAI workflows, GitHub automations, Twilio messaging, and email integrations. The dangerous part is that they also run the code they write.
+
+That creates a bad default loop:
+
+| Agent action | Production risk |
+| --- | --- |
+| Tests a Stripe flow | Real money movement or broken payment state. |
+| Tests Twilio or Resend | Real SMS or email sent to real people. |
+| Tests GitHub automation | Real issues, branches, releases, or repo mutations. |
+| Tests OpenAI calls | Real token spend and possible prompt/data leakage. |
+| Logs request/response payloads | Secrets leak into terminals, prompts, screenshots, or cache. |
+
+GhostAPI gives agents a local universe where integrations behave like real providers, but every request stays on your machine.
+
+## What GhostAPI Does
 
-## Install
+GhostAPI is a local API control layer for agent-driven development.
 
-Run without installing:
+<table>
+  <tr>
+    <td><strong>Local API Sandbox</strong><br>Run provider-shaped APIs on <code>127.0.0.1:8080</code> instead of live Stripe, OpenAI, Twilio, Resend, GitHub, Discord, or random REST services.</td>
+    <td><strong>Live Dashboard</strong><br>Watch every request, inspect request and response bodies, replay scenarios, generate setup snippets, and verify what your agent actually did.</td>
+  </tr>
+  <tr>
+    <td><strong>MCP Control Plane</strong><br>Let agents inspect state, read traffic logs, force deterministic responses, and toggle Chaos Mode through MCP tools.</td>
+    <td><strong>Safe Failure Testing</strong><br>Force card declines, rate limits, upstream errors, latency, and provider-shaped edge cases without waiting for real APIs to fail.</td>
+  </tr>
+  <tr>
+    <td><strong>Secret Masking</strong><br>Mask secret-looking headers, query params, bodies, cache keys, dashboard payloads, events, and prompt inputs.</td>
+    <td><strong>Repo Setup Generator</strong><br>Generate MCP config, agent instructions, environment snippets, and SDK patches for the current project.</td>
+  </tr>
+</table>
+
+## Quickstart
+
+Run GhostAPI instantly:
 
 ```bash
 npx @yiaany/ghostapi start --open
 ```
 
-Or install globally:
+Install globally:
 
 ```bash
 npm i -g @yiaany/ghostapi
 ghostapi start --open
 ```
 
-Dashboard:
+Open the dashboard:
 
 ```text
 http://127.0.0.1:8080/dashboard
@@ -39,15 +98,15 @@ Health check:
 curl http://127.0.0.1:8080/health
 ```
 
-## 30 Second Win
+## 30 Second Demo
 
-Start GhostAPI:
+Start the local API world:
 
 ```bash
 npx @yiaany/ghostapi start --open
 ```
 
-Send a local API request:
+Send a Stripe-shaped request locally:
 
 ```bash
 curl -X POST http://127.0.0.1:8080/v1/customers \
@@ -56,12 +115,30 @@ curl -X POST http://127.0.0.1:8080/v1/customers \
   -d '{"email":"ada@example.com","name":"Ada Lovelace"}'
 ```
 
-Open the dashboard and inspect the captured request:
+Inspect the captured request in the dashboard:
 
 ```text
 http://127.0.0.1:8080/dashboard
 ```
 
+## One-Command Repo Setup
+
+Run setup inside any project:
+
+```bash
+npx @yiaany/ghostapi setup --write
+```
+
+This generates local setup assets for agent workflows:
+
+| Output | Why it matters |
+| --- | --- |
+| Agent instructions | Tell coding agents to keep provider calls local. |
+| MCP snippets | Configure Cursor, Claude, Cline, Aider, Codex, OpenCode, Gemini CLI, Goose, OpenClaw, Hermes, and generic MCP clients. |
+| Environment snippets | Point SDKs at `http://127.0.0.1:8080`. |
+| SDK patches | Show how to route Stripe and OpenAI SDKs into GhostAPI. |
+| Safety guidance | Warn before live providers or live-looking keys enter the loop. |
+
 ## MCP Setup
 
 Start the MCP server:
@@ -70,7 +147,7 @@ Start the MCP server:
 npx @yiaany/ghostapi mcp
 ```
 
-Universal stdio MCP config:
+Universal MCP config:
 
 ```json
 {
@@ -83,30 +160,50 @@ Universal stdio MCP config:
 }
 ```
 
-Generate repo-specific setup snippets for Cursor, Claude, Cline, Aider, Codex, OpenCode, Gemini CLI, Goose, OpenClaw, Hermes Desktop, and generic MCP clients:
+Agent prompt:
 
-```bash
-npx @yiaany/ghostapi setup --write
+```text
+Use the GhostAPI MCP server.
+
+Keep all third-party API calls local on http://127.0.0.1:8080.
+Do not call real providers.
+
+Use GhostAPI MCP tools to inspect state, read traffic logs, configure deterministic responses, and test failure scenarios.
 ```
 
-## MCP Tools
+MCP tools:
 
 | Tool | Purpose |
 | --- | --- |
 | `inspect_state` | Read local API objects from `.ghostapi/state.json`. |
 | `get_traffic_logs` | Inspect recent local traffic. |
-| `set_api_behavior` | Force a deterministic response for `method + path`. |
-| `toggle_chaos_mode` | Enable local latency and error injection. |
-
-## Stripe Locally
+| `set_api_behavior` | Force deterministic responses for `method + path`. |
+| `toggle_chaos_mode` | Enable local latency and provider-shaped errors. |
 
-Install Stripe:
+## How It Works
 
-```bash
-npm install stripe
+```text
+Your app or agent
+  -> http://127.0.0.1:8080
+  -> GhostAPI proxy
+  -> provider detection
+  -> local state / scenarios / deterministic behavior
+  -> dashboard + MCP inspection
 ```
 
-Point the Stripe SDK at GhostAPI:
+GhostAPI does five things in the loop:
+
+| Step | What happens |
+| --- | --- |
+| Detect | It infers the provider from routes, headers, SDK shapes, and request bodies. |
+| Normalize | It converts requests into safe, inspectable local events. |
+| Mask | It strips secret-looking values before logs, cache, dashboard, and prompts. |
+| Respond | It returns provider-shaped mock responses, errors, or saved state. |
+| Control | MCP and dashboard tools let agents force behavior and replay flows. |
+
+## SDK Recipes
+
+Stripe:
 
 ```ts
 import Stripe from "stripe";
@@ -118,21 +215,7 @@ export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? "stripe_test_g
 });
 ```
 
-Now Stripe-shaped calls go to GhostAPI instead of real Stripe:
-
-```text
-POST http://127.0.0.1:8080/v1/payment_intents
-```
-
-## OpenAI Locally
-
-Install OpenAI:
-
-```bash
-npm install openai
-```
-
-Point the OpenAI SDK at GhostAPI:
+OpenAI:
 
 ```ts
 import OpenAI from "openai";
@@ -143,18 +226,43 @@ export const openai = new OpenAI({
 });
 ```
 
-## Agent Prompt
+Generic REST:
 
-```text
-Use the GhostAPI MCP server.
+```bash
+curl -X POST http://127.0.0.1:8080/tasks \
+  -H "content-type: application/json" \
+  -d '{"title":"Write integration tests","status":"open"}'
+```
 
-Keep all third-party API calls local on http://127.0.0.1:8080.
-Do not call real providers.
+## Built For
 
-Use GhostAPI MCP tools to inspect state, read traffic logs, configure deterministic responses, and test failure scenarios.
-```
+| Audience | Use GhostAPI to |
+| --- | --- |
+| AI coding agents | Build integrations without accidentally touching production. |
+| SaaS developers | Test provider happy paths and failure paths locally. |
+| API-heavy teams | Turn captured traffic into repeatable scenarios and tests. |
+| Open-source maintainers | Give contributors safe examples that do not require live provider accounts. |
+
+## Safety Model
+
+- No real provider calls by default.
+- Keep SDKs pointed at `http://127.0.0.1:8080`.
+- Use fake local keys like `stripe_test_ghostapi` and `sk-ghostapi`.
+- Secrets are masked before logs, cache, dashboard, events, and prompts.
+- Chaos Mode is opt-in.
+- Local state lives under `.ghostapi/` and is gitignored.
+
+## Local Files
+
+| Path | Purpose |
+| --- | --- |
+| `.ghostapi/config.json` | Local GhostAPI config. |
+| `.ghostapi/state.json` | Simulated API object state. |
+| `.ghostapi/events.jsonl` | Captured local request events. |
+| `.ghostapi/behaviors.json` | Deterministic behavior overrides. |
+| `.ghostapi/cache/` | Local response cache. |
 
-## Common Commands
+## CLI Reference
 
 ```bash
 npx @yiaany/ghostapi start --open
@@ -168,23 +276,42 @@ npx @yiaany/ghostapi providers list
 npx @yiaany/ghostapi providers inspect stripe
 ```
 
-## Why
+## Repository About
 
-AI agents are great at writing integration code. They also run that code. GhostAPI gives them a safe local world where failures are realistic, traffic is visible, scenarios are replayable, and production keys never need to be used.
+Use this for the GitHub repository description:
 
-## Safety
+```text
+The local internet for AI coding agents. Simulate Stripe, OpenAI, Twilio, Resend, GitHub, Discord, and REST APIs locally with a dashboard, MCP tools, scenarios, and secret masking.
+```
 
-- No real provider calls by default.
-- Keep SDKs pointed at `http://127.0.0.1:8080`.
-- Use fake local keys like `stripe_test_ghostapi` and `sk-ghostapi`.
-- Secrets are masked before logs, cache, dashboard, events, and prompts.
-- Chaos Mode is opt-in.
+Recommended topics:
+
+```text
+mcp, ai-agents, stripe, openai, mock-server, api-testing, sandbox, proxy, local-development, typescript, cursor
+```
 
 ## Docs
 
-- GitHub: https://github.com/ghostapi/ghostapi
-- Issues: https://github.com/ghostapi/ghostapi/issues
+- [MCP setup](docs/mcp.md)
+- [Usage guide](docs/usage.md)
+- [Release checklist](docs/release-checklist.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+
+## Contributing
+
+Contributions are welcome. GhostAPI should stay local-first, safe by default, and useful for real agent workflows.
+
+Before opening a pull request:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+```
+
+Do not add tests or examples that call live providers by default. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
 
 ## License
 
-MIT
+MIT. See [LICENSE](LICENSE).

package/docs/mcp.md

@@ -0,0 +1,50 @@
+# GhostAPI MCP Setup
+
+GhostAPI ships with a local stdio MCP server so coding agents can inspect and control the local API world.
+
+## Start MCP
+
+```bash
+npx @yiaany/ghostapi mcp
+```
+
+## Universal Config
+
+```json
+{
+  "mcpServers": {
+    "ghostapi": {
+      "command": "npx",
+      "args": ["-y", "@yiaany/ghostapi", "mcp"]
+    }
+  }
+}
+```
+
+## Generate Client Snippets
+
+```bash
+npx @yiaany/ghostapi setup --write
+```
+
+This writes copy-ready local snippets under `.ghostapi/agent-configs/` and project instructions for supported agent clients.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `inspect_state` | Read local API objects from `.ghostapi/state.json`. |
+| `get_traffic_logs` | Inspect recent captured API traffic. |
+| `set_api_behavior` | Force a deterministic local response for `method + path`. |
+| `toggle_chaos_mode` | Enable or disable local latency and error injection. |
+
+## Agent Prompt
+
+```text
+Use the GhostAPI MCP server.
+
+Keep all third-party API calls local on http://127.0.0.1:8080.
+Do not call real providers.
+
+Use GhostAPI MCP tools to inspect state, read traffic logs, configure deterministic responses, and test failure scenarios.
+```

package/docs/usage.md

@@ -0,0 +1,57 @@
+# GhostAPI Usage Guide
+
+## Start The Local API
+
+```bash
+npx @yiaany/ghostapi start --open
+```
+
+GhostAPI listens on:
+
+```text
+http://127.0.0.1:8080
+```
+
+Dashboard:
+
+```text
+http://127.0.0.1:8080/dashboard
+```
+
+## Send A Local Request
+
+```bash
+curl -X POST http://127.0.0.1:8080/v1/customers \
+  -H "content-type: application/json" \
+  -H "authorization: Bearer stripe_test_ghostapi" \
+  -d '{"email":"ada@example.com","name":"Ada Lovelace"}'
+```
+
+## Stripe SDK
+
+```ts
+import Stripe from "stripe";
+
+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY ?? "stripe_test_ghostapi", {
+  host: process.env.GHOSTAPI_HOST ?? "127.0.0.1",
+  port: Number(process.env.GHOSTAPI_PORT ?? "8080"),
+  protocol: process.env.GHOSTAPI_PROTOCOL ?? "http"
+});
+```
+
+## OpenAI SDK
+
+```ts
+import OpenAI from "openai";
+
+export const openai = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY ?? "sk-ghostapi",
+  baseURL: process.env.GHOSTAPI_OPENAI_BASE_URL ?? "http://127.0.0.1:8080/v1"
+});
+```
+
+## Failure Scenarios
+
+Use MCP or the dashboard to force deterministic responses such as Stripe card declines, rate limits, upstream errors, and latency.
+
+The goal is to make failure handling repeatable instead of relying on live provider behavior.

package/examples/stripe-node/README.md

@@ -15,7 +15,7 @@ Create a customer:
 ```bash
 curl -X POST http://localhost:8080/v1/customers \
   -H "content-type: application/json" \
-  -H "authorization: Bearer sk_test_local_only" \
+  -H "authorization: Bearer stripe_test_local_only" \
   -d '{"email":"ada@example.com","name":"Ada Lovelace","metadata":{"source":"ghostapi-example"}}'
 ```
 
@@ -23,7 +23,7 @@ Copy the returned `id`, then fetch it:
 
 ```bash
 curl http://localhost:8080/v1/customers/cus_mock_example \
-  -H "authorization: Bearer sk_test_local_only"
+  -H "authorization: Bearer stripe_test_local_only"
 ```
 
 GhostAPI detects Stripe from the `/v1/customers` path and keeps the created object in `.ghostapi/state.json`.

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@yiaany/ghostapi",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "The local internet for AI coding agents.",
   "type": "module",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ghostapi/ghostapi.git"
+    "url": "git+https://github.com/yiaany/ghostapi.git"
   },
   "bugs": {
-    "url": "https://github.com/ghostapi/ghostapi/issues"
+    "url": "https://github.com/yiaany/ghostapi/issues"
   },
-  "homepage": "https://github.com/ghostapi/ghostapi#readme",
+  "homepage": "https://github.com/yiaany/ghostweb#readme",
   "bin": {
     "ghostapi": "dist/cli/index.js"
   },