kata-context 0.1.0 → 0.2.0

package/.claude/hooks/kata-statusline.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Claude Code Statusline - Kata Plugin Edition
+// Shows: model | current task | directory | context usage
+
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+// Read JSON from stdin
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => (input += chunk));
+process.stdin.on("end", () => {
+  try {
+    const data = JSON.parse(input);
+    const model = data.model?.display_name || "Claude";
+    const dir = data.workspace?.current_dir || process.cwd();
+    const session = data.session_id || "";
+    const remaining = data.context_window?.remaining_percentage;
+
+    // Context window display (shows USED percentage)
+    let ctx = "";
+    if (remaining != null) {
+      const rem = Math.round(remaining);
+      const used = 100 - rem;
+
+      // Build progress bar (10 segments)
+      const filled = Math.floor(used / 10);
+      const bar = "\u2588".repeat(filled) + "\u2591".repeat(10 - filled);
+
+      // Color based on usage
+      if (used < 50) {
+        ctx = ` \x1b[32m${bar} ${used}%\x1b[0m`;
+      } else if (used < 65) {
+        ctx = ` \x1b[33m${bar} ${used}%\x1b[0m`;
+      } else if (used < 80) {
+        ctx = ` \x1b[38;5;208m${bar} ${used}%\x1b[0m`;
+      } else {
+        ctx = ` \x1b[5;31m\u{1F480} ${bar} ${used}%\x1b[0m`;
+      }
+    }
+
+    // Current task from todos
+    let task = "";
+    const homeDir = os.homedir();
+    const todosDir = path.join(homeDir, ".claude", "todos");
+    if (session && fs.existsSync(todosDir)) {
+      const files = fs
+        .readdirSync(todosDir)
+        .filter((f) => f.startsWith(session) && f.includes("-agent-") && f.endsWith(".json"))
+        .map((f) => ({ name: f, mtime: fs.statSync(path.join(todosDir, f)).mtime }))
+        .sort((a, b) => b.mtime - a.mtime);
+
+      if (files.length > 0) {
+        try {
+          const todos = JSON.parse(fs.readFileSync(path.join(todosDir, files[0].name), "utf8"));
+          const inProgress = todos.find((t) => t.status === "in_progress");
+          if (inProgress) task = inProgress.activeForm || "";
+        } catch (e) {}
+      }
+    }
+
+    // Kata update available?
+    let kataUpdate = "";
+    const currentDir = dir;
+
+    // For plugin installs, check the project-local cache
+    const cacheFile = path.join(currentDir, ".claude", "kata", "cache", "update-check.json");
+
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(cacheFile, "utf8"));
+
+        if (cache.update_available) {
+          // Plugin update message with version and both update methods
+          const latest = cache.latest || "new";
+          kataUpdate = `\x1b[33m⬆ v${latest}: /plugin (CC) or claude plugin update kata@kata-marketplace (term)\x1b[0m \u2502 `;
+        }
+      } catch (e) {}
+    }
+
+    // Output
+    const dirname = path.basename(dir);
+    if (task) {
+      process.stdout.write(
+        `${kataUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[1m${task}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`,
+      );
+    } else {
+      process.stdout.write(
+        `${kataUpdate}\x1b[2m${model}\x1b[0m \u2502 \x1b[2m${dirname}\x1b[0m${ctx}`,
+      );
+    }
+  } catch (e) {
+    // Silent fail - don't break statusline on parse errors
+  }
+});

package/.env.example

@@ -0,0 +1,6 @@
+# Database connection (use pooled endpoint with -pooler hostname)
+# Format: postgresql://user:password@ep-xxx-pooler.region.aws.neon.tech/dbname?sslmode=require
+DATABASE_URL=
+
+# Enable corepack for pnpm 10 in Vercel
+ENABLE_EXPERIMENTAL_COREPACK=1

package/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  HUSKY: 0  # Disable husky in CI (hooks not needed)
+
+jobs:
+  lint-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm run lint
+
+      - name: Test
+        run: pnpm run test:coverage

package/.github/workflows/claude-code-review.yml

@@ -0,0 +1,44 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+

package/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

package/.github/workflows/release.yml

@@ -54,7 +54,7 @@ jobs:
 
       - name: Publish to npm
         if: steps.check.outputs.should_publish == 'true'
-        run: npm publish --access public
+        run: npm publish --access public --ignore-scripts
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

package/.husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged

package/.planning/MILESTONES.md

@@ -0,0 +1,53 @@
+# Project Milestones: Kata Context
+
+## v0.2.0 Database + Storage Layer (Shipped: 2026-02-04)
+
+**Delivered:** PostgreSQL storage foundation with Drizzle ORM, repository abstraction, REST API, and 87 tests at 100% coverage.
+
+**Phases completed:** 3-5 (8 plans total)
+
+**Key accomplishments:**
+- PostgreSQL on Neon with pgvector, Drizzle ORM, serverless connection pooling
+- Type-safe schema for contexts (soft-delete, fork tracking) and messages (versioned, vector-ready)
+- Repository layer: ContextRepository and MessageRepository with token-budgeted windowing
+- REST API: 6 endpoints with Zod validation and RFC 9457 error format
+- 87 tests (40 repository + 26 unit + 21 integration) with 100% coverage enforcement
+- PGlite in-memory testing (no external database dependency)
+
+**Stats:**
+- 93 files created/modified
+- 4,279 lines of TypeScript
+- 3 phases, 8 plans, 23 requirements
+- 6 days from v0.1.0 to ship (Jan 29 - Feb 3)
+
+**Git range:** `v0.1.0` -> `8a50531`
+
+**What's next:** Policy engine with compaction, context forking, and semantic retrieval (v0.3.0)
+
+---
+
+## v0.1.0 Core Setup (Shipped: 2026-01-29)
+
+**Delivered:** TypeScript/Vercel project foundation with linting, testing, CI, and serverless infrastructure.
+
+**Phases completed:** 1-2 (4 plans total)
+
+**Key accomplishments:**
+- TypeScript 5.9 with strict mode and NodeNext module resolution
+- Biome 2.3 for linting and formatting with recommended rules
+- Vitest 4 for testing with passWithNoTests for clean CI
+- Husky v9 pre-commit hooks with lint-staged for automatic code validation
+- GitHub Actions CI pipeline running lint and test on push/PR
+- Vercel serverless health endpoint at `/api/health`
+
+**Stats:**
+- 39 files created/modified
+- 39 lines of TypeScript
+- 2 phases, 4 plans
+- 1 day from start to ship
+
+**Git range:** Initial commit -> `0fdbd5c`
+
+**What's next:** Database schema and context engine (v0.2.0)
+
+---

package/.planning/PROJECT.md

@@ -2,45 +2,63 @@
 
 ## What This Is
 
-A standalone context policy engine for AI agents. Manages what goes in and out of the LLM context window — compaction, summarization, retrieval, and budget-aware windowing. Framework-agnostic infrastructure: works with any agent system, or none.
+A standalone context policy engine for AI agents. Manages what goes in and out of the LLM context window with policy-based compaction, summarization, retrieval, and budget-aware windowing. Framework-agnostic infrastructure backed by PostgreSQL with pgvector. Works with any agent system, or none.
 
 ## Core Value
 
 Given messages and a context budget, determine the optimal window to send to the model. Policy, not storage.
 
-## Current Milestone: v0.1.0 Core Setup
+## Current State
 
-**Goal:** Establish project foundation with TypeScript/Vercel scaffolding, linting, and testing infrastructure.
+**Shipped:** v0.2.0 Database + Storage Layer (2026-02-04)
+- PostgreSQL on Neon with pgvector, Drizzle ORM, serverless connection pooling
+- Type-safe schema for contexts (soft-delete, fork tracking) and messages (versioned, vector-ready)
+- Repository layer: ContextRepository and MessageRepository with token-budgeted windowing
+- REST API: 6 endpoints with Zod validation and RFC 9457 error format
+- 87 tests with 100% coverage enforcement
+- 4,279 lines of TypeScript across 93 files
 
-**Target features:**
-- TypeScript project structure for Vercel serverless
-- Linting configuration (ESLint, Prettier)
-- Testing setup (Vitest or similar)
-- Development workflow (scripts, environment)
+**Previous:** v0.1.0 Core Setup (2026-01-29)
+- TypeScript/Vercel project foundation
+- Biome linting, Vitest testing, Husky pre-commit hooks
+- GitHub Actions CI pipeline
+- Vercel serverless health endpoint
 
 ## Requirements
 
 ### Validated
 
-(None yet — ship to validate)
+- TypeScript with strict mode and NodeNext -- v0.1.0
+- pnpm with lockfile -- v0.1.0
+- Build, test, lint, format scripts -- v0.1.0
+- Biome for linting/formatting -- v0.1.0
+- Vitest for testing -- v0.1.0
+- Pre-commit hooks with Husky -- v0.1.0
+- GitHub Actions CI -- v0.1.0
+- Vercel serverless structure -- v0.1.0
+- PostgreSQL with pgvector on Neon -- v0.2.0
+- Drizzle ORM with type-safe schema -- v0.2.0
+- Database migration workflow -- v0.2.0
+- Serverless connection pooling -- v0.2.0
+- Context CRUD operations (create, read, soft delete) -- v0.2.0
+- Message append with batch insert and versioning -- v0.2.0
+- Cursor-based message pagination -- v0.2.0
+- Token-budgeted windowing -- v0.2.0
+- REST API with Zod validation -- v0.2.0
+- 100% test coverage enforcement -- v0.2.0
 
 ### Active
 
 **Core Engine:**
 - [ ] Versioned context storage with full history
 - [ ] Basic compaction policy (configurable aggressiveness)
-- [ ] Budget-aware windowing (fit within token limit)
 - [ ] Context forking for exploration paths
 - [ ] Time-travel (jump to any version)
 
 **API & SDKs:**
-- [ ] Framework-agnostic REST API
 - [ ] Python SDK
 - [ ] TypeScript SDK
 
-**Storage:**
-- [ ] PostgreSQL with pgvector
-
 **Commercial MVP (1.0):**
 - [ ] Hosted API on Vercel (serverless)
 - [ ] Stripe integration for SaaS billing
@@ -54,34 +72,37 @@ Given messages and a context budget, determine the optimal window to send to the
 
 ### Out of Scope
 
-- **Full agent framework** — We're infrastructure (Postgres), not framework (Rails). Use with any agent system.
-- **Tool execution/sandboxing** — Orthogonal concern. Use whatever tool layer you want.
-- **Agent orchestration** — Kata Orchestrator handles this. We're the context layer beneath it.
-- **Opinionated agent patterns** — No opinion on how you build agents.
-- **Letta fork/rebrand** — Fresh codebase. Study Letta for learnings, don't import code.
+- **Full agent framework** -- Infrastructure (Postgres), not framework (Rails). Use with any agent system.
+- **Tool execution/sandboxing** -- Orthogonal concern. Use whatever tool layer you want.
+- **Agent orchestration** -- Kata Orchestrator handles this. We're the context layer beneath it.
+- **Opinionated agent patterns** -- No opinion on how you build agents.
+- **Letta fork/rebrand** -- Fresh codebase. Study Letta for learnings, don't import code.
 
 ## Context
 
 **Kata Ecosystem:**
-Kata Context is one layer in a vertically integrated stack. Kata Orchestrator is the first customer — currently uses markdown files in `.planning/` for state persistence. Works but is brittle (manual edits break workflows, parsing markdown is fragile). Kata Context replaces this with proper context management.
+Kata Context is one layer in a vertically integrated stack. Kata Orchestrator is the first customer -- currently uses markdown files in `.planning/` for state persistence. Works but is brittle (manual edits break workflows, parsing markdown is fragile). Kata Context replaces this with proper context management.
 
 **Why vertical integration:**
-1. Real requirements — not guessing what developers need. We are the developer.
-2. Proof of concept built-in — production multi-agent system running on Kata Context.
-3. Forces good design — if the API is awkward for Kata, it'll be awkward for everyone.
+1. Real requirements -- not guessing what developers need. We are the developer.
+2. Proof of concept built-in -- production multi-agent system running on Kata Context.
+3. Forces good design -- if the API is awkward for Kata, it'll be awkward for everyone.
 
 **Prior Art:**
-- Letta — Full agent framework with bundled memory. Learning source for context window calculation, summarization approaches. Not forking — context layer is coupled to their agent model.
-- mem0, Zep — Similar space, but more opinionated. We're lower-level infrastructure.
+- Letta -- Full agent framework with bundled memory. Learning source for context window calculation, summarization approaches. Not forking -- context layer is coupled to their agent model.
+- mem0, Zep -- Similar space, but more opinionated. We're lower-level infrastructure.
 
 **Competitive Positioning:**
 The context layer you'd build yourself, but shouldn't have to. Infrastructure, not framework. Works with everything.
 
+**Tech Stack (v0.2.0):**
+pnpm 10.x, Node.js 24.x, TypeScript 5.9.x, Biome 2.3.x, Vitest 4.x, Zod 4.x, Drizzle ORM 0.45.1, pg 8.14.1, Neon PostgreSQL with pgvector
+
 ## Constraints
 
 - **Tech stack**: Vercel ecosystem (serverless functions, Postgres via Neon with pgvector), TypeScript for server
-- **SDKs**: Python and TypeScript required — these are what developers actually use
-- **First customer**: Kata Orchestrator — API must support its workflows
+- **SDKs**: Python and TypeScript required -- these are what developers actually use
+- **First customer**: Kata Orchestrator -- API must support its workflows
 - **Solo developer**: One person building, so scope must stay tight
 - **Open source**: Public repo from day one, Apache 2.0 for core and SDKs
 
@@ -89,15 +110,27 @@ The context layer you'd build yourself, but shouldn't have to. Infrastructure, n
 
 | Decision | Rationale | Outcome |
 | -------- | --------- | ------- |
-| Standalone layer, not framework | Larger market, cleaner differentiation, smaller surface area | — Pending |
-| Fresh codebase, not Letta fork | Avoid rebrand complexity, build what we need | — Pending |
-| Vercel serverless deployment | Simplicity, TypeScript-native, scales automatically | — Pending |
-| PostgreSQL with pgvector | Battle-tested, embeddings built-in, Vercel Postgres available | — Pending |
-| TypeScript for server | Vercel-native, faster iteration than Rust, good enough perf for MVP | — Pending |
-| Open source from day one | Builds trust, consistency with other Kata projects, no awkward transition | — Pending |
-| Local beta first, then hosted MVP | Validate with self as customer before commercializing | — Pending |
-| Open core business model | Open source core for adoption, monetize hosted service | — Pending |
-| Small milestones (1-3 phases) | Shippable in a day, maintain momentum | — Pending |
+| Standalone layer, not framework | Larger market, cleaner differentiation, smaller surface area | Good |
+| Fresh codebase, not Letta fork | Avoid rebrand complexity, build what we need | Good |
+| Vercel serverless deployment | Simplicity, TypeScript-native, scales automatically | Good |
+| PostgreSQL with pgvector | Battle-tested, embeddings built-in, Vercel Postgres available | Good |
+| TypeScript for server | Vercel-native, faster iteration than Rust, good enough perf for MVP | Good |
+| Open source from day one | Builds trust, consistency with other Kata projects, no awkward transition | Good |
+| Local beta first, then hosted MVP | Validate with self as customer before commercializing | Pending |
+| Open core business model | Open source core for adoption, monetize hosted service | Pending |
+| Small milestones (1-3 phases) | Shippable in a day, maintain momentum | Good |
+| ESM with type: module | NodeNext resolution requires ESM; Vercel serverless expects ESM | Good |
+| Exact version pinning | Reproducible builds; avoids surprise breakage | Good |
+| Biome over ESLint/Prettier | Faster, simpler config, all-in-one tool | Good |
+| Web Standard APIs for Vercel | No SDK dependency; portable code; modern standard | Good |
+| Neon over Vercel Postgres | Vercel Postgres deprecated Q4 2024; Neon is the underlying provider | Good |
+| Drizzle over Prisma | Lighter weight, better serverless cold start, closer to SQL | Good |
+| pg driver over @neondatabase/serverless | Node.js serverless runtime, simpler driver model | Good |
+| Repository pattern | Clean data access abstraction, testable with PGlite | Good |
+| Soft delete for contexts | Preserve history, enable future undelete/audit | Good |
+| PGlite for testing | No external database dependency, fast in-memory tests | Good |
+| Zod v4 for validation | Type-safe API validation, zod/v4 import path for compatibility | Good |
+| RFC 9457 error format | Standard problem detail for API error responses | Good |
 
 ---
-*Last updated: 2025-01-29 after initialization*
+*Last updated: 2026-02-04 after v0.2.0 milestone*

package/.planning/STATE.md

@@ -1,45 +1,54 @@
 # State
 
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-02-04)
+
+**Core value:** Policy-based context window management for AI agents
+**Current focus:** Planning next milestone
+
 ## Current Position
 
-Phase: 1 of 2 (Foundation)
-Plan: 2 of 2 in phase
-Status: Phase complete
-Last activity: 2026-01-29 - Completed 01-02-PLAN.md
+Phase: v0.2.0 complete
+Plan: N/A
+Status: Ready for next milestone
+Last activity: 2026-02-04 -- v0.2.0 milestone complete
 
 ## Progress
 
 ```
-v0.1.0 Core Setup
-[#####-----] Phase 1: Foundation (2/2 plans complete)
-[----------] Phase 2: Automation and Deployment (0/? plans)
+v0.1.0 Core Setup - SHIPPED
+[##########] Phase 1: Foundation (2/2 plans complete)
+[##########] Phase 2: Automation and Deployment (2/2 plans complete)
+
+v0.2.0 Database + Storage Layer - SHIPPED
+[##########] Phase 3: Database Foundation (2/2 plans) - COMPLETE
+[##########] Phase 4: Repository Layer (2/2 plans) - COMPLETE
+[##########] Phase 5: API + Testing Layer (4/4 plans) - COMPLETE
 ```
 
 ## Accumulated Context
 
 ### Decisions Made
 
-| ID | Decision | Rationale | Phase |
-|----|----------|-----------|-------|
-| esm-module-type | type: module in package.json | NodeNext module resolution requires ESM; Vercel serverless expects ESM | 01-01 |
-| exact-versions | --save-exact for all dependencies | Reproducible builds; avoids surprise breakage from minor updates | 01-01 |
-| license | Apache-2.0 | Matches PROJECT.md open source constraint | 01-01 |
-| biome-2-organize-imports | Use assist.actions.source.organizeImports | Biome 2.x moved organize imports to assist section; old schema key invalid | 01-02 |
-| biome-ignore-claude | Exclude .claude directory with includes pattern | Claude Code hooks directory contains external JS files that fail lint | 01-02 |
-| vitest-pass-no-tests | Enable passWithNoTests option | Clean CI builds when no test files exist yet | 01-02 |
+See PROJECT.md Key Decisions table for cumulative record.
 
 ### Blockers
+
 (None)
 
+### TODOs
+
+(None -- milestone complete)
+
 ### Notes
-- First milestone - establishing project foundation
-- Kata Orchestrator is the first customer
-- Stack: pnpm 10.x, Node.js 24.x, TypeScript 5.9.x, Biome 2.3.x, Vitest 4.x
-- Engine warning on Node 23.6 is expected (project targets Node 24+)
-- Phase 1 Foundation complete: all developer workflow commands functional
+
+- v0.1.0 shipped with full developer workflow and CI infrastructure
+- v0.2.0 shipped with storage foundation, repository layer, and REST API
+- Stack: pnpm 10.x, Node.js 24.x, TypeScript 5.9.x, Biome 2.3.x, Vitest 4.x, Zod 4.x, Drizzle ORM 0.45.1, pg 8.14.1
 
 ## Session Continuity
 
-Last session: 2026-01-29 11:15 UTC
-Stopped at: Completed 01-02-PLAN.md (Phase 1 complete)
-Resume file: .planning/phases/02-automation/02-01-PLAN.md
+Last session: 2026-02-04
+Stopped at: v0.2.0 milestone complete
+Resume with: `/kata:kata-add-milestone` for v0.3.0