@kitkat-vn/kitcode 0.2.0-staging.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KitCode Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,328 @@
+# @kitkat-vn/kitcode
+
+Local break companion for coding campaigns. This package is the **source of truth** for tracking, reward eligibility, redeem state, hooks, and the local Mini companion.
+
+Published package: `@kitkat-vn/kitcode`
+
+---
+
+## For people
+
+### Before you set up
+
+Setup only works when an assistant can run commands on your machine.
+
+| Tool | What works | What does not work |
+| --- | --- | --- |
+| **Codex** | **Codex Task** or **project chat** (Desktop, Go+) | Regular chat |
+| **Claude** | **Claude Code** on Claude Desktop (Pro+) | Cloud-only browser chat |
+
+**Minimum requirements:**
+
+| | **Codex** | **Claude Code** |
+| --- | --- | --- |
+| App | ChatGPT desktop app | Claude Desktop (Code tab) |
+| Permission control | Approve for me or Full access | Auto or Bypass permissions |
+| Account plan | Go (or higher) | Pro (or higher) |
+
+Use the permission setting that lets setup commands run without stopping between steps.
+
+### Quick Start
+
+Install KitCode first, from the dist-tag meant for you (see Releases, below): no `latest` release exists yet, and `staging` is for the invited testers of the staging round.
+
+<table>
+  <tr>
+    <th>Command</th>
+    <th>What it opens or enables</th>
+  </tr>
+  <tr>
+    <td>
+      <pre><code>kitcode codex on
+kitcode claude on</code></pre>
+    </td>
+    <td>
+      Codex / Claude integration plus Welcome when onboarding is incomplete.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <pre><code>Save Welcome with at least one project</code></pre>
+    </td>
+    <td>
+      Opens the Mini companion and can start background tracking when you chose YES in Welcome.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <pre><code>kitcode track
+kitcode dashboard</code></pre>
+    </td>
+    <td>
+      Starts tracking or opens the hosted dashboard.
+    </td>
+  </tr>
+</table>
+
+Local API: `http://127.0.0.1:4747`
+
+Finish **Welcome** with at least one project folder before expecting tracking to work.
+
+---
+
+## For agents / developers
+
+### Hard rules
+
+1. Use Codex Task or a project chat (Desktop, Go+), or Claude Code on Claude Desktop (Pro+).
+2. Set permission control before setup: Codex **Approve for me** or **Full access**; Claude Code **Auto** or **Bypass permissions**.
+3. Execute commands yourself. Do not stop after printing shell instructions.
+4. Never calculate or mutate rewards. Use `kitcode status`, `kitcode summary`, and `kitcode awards`.
+
+### Daily commands
+
+| Command | What it does |
+| --- | --- |
+| `kitcode add [path]` | Add a project. Defaults to current folder. Existing code becomes baseline. |
+| `kitcode remove [path]` | Remove a project, its snapshot and its counted `=`. Focus time already earned stays. |
+| `kitcode track` | Start the background tracker. Can run before projects are added. |
+| `kitcode untrack` | Stop the tracker. Added projects remain registered. |
+| `kitcode list` | Show how many projects are added. |
+| `kitcode status` | Tracker state, project count, compact reward progress. |
+| `kitcode summary` | Total counted `=`, active time, next milestone progress. |
+| `kitcode awards` | Reward and milestone readiness. Aliases: `award`, `rewards`. |
+| `kitcode setup` | Welcome: projects and auto-track preference. |
+| `kitcode uninstall` | Remove hooks, skills, tracker, and all `~/.kitcode` data. |
+| `kitcode dashboard` | Open the hosted dashboard for the running tracker. |
+| `kitcode codex on/off/status` | Install, remove, or inspect the Codex hook and skill. |
+| `kitcode claude on/off/status` | Install, remove, or inspect the Claude hook and skill. |
+
+Simplest flow:
+
+```bash
+kitcode track
+cd your-project
+kitcode add .
+kitcode dashboard
+```
+
+Or add first, track later:
+
+```bash
+cd your-project
+kitcode add .
+kitcode track
+```
+
+`dashboard` and the Mini companion require a running tracker.
+
+During first-time `codex on` / `claude on`, do **not** run `add` or `track` for the user. Welcome owns first project selection.
+
+## Surfaces
+
+### Mini companion
+
+A successful Welcome save opens the Mini companion, which shows the page the tracker serves at `/companion`, or a copy of that page when no tracker answers as it opens. `kitcode setup` opens Welcome.
+
+The Mini is a compact metrics bar beside your work. There is **no** standalone `kitcode mini` command.
+
+### Setup / Welcome
+
+`kitcode setup` and first-time `codex on` / `claude on` can open Welcome so the user can:
+
+- pick one or more project folders
+- choose whether background tracking should start after save
+
+Welcome no longer asks for a companion preference. Saving Welcome opens the Mini companion.
+
+Setup needs the optional Electron dependency.
+
+### Dashboard
+
+`kitcode dashboard` opens the hosted dashboard, which reads the local tracker API.
+
+Use `--no-open` or `KITCODE_NO_OPEN=1` to skip auto-opening the browser.
+
+## What KitCode counts
+
+### Focus time
+
+Focus time is one clock for all your projects: a second is active when any added project had real activity in the 5 minutes before it, and it counts once, however many projects were active. Real activity is a change to the lines KitCode counts in a file it reads (below). Touching a file, a save that changes no line, re-indenting, and a git operation on its own (a pull, a merge, a checkout of another branch, a stash) are not. After **5 quiet minutes**, new time is recorded as idle. No time is earned while the tracker is stopped.
+
+### Equal count
+
+KitCode scans local source snapshots and counts `=` on **real code lines** added after the project baseline.
+
+Rules:
+
+- `kitcode add` creates the baseline.
+- Existing lines at add time do not earn reward by themselves.
+- Only lines with enough alphanumeric content count as real code lines.
+- A line is compared without its whitespace, with `"` and `` ` `` read as `'`, and without one trailing `;` or `,`: re-indenting, re-spacing or re-quoting a line does not make it new.
+- A line earns at most 3 `=`, and once per user, ever: a line KitCode has seen before, in any file of any of your projects, earns nothing, whether it was moved, copied, pasted, or deleted and added back.
+- Ignored paths include `.git`, `node_modules`, `dist`, `build`, `.next`, `out`, and `coverage`.
+- Lockfiles, minified files (`*.min.js`, `*.min.css`) and source maps (`*.map`) are not counted. Secret files (a name that starts with `.env`, ends in `.pem` or `.key`, or is an SSH key's) are never read.
+- Files larger than 1 MiB and binary files are skipped.
+- In both modes, the `=` a scan adds are recorded as one source-change batch.
+
+Example:
+
+```js
+const total = price + tax
+```
+
+If that line is new after `kitcode add .`, KitCode has not seen it before, and it passes the real-code-line check, its `=` counts toward the ledger.
+
+## Git Mode and Vibe Mode
+
+| Mode | When | What KitCode tracks |
+| --- | --- | --- |
+| Git Mode | Folder is inside a Git repository | Commit count, focus time, source-change batches |
+| Vibe Mode | Folder is not inside a Git repository | Focus time and source-change batches |
+
+Both modes count `=` by the same line rules. In Git Mode, KitCode reads only the files git lists (tracked, or untracked and not ignored), and code that arrives through git as it moves HEAD earns nothing and is not activity: a pull, a merge, a checkout of another branch, a rebase, a cherry-pick. Code git writes without moving HEAD, such as `git stash pop` or `git restore`, counts as yours. Your own new lines earn whether you commit them or not. The commit count is only reported: no reward depends on it.
+
+## Reward model
+
+The time target is fixed at `3600` active seconds: no flag or variable changes it.
+
+Each milestone needs both enough active time and enough counted `=`:
+
+- time target for a percent = `ceil(3600 * percent / 100)` seconds: 360 for 10%, 720 for 20%, 1080 for 30%, 1800 for 50%, and 3600 for 100%
+- equals target comes from the tier table below
+
+### Local reward tiers
+
+Their break codes are shown in the dashboard, which records a code as shown through `POST /api/reward/redeem`, on this machine only.
+
+| Tier | Code | Required counted `=` |
+| ---: | --- | ---: |
+| `10%` | `if(tired){return 10;}` | 3 |
+| `20%` | `takeBreak(20);` | 6 |
+| `30%` | `while(working)break(30);` | 9 |
+
+### Display milestones
+
+Shown in summary/awards/dashboard, but not redeemable unless backed by campaign flow.
+
+| Milestone | Code | Required counted `=` |
+| ---: | --- | ---: |
+| `50%` | `mediumStake.unlock(50);` | 12 |
+| `100%` | `finalBreak.claim(100);` | 15 |
+
+## Codex and Claude integrations
+
+The hosted gateway copies **agent-specific** setup prompts: Codex prompts mention only Codex; Claude prompts mention only Claude Code.
+
+`kitcode codex on` and `kitcode claude on` install:
+
+- a KitCode skill file
+- a `UserPromptSubmit` hook whose command runs the runner below: `~/.kitcode/bin/kitcode hook prompt --source <agent>` (on Windows, `node` with the runner's `kitcode.mjs`)
+- a durable local runner at `~/.kitcode/bin/kitcode`
+
+The hook:
+
+- runs after each submitted prompt
+- fails open and never blocks prompts
+- can add compact context: counted `=`, active time, next milestone progress, reward readiness
+- can announce newly ready tiers once per agent source
+
+Disable hooks with:
+
+```bash
+KITCODE_HOOKS_OFF=1
+```
+
+## Local state
+
+```txt
+~/.kitcode/state.json     Projects and their snapshots, onboarding prefs, focus time, equals ledger
+~/.kitcode/seen-lines     Every line KitCode has seen, as hashes: a line earns once
+~/.kitcode/install-id     A random id the claim bundle carries, made by the tracker
+~/.kitcode/tracker.json   Background tracker PID/host/port metadata
+~/.kitcode/tracker.log    The background tracker's log
+~/.kitcode/hook.log       Hook errors, when logging succeeds
+~/.kitcode/bin/kitcode    Durable runner used by agent hooks
+```
+
+## Privacy
+
+By default KitCode does not send:
+
+- source code
+- raw diffs
+- arbitrary file contents
+- full local paths
+- project names
+- commit metadata
+
+The local API returns totals only: active/idle time, project count, commit count, change batches, counted `=`, and reward progress, with the tracker's health. The claim bundle, which it gives an allowed origin alone, adds when each milestone was reached, the CLI's and the counting rules' versions, and the install id, which names no person, machine or project.
+
+## API
+
+```txt
+GET  /api/health
+GET  /api/summary
+GET  /api/projects
+GET  /api/events
+GET  /api/claim/bundle
+GET  /companion
+POST /api/reward/redeem
+```
+
+The API answers only requests addressed to `127.0.0.1` or `localhost` on its port, and web pages only from an allowed origin (below) or its own. `GET /api/claim/bundle` and `POST /api/reward/redeem` need an allowed origin, and the POST a JSON body.
+
+`/api/events` is SSE and emits `summary` every second.
+
+`POST /api/reward/redeem` accepts optional `{ "tier": 10 }`. If `tier` is omitted, all ready local tiers are redeemed.
+
+Legacy endpoints return `410 Gone`:
+
+```txt
+GET  /api/projects/:id/commits
+POST /api/projects/:id/start
+POST /api/projects/:id/stop
+POST /api/projects/selection
+```
+
+## Options and environment
+
+```bash
+kitcode track --host 127.0.0.1
+kitcode track --port 4757
+kitcode dashboard --no-open
+```
+
+| Variable | Effect |
+| --- | --- |
+| `KITCODE_ALLOWED_ORIGINS` | Extra CORS origins for the local API |
+| `KITCODE_NO_OPEN` | Skip auto-opening the hosted dashboard |
+| `KITCODE_HOOKS_OFF` | Disable prompt hook side effects |
+| `KITCODE_DAEMON` | Internal flag used by the background tracker |
+
+With nothing configured, the local API allows the origin of the dashboard `kitcode dashboard` opens, and local development servers on ports `3000`, `5173`, and `8686`, on `localhost` and `127.0.0.1`.
+
+## Requirements
+
+- Node.js 22.12 or later
+- Git optional (enables Git Mode)
+- Electron optional (required for native Mini and Welcome)
+
+## Releases
+
+Nobody runs `npm publish` for this package. A release comes from a pushed tag, `cli-v<version>`: the project's CI runs
+its checks on the tagged commit, packs the tarball from that commit, and stages it on npm with `npm stage publish`. A
+staged version becomes public only when a maintainer approves it with two-factor authentication. The package's first
+version is the one exception to CI's staging: a maintainer stages CI's tarball by hand, once, since npm lets CI stage
+only for a package that exists.
+
+Two dist-tags:
+
+| Dist-tag | Versions | Install |
+| --- | --- | --- |
+| `latest` | `<x>.<y>.<z>`, the version in `package.json` | `npm install -g @kitkat-vn/kitcode` |
+| `staging` | `<x>.<y>.<z>-staging.<N>`, the tester build of a tagged commit, for the invited testers of the staging round. Its dashboard is KitCode's protected staging site, which only they can open | `npm install -g @kitkat-vn/kitcode@staging` |
+
+No `latest` release exists yet.
+
+What each dist-tag points at now: `npm view @kitkat-vn/kitcode dist-tags`.