fathom-cli 0.3.0 → 0.3.3

package/README.md

@@ -1,95 +1,101 @@
 # fathom-cli
 
-> **Active development.** APIs and features may change between versions. We welcome feedback — run `fathom feedback` or see [FEEDBACK.md](../../FEEDBACK.md).
+[![npm version](https://img.shields.io/npm/v/fathom-cli)](https://www.npmjs.com/package/fathom-cli)
 
-The CLI for [Fathom](https://github.com/olivelliott/fathom) -- the headless intelligence layer for AI-augmented development. One command runs the full loop: capture intent, estimate tokens, route to the right model, build with full context, track actuals, reconcile, calibrate.
-
-## Install
+**Know what your AI coding actually costs.** Estimate tokens before you build, track actuals while you build, calibrate so estimates get better over time.
 
 ```bash
 npm install -g fathom-cli
+fathom
+```
+
+## The Problem
+
+You're spending real money on AI coding and have zero visibility into where it goes. You don't know what a feature costs until the bill arrives. Overhead — context resends, tool calls, error recovery — is invisible.
+
+## What Fathom Does
+
+**Estimate** → token cost per feature, based on task type + complexity + overhead model
+
+**Track** → auto-imports sessions from Claude, GPT, Gemini, or any provider. Tags to features automatically.
+
+**Calibrate** → compares estimates to actuals, adjusts the model. Gets more accurate every cycle.
+
+```
+$ fathom estimate "add OAuth login with Google and GitHub"
+  ~42,000 tokens (~$0.84) — complexity: L, type: integration
+
+$ fathom track
+  3 sessions imported, 2 auto-tagged (auth-login: 89%, payment: 72%)
+
+$ fathom reconcile
+  auth-login: estimated 42K, actual 67K (1.6x over — error recovery overhead)
+
+$ fathom calibrate
+  adjusted integration overhead: 1.8x → 2.4x (based on 12 data points)
 ```
 
-## One Command
+## One Command Workflow
 
 ```bash
 fathom
 ```
 
-That's it. `fathom` with no arguments walks through the entire workflow:
+With no arguments, `fathom` runs the full loop:
 
-1. **Intent** -- captures what you're building, what matters, your budget and guardrails
-2. **Intake** -- extracts work items from your requirements, estimates tokens and cost
-3. **Build** -- generates a context-rich prompt and launches your AI tool of choice
-4. **Review** -- tracks sessions, reconciles estimates vs actuals, calibrates
+1. **Intent** — captures what you're building, what matters, your budget and guardrails
+2. **Intake** — extracts work items, estimates tokens and cost
+3. **Build** — launches your AI tool with full context
+4. **Review** — tracks sessions, reconciles, calibrates
 
-New project? It auto-scaffolds everything. Returning project? Shows progress and offers contextual next steps:
+New project? Auto-scaffolds everything. Returning? Shows progress:
 
 ```
 $ fathom
 
-  Fathom -- myproject
-  6/12 features complete (50%) -- $8.40 of $14.20 spent
+  Fathom — myproject
+  6/12 features complete (50%) — $8.40 of $14.20 spent
 
-  What would you like to do?
   > Continue building (next: payment-integration)
-    New intake -- add more work
-    Review -- reconcile recent sessions
-    Status overview
+    New intake — add more work
+    Review — reconcile recent sessions
 ```
 
-Resume from any phase:
+## Also Does
 
-```bash
-fathom --from build     # Skip intake
-fathom --from review    # Just track + reconcile + calibrate
-```
+- **Model routing** — recommends Haiku/Sonnet/Opus based on task complexity and budget
+- **Tool config generation** — creates system prompts for Claude, Cursor, Copilot, Windsurf from your project intent
+- **Guardrail templates** — OWASP, WCAG, HIPAA, GDPR, PCI, SOC2 built-in
+- **MCP server** — use Fathom as tools inside any MCP-compatible editor
+- **Velocity benchmarks** — "auth features take 2.3 days and 85K tokens on average"
 
 ## All Commands
 
-| Command | Description |
+| Command | What it does |
 |---------|-------------|
-| `fathom` | Full workflow -- intake, build, review (default) |
-| `fathom intake` | Turn raw feedback into structured spec slices with estimates |
-| `fathom analyze <spec>` | Parse a spec file and estimate all features |
-| `fathom estimate <desc>` | Quick cost estimate for a single feature |
-| `fathom setup` | Scaffold project tracking |
-| `fathom init` | Initialize a new Fathom project |
-| `fathom track` | Import sessions, auto-tag to features |
-| `fathom reconcile` | Compare estimates vs actuals |
-| `fathom calibrate` | Adjust task profiles from real data |
-| `fathom velocity` | Throughput metrics and benchmarks |
-| `fathom project` | Manage project configuration |
+| `fathom` | Full workflow — intake, build, review |
+| `fathom estimate <desc>` | Quick cost estimate |
+| `fathom intake` | Requirements → estimated spec slices |
+| `fathom analyze <spec>` | Parse spec, estimate features |
+| `fathom track` | Import + auto-tag sessions |
+| `fathom reconcile` | Estimates vs actuals |
+| `fathom calibrate` | Adjust from real data |
+| `fathom velocity` | Throughput metrics |
 | `fathom status` | Project overview |
-| `fathom pricing` | Show model pricing |
-| `fathom validate` | Validate project configuration |
-| `fathom rename <name>` | Rename project across config files |
-| `fathom research` | Research tasks with AI assistance |
-| `fathom feedback` | How to report bugs and request features |
+| `fathom pricing` | Model pricing table |
+| `fathom go` | Launch AI tool with context |
 
 ## Environment Variables
 
-Auto-loaded from `.env` in your project directory.
-
 | Variable | Purpose |
 |----------|---------|
-| `ANTHROPIC_API_KEY` | Required for intake extraction and AI-powered estimation |
-| `OPENAI_API_KEY` | Alternative provider for intake extraction |
-| `CONVEX_URL` | Optional -- enables real-time dashboard sync |
-
-## Feedback
-
-```bash
-fathom feedback
-fathom feedback --bug "description of the issue"
-fathom feedback --feature "description of what you'd like"
-```
-
-See [FEEDBACK.md](https://github.com/olivelliott/fathom/blob/main/FEEDBACK.md) for details.
+| `ANTHROPIC_API_KEY` | For intake extraction |
+| `OPENAI_API_KEY` | Alternative provider |
+| `CONVEX_URL` | Optional — real-time dashboard |
 
-## Part of the Fathom ecosystem
+## Part of Fathom
 
-`fathom-cli` is a consumer of the Fathom packages -- it wires all the headless intelligence into a command-line interface. See the [Fathom README](https://github.com/olivelliott/fathom) for the full picture.
+`fathom-cli` wraps the [Fathom](https://github.com/olivelliott/fathom) headless packages into a CLI. Use the packages directly if you're building your own tooling.
 
 ## License
 

package/dist/data/guardrails/gdpr-basic.yaml

@@ -0,0 +1,19 @@
+name: gdpr-basic
+description: GDPR Basic Compliance Guidelines
+category: security
+rules:
+  - "Collect explicit, informed, and freely given consent before processing personal data — pre-checked boxes are not valid consent"
+  - "Practice data minimization — only collect and retain personal data that is strictly necessary for the stated purpose"
+  - "Implement right to deletion (right to be forgotten) — users must be able to request complete removal of their personal data"
+  - "Implement data portability — provide users a machine-readable export (JSON/CSV) of all their personal data on request"
+  - "Implement right of access — users must be able to view all personal data you hold about them within 30 days of request"
+  - "Apply privacy by design — build data protection into system architecture from the start, not as an afterthought"
+  - "Maintain a Record of Processing Activities (ROPA) documenting what data you collect, why, and how long you keep it"
+  - "Implement breach notification — report personal data breaches to the supervisory authority within 72 hours of discovery"
+  - "Obtain explicit consent before setting non-essential cookies or tracking — implement a compliant cookie consent banner"
+  - "Do not transfer personal data outside the EEA without appropriate safeguards (SCCs, adequacy decisions, or BCRs)"
+  - "Define and enforce data retention periods — automatically delete or anonymize personal data when the retention period expires"
+  - "Implement granular consent management — users must be able to withdraw consent as easily as they gave it"
+  - "Conduct Data Protection Impact Assessments (DPIA) before processing that is likely to result in high risk to individuals"
+  - "Pseudonymize personal data wherever possible — separate identifying information from the data being processed"
+  - "Never use personal data for purposes beyond what was explicitly communicated at the time of collection without new consent"

package/dist/data/guardrails/hipaa-basic.yaml

@@ -0,0 +1,19 @@
+name: hipaa-basic
+description: HIPAA Basic Compliance Guidelines
+category: security
+rules:
+  - "Encrypt all Protected Health Information (PHI) at rest using AES-256 — this includes databases, backups, and file storage"
+  - "Encrypt all PHI in transit using TLS 1.2+ — never send health data over unencrypted channels"
+  - "Apply the minimum necessary principle — only request, display, and process the specific PHI fields needed for the task"
+  - "Implement role-based access control (RBAC) so users only see PHI relevant to their job function"
+  - "Log all access to PHI with immutable audit trails — record who accessed what, when, and why"
+  - "Retain audit logs for at least six years as required by HIPAA retention rules"
+  - "Never include PHI in URLs, query parameters, client-side storage, or application logs"
+  - "Require unique user IDs and enforce multi-factor authentication for all systems containing PHI"
+  - "Implement automatic session timeout (15 minutes or less of inactivity) for applications accessing PHI"
+  - "Verify that all third-party services handling PHI have signed a Business Associate Agreement (BAA) before integration"
+  - "Implement a breach notification mechanism — HIPAA requires notification within 60 days of discovering a breach"
+  - "Provide a mechanism for patients to request access to, amendment of, and an accounting of disclosures of their PHI"
+  - "Run regular risk assessments on all systems that store, process, or transmit PHI — document findings and remediation"
+  - "Ensure PHI is completely and irreversibly deleted when no longer needed — including backups and replicas"
+  - "De-identify data according to HIPAA Safe Harbor (remove all 18 identifiers) before using it for analytics or testing"

package/dist/data/guardrails/owasp-top-10.yaml

@@ -0,0 +1,16 @@
+name: owasp-top-10
+description: OWASP Top 10 Web Application Security Risks
+category: security
+rules:
+  - "Validate and sanitize all user input server-side — never trust client-side validation alone"
+  - "Use parameterized queries or prepared statements — never concatenate user input into SQL"
+  - "Implement proper authentication with secure password hashing (bcrypt/argon2) and session management"
+  - "Apply principle of least privilege — users and services should only access what they need"
+  - "Never expose sensitive data in error messages, logs, or API responses"
+  - "Use HTTPS everywhere — never transmit sensitive data over unencrypted connections"
+  - "Validate Content-Type headers and reject unexpected content types"
+  - "Implement rate limiting on authentication endpoints and sensitive operations"
+  - "Keep dependencies updated and audit for known vulnerabilities regularly"
+  - "Encode output contextually (HTML, URL, JavaScript) to prevent XSS"
+  - "Use CSRF tokens for state-changing operations"
+  - "Never store secrets, API keys, or credentials in source code or client-side storage"

package/dist/data/guardrails/pci-basic.yaml

@@ -0,0 +1,19 @@
+name: pci-basic
+description: PCI DSS Basic Compliance Guidelines
+category: security
+rules:
+  - "Never store full card numbers (PAN) in plaintext — use tokenization or truncation (first 6/last 4 only)"
+  - "Never log, print, or include in error messages: full PAN, CVV/CVC, PIN, or magnetic stripe data"
+  - "Encrypt cardholder data at rest using AES-256 or equivalent — manage keys separately from encrypted data"
+  - "Transmit cardholder data only over TLS 1.2+ — reject connections using older protocols"
+  - "Isolate payment processing systems from the general application network — use dedicated subnets or services"
+  - "Restrict access to cardholder data to only the services and personnel that absolutely need it"
+  - "Use unique credentials for every user and service account that accesses payment systems — no shared accounts"
+  - "Enforce multi-factor authentication for all administrative access to payment processing environments"
+  - "Log all access to cardholder data and payment systems — include who, what, when, and from where"
+  - "Retain audit logs for at least one year, with a minimum of three months immediately available for analysis"
+  - "Run vulnerability scans on all payment-facing systems quarterly and after any significant change"
+  - "Never use vendor-supplied default passwords or settings on any system in the cardholder data environment"
+  - "Mask PAN when displayed — show no more than first 6 and last 4 digits unless there is a legitimate business need"
+  - "Implement a web application firewall (WAF) or rigorous code review for all public-facing payment applications"
+  - "Maintain an inventory of all system components in scope for PCI DSS and review scope annually"

package/dist/data/guardrails/soc2-basic.yaml

@@ -0,0 +1,19 @@
+name: soc2-basic
+description: SOC 2 Basic Compliance Guidelines
+category: security
+rules:
+  - "Enforce multi-factor authentication (MFA) for all user and administrative access to production systems"
+  - "Implement role-based access control (RBAC) with least-privilege — review and recertify access quarterly"
+  - "Log all system access, configuration changes, and data operations to a centralized, tamper-evident logging system"
+  - "Establish a formal change management process — all production changes require review, approval, and rollback plans"
+  - "Conduct regular vulnerability scans and penetration tests — remediate critical findings within defined SLAs"
+  - "Implement automated monitoring and alerting for system availability, performance anomalies, and security events"
+  - "Maintain and test an incident response plan — define roles, escalation paths, communication templates, and post-mortem processes"
+  - "Encrypt sensitive data at rest (AES-256) and in transit (TLS 1.2+) across all system components"
+  - "Perform vendor security assessments before onboarding third-party services that process or store customer data"
+  - "Implement automated backups with defined RPO/RTO targets and test restoration procedures at least annually"
+  - "Enforce separation of duties — no single person should be able to deploy code, approve changes, and access production data"
+  - "Revoke access to all systems within 24 hours of employee termination or role change"
+  - "Maintain a documented and enforced data classification policy — label data as public, internal, confidential, or restricted"
+  - "Implement network segmentation — isolate production, staging, and development environments from each other"
+  - "Require security awareness training for all employees and contractors with access to customer data at least annually"

package/dist/data/guardrails/wcag-aa.yaml

@@ -0,0 +1,16 @@
+name: wcag-aa
+description: WCAG 2.1 Level AA Accessibility Guidelines
+category: quality
+rules:
+  - "All images must have descriptive alt text (or empty alt for decorative images)"
+  - "Ensure color contrast ratio of at least 4.5:1 for normal text, 3:1 for large text"
+  - "All interactive elements must be keyboard accessible with visible focus indicators"
+  - "Form inputs must have associated labels — use htmlFor/id or aria-label"
+  - "Use semantic HTML elements (nav, main, header, footer, article, section) for document structure"
+  - "Provide skip navigation links for keyboard users"
+  - "Ensure all content is readable and functional at 200% zoom"
+  - "Use aria-live regions for dynamic content updates that should be announced to screen readers"
+  - "Never use color alone to convey information — supplement with text, icons, or patterns"
+  - "Provide text alternatives for all non-text content (video captions, audio transcripts)"
+  - "Ensure touch targets are at least 44x44px on mobile"
+  - "Support reduced-motion preferences via prefers-reduced-motion media query"