clawck 0.4.3 → 0.5.2

package/docs/api-reference.md

@@ -0,0 +1,380 @@
+# API Reference
+
+## Overview
+
+- **Base URL:** `http://localhost:3456` (default port, configurable via `--port` or `PORT` env var)
+- **Content-Type:** `application/json` for all request/response bodies
+- **Error format:** `{ "error": "description" }` with appropriate HTTP status code
+- **No API versioning prefix** — endpoints are at `/api/*` directly
+
+---
+
+## Health
+
+### GET /api/health
+
+Health check.
+
+**Response:** `200 OK`
+```json
+{ "status": "ok", "version": "0.4.3", "spec": "0.2.0" }
+```
+
+### GET /api/stats
+
+Quick database statistics.
+
+**Response:** `200 OK`
+```json
+{
+  "total_entries": 150,
+  "running": 2,
+  "clients": 5,
+  "projects": 12,
+  "agents": 3
+}
+```
+
+---
+
+## Time Tracking
+
+### POST /api/start
+
+Start tracking a task. Returns the created entry with a generated UUID.
+
+**Request body:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| task | string | yes | Task description |
+| project | string | no | Project name |
+| client | string | no | Client name |
+| category | string | no | One of: `research`, `content`, `code`, `data_entry`, `design`, `communication`, `analysis`, `testing`, `planning`, `other` |
+| agent | string | no | Agent identifier |
+| model | string | no | LLM model name |
+| tags | string[] | no | Arbitrary tags |
+
+**Response:** `201 Created` — full `ClawckEntry` object
+
+### POST /api/stop
+
+Stop a running task.
+
+**Request body:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | yes | Entry ID |
+| status | string | no | `completed` or `failed` (default: `completed`) |
+| summary | string | no | Summary of work done |
+| tokens_in | number | no | Input tokens consumed |
+| tokens_out | number | no | Output tokens generated |
+| cost_usd | number | no | Estimated cost in USD |
+| tool_calls | number | no | Number of tool calls made |
+
+**Response:** `200 OK` — updated `ClawckEntry` object
+**Error:** `404` if entry not found
+
+### POST /api/log
+
+Log a completed task retroactively (task already finished, recording it after the fact).
+
+**Request body:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| task | string | yes | Task description |
+| duration_minutes | number | yes | How long the task took |
+| project | string | no | Project name |
+| client | string | no | Client name |
+| category | string | no | Task category |
+| agent | string | no | Agent identifier |
+| model | string | no | LLM model name |
+| summary | string | no | Summary of work done |
+| tokens_in | number | no | Input tokens consumed |
+| tokens_out | number | no | Output tokens generated |
+| cost_usd | number | no | Estimated cost |
+| tags | string[] | no | Tags |
+
+**Response:** `201 Created` — full `ClawckEntry` object
+
+---
+
+## Entries
+
+### GET /api/entries
+
+Query entries with filters.
+
+**Query parameters:**
+| Param | Type | Description |
+|-------|------|-------------|
+| client | string | Filter by client |
+| project | string | Filter by project |
+| agent | string | Filter by agent |
+| category | string | Filter by category |
+| status | string | Filter by status (`running`, `completed`, `failed`, `paused`) |
+| from | string | Start date (ISO 8601) |
+| to | string | End date (ISO 8601) |
+| limit | number | Max entries (default: 500) |
+
+**Response:** `200 OK` — array of `ClawckEntry` objects
+
+### GET /api/entries/:id
+
+Get a single entry by ID.
+
+**Response:** `200 OK` — `ClawckEntry` object
+**Error:** `404` if not found
+
+### PATCH /api/entries/:id
+
+Update fields on an existing entry.
+
+**Request body:** Any subset of entry fields (task, project, client, category, status, summary, tokens_in, tokens_out, cost_usd, tool_calls, tags, agent, approved)
+
+**Response:** `200 OK` — updated `ClawckEntry` object
+**Error:** `404` if not found
+
+### POST /api/entries/:id/approve
+
+Mark an entry as approved.
+
+**Response:** `200 OK` — updated `ClawckEntry` object with `approved: true`
+**Error:** `404` if not found
+
+### GET /api/running
+
+Get all currently running entries.
+
+**Response:** `200 OK` — array of `ClawckEntry` objects with `status: "running"`
+
+---
+
+## Reporting
+
+### GET /api/timesheet
+
+Get a timesheet summary for a date range.
+
+**Query parameters:**
+| Param | Type | Description |
+|-------|------|-------------|
+| from | string | Start date (ISO 8601, default: 7 days ago) |
+| to | string | End date (ISO 8601, default: now) |
+| client | string | Filter by client |
+| project | string | Filter by project |
+| agent | string | Filter by agent |
+
+**Response:** `200 OK` — `TimesheetSummary` object with aggregated stats, breakdowns by client/agent/project/category, and individual rows
+
+### POST /api/reports/generate
+
+Generate a report (terminal JSON, HTML, or PDF).
+
+**Request body:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| period | string | no | `day`, `week`, `month`, `year`, `custom` |
+| from | string | no | Start date (ISO 8601) |
+| to | string | no | End date (ISO 8601) |
+| days | number | no | Number of days back from now |
+| style | string | no | `full`, `short`, `visual`, `text`, `table`, `calendar` (default: `full`) |
+| format | string | no | `terminal`, `html`, `pdf` (default: `terminal`) |
+| filters | object | no | `{ client?, project?, agent? }` |
+| name | string | no | Report name (for saved reports) |
+| save | boolean | no | Whether to save the report to the database |
+
+**Response:** `200 OK`
+- For `pdf` format without `save`: raw PDF binary with `Content-Type: application/pdf`
+- Otherwise: `{ "content": "...", "metadata": { ... } }` (plus `"id"` if saved)
+
+### GET /api/reports
+
+List saved reports.
+
+**Query parameters:**
+| Param | Type | Description |
+|-------|------|-------------|
+| limit | number | Max results (default: 50) |
+| offset | number | Pagination offset (default: 0) |
+
+**Response:** `200 OK` — array of `StoredReport` objects (without content)
+
+### GET /api/reports/:id
+
+Get a saved report by ID (without content blob).
+
+**Response:** `200 OK` — `StoredReport` object
+**Error:** `404` if not found
+
+### DELETE /api/reports/:id
+
+Delete a saved report.
+
+**Response:** `200 OK` — `{ "ok": true }`
+**Error:** `404` if not found
+
+---
+
+## Baselines
+
+### GET /api/baselines
+
+List all personal baselines.
+
+**Response:** `200 OK` — array of `PersonalBaseline` objects
+
+### POST /api/baselines
+
+Create a personal baseline.
+
+**Request body:**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| category | string | yes | Task category |
+| task_type | string | yes | Task type label |
+| description | string | no | Description |
+| my_minutes | number | yes | Your personal time for this task type |
+
+**Response:** `201 Created` — `PersonalBaseline` object
+
+### DELETE /api/baselines/:id
+
+Delete a personal baseline.
+
+**Response:** `200 OK` — `{ "ok": true }`
+**Error:** `404` if not found
+
+### GET /api/compare/:entryId
+
+Compare an entry against industry and personal benchmarks.
+
+**Response:** `200 OK` — comparison object with benchmark data
+**Error:** `404` if entry not found
+
+---
+
+## Import/Export
+
+### GET /api/export/atp
+
+Export entries as an ATP (Agent Time Protocol) envelope.
+
+**Query parameters:**
+| Param | Type | Description |
+|-------|------|-------------|
+| from | string | Start date (default: 7 days ago) |
+| to | string | End date (default: now) |
+
+**Response:** `200 OK` — ATP JSON envelope (see `docs/atp-spec-v0.2.md`)
+
+### POST /api/import/atp
+
+Import entries from an ATP envelope.
+
+**Request body:** ATP JSON envelope
+
+**Response:** `200 OK` — `{ "ingested": 10, "total": 12 }`
+
+### POST /api/ingest
+
+Bulk import/merge entries. Entries are upserted by UUID — duplicates are updated, new entries are created.
+
+**Request body:** Single `ClawckEntry` object or array of entries
+
+**Response:** `200 OK` — `{ "ingested": 5, "total": 5 }`
+
+---
+
+## Sync
+
+### GET /api/sync/status
+
+Get sync status for configured remote sources.
+
+**Response:** `200 OK`
+```json
+{ "enabled": true, "states": [{ "source_name": "...", "last_sync_at": "...", "last_status": "success", "entries_synced": 42 }] }
+```
+
+### POST /api/sync/trigger
+
+Manually trigger a sync from all remote sources.
+
+**Response:** `200 OK` — `{ "states": [...] }`
+**Error:** `400` if no remote sources configured
+
+---
+
+## Filter Options
+
+### GET /api/clients
+
+List distinct client names.
+
+**Response:** `200 OK` — `["acme-corp", "internal"]`
+
+### GET /api/projects
+
+List distinct project names.
+
+**Response:** `200 OK` — `["website-rebuild", "grant-research"]`
+
+### GET /api/agents
+
+List distinct agent identifiers.
+
+**Response:** `200 OK` — `["claude-agent", "research-bot"]`
+
+---
+
+## ClawckEntry Object
+
+The core data model returned by most endpoints:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "agent": "research-agent-01",
+  "model": "claude-sonnet-4-20250514",
+  "client": "acme-corp",
+  "project": "grant-research",
+  "task": "Research NEA grant opportunities",
+  "category": "research",
+  "start": "2026-03-08T10:00:00.000Z",
+  "end": "2026-03-08T10:05:30.000Z",
+  "status": "completed",
+  "tokens_in": 25000,
+  "tokens_out": 3500,
+  "cost_usd": 0.12,
+  "tool_calls": 8,
+  "summary": "Found 12 matching grants",
+  "tags": ["grants", "nea"],
+  "source": "mcp",
+  "spec_version": "0.2.0",
+  "created_at": "2026-03-08T10:00:00.000Z",
+  "updated_at": "2026-03-08T10:05:30.000Z",
+  "approved": false,
+  "agent_runtime_ms": 15200,
+  "wall_clock_ms": 330000
+}
+```
+
+---
+
+## MCP Tools
+
+Clawck's MCP server (started via `clawck mcp`) exposes these tools over stdio:
+
+| Tool | Required Inputs | Description |
+|------|----------------|-------------|
+| `clawck_start_task` | `task` | Start tracking a task |
+| `clawck_stop_task` | `id` | Stop a running task |
+| `clawck_log_task` | `task`, `duration_minutes` | Log completed work retroactively |
+| `clawck_status` | (none) | Get running entries and stats |
+| `clawck_timesheet` | (none) | Get timesheet summary (defaults to last 7 days) |
+| `clawck_get_entry` | `id` | Get a single entry |
+| `clawck_query_entries` | (none) | Query entries with filters |
+| `clawck_update_entry` | `id` | Update an existing entry |
+| `clawck_list_metadata` | `type` | List clients, projects, or agents |
+
+All tools return JSON with an `ok` boolean. See `src/server/mcp.ts` for full input schemas.

package/docs/deployment.md

@@ -0,0 +1,140 @@
+# Deployment Guide
+
+## Local Development
+
+```bash
+# Watch mode (auto-recompile on changes)
+npm run dev
+
+# Start the server directly via tsx
+npm run serve
+
+# Run tests
+npm test
+```
+
+## Production Deployment
+
+### Build and Run
+
+```bash
+npm run build          # Compile TypeScript to dist/
+npm start              # Run dist/cli/index.js
+# or
+clawck serve --port 3456
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CLAWCK_DIR` | Path to the data directory | `.clawck` (relative to cwd) |
+| `PORT` | Server port (can also use `--port` flag) | `3456` |
+
+### systemd Example
+
+```ini
+[Unit]
+Description=Clawck Time Tracking Server
+After=network.target
+
+[Service]
+Type=simple
+User=clawck
+WorkingDirectory=/opt/clawck
+Environment=CLAWCK_DIR=/opt/clawck/data
+ExecStart=/usr/bin/node /opt/clawck/dist/cli/index.js serve --port 3456
+Restart=on-failure
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### pm2 Example
+
+```bash
+pm2 start dist/cli/index.js --name clawck -- serve --port 3456
+pm2 save
+```
+
+## Data Directory Structure
+
+The data directory (default `.clawck/`, override with `CLAWCK_DIR` or `-d` flag) contains:
+
+```
+.clawck/
+  clawck.db           # SQLite database (all entries, baselines, reports, sync state)
+  config.json         # Configuration file
+  hooks/
+    sessions/         # Hook session state files (JSON, one per active session)
+    hook-errors.log   # Append-only log of hook processing errors
+```
+
+### Database File
+
+`clawck.db` is a standard SQLite database. It uses WAL mode (`journal_mode = WAL`), which creates two additional files during operation:
+
+- `clawck.db-wal` — Write-Ahead Log
+- `clawck.db-shm` — Shared memory file
+
+These are normal and are managed automatically by SQLite. Do not delete them while the server is running.
+
+### Database Pragmas
+
+- **`journal_mode = WAL`** — Enables concurrent reads while writing. Multiple processes can read the database simultaneously, but only one can write at a time.
+- **`synchronous = NORMAL`** — In WAL mode, this provides good durability without the performance cost of `FULL`. Data is safe against application crashes; a power loss during a write could lose the most recent transaction.
+
+## Backup and Restore
+
+### File Copy (Simplest)
+
+Stop the server and copy the database file:
+
+```bash
+# Stop clawck first, then:
+cp .clawck/clawck.db .clawck/clawck.db.bak
+```
+
+### SQLite .backup (While Running)
+
+If you cannot stop the server, use SQLite's built-in backup command:
+
+```bash
+sqlite3 .clawck/clawck.db ".backup '/path/to/backup/clawck.db'"
+```
+
+This creates a consistent snapshot even while the database is in use.
+
+### ATP Export (Portable)
+
+Export entries as a JSON envelope for platform-independent backup:
+
+```bash
+# Via CLI
+clawck export --format json --days 365 > backup.json
+
+# Via API
+curl http://localhost:3456/api/export/atp?from=2025-01-01T00:00:00Z > backup-atp.json
+```
+
+Import into a new instance:
+
+```bash
+curl -X POST http://localhost:3456/api/import/atp \
+  -H "Content-Type: application/json" \
+  -d @backup-atp.json
+```
+
+### Automated Backup (cron)
+
+```bash
+# Daily backup at 2 AM
+0 2 * * * sqlite3 /opt/clawck/data/clawck.db ".backup '/opt/clawck/backups/clawck-$(date +\%Y\%m\%d).db'"
+```
+
+### Restore
+
+1. Stop the server
+2. Replace `clawck.db` with the backup file
+3. Delete any stale `-wal` and `-shm` files
+4. Start the server — migrations will auto-apply if the backup is from an older version

package/docs/deprecation-policy.md

@@ -0,0 +1,32 @@
+# Deprecation Policy
+
+## During 0.x (current)
+
+- Breaking changes may happen in **minor** versions (e.g., 0.5.0 → 0.6.0)
+- All breaking changes are documented in [CHANGELOG.md](../CHANGELOG.md)
+- Experimental features (labeled in README) may change without notice
+
+## Post 1.0 (planned)
+
+- Breaking changes require a **major** version bump
+- Deprecated features receive at least **1 minor version** deprecation notice before removal
+- Deprecation notices appear in:
+  - CHANGELOG.md
+  - Console warnings at runtime (via structured logger)
+
+## Config Keys
+
+- Deprecated config keys will log a warning for **2 minor versions** before removal
+- The warning includes the replacement key/approach
+
+## Experimental Features
+
+Features labeled "Experimental" in the README:
+- May change behavior, API shape, or be removed without a deprecation cycle
+- Current experimental features: webhooks, multi-agent sync, pricing estimation
+
+## Stable Surface
+
+Features labeled "Stable" in the README:
+- Will follow the deprecation policy above
+- Current stable surfaces: CLI commands, REST API, MCP tools, SQLite storage, ATP export/import

package/docs/migration-guide.md

@@ -0,0 +1,78 @@
+# Migration Guide
+
+## Database Schema Migrations
+
+Clawck uses a versioned migration system to evolve the SQLite schema. Migrations run automatically on startup — no manual steps required.
+
+### How It Works
+
+1. A `schema_version` table stores a single integer indicating the current version.
+2. On startup, Clawck compares the stored version against `ClawckDB.SCHEMA_VERSION`.
+3. Any pending migrations run inside a single transaction — all-or-nothing.
+4. Legacy databases (created before the migration system) are auto-detected: Clawck probes for columns and tables to infer the correct starting version.
+
+### Migration Table
+
+| Version | Added In | What It Does |
+|---------|----------|--------------|
+| 1 | v0.1.0 | Initial schema: `entries` table with all core columns, `sync_state` table, indexes on agent/client/project/status/start |
+| 2 | v0.3.0 | Adds `approved` column (INTEGER, default 0) to `entries` |
+| 3 | v0.3.0 | Adds `agent_runtime_ms` and `wall_clock_ms` columns (INTEGER, nullable) to `entries` |
+| 4 | v0.3.0 | Creates `personal_baselines` table (id, category, task_type, description, my_minutes, timestamps) |
+| 5 | v0.3.0 | Creates `reports` table (id, name, period, period_start, period_end, style, format, content BLOB, metadata, created_at) with index on created_at |
+
+### Checking the Current Version
+
+**Programmatically:**
+
+```typescript
+const db = new ClawckDB(config);
+console.log(db.getSchemaVersion()); // e.g., 5
+```
+
+**Via SQLite directly:**
+
+```bash
+sqlite3 .clawck/clawck.db "SELECT version FROM schema_version"
+```
+
+### Database Pragmas
+
+Clawck sets these pragmas on every connection:
+
+- `journal_mode = WAL` — Write-Ahead Logging for better concurrent read performance
+- `synchronous = NORMAL` — Balances durability with write speed (safe for WAL mode)
+
+## Upgrading Between Releases
+
+### General Upgrade Steps
+
+1. Stop the running Clawck server
+2. Pull the new version (`npm update -g clawck` or `git pull && npm install`)
+3. Build (`npm run build`)
+4. Start the server (`clawck serve` or `npm start`)
+
+Migrations run automatically on first startup after upgrade. No manual database changes needed.
+
+### Version-Specific Notes
+
+#### v0.1.0 to v0.3.0
+
+- **4 new migrations** (2–5) will auto-apply. The `entries` table gains three new columns (`approved`, `agent_runtime_ms`, `wall_clock_ms`), and two new tables (`personal_baselines`, `reports`) are created.
+- **Spec version changed** from 0.1.0 to 0.2.0. New entries use the updated spec. Existing entries retain their original `spec_version` value.
+- **New config fields** available: `patterns`, `default_pattern`, `runtime_estimation`, `use_industry_benchmarks`, `personal_rate_usd`. All are optional with sensible defaults.
+
+#### v0.3.0 to v0.4.x
+
+- No schema changes (still version 5).
+- Bug fixes to hook handling, CLI output, and runtime calculation.
+- The `--verbose` flag was added to CLI commands.
+
+### Rollback
+
+There is no automated downgrade path. To roll back:
+
+1. Stop Clawck
+2. Restore the database file from a backup taken before the upgrade (see `docs/deployment.md` for backup guidance)
+3. Install the older version of Clawck
+4. Start the server

package/docs/security.md

@@ -0,0 +1,70 @@
+# Security
+
+This document describes Clawck's current security posture. Clawck is designed as a local/trusted-network tool — it does not include built-in authentication or authorization.
+
+## Authentication
+
+**Clawck has no built-in authentication.** The REST API and dashboard are open to anyone who can reach the server. This is by design for local development use.
+
+If you expose Clawck beyond localhost, place it behind a reverse proxy with authentication:
+
+```nginx
+# nginx example
+server {
+    listen 443 ssl;
+    server_name clawck.internal.example.com;
+
+    # Add your auth method (basic auth, OAuth proxy, etc.)
+    auth_basic "Clawck";
+    auth_basic_user_file /etc/nginx/.htpasswd;
+
+    location / {
+        proxy_pass http://127.0.0.1:3456;
+    }
+}
+```
+
+## CORS
+
+CORS is wide open by default (`cors()` with no restrictions). All origins, methods, and headers are allowed. To restrict this, you would need to modify `src/server/api.ts` and pass a configuration object to the `cors()` middleware.
+
+## Input Handling
+
+- **SQL injection:** All database queries use prepared statements via better-sqlite3. No string interpolation is used in SQL.
+- **JSON validation:** Express `express.json()` middleware parses request bodies. Invalid JSON returns a 400 error.
+- **Entry IDs:** UUIDs are generated via the `uuid` package (v4). ID prefix lookups use parameterized `LIKE` queries.
+
+## Hook System
+
+- **Execution context:** Platform hooks (`clawck hook start`, `clawck hook stop`) run as CLI commands in the calling process's context — they inherit the user's permissions and environment.
+- **Session files:** Hook state is stored as JSON files in `.clawck/hooks/sessions/`. These are local to the data directory and are read/written by the CLI process.
+- **Error logging:** Hook errors are appended to `.clawck/hooks/hook-errors.log`. This file grows without rotation — monitor its size in long-running deployments.
+
+## MCP Server
+
+The MCP server runs on stdio (stdin/stdout) and inherits the trust model of the parent process. It does not open network ports. The parent process (e.g., Claude Code, Cursor) controls access.
+
+## Data Sensitivity
+
+Time entries may contain:
+- **Task descriptions** — can include sensitive project names, client names, or work details
+- **Cost data** — token usage and estimated USD costs
+- **Agent identifiers** — which models and agents are being used
+
+The SQLite database file (`.clawck/clawck.db`) contains all of this data. Treat it with the same care as any business data.
+
+## Webhooks
+
+Webhook payloads are sent via HTTP POST to configured URLs. Payloads include entry details (task, client, project, cost). If webhook URLs point to external services, entry data leaves your network. Configure webhook URLs to trusted endpoints only.
+
+## Summary
+
+| Area | Status |
+|------|--------|
+| Authentication | None — use a reverse proxy if exposed |
+| Authorization | None — all API endpoints are open |
+| CORS | Open to all origins |
+| SQL injection | Protected (prepared statements) |
+| Transport encryption | None — use a reverse proxy with TLS |
+| MCP | stdio-based, inherits parent trust |
+| Data at rest | Unencrypted SQLite file |