currentlybuilding 0.1.0

package/README.md

@@ -0,0 +1,153 @@
+# currentlybuilding
+
+Turn your real AI-coding sessions into verified proof-of-work.
+
+A commit shows what changed. Your session shows how you got there: the problem you
+started with, the approach you took, the calls you made, and what shipped. This small
+tool reads those sessions on your machine, redacts them, grounds them to real git
+commits, and keeps that story with your work.
+
+It is a single self-contained JavaScript file. `npm install -g currentlybuilding` puts a
+`currentlybuilding` command on your path that runs on any Node 18+ with no build step,
+no `tsx`, and no runtime TypeScript loading.
+
+## Privacy first (the trust story)
+
+- **Everything runs locally.** Sessions are read from each tool's local store on your
+  machine (for Claude Code, `~/.claude/projects`). Parsing, redaction, and grounding all
+  happen on-device.
+- **Secrets and personal data are stripped before anything leaves.** API keys, tokens,
+  passwords, `.env` values, emails, and the username in home paths are redacted. The
+  preview shows how many values were removed so you can see it working.
+- **A session only counts if it grounds to real commits.** If the work is not backed by
+  at least one git commit in the session's time window, the session is dropped. You
+  cannot manufacture proof-of-work by talking.
+- **Nothing raw is sent.** `sync` only sends the redacted, grounded event, and the app
+  turns it into a draft. Drafts are never published without your approval.
+
+## Install
+
+```
+npm install -g currentlybuilding
+```
+
+That puts a `currentlybuilding` command on your path.
+
+## Connect (once)
+
+1. Open your Currently dashboard, go to **Sources**, and find the **Connect your editor**
+   card.
+2. Click **Generate token** and copy it.
+3. Save it on this machine:
+
+```
+currentlybuilding connect cur_your_token_here
+```
+
+The token is stored in `~/.currently/config.json` (readable only by you). The server
+derives who you are from the token, so the CLI never sends a user id. `login` is an alias
+for `connect` if you prefer it.
+
+You can also point the CLI at your app while connecting:
+
+```
+currentlybuilding connect cur_your_token_here --url https://your-app.example.com
+```
+
+## Everyday use
+
+```
+currentlybuilding sources    list the AI tools detected on this machine
+currentlybuilding scan       list the sessions found across all tools
+currentlybuilding preview    parse + redact + ground the latest session(s) and print
+                             the proof-of-work. Read-only. Nothing is sent.
+currentlybuilding sync       do the same for new sessions, then send the grounded events
+                             to your app so they become drafts you can approve
+currentlybuilding watch      run sync on a loop, so it works as a background agent
+```
+
+`preview` is the default, so plain `currentlybuilding` is always safe to run.
+
+`sync` is incremental: it only processes sessions newer than the last successful sync
+(the cursor lives in `~/.currently/state.json`). The server also dedupes on a stable
+event id, so a re-run never creates duplicates. Use `--all` to reprocess everything.
+
+## Supported tools
+
+| Tool           | Status       | Notes                                             |
+| -------------- | ------------ | ------------------------------------------------- |
+| Claude Code    | ready        | reads `~/.claude/projects` JSONL                  |
+| Codex          | ready        | reads local session JSONL                         |
+| GitHub Copilot | ready        | reads local chat JSON                             |
+| Aider          | ready        | reads local history                               |
+| Continue       | ready        | reads local session JSON                          |
+| Cursor         | needs SQLite | reads `state.vscdb`; see the SQLite note below    |
+| Windsurf       | experimental | SQLite-backed; detected, capture is best-effort   |
+| Zed            | experimental | detected, capture is best-effort                  |
+
+Add `--tool <id>` (`claude-code`, `codex`, `cursor`, `copilot`, `aider`, `continue`, ...)
+to any command to restrict it to one tool.
+
+### Enabling SQLite-backed tools (Cursor, Windsurf, Zed)
+
+Cursor, Windsurf, and Zed keep their chat history in a SQLite database. The CLI reads it
+with whatever is already on your machine, in this order:
+
+1. `node:sqlite`, built in on Node 22.5+ (nothing to install)
+2. `better-sqlite3`, an optional dependency, used only if it is installed
+3. the `sqlite3` CLI, if it is on your `PATH`
+
+If none is available, the tool is still detected and the CLI prints a one-line hint and
+skips it. To enable capture on older Node without the `sqlite3` CLI, install the optional
+native reader:
+
+```
+npm i -g better-sqlite3
+```
+
+## Options
+
+- `--limit N` how many sessions to process (preview and sync)
+- `--url <app-url>` where to send events (or set `CURRENTLY_URL`, or save it with `connect`)
+- `--token <token>` auth token for `sync` (or set `CURRENTLY_TOKEN`, or save it with `connect`)
+- `--tool <id>` restrict any command to a single tool
+- `--interval N` minutes between passes in `watch` mode (default 5)
+- `--all` ignore the incremental cursor and reprocess every session
+- `--refine` tighten the wording with Groq when `GROQ_API_KEY` is set. Optional;
+  the plain heuristic reads well on its own and needs no key.
+
+Resolution order for both the token and the url is: flag, then environment variable, then
+the saved `~/.currently/config.json`.
+
+## The whole flow
+
+```
+npm install -g currentlybuilding
+currentlybuilding connect cur_...                          # once, token from the dashboard
+currentlybuilding preview --limit 3                         # see what would be sent, read-only
+currentlybuilding sync --url https://your-app.example.com   # send new grounded sessions
+currentlybuilding watch --interval 10                       # keep it current in the background
+```
+
+## Build (maintainers)
+
+The published package ships one bundled file, `dist/currentlybuilding.mjs`, produced by
+esbuild from `currently.mjs` (which statically imports the shared TypeScript session
+logic in `../lib/sessions`):
+
+```
+npm install
+npm run build
+```
+
+The build command is:
+
+```
+esbuild currently.mjs --bundle --platform=node --format=esm --target=node18 \
+  --outfile=dist/currentlybuilding.mjs \
+  --banner:js='#!/usr/bin/env node' --external:better-sqlite3
+```
+
+`better-sqlite3` is kept external so it is required only when a user has installed the
+optional native reader. `prepublishOnly` runs the build, so `npm publish` always ships a
+fresh bundle. Only `dist/` and `README.md` are included in the tarball.