clawck 0.4.2 → 0.5.2

package/docs/versioning.md

@@ -0,0 +1,49 @@
+# Versioning Policy
+
+Clawck tracks three independent version numbers. Each serves a different purpose and follows its own release cadence.
+
+## App Version
+
+- **Constant:** `APP_VERSION` in `src/core/types.ts`, mirrored in `package.json` `"version"`
+- **Format:** Semantic versioning (`MAJOR.MINOR.PATCH`)
+- **Current:** `0.4.3`
+- **What it tracks:** The overall Clawck release — CLI, server, SDK, dashboard, reports
+- **When bumped:**
+  - MAJOR: Breaking API or config changes (not yet — still 0.x)
+  - MINOR: New features (e.g., patterns, approval workflow, HTML reports)
+  - PATCH: Bug fixes and small improvements
+- **Compatibility:** While in 0.x, minor versions may contain breaking changes. Upgrade notes are in `CHANGELOG.md`.
+
+## Spec Version
+
+- **Constant:** `SPEC_VERSION` in `src/core/types.ts`
+- **Format:** Semantic versioning (`MAJOR.MINOR.PATCH`)
+- **Current:** `0.2.0`
+- **What it tracks:** The ATP (Agent Time Protocol) wire format — the JSON envelope used for import/export and multi-agent sync
+- **When bumped:** When the ATP schema changes (new required fields, structural changes)
+- **Compatibility:** ATP envelopes include a `spec_version` field. Import accepts older spec versions. See `docs/atp-spec-v0.2.md` for the current spec.
+
+## Schema Version
+
+- **Constant:** `ClawckDB.SCHEMA_VERSION` in `src/core/database.ts`
+- **Format:** Integer, incrementing from 1
+- **Current:** `5`
+- **What it tracks:** The SQLite database schema — tables, columns, indexes
+- **When bumped:** Each time a migration is added to the `MIGRATIONS` array in `database.ts`
+- **Compatibility:** Migrations are **forward-only** and **auto-applied** — Clawck detects the current schema version on startup and runs any pending migrations in a transaction. There is no downgrade path. See `docs/migration-guide.md` for details.
+
+## Version Independence
+
+These three versions are independent. A single release may bump the app version without changing the spec or schema version. For example:
+
+| Release | App Version | Spec Version | Schema Version |
+|---------|-------------|--------------|----------------|
+| v0.1.0  | 0.1.0       | 0.1.0        | 1              |
+| v0.3.0  | 0.3.0       | 0.2.0        | 5              |
+| v0.4.1  | 0.4.1       | 0.2.0        | 5              |
+| v0.4.3  | 0.4.3       | 0.2.0        | 5              |
+
+## Known Limitations
+
+- **No API versioning prefix** — REST endpoints are served at `/api/*` with no version prefix (e.g., no `/api/v1/`). Breaking API changes will be communicated via changelog and app version bumps.
+- **No schema downgrade** — If you need to roll back Clawck to an older version, restore the database from a backup taken before the upgrade.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawck",
-  "version": "0.4.2",
+  "version": "0.5.2",
   "description": "⏱️🦀 Time tracking for AI agents. Toggl for the agentic era.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,7 +10,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsx watch src/cli/index.ts",
-    "start": "node dist/cli/index.ts",
+    "start": "node dist/cli/index.js",
     "serve": "tsx src/cli/index.ts serve",
     "test": "vitest run",
     "lint": "eslint src/",
@@ -39,12 +39,13 @@
   "dependencies": {
     "better-sqlite3": "^12.6.2",
     "commander": "^12.0.0",
-    "pdfkit": "^0.15.0",
     "cors": "^2.8.5",
     "express": "^4.21.0",
+    "pdfkit": "^0.15.0",
     "uuid": "^10.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@types/better-sqlite3": "^7.6.13",
     "@types/cors": "^2.8.0",
     "@types/express": "^4.17.0",
@@ -52,9 +53,11 @@
     "@types/pdfkit": "^0.13.0",
     "@types/supertest": "^7.2.0",
     "@types/uuid": "^10.0.0",
+    "eslint": "^10.0.3",
     "supertest": "^7.2.2",
     "tsx": "^4.0.0",
     "typescript": "^5.6.0",
+    "typescript-eslint": "^8.56.1",
     "vitest": "^2.0.0"
   },
   "engines": {