@yiaany/ghostapi 0.1.7 → 0.1.8

package/docs/design-partners/discovery-questions.md

@@ -0,0 +1,28 @@
+# Discovery Questions
+
+Ask for concrete recent behavior before presenting GhostAPI. Do not ask all questions mechanically; follow the evidence.
+
+1. Tell me about the last integration change written or materially changed by a coding agent.
+2. Which external provider made that change risky: money, messages, source control, AI spend, webhooks, or something else?
+3. What happened when the team tested it?
+4. Has a test, script, or agent ever hit the wrong environment? What was the impact?
+5. How do you currently prevent production credentials from reaching agents or CI jobs?
+6. How would a reviewer know that a pull request never contacted production?
+7. Which failure modes have caused the most rework: retries, idempotency, rate limits, timeouts, malformed responses, or webhooks?
+8. Describe the last duplicate side effect, such as a payment, message, ticket, or deployment. Where did detection fail?
+9. How do you validate webhook signatures today? Is that test mandatory before merge?
+10. What must happen in CI before an agent-authored integration change can merge?
+11. Which repositories and runners could support a Linux CI experiment?
+12. Which provider integration would make a pilot meaningful within two weeks?
+13. What would be unsafe to store in a testing tool or evidence artifact?
+14. What information would security require before allowing a developer tool to observe test execution?
+15. Who owns the budget if this removes a recurring risk or release delay?
+16. What would make this a must-have rather than a nice-to-have?
+17. What existing tool or workaround would GhostAPI need to displace or complement?
+18. What proof would make you trust a claim that production egress was blocked?
+19. If the pilot catches nothing, what result would still show operational value?
+20. If the pilot catches a real defect or blocks egress, what procurement or budget step could follow?
+
+## Capture Rules
+
+Record direct quotes only with consent. Otherwise capture a sanitized summary, the workflow, severity, current workaround, decision owner, and next evidence-producing step. Never copy credentials, source code, raw traffic, customer data, or incident details into this repository.

package/docs/design-partners/feedback-capture-template.md

@@ -0,0 +1,48 @@
+# Feedback Capture Template
+
+Use this in a private founder system or a sanitized issue. Do not paste source code, traffic, credentials, tokens, personal data, or customer names unless independently authorized and stored in an approved system.
+
+```markdown
+## Validation Record
+
+- Date: YYYY-MM-DD
+- Record type: discovery | onboarding | CI run | bug caught | egress prevented | pricing | closeout
+- Company segment and engineering size:
+- Participant role:
+- Workflow / integration:
+- Coding-agent usage:
+
+### Observed Facts
+
+- What actually ran or occurred:
+- Evidence location / sanitized reference:
+- Frequency / severity:
+
+### User Interpretation
+
+- Why it matters to them:
+- Current workaround and cost:
+- Exact quote (only if consented):
+
+### Product Hypothesis Tested
+
+- Hypothesis:
+- Supported / rejected / inconclusive:
+- Why:
+
+### Commercial Signal
+
+- Buyer / decision process:
+- Budget or willingness-to-pay signal:
+- Paid pilot / LOI status:
+
+### Next Step
+
+- Owner:
+- Due date:
+- Smallest evidence-producing action:
+```
+
+## Evidence Quality
+
+Prefer a dated CI artifact, issue/PR reference, or buyer confirmation over a feature request. Mark a signal `inconclusive` when it is based on a hypothetical answer, a demo reaction, or an unverified claim.

package/docs/design-partners/icp-one-pager.md

@@ -0,0 +1,43 @@
+# ICP One-Pager
+
+## Primary ICP
+
+SaaS companies with 10-200 engineers that actively use AI coding agents and operate sensitive Stripe, OpenAI, GitHub, Twilio, Resend, webhook, or generic external integrations.
+
+## Buyer And User
+
+| Role | Job | Pain To Validate |
+| --- | --- | --- |
+| Head of Platform / Developer Productivity | Make agent-assisted development safe and repeatable | Cannot prove AI-written integration tests stayed away from production. |
+| AppSec / AI governance lead | Reduce credential and external-action exposure | Agent workflows create new egress and secret-leak paths without enforceable evidence. |
+| Engineering manager / CTO | Ship integrations without operational surprises | Retry, webhook, and idempotency bugs reach review or production too late. |
+| AI engineer / SDET / senior developer | Test the code the agent produced | Mocks are incomplete, manual setup is slow, and failures are hard to reproduce in CI. |
+
+## Trigger
+
+- The team has had an agent, test, script, or integration contact a real provider unexpectedly.
+- A payment, webhook, retry, or timeout defect escaped review.
+- The team is writing AI-agent governance or CI policy and cannot produce a credible evidence artifact.
+- A platform team is standardizing coding-agent workflows across repositories.
+
+## Job To Be Done
+
+When an AI coding agent creates or modifies an external integration, help the team run a deterministic local/CI verification that blocks unsafe egress and proves the relevant failure path was exercised, so reviewers can merge without handing the agent production credentials or trusting an unverifiable mock.
+
+## Current Alternatives
+
+- SDK base-URL overrides, test-mode keys, and manual reviewer discipline.
+- Generic mocks, contract tests, or API virtualization.
+- CI logs and informal screenshots.
+- Restricting agents from integration work entirely.
+
+## Disqualifiers
+
+- No coding-agent use and no external integrations.
+- The only need is a hosted dashboard or generic API mocking.
+- The buyer expects host-level sandboxing on unsupported Windows/macOS hosts.
+- The team cannot run a small local or Linux CI experiment.
+
+## Qualification Signal
+
+Prioritize a pilot only if the team can name one repository, one sensitive integration, one failure mode, and one merge/release workflow where evidence would change a decision.

package/docs/design-partners/onboarding-checklist.md

@@ -0,0 +1,33 @@
+# Design-Partner Onboarding Checklist
+
+## Before Kickoff
+
+- [ ] Confirm the partner has authorized the named technical contact and repository experiment.
+- [ ] Select one integration, one failure mode, and one merge/release workflow.
+- [ ] Confirm no production credentials, code, raw traffic, customer data, or incident exports will be sent to GhostAPI.
+- [ ] Confirm a supported Linux CI runner is available if enforcement evidence is required.
+- [ ] State the success criterion, decision owner, and pilot end date.
+
+## Setup
+
+- [ ] Run `ghostapi doctor --json` and save only the non-sensitive capability result.
+- [ ] Create or review `ghostapi.policy.yaml`; default external network access remains denied.
+- [ ] Use fake/local credentials and provider-shaped local endpoints.
+- [ ] Choose one deterministic scenario: egress block, duplicate payment, or webhook signature validation.
+- [ ] Run the selected test locally and create one sanitized evidence artifact.
+- [ ] Add the CI job only after the local artifact is understood.
+
+## Weekly Review
+
+- [ ] Count the selected CI runs without uploading CI logs or payloads.
+- [ ] Record whether the agreed scenario ran and whether the evidence changed a review decision.
+- [ ] Capture a sanitized bug/egress outcome, if any.
+- [ ] Ask the buyer whether the current evidence is worth paying for and why.
+- [ ] Record one blocker, owner, and due date; avoid open-ended feature requests.
+
+## Closeout
+
+- [ ] Score the criteria in `pilot-success-criteria.md` from evidence.
+- [ ] Separate observed facts from user opinions and founder hypotheses.
+- [ ] Capture a paid-pilot / LOI / no-decision outcome and date.
+- [ ] Delete any local pilot notes that contain unnecessary sensitive data.

package/docs/design-partners/pilot-success-criteria.md

@@ -0,0 +1,27 @@
+# Pilot Success Criteria
+
+Agree on the rows below before setup. A successful pilot needs more than installation.
+
+| Dimension | Minimum measurable signal | Source of truth |
+| --- | --- | --- |
+| Activation | A team completes `init`, configures one policy/scenario, and produces a valid local or CI evidence artifact. | Sanitized artifact hash and dated owner confirmation. |
+| Regular CI use | At least one selected workflow runs in CI weekly for two consecutive weeks. | CI run links or sanitized run-count export. |
+| Enforcement value | The team can explain a merge/release decision changed by egress enforcement or evidence. | Buyer/developer closeout note. |
+| Defect value | At least one real integration defect is caught before merge, or a documented absence of defects after exercising agreed failure paths. | Sanitized issue/PR reference and reproduction summary. |
+| Willingness to pay | The buyer states a budget range, paid-pilot decision, or LOI decision with a date. | Pricing interview summary. |
+
+## Guardrails
+
+- A synthetic demo alone does not count as a real bug caught.
+- An installed CLI without repeated CI use does not count as retention.
+- A product claim without a dated source record does not satisfy this table.
+- Do not claim prevented production egress unless the supported enforcement evidence proves the relevant run.
+
+## Exit Decisions
+
+| Outcome | Decision |
+| --- | --- |
+| Weekly CI use plus real buyer value | Continue the narrow CI/shared-scenario product path and offer paid pilot terms. |
+| Strong local value but CI blocker | Fix only the blocker proven across partners; do not expand general cloud scope. |
+| No recurring pain or no buyer | Stop/reshape the wedge before building billing or enterprise control-plane features. |
+| Security/platform mismatch | Document the limitation and qualify a different environment; do not overclaim enforcement. |

package/docs/design-partners/pricing-interview-script.md

@@ -0,0 +1,18 @@
+# Pricing Interview Script
+
+Run this after the buyer understands one concrete workflow and outcome. Do not present a price as validated market data.
+
+1. What would it cost if this risk caused one escaped defect, production contact, or delayed release per quarter?
+2. Who feels that cost and who owns the decision to change the workflow?
+3. Which part has value: local simulation, enforced CI evidence, shared scenarios, policy control, or audit history?
+4. Is the value tied more to protected repositories, protected agents, CI runs, provider accounts, or retained evidence?
+5. What tool or internal effort would this replace or reduce?
+6. Would you fund a time-bounded paid pilot if it met the written success criteria? Why or why not?
+7. What procurement, security, or deployment constraints would block payment?
+8. What price range would make this a fast team-level decision, a director-level decision, or an enterprise review?
+9. What proof would you require before renewal or expansion?
+10. If this caught a real defect before merge, what would have to be true for you to sign an LOI or convert to a paid pilot?
+
+## Capture
+
+Record the buyer role, stated value unit, price range if voluntarily offered, decision path, and date. Do not turn a polite reaction into willingness to pay. `No budget`, `needs more proof`, and `would use OSS only` are valid outcomes.

package/docs/design-partners/telemetry-plan.md

@@ -0,0 +1,48 @@
+# Privacy-First Product Telemetry Plan
+
+## Principles
+
+- Collection is off by default and requires `ghostapi telemetry enable` on the local machine.
+- The implementation has no network transport, endpoint, cloud account, automatic upload, or background process.
+- It never records source code, prompts, commands, request/response traffic, URLs, provider names, credentials, tokens, personal data, repository identity, machine identity, or full timestamps beyond local aggregate activity timing.
+- `ghostapi telemetry disable` deletes the local aggregate. Users can inspect it at any time with `status` or `export`.
+
+## Local Implementation
+
+The bounded aggregate is stored at `.ghostapi/product-telemetry.json` (or `GHOSTAPI_DATA_DIR`) with owner-only permissions on POSIX. It contains four integer counters, up to eight ISO week labels, and optional activation/last-activity timestamps. Atomic writes and a local file lock prevent lost updates between cooperating GhostAPI processes. Malformed or unknown-field data fails closed, and a telemetry file observed as a symlink is rejected. This local store is not a security boundary against a same-user attacker able to race filesystem operations.
+
+```bash
+ghostapi telemetry status
+ghostapi telemetry enable
+ghostapi telemetry export --json
+ghostapi telemetry disable
+```
+
+`export` is a local JSON print operation, not an upload feature. If a partner chooses to share a result, they should review and transfer only the exported aggregate through an approved channel.
+
+## Event Schema
+
+| Event | Recorded only after opt-in | Why |
+| --- | --- | --- |
+| `init_completed` | Incrementing count | Measures setup starts, not activation. |
+| `enforced_run_completed` | Incrementing count and first activation time | Measures completion of the supported enforcement workflow. |
+| `evidence_generated` | Incrementing count and first activation time | Measures evidence creation, the earliest useful product outcome. |
+| `eval_completed` | Incrementing count | Measures recurring verification behavior. |
+
+## Metrics
+
+| Metric | Definition | Interpretation |
+| --- | --- | --- |
+| Activation | At least one `enforced_run_completed` or `evidence_generated` event. | A user reached a meaningful safety/evidence result. |
+| Weekly active local project | At least one tracked event in an ISO week. | Directional local engagement only; it does not identify a team. |
+| Four-week retention | At least two active weeks separated by 21+ days. | Requires partner-shared aggregate or another consented evidence source. |
+| CI retention | Repeated selected CI workflow runs weekly. | Must come from a partner's sanitized CI evidence; the local counter does not prove CI. |
+
+## What Is Deliberately Not Measured Yet
+
+- Users, companies, seats, repositories, agents, providers, commands, source files, traffic, errors, exact scenario names, runtime duration, revenue, or raw defect details.
+- Any server-side metric, cross-device identity, attribution, or automatic product analytics.
+
+## Review Trigger
+
+Revisit the plan only when a design partner explicitly asks for aggregate sharing or hosted reporting. Any networked telemetry proposal requires a new opt-in, schema review, data-retention policy, threat model, and explicit customer approval.

package/docs/development/baseline.md

@@ -0,0 +1,114 @@
+# Development Baseline
+
+Baseline captured on 2026-08-05 before product changes.
+
+## Repository
+
+- Working copy: `./repo`
+- Remote: `https://github.com/yiaany/ghostapi.git` (repository identity metadata corrected on 2026-08-22; historical verification outcomes are unchanged)
+- Branch: `main`
+- Commit before baseline documentation: `f02d3e914c50ab6ade952aa38347b4e7ac4a35d8`
+- Package: `@yiaany/ghostapi@0.1.7`
+- License: MIT
+
+## Environment
+
+- Platform: Windows x64
+- Git: `2.54.0.windows.1`
+- Node.js: `26.4.0`
+- npm: `11.17.0`
+- pnpm: `11.12.0` (available but not used)
+- Corepack: unavailable
+- Required package manager: npm, selected from `package-lock.json` and the CI workflow
+- Declared Node.js support: `>=20`
+- CI environment: `ubuntu-latest`, Node.js 20
+
+The local Node.js version satisfies the declared engine range but is newer than the version exercised by CI.
+
+## Project Inventory
+
+- Runtime: TypeScript, Node.js, Express, ESM
+- Tests: Vitest with serial test-file execution
+- Build: TypeScript compiler plus Vite landing-page build and static dashboard copy
+- Providers: Stripe, Twilio, Resend, GitHub, Discord, OpenAI, and generic REST
+- State: local files under `.ghostapi/`
+- Interfaces: CLI, HTTP proxy/dashboard, and MCP stdio server
+- CI: `.github/workflows/ci.yml` runs install, typecheck, tests, and build
+- Release: manual checklist in `docs/release-checklist.md`; no automated publish workflow was found
+
+## Verification Results
+
+| Command | Result | Details |
+| --- | --- | --- |
+| `npm ci` | PASS | Installed 263 packages from the lockfile. npm reported 11 audit findings and two esbuild install scripts pending allow-scripts review. |
+| `npm run typecheck` | PASS | Strict TypeScript check completed without diagnostics. |
+| `npm test` | PASS | 21 test files and 102 tests passed. |
+| `npm run build` | PASS | TypeScript, landing page, and dashboard static assets built successfully. |
+| `node dist/cli/index.js --help` | PASS | Built CLI printed its command reference. |
+| `node dist/cli/index.js providers list` | PASS | Printed seven registered providers. |
+| `node dist/cli/index.js model get` | PASS | Printed `gpt-4o-mini`. |
+| `npm pack --dry-run` | PASS | 188 files, 235.5 kB packed, 659.6 kB unpacked. No ignored local state or dependency directory was included. |
+| Isolated packed-package install | PASS | Installed the generated tarball into a temporary project. The installed CLI, offline `/health`, and `/dashboard` smoke checks passed. |
+| Formatter check | NOT RUN | No formatter script or repository formatter configuration exists. |
+| Lint | NOT RUN | No lint script or repository lint configuration exists. |
+| `npm audit` | FAIL | 11 findings: 7 moderate, 3 high, and 1 critical. |
+| `npm audit --omit=dev` | FAIL | 5 runtime findings: 3 moderate and 2 high. |
+
+The dependency tree was not updated during this baseline session. Audit remediation needs a controlled dependency session because one suggested full remediation upgrades Vite across a breaking major version.
+
+## Findings
+
+### P0
+
+No confirmed secret disclosure, remote code execution, destructive production behavior, or live provider access by default was found during this baseline.
+
+### P1
+
+- Ambient `OPENAI_API_KEY` activates external LLM calls without a GhostAPI-specific opt-in. A local probe confirmed that `loadServerConfig` accepts the ambient key, and the configured path sends requests to the OpenAI API.
+- Non-loopback bind is accepted without authentication. A local remote-bind probe confirmed an unauthenticated dashboard API mutation returned HTTP 200, and `/events` accepted a hostile browser origin with HTTP 200.
+- Multiple tests recursively delete `.ghostapi/` relative to the repository working directory. Running the suite in a project with real GhostAPI state can erase user data.
+- Persisted state and behavior updates use process-local locks and non-atomic whole-file writes. Multiple GhostAPI processes or a crash during a write can lose updates or leave corrupted JSON.
+- Cache canonicalization sorts array elements. Requests whose array order is semantically meaningful can collide and receive an incorrect cached response.
+
+### P2
+
+- The root dependency tree has unresolved runtime and development advisories, including path traversal, host-confusion, SSRF-boundary bypass, ReDoS, and development-server findings. Exploitability in GhostAPI has not yet been established.
+- `.ghostapi/events.jsonl` grows without a size or retention bound, and disk-write failures are silently ignored.
+- CI tests only Linux on Node.js 20. The baseline was executed on Windows with Node.js 26.4.0, leaving other supported versions and operating systems uncovered.
+- Formatting and linting are not automated.
+- Generated tests hardcode `http://127.0.0.1:8080`, reducing portability in CI and parallel test environments.
+- Package correctness depends on a prior build because no `prepack` verification prevents stale or missing `dist/` contents.
+
+### P3
+
+- `.env.example` describes `OPENAI_API_KEY` as future support even though the runtime currently consumes it.
+- Release verification is documented but remains manual.
+
+## Security Review Scope
+
+The baseline inspected external network call sites, secret masking, request normalization, dashboard and SSE boundaries, local persistence, cache identity, tests that delete files, package contents, dependency advisories, and the release workflow.
+
+The source tree contains one active external fetch target: the OpenAI chat-completions endpoint. Provider-shaped URLs in deterministic response bodies are data and are not outbound requests.
+
+Deep fixes for authentication, LLM opt-in, data-directory isolation, retention, atomic persistence, cross-process locking, and dependency updates are intentionally deferred so the baseline remains a minimal documentation-only change.
+
+## Reproduction
+
+From `./repo`:
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run build
+node dist/cli/index.js --help
+node dist/cli/index.js providers list
+node dist/cli/index.js model get
+npm pack --dry-run
+npm audit
+npm audit --omit=dev
+```
+
+## Recommended Next Step
+
+Run `sessions/02-security-and-reliability-baseline.md`. Prioritize explicit external-LLM opt-in, authentication for non-loopback control surfaces, isolated test data, bounded event persistence, atomic cross-process-safe state writes, and ordered cache-array semantics before expanding product surface area.

package/docs/development/onboarding-smoke.md

@@ -0,0 +1,37 @@
+# Onboarding Smoke Measurement
+
+- Date: 2026-08-09
+- Host: Windows, Node.js measured from the local runtime
+- Package under test: source build plus tarball smoke for `@yiaany/ghostapi@0.1.7`
+- Live provider credentials: not used
+
+## Measured First Useful Result
+
+Measured command sequence:
+
+```bash
+npx @yiaany/ghostapi init
+npx @yiaany/ghostapi doctor
+npx @yiaany/ghostapi start --port <ephemeral>
+curl-like POST /v1/customers with authorization: Bearer stripe_test_ghostapi
+node examples/openai-streaming/streaming-tool-call.mjs
+```
+
+Result on this host: `3.03` seconds from initialization start to successful local Stripe-shaped request plus OpenAI-shaped streaming completion.
+
+This is a Windows local-provider-simulation measurement, not a Linux egress-enforcement measurement. `ghostapi run -- npm test` remains unsupported on Windows and macOS.
+
+## Linux Enforcement Verification
+
+- Date: 2026-08-09
+- Host: Ubuntu WSL 2, Node.js `20.20.2`, working copy on the Linux filesystem rather than `/mnt/c`.
+- Command: `ghostapi run -- npm test`.
+- Result: `48.75` seconds; 42 test files passed, 232 tests passed, and 1 optional test skipped.
+- Evidence: the exact run produced a PASS evidence report with a completed `linux-network-namespace` boundary, zero allowed or production egress attempts, no secret categories, and no warnings.
+
+This is an enforced full-suite verification, not a time-to-first-value benchmark: it intentionally runs the entire test suite. The pinned GitHub workflow must still run on the exact release commit before publication.
+
+## Automated Coverage
+
+- `npm run smoke:package` builds a real npm tarball, installs it into a temporary project whose path contains spaces, runs `init`, `doctor --json`, and `providers inspect stripe`, and rejects prompt-pack/session/hosted artifacts plus live-secret-shaped package contents.
+- Targeted tests cover CLI parsing, generated setup instructions, and machine-readable doctor output.

package/docs/development/verification-0.1.8.md

@@ -0,0 +1,25 @@
+# 0.1.8 Verification Record
+
+- Date: 2026-08-22
+- Package: `@yiaany/ghostapi@0.1.8`
+- Scope: final local release verification, package/release evidence, hosted checks, Docker build, and native Linux enforcement
+- Historical records: the 2026-08-05 baseline and 2026-08-09 onboarding smoke remain records of `0.1.7` and were not re-dated or relabeled
+
+## Verification
+
+This record is intentionally separate from the historical baseline and onboarding measurements. All results below passed against the final 0.1.8 working tree on 2026-08-22. GitHub Actions still must be observed on the exact final commit after that commit is pushed; local and WSL2 results do not substitute for that post-push check.
+
+| Check | Result | Evidence |
+| --- | --- | --- |
+| Root lint | PASS | `npm run lint`; configured Prettier check passed |
+| Root typecheck | PASS | `npm run typecheck`; completed without diagnostics |
+| Root tests | PASS | `npm test`; 55 files and 341 tests passed with zero skipped |
+| Root build | PASS | `npm run build`; TypeScript and static dashboard builds completed |
+| Package smoke | PASS | `npm run smoke:package`; packed artifact installed and its CLI, package export, generated project, doctor, and provider checks passed |
+| Root dependency audits | PASS | Full `npm audit` and production-only `npm audit --omit=dev` both reported zero vulnerabilities |
+| Hosted clean install and check | PASS | Fresh `npm ci`, then `npm run check`; hosted typecheck, 26 tests with zero skipped, and Bun build passed |
+| Hosted dependency audit | PASS | `npm audit --audit-level=low`; zero vulnerabilities |
+| Hosted Docker image | PASS | Local Docker image build completed, including frozen install, hosted typecheck, tests, Bun build, production dependency pruning, and non-root runtime image assembly |
+| Hosted PostgreSQL migrations and quota race | PASS | Forward migrations `001` through `004` applied to PostgreSQL 17; two concurrent organization creates against a quota of one produced one success, one rejection, and one persisted organization |
+| Native Ubuntu WSL2 Linux enforcement | PASS | Native Ubuntu WSL2 enforcement suite passed 12 of 12 tests with zero skipped, exercising the Linux namespace boundary rather than the Windows fallback path |
+| GitHub Actions on exact final commit | PENDING POST-PUSH | Observe the pinned workflows on the exact final commit after push and retain the run/evidence links before publication; do not infer this result from the local verification |