The Problem

Modeling a cap table quickly becomes nonlinear when SAFEs, option‑pool refreshes, and priced rounds interact recursively. Small PPS or rounding differences shift final ownership, so founders need a deterministic calculation engine rather than spreadsheets.

What This Does

The repository provides a TypeScript library that computes ownership after SAFE conversions, option‑pool refreshes, and a priced round.

  • Core logic lives in src/cap-table/priced-round.ts, which orchestrates SAFE conversion, series‑share allocation, and pool‑size adjustment.
  • SAFE math is handled by src/safe-calcs.ts and validated through src/validation.ts.
  • Type definitions are in src/cap-table/types.ts; the public API is re‑exported from src/cap-table/index.ts.
  • A CLI wrapper is src/cli.ts; the module graph also includes src/index.ts as the top‑level entry point.
  • Seven test files under src/__tests__/ exercise pre‑round, priced‑round, financial correctness, risks, number formatting, and CLI behaviour, giving confidence that the engine stays deterministic across the recursive term interactions.

How It Is Wired

Execution starts at the CLI (src/cli.ts), which parses command‑line arguments or JSON input and delegates to src/index.ts. That file re‑exports the core priced-round function from src/cap-table/priced-round.ts. That function:

  1. Calls src/validation.ts to coerce and check input shapes.
  2. Invokes SAFE conversion routines in src/safe-calcs.ts to determine each SAFE’s share count based on caps, MFN side‑letters, and conversion type.
  3. Computes the post‑money option‑pool size required to hit targetOptionsPct, then adjusts the fully‑diluted share base.
  4. Allocates series‑A shares at the given pre‑money valuation.

The call graph is shallow: cli → index → priced-round → (validation, safe‑calcs). No external services or database writes occur; the process reads JSON, performs pure arithmetic, and returns a plain object. The widest blast radius is priced-round.ts because any change to SAFE terms, valuation, or pool target ripples through every subsequent share calculation.

How To Use It

Setup – The project uses pnpm. Install dependencies with

pnpm install

Configuration – No environment variables or secret keys are required; all data is passed via the JSON scenario or CLI flags.

Running it –

  • To invoke the CLI:
npx @1984vc/cap-table priced-round './scenario.json'
  • Or provide the scenario inline (as shown in the README). The entry point is src/cli.ts; it reads the JSON, runs the engine in priced-round.ts, and prints a table of final ownership.

Real‑World Use

A startup founder can pipe a JSON scenario describing founders, existing options, five SAFEs (YC 7%, YC MFN, three priced SAFEs), a $4M Series A at $25M pre‑money, and a 10 % post‑money pool refresh. The library returns the reconciled cap table (e.g., Founder A 26.54 %, YC 7% 5.64 %, etc.) without manual spreadsheet updates. The result can be fed into a reporting tool or an AI coding agent that asks the skill to “model my cap table” and then explains the before/after ownership.

Code Health & Issues

  • No CI/CD pipeline detected – the .github/ directory or any CI config is absent, so there is no automated build/test gate.
  • Test coverage – 7 test files exist under src/__tests__/; they can be run locally with pnpm test (script defined in package.json), but without CI they remain unguarded on push.
  • Licence – a LICENSE file is present, so redistribution terms are documented.

No other SDLC gaps were found beyond the missing CI configuration.

The Bottom Line

This repo delivers a compact, well‑tested calculation engine for complex cap‑table scenarios, ideal for founders, AI agents, or anyone needing deterministic ownership math without building a spreadsheet. The main drawback is the absence of automated CI, so teams must run the test suite locally to catch regressions. It works best as a library embedded in a larger tooling chain or called via its CLI for one‑off calculations.