@blueforge-studio/app-dev-db

SDK for app-dev-db, the BlueForge readings store. A repo's CI pushes readings (test.run, audit.score, flows.verify) and other apps read them back (catalog, latest, series, runs), without hand-rolled fetch.

• Two clients in one package: createProducer (write) and createReader (read).
• Zero runtime dependencies beyond the platform fetch (Node 20+, browsers, edge runtimes).
• Server-side only. Both clients hold a secret; never put one in browser code.

Operator side (minting secrets, onboarding a producer or reader, rotation): docs/runbooks/app-dev-db.md in forge-control.

Install

pnpm add @blueforge-studio/app-dev-db   # registry: https://api.packr.blueforge.studio (needs PACKR_TOKEN)

Producer: push a reading from CI

Report main-branch pushes only. The read side treats only the default branch as "current", and a PR run has no stable ref. Gate the step on a push to main:

# .gitea/workflows/ci.yml
- name: Report test run to app-dev-db
  if: github.event_name == 'push' && github.ref == 'refs/heads/main'
  run: node scripts/report-readings.mjs
  env:
    APP_DEVDB_URL: ${{ vars.APP_DEVDB_URL }}            # the FULL ingest URL, .../api/app-dev-db/ingest
    APP_DEVDB_PROJECT: ${{ vars.APP_DEVDB_PROJECT }}    # the project UUID, not the slug
    APP_DEVDB_SECRET: ${{ secrets.APP_DEVDB_PRODUCER_SECRET }}

// scripts/report-readings.mjs
import { readFileSync, existsSync } from 'node:fs'
import { createProducer, testRunFromVitestReport, AppDevDbApiError } from '@blueforge-studio/app-dev-db'

const producer = createProducer({
  ingestUrl: process.env.APP_DEVDB_URL,
  secret: process.env.APP_DEVDB_SECRET,
  project: process.env.APP_DEVDB_PROJECT,
  repo: 'taskmaster',
  producer: 'gitea-actions:taskmaster',
})

// vitest --reporter=json --outputFile.json=vitest-report.json
const report = existsSync('vitest-report.json') && JSON.parse(readFileSync('vitest-report.json', 'utf8'))
const payload = report && testRunFromVitestReport(report, { suite: 'unit' })

if (!payload) {
  console.log('no tests ran: nothing to report') // skipped, never pushed as a zero
} else {
  try {
    const out = await producer.push('test.run', payload, {
      ref: process.env.GITHUB_REF_NAME ?? 'main',
      commit: process.env.GITHUB_SHA,
      source: `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`,
    })
    console.log(out.deduped ? 'already stored' : 'stored', out.contentHash)
  } catch (e) {
    // Telemetry must not stop a deploy: our payload being wrong (4xx) is ours to fix, an unreachable plane is not.
    console.error(String(e))
    process.exitCode = e instanceof AppDevDbApiError && [400, 413, 422].includes(e.status) ? 1 : 0
  }
}

push(kind, payload, options):

Ingest is idempotent on commit + payload content: a retried or re-run push returns deduped: true.

Payloads

Counts must be non-negative integers; score / floor finite numbers; unknown fields are rejected (the server is strict too). Only push what was measured. A dimension you could not measure is skipped, never pushed as 0: an empty scope throws AppDevDbClientError with code: 'empty_scope' before any request, and the server's 422 empty_scope is the backstop.

testRunFromVitestReport(report, { suite }) (also importable from @blueforge-studio/app-dev-db/vitest) reads counts from a vitest JSON report: numPassedTests, numFailedTests, and numPendingTests + numTodoTests as skipped. It returns null when the run measured no tests (skip the push) and throws on a malformed report; a missing or non-numeric count is never read as 0.

Reader: show a project's current pass rate and freshness

The taskmaster case: a project-management view that shows how healthy a project's tests are, and how much to trust that number.

import { createReader, AppDevDbApiError } from '@blueforge-studio/app-dev-db'

const reader = createReader({
  baseUrl: process.env.APP_DEVDB_BASE_URL,   // the mission-control BASE url, not the ingest url
  secret: process.env.APP_DEVDB_READER_SECRET,
})

type Health =
  | { state: 'unknown'; reason: string }                       // nothing measured: NOT 0%
  | { state: 'no-rate' }                                       // measured, but only skips: no pass rate exists
  | { state: 'known'; passRate: number; stale: boolean; ageHours: number }

export async function testHealth(projectSlug: string): Promise<Health | 'not-found'> {
  try {
    const res = await reader.latest({ project: projectSlug, kind: 'test.run' })

    if (res.status === 'unknown') return { state: 'unknown', reason: res.reason }

    // One reading per suite; the project's rate is passed / (passed + failed) over all of them.
    let passed = 0, failed = 0
    for (const r of res.readings) { passed += r.derived.passed; failed += r.derived.failed }
    if (passed + failed === 0) return { state: 'no-rate' }

    const stale = res.readings.some((r) => r.freshness === 'stale')
    return { state: 'known', passRate: passed / (passed + failed), stale, ageHours: Math.max(...res.readings.map((r) => r.ageHours)) }
  } catch (e) {
    if (e instanceof AppDevDbApiError && e.status === 404) return 'not-found' // missing and not-yours look identical, by design
    throw e
  }
}

Reads default to the project's default branch. ref: 'release/1.0' (with optional repo, refKind) pins one ref; allRefs: true widens to every ref, newest wins. Every ref-scoped response says which it used (refSelection, ref, defaultBranch).

for await (const row of reader.iterateRuns({ project: 'taskmaster', kind: 'test.run', window: '7d' })) {
  console.log(row.measuredAt, row.derived.passRate)
}

Unknown is not zero

Never turn an absent or unknown reading into 0.

• latest with nothing stored returns status: 'unknown' (freshness: 'undeclared', readings: []). The SDK passes it through unchanged; it is a distinct type, not an empty success. Branch on res.status before reading readings. Do not render it as 0%, "all green" or "0 failures".
• derived.passRate is null when nothing passed or failed (every test skipped). That is "no rate", not 0. A count of 0 (passed: 0) is a real measurement; a null rate is not.
• series over a window with no readings is an empty points list; do not zero-fill it.
• freshness: 'stale' means the newest reading is old (7 days until per-series cadence exists). The value is still the last measurement; show it as stale, not as current.
• "Missing" and "not yours" are the same 404: do not try to tell them apart.

Errors

Every failure is a typed error. None ever contains the secret: server text and lower-level errors are redacted, and the clients expose no secret through toString, JSON.stringify or util.inspect.

AppDevDbApiError.code:

Retry policy: only network errors and 502 / 503 / 504, with exponential backoff (250 ms, 500 ms, ... capped at 4 s) and 2 retries by default (retry: { retries, baseDelayMs, maxDelayMs }). A 4xx is never retried. Each attempt has a 15 s timeout (timeoutMs, 0 disables). Pass fetch to inject your own, e.g. in tests.

Versioning

0.x: the wire contract is additive-only (a shipped reading kind is never removed or redefined), so new kinds arrive as new entries in READING_KINDS; the SDK's types and clients may still change between minors until 1.0.