fallow coverage

fallow coverage groups the paid Runtime Coverage workflow commands:

fallow coverage setup              # resumable first-run flow
fallow coverage analyze --cloud --repo owner/repo
fallow coverage upload-inventory   # push a static function inventory
fallow coverage upload-source-maps           # upload build source maps for bundled code

setup

The setup flow is resumable: run it once to bootstrap, follow the generated recipe, then run it again after traffic has been captured. It performs four steps:

1. check license state
2. locate or install fallow-cov
3. write a framework-specific collection recipe to docs/collect-coverage.md
4. if coverage already exists, hand off directly to fallow health --runtime-coverage <path>

fallow coverage setup
fallow coverage setup --non-interactive
fallow coverage setup --yes
fallow coverage setup --yes --json
fallow coverage setup --yes --json --explain

Flags

What setup detects automatically

fallow coverage setup inspects package.json, lockfiles, and scripts to tailor the instructions:

If the project does not match a built-in framework recipe, fallow still writes a fallback docs/collect-coverage.md with a link to the public coverage docs for manual setup.

Agent-readable JSON

fallow coverage setup --yes --json is the agent-driven entry point. The payload is deterministic and stable across reruns; --explain adds the optional _meta keys without changing schema_version.

On a workspace monorepo (Elysia API at root + two Vite browser apps in dashboard/ and site/):

{
  "schema_version": "1",
  "framework_detected": "plain_node",
  "package_manager": "bun",
  "runtime_targets": ["node", "browser"],
  "members": [
    {
      "name": "fallow-cloud",
      "path": ".",
      "framework_detected": "plain_node",
      "runtime_targets": ["node"],
      "files_to_edit": [{"path": "src/index.ts", "reason": "..."}],
      "snippets": [{"label": "Node entrypoint", "path": "src/index.ts", "content": "..."}],
      "dockerfile_snippet": "ENV FALLOW_TRANSPORT=fs\nENV FALLOW_WRITE_TO_DIR=/tmp/fallow-coverage",
      "warnings": []
    },
    {
      "name": "fallow-dashboard",
      "path": "dashboard",
      "framework_detected": "vite",
      "runtime_targets": ["browser"],
      "files_to_edit": [{"path": "dashboard/src/main.ts", "reason": "..."}],
      "snippets": [{"label": "Vite browser entry", "path": "dashboard/src/main.ts", "content": "..."}],
      "dockerfile_snippet": null,
      "warnings": []
    }
  ],
  "config_written": null,
  "commands": ["bun add @fallow-cli/beacon", "bun add -d @fallow-cli/fallow-cov"],
  "files_to_edit": [{"path": "src/index.ts", "reason": "..."}],
  "snippets": [{"label": "Node entrypoint", "path": "src/index.ts", "content": "..."}],
  "dockerfile_snippet": "ENV FALLOW_TRANSPORT=fs\nENV FALLOW_WRITE_TO_DIR=/tmp/fallow-coverage",
  "next_steps": [...],
  "warnings": []
}

framework_detected uses canonical ids (nextjs, nestjs, nuxt, sveltekit, astro, remix, vite, plain_node, unknown). Workspace projects emit one members[] entry per runtime-bearing workspace, each with its own framework_detected, runtime_targets, files_to_edit, snippets, and dockerfile_snippet. Top-level fields mirror the first emitted runtime member (the root when the root itself is a runtime app, otherwise the first runtime workspace), so on a browser-rooted monorepo with a Node child agents should read each member's dockerfile_snippet rather than the top-level one. Single-app projects emit a members array of length 1 (path "."), so consumers can treat members[] uniformly.

Aggregator-only repos (workspaces whose only runtime indicator is a Turbo/Nx-style dev script delegating to children, plus build-only library packages) are not runtime-bearing and emit an empty payload: framework_detected: "unknown", runtime_targets: [], members: [], plus a warnings entry of "No runtime workspace members were detected; emitted install commands only.". Agents can branch on members.length === 0 (or framework_detected === "unknown") to detect this case and skip the snippet-application step.

Generated recipe

The generated docs/collect-coverage.md recipe typically looks like:

1. Remove any old dump directory: rm -rf ./coverage
2. Build the app
3. Start the app with NODE_V8_COVERAGE=./coverage ...
4. Exercise the routes or jobs you care about
5. Stop the app and run: fallow coverage setup

Framework-aware script selection means fallow prefers existing build, start, or preview scripts when they exist and falls back to common framework commands otherwise.

Typical flow

fallow license activate --trial --email [email protected]
fallow coverage setup

# Follow docs/collect-coverage.md, then run setup again.
# With coverage present it hands off to `fallow health --runtime-coverage ./coverage`.
fallow coverage setup

analyze

Use local mode when you have a coverage artifact on disk:

fallow coverage analyze --runtime-coverage ./coverage --format json

Use cloud mode when you want the latest fallow.cloud runtime context for a repo:

FALLOW_API_KEY=fallow_live_... \
  fallow coverage analyze --cloud --repo owner/repo --format json

FALLOW_API_KEY alone never selects cloud mode. You must pass --cloud, --runtime-coverage-cloud, or set FALLOW_RUNTIME_COVERAGE_SOURCE=cloud.

Analyze flags

Cloud analysis emits the same runtime_coverage JSON block as local mode. Its summary includes data_source: "cloud", last_received_at, and capture_quality derived from the pulled runtime window. Cloud functions that cannot be matched to the local AST/static index are omitted from findings and reported through a cloud_functions_unmatched warning.

Each finding's actions[].type uses the canonical kebab-case vocabulary: delete-cold-code is emitted on verdict=safe_to_delete, review-runtime on verdict=review_required. The sidecar may emit additional protocol-specific identifiers, so consumers should treat unknown values as forward-compat extensions rather than schema violations.

Sidecar installation

If fallow-cov is missing, setup tells you exactly what it checked and suggests the correct install command for your package manager, for example:

pnpm add -D @fallow-cli/fallow-cov

You can also bypass auto-discovery by setting either explicit-override env var to a binary path. Resolution order is FALLOW_COV_BIN first, then FALLOW_COV_BINARY_PATH, then project-local auto-discovery. Both fail hard with a clear error if the configured path does not exist (they never silently fall through to the next step). FALLOW_COV_BINARY_PATH exists for air-gapped enterprise installs, Linux distro-packaged sidecars, and Docker multi-user setups where ~/.fallow/bin is not writable.

Sidecar signature verification

Every sidecar spawn runs an Ed25519 signature check against the compiled-in public key. The sidecar binary must ship with an adjacent <binary>.sig file. A missing, wrong-length, or invalid signature fails hard with exit code 4 rather than executing an unverified binary. There is no warn-and-run mode and no opt-out env var. If verification fails, reinstall the signed distribution with the install command above.

upload-inventory

fallow coverage upload-inventory walks every JS/TS source in the project and POSTs a static function inventory (one row per declaration, expression, arrow, or method) to fallow cloud. The server computes inventory − runtime-seen = untracked for the matching git SHA, which lights up the dashboard's Untracked filter.

fallow coverage upload-inventory \
  --api-key $FALLOW_API_KEY \
  --project-id acme/web

Defaults and inference

Flags

Function naming

Inventory entries use names that match oxc-coverage-instrument byte-for-byte so the runtime join succeeds. Precedence:

1. Parent context (method key, variable binding, property key, export default).
2. The function's own id (function foo() {}, named function expression).
3. (anonymous_N) where N is a file-scoped monotonic counter.

TypeScript declaration files (*.d.ts, *.d.mts, *.d.cts, *.d.tsx) and overload signatures with no body are intentionally skipped: they have no runtime footprint, so including them would pollute the dashboard with permanently untracked entries.

Path prefix (containerized deployments)

The runtime beacon reports V8's filePath as it sees it at runtime. In a container, that is the path inside the image (e.g. /app/src/foo.ts when the Dockerfile sets WORKDIR /app). The static inventory walker, running in CI against the checkout, emits repo-relative paths (src/foo.ts) by default. The server joins runtime and inventory on the exact (filePath, functionName) pair; if the two sides don't share a prefix shape, the Untracked filter never lights up and the dashboard surfaces a mismatched state.

The fix: pass --path-prefix matching your deployed WORKDIR:

fallow coverage upload-inventory --path-prefix /app

Common values by deployment target:

After upload, the server samples up to 100 recent runtime rows and reports the overlap with the inventory. The CLI prints a yellow warning if overlap < 50% with an example mismatch, and the dashboard renders a configuration-needed state on the repo detail page until the prefix is corrected.

Exit codes

Example CI job (GitHub Actions)

- name: Upload function inventory to fallow cloud
  run: |
    npx fallow coverage upload-inventory
  env:
    FALLOW_API_KEY: ${{ secrets.FALLOW_API_KEY }}

Dry-run output

fallow coverage upload-inventory (dry run)
  project-id:    acme/web
  git-sha:       a1b2c3d4e5f6...
  functions:     14,280
  endpoint:      https://api.fallow.cloud/v1/coverage/acme/web/inventory

first 5 of 14,280 entries:
  src/index.ts:1   bootstrap
  src/index.ts:12  (anonymous_1)
  src/user.ts:3    createUser
  src/user.ts:18   default
  src/user.ts:42   (anonymous_5)
  ... and 14,275 more

upload-source-maps

fallow coverage upload-source-maps scans a build output directory for source maps and POSTs each map to fallow cloud under the current repo and git SHA. The production beacon reports coverage against deployed bundles; uploaded source maps let the cloud resolver remap those bundle positions back to original source files.

FALLOW_API_KEY=fallow_live_... \
  fallow coverage upload-source-maps --dir dist --repo my-app --git-sha "$GITHUB_SHA"

Source-map defaults

The API key comes only from FALLOW_API_KEY; there is intentionally no --api-key flag, so secrets do not land in shell history or process lists. Set FALLOW_CA_BUNDLE=/path/to/bundle.pem when CI needs a custom PEM trust bundle for fallow cloud. The bundle replaces the default WebPKI roots, so private-CA environments should pass a complete bundle containing public roots plus the private CA. Relative bundle paths resolve from the process working directory.

Uploads retry network failures, HTTP 429, and HTTP 502/503/504 up to three attempts. HTTP 429 honors Retry-After delta seconds and HTTP-date values, capped at 60 seconds. Setup or transport failures that prevent every map from uploading exit 7; mixed per-map failures still exit 1.

Source-map CI snippets

- name: Build
  run: npm run build

- name: Upload source maps to fallow
  run: npx fallow coverage upload-source-maps --dir dist --git-sha "$GITHUB_SHA"
  env:
    FALLOW_API_KEY: ${{ secrets.FALLOW_API_KEY }}

Source-map failure modes

See also