Skip to content

feat: Prometheus /metrics + TypeScript SDK + docs revamp - #75

Merged
Gsbreddy merged 4 commits into
mainfrom
feat/prometheus-ts-sdk
Jun 1, 2026
Merged

feat: Prometheus /metrics + TypeScript SDK + docs revamp#75
Gsbreddy merged 4 commits into
mainfrom
feat/prometheus-ts-sdk

Conversation

@Gsbreddy

@GsbreddyGsbreddy commented Jun 1, 2026•
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

Three independently valuable additions in one PR:

1. Prometheus /metrics scrape endpoint

  • GET /metrics — standard text/plain; version=0.0.4 Prometheus exposition format
  • No new runtime dependencies — formatted manually
  • Same Bearer/loopback gate as GET /v1/metrics
  • Exposes: flightdeck_releases_total, flightdeck_run_events_total, flightdeck_promoted_pointers_total, flightdeck_actions_total, flightdeck_actions_by_type{action=}, flightdeck_pricing_tables_total, flightdeck_schema_version
  • 8 new tests, documented in docs/http-api.md with sample output + Prometheus scrape config YAML
  • Lights up Datadog, Grafana, Honeycomb, New Relic, Prometheus, VictoriaMetrics for free

2. TypeScript / Node.js SDK (sdk-ts/, package: flightdeck-ai)

  • FlightDeckClient: ingestEvent/s(), diff(), getWorkspace(), health() using native fetch (Node 18+, zero runtime deps)
  • FlightDeckOpenAIAdapter: wraps openai.chat.completions.create(), records tokens + latency + success as a RunEvent (fire-and-forget)
  • Types fully grounded in schemas/v1/run_event.schema.json and src/flightdeck/models.py
  • Retry on 429/5xx (3 attempts, exponential backoff). X-FlightDeck-Actor and X-Request-Id on every request
  • 584-line vitest suite covering auth, retry, diff parsing, adapter latency, cached tokens
  • Package name flightdeck-ai matches PyPI — npm install flightdeck-ai

3. MkDocs docs revamp (mkdocs build --strict passes)

  • docs/getting-started.md (NEW) — the "demo worked, now what?" bridge: 5 steps from real release registration to promotion with your actual agent
  • docs/index.md: "Where to start" decision table for first-time visitors
  • docs/cli.md: "Common patterns" section at top (4 copy-paste recipes)
  • docs/sdk.md: End-to-end quickstart example at top
  • docs/troubleshooting.md: "First 5 things to check" triage checklist
  • CHANGELOG: two blob links → hosted Pages URLs

Verification

  • ruff: clean
  • pytest --cov-fail-under=80: 210 passed / 4 skipped / 82.24% coverage (+8 Prometheus tests)
  • mkdocs build --strict: 0.33s, no warnings

Pre-merge checklist

  • Review sdk-ts/ — the TS SDK doesn't have a CI job yet (add npm ci && npm run typecheck && npm test to a new sdk-ts job in ci.yml if desired before publishing to npm)
  • Decide npm publish flow for flightdeck-ai on npm (separate workflow needed, similar to release-pypi.yml)
  • Smoke-test GET /metrics against a running flightdeck serve before tagging v1.4.0

@Gsbreddy
feat: Prometheus /metrics, TypeScript SDK, docs revamp, link cleanup
44e37e5
Prometheus endpoint (no new dependencies):
- GET /metrics — standard text/plain; version=0.0.4 Prometheus scrape
target. Exposes releases_total, run_events_total, promoted_pointers_
total, actions_total, actions_by_type{action=}, pricing_tables_total,
schema_version. Same Bearer/loopback gate as GET /v1/metrics.
8 new tests in tests/test_prometheus_metrics.py.
Documented in docs/http-api.md with sample output + scrape config.
TypeScript SDK (sdk-ts/, package name: flightdeck-ai):
- FlightDeckClient: ingestEvent/s(), diff(), getWorkspace(), health()
using native fetch (Node 18+, zero deps).
- FlightDeckOpenAIAdapter: wraps openai.chat.completions.create(),
records tokens + latency + success as a RunEvent. Fire-and-forget.
- Types fully grounded in schemas/v1/run_event.schema.json and
src/flightdeck/models.py. No any casts except JSON deserialization.
- Retry on 429/5xx (3 attempts, exp backoff). X-FlightDeck-Actor and
X-Request-Id headers on every request.
- 584-line vitest suite: auth, retry, diff parsing, adapter latency,
cached tokens, fire-and-forget ingest errors.
- sdk-ts/README.md: install + 10-line quickstart + OpenAI snippet.
- Package name flightdeck-ai matches the PyPI package.
MkDocs docs revamp (--strict build passes, 0.33s):
- docs/getting-started.md (NEW): 'demo worked, now what?' — 5-step
guide from real release registration through promotion. The page
that was missing for first-time users.
- docs/index.md: 'Where to start' decision table (7 rows) above Quick
reference.
- docs/cli.md: 'Common patterns' section at top (4 copy-paste recipes:
register+diff, CI gate, weekly health, Slack webhook).
- docs/sdk.md: 'Quickstart' section at top (50-line annotated Python
example, end-to-end).
- docs/troubleshooting.md: 'First 5 things to check' numbered checklist.
- mkdocs.yml: Getting started added as second nav item.
Link cleanup:
- CHANGELOG.md: two GitHub blob /docs/cli.md links → hosted Pages URL.
- All other relative links left intact (GitHub renders them correctly).
github-advanced-security[bot]
github-advanced-securityBot found potential problems Jun 1, 2026
View reviewed changes
Comment threadsdk-ts/src/client.ts Fixed
@Gsbreddy
docs: clarify PostgreSQL / production deployment path
cb5b08d
Three audiences kept hitting dead ends:
- 'I want to run this for my team' → no clear Postgres path
- 'Is SQLite OK for prod?' → no guidance
- 'How do I back up?' → pg_dump mention was buried
Changes:
- docs/getting-started.md: 'Production checklist' section — Postgres
install (pip install 'flightdeck-ai[postgres]'), database_url YAML +
env var, Bearer token for remote access, process supervisor guidance.
- docs/operations-and-policy.md: SQLite vs PostgreSQL summary table
near the top, links to existing detailed section.
- docs/index.md: 'Deploy for a team in production' row added to the
Where-to-start decision table.
- examples/deploy/README.md: 'Using PostgreSQL' section with a complete
docker-compose.postgres.yml snippet (postgres:16-alpine + flightdeck
wired via FLIGHTDECK_DATABASE_URL).
@Gsbreddy
fix(pr75-review): address 3 MAJORs from reviewer
4b2f857
MAJOR-1: sdk-ts/package.json: peerDependenciesOptional -> peerDependenciesMeta
peerDependenciesOptional is not a valid npm field (silently ignored,
causes unmet peer dep warnings on every install). Replaced with the
npm 7+ spec-compliant peerDependenciesMeta: { openai: { optional: true } }.
MAJOR-2: metrics.py: skip actions_by_type block when empty
Prometheus text format 0.0.4 prohibits HELP/TYPE headers with zero
time-series beneath them. Scraper warnings / rejections on fresh
workspaces. Wrapped the block in 'if actions_by_action:'.
MAJOR-3: test_prometheus_metrics.py: tighten content-type assertion
Was: 'text/plain' in content-type (too loose — any text/plain passes).
Now: startswith('text/plain; version=0.0.4') to catch regressions in
the full required header value.
@Gsbreddy
fix(security): replace quantified regex with loop in TS SDK client
a7170de
CodeQL CWE-1333: /\/+$/ applied to user-supplied serverUrl flagged as
potential ReDoS. While /\/+$/ is linear in V8, CodeQL cannot statically
prove that and warns conservatively. Replaced with a plain while loop
that is provably O(n) and CodeQL-safe.
@Gsbreddy
Gsbreddy marked this pull request as ready for review June 1, 2026 23:54
@Gsbreddy
Gsbreddy merged commit afbd0fd into mainJun 1, 2026
13 checks passed
@Gsbreddy
Gsbreddy deleted the feat/prometheus-ts-sdk branch June 1, 2026 23:57
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer
@github-advanced-securitygithub-advanced-security[bot]github-advanced-security[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Gsbreddy@github-advanced-security