@jamesaphoenix/tx 0.4.2 → 0.4.4

package/README.md

@@ -0,0 +1,309 @@
+# tx
+
+**Primitives, not frameworks.** Headless infrastructure for AI agents.
+
+Memory, tasks, and orchestration — you own the loop.
+
+```bash
+# CLI (global install)
+npm install -g @jamesaphoenix/tx-cli
+
+# Library (project dependency)
+npm install @jamesaphoenix/tx
+```
+
+---
+
+## The Problem
+
+Your agents lose context between sessions. Tasks collide when multiple agents work in parallel. Learnings vanish into conversation history. You're rebuilding the same infrastructure every project.
+
+## The Solution
+
+Composable primitives that handle the hard parts. You keep control of the orchestration.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Your Orchestration (your code, your rules)             │
+├─────────────────────────────────────────────────────────┤
+│  tx primitives                                          │
+│                                                         │
+│   tx ready     tx done      tx context    tx learn      │
+│   tx claim     tx block     tx sync       tx trace      │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Primitives
+
+### Memory
+
+Learnings that persist and surface when relevant.
+
+```bash
+# Store knowledge
+tx learning:add "Use bcrypt for passwords, not SHA256"
+tx learning:add "Redis cache invalidation has race conditions" -c database
+
+# Attach learnings to file paths
+tx learn "src/auth/*.ts" "Services must use Effect-TS patterns"
+
+# Retrieve via search or task context
+tx learning:search "authentication"
+tx context tx-abc123  # Get relevant learnings for a task
+tx recall "src/auth/hash.ts"  # Recall learnings for a file
+```
+
+Hybrid search (BM25 + vector with RRF fusion) finds relevant knowledge.
+
+### Tasks
+
+Dependency-aware task management. Agents only see work they can actually do.
+
+```bash
+# Create with dependencies
+tx add "Implement auth service" --score 800
+tx add "Design auth schema" --score 900
+tx block tx-impl tx-schema  # impl waits for schema
+
+# Work on what's ready
+tx ready                    # Only unblocked tasks
+tx done tx-schema           # Completes → unblocks dependents
+```
+
+Full hierarchy support. Epics contain milestones contain tasks contain subtasks.
+
+### Coordination
+
+Lease-based claims prevent parallel agents from colliding.
+
+```bash
+tx claim tx-abc123 worker-1          # Claim with 30-min lease
+tx claim tx-abc123 worker-1 --lease 60  # Custom lease duration
+tx claim:renew tx-abc123 worker-1    # Extend lease
+tx claim:release tx-abc123 worker-1  # Release early
+```
+
+### Attempts
+
+Track what approaches have been tried on a task.
+
+```bash
+tx try tx-abc123 "Used Redux" --failed "Too complex for this use case"
+tx try tx-abc123 "Used Zustand" --succeeded
+tx attempts tx-abc123  # See all attempts
+```
+
+### Docs
+
+Structured documentation as primitives. YAML-based with versioning, locking, and linking.
+
+```bash
+tx doc add prd auth-system --title "Auth System PRD"
+tx doc render           # Generate markdown from YAML
+tx doc lock auth-system # Lock doc (immutable)
+tx doc link auth-prd auth-dd  # Link PRD to DD
+tx doc drift            # Detect stale docs
+```
+
+### Invariants
+
+Track and verify project invariants across sessions.
+
+```bash
+tx invariant list                          # List all invariants
+tx invariant show INV-001                  # Show details
+tx invariant record INV-001 --passed       # Record check result
+tx invariant sync                          # Sync from CLAUDE.md
+```
+
+### Cycle Scan
+
+Sub-agent swarm scanning for codebase analysis.
+
+```bash
+tx cycle --task-prompt "Review auth" --scan-prompt "Find bugs"
+```
+
+---
+
+## Your Loop, Your Rules
+
+We ship **example loops**, not **the loop**:
+
+```bash
+# Simple: one agent, one task
+while task=$(tx ready --limit 1 --json | jq -r '.[0].id'); do
+  claude "Work on task $task, then run: tx done $task"
+done
+```
+
+```bash
+# Parallel: N agents with claims
+for i in {1..5}; do
+  (while task=$(tx ready --json --limit 1 | jq -r '.[0].id // empty'); do
+    [ -z "$task" ] && break
+    tx claim "$task" "worker-$i" || continue
+    claude "Complete $task" && tx done "$task"
+  done) &
+done
+wait
+```
+
+```bash
+# Human-in-loop: agent proposes, human approves
+task=$(tx ready --json --limit 1 | jq -r '.[0].id')
+claude "Plan implementation for $task" > plan.md
+read -p "Approve? [y/n] " && claude "Execute plan.md"
+tx done $task
+```
+
+**The flow is yours.** Serial, parallel, swarm, human-in-loop. Your call.
+
+---
+
+## TypeScript SDK
+
+This package (`@jamesaphoenix/tx`) is the library entry point. It re-exports everything from `@jamesaphoenix/tx-core` plus convenience helpers.
+
+```typescript
+import { TaskService, LearningService, makeAppLayer } from "@jamesaphoenix/tx";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const tasks = yield* TaskService;
+  const ready = yield* tasks.getReady({ limit: 5 });
+  return ready;
+});
+
+// Run with the default layer (SQLite-backed)
+const layer = makeAppLayer(".tx/tasks.db");
+await Effect.runPromise(program.pipe(Effect.provide(layer)));
+```
+
+For a Promise-based HTTP client, use the Agent SDK:
+
+```typescript
+import { TxClient } from "@jamesaphoenix/tx-agent-sdk";
+
+const tx = new TxClient({ apiUrl: "http://localhost:3456" });
+const ready = await tx.tasks.ready({ limit: 10 });
+```
+
+---
+
+## Why tx?
+
+|  | Native Tasks | CLAUDE.md | tx |
+|---|---|---|---|
+| **Persistence** | Session-scoped | File grows forever | Git-native, branch-aware |
+| **Multi-agent** | Collisions | Manual coordination | Claim with lease expiry |
+| **Knowledge** | Lost each session | Static dump | Hybrid search, contextual retrieval |
+| **Orchestration** | None | None | Primitives for any pattern |
+
+---
+
+## Design Principles
+
+- **No opinions on orchestration.** Serial, parallel, swarm, human-in-loop. Your call.
+- **Powerful defaults.** `tx ready` just works. So does dependency resolution.
+- **Escape hatches everywhere.** Raw SQL access, JSONL export, custom scoring.
+- **Framework agnostic.** CLI, MCP, REST API, TypeScript SDK. Use what fits.
+- **Local-first.** SQLite + git. No server required. Works offline.
+
+---
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@jamesaphoenix/tx`](https://www.npmjs.com/package/@jamesaphoenix/tx) | Library entry point (this package) |
+| [`@jamesaphoenix/tx-cli`](https://www.npmjs.com/package/@jamesaphoenix/tx-cli) | CLI binary (`tx` command) |
+| [`@jamesaphoenix/tx-core`](https://www.npmjs.com/package/@jamesaphoenix/tx-core) | Core services (Effect-TS) |
+| [`@jamesaphoenix/tx-types`](https://www.npmjs.com/package/@jamesaphoenix/tx-types) | Shared type definitions |
+| [`@jamesaphoenix/tx-agent-sdk`](https://www.npmjs.com/package/@jamesaphoenix/tx-agent-sdk) | Promise-based HTTP client |
+| [`@jamesaphoenix/tx-mcp-server`](https://www.npmjs.com/package/@jamesaphoenix/tx-mcp-server) | MCP server (42 tools) |
+| [`@jamesaphoenix/tx-api-server`](https://www.npmjs.com/package/@jamesaphoenix/tx-api-server) | REST API server |
+
+---
+
+## Interfaces
+
+| Interface | Use Case |
+|-----------|----------|
+| **CLI** | Scripts, terminal workflows, agent loops |
+| **MCP Server** | Claude Code integration (42 tools) |
+| **REST API** | Custom dashboards, external integrations |
+| **TypeScript SDK** | Programmatic access from your agents |
+| **Dashboard** | Visual monitoring and management |
+
+---
+
+## Quick Reference
+
+```bash
+# Tasks
+tx add <title>              # Create task
+tx list                     # List all tasks
+tx ready                    # List unblocked tasks
+tx show <id>                # View details
+tx update <id>              # Update task fields
+tx done <id>                # Complete task
+tx delete <id>              # Delete task
+tx block <id> <blocker>     # Add dependency
+tx tree <id>                # Show hierarchy
+
+# Context & Learnings
+tx learning:add <content>   # Store knowledge
+tx learning:search <query>  # Search learnings
+tx context <task-id>        # Contextual retrieval
+tx learn <path> <note>      # Attach to file
+tx recall [path]            # Query by file
+
+# Coordination
+tx claim <id> <worker>      # Lease-based claim
+tx claim:renew <id> <worker>  # Extend lease
+tx claim:release <id> <worker>  # Release early
+tx try <id> <approach>      # Record attempt
+
+# Docs & Invariants
+tx doc add <type> <slug>    # Create doc
+tx doc render               # Generate markdown
+tx invariant list           # List invariants
+tx invariant sync           # Sync from CLAUDE.md
+
+# Sync
+tx sync export              # SQLite → JSONL (git-friendly)
+tx sync import              # JSONL → SQLite
+tx sync claude --team <name>  # Push to Claude Code team
+
+# Traces & Utilities
+tx cycle                    # Sub-agent swarm scan
+tx trace list               # Recent runs
+tx stats                    # Queue metrics
+tx doctor                   # System diagnostics
+tx dashboard                # Launch dashboard
+```
+
+---
+
+## Storage
+
+```
+.tx/
+├── tasks.db           # SQLite (gitignored)
+├── tasks.jsonl        # Git-tracked
+├── learnings.jsonl    # Git-tracked
+├── runs.jsonl         # Git-tracked
+└── docs/              # YAML doc sources
+```
+
+Local SQLite for speed. JSONL for git sync. Branch your knowledge with your code.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -36,6 +36,6 @@
  */
 export * from "@jamesaphoenix/tx-core";
 export { createTx, type CreateTxOptions, type TxClient } from "./create-tx.js";
-export type { TaskStatus, TaskId, Task, TaskWithDeps, TaskTree, TaskDependency, CreateTaskInput, UpdateTaskInput, TaskFilter, LearningSourceType, LearningId, Learning, LearningWithScore, CreateLearningInput, UpdateLearningInput, LearningQuery, ContextOptions, ContextResult, RetrievalOptions, AttemptOutcome, AttemptId, Attempt, CreateAttemptInput, RunId, RunStatus, Run, CreateRunInput, UpdateRunInput, AnchorId, AnchorType, AnchorStatus, Anchor, CreateAnchorInput, EdgeId, NodeType, EdgeType, Edge, CreateEdgeInput, } from "@jamesaphoenix/tx-types";
-export { TASK_STATUSES, VALID_TRANSITIONS, LEARNING_SOURCE_TYPES, ATTEMPT_OUTCOMES, RUN_STATUSES, ANCHOR_TYPES, ANCHOR_STATUSES, NODE_TYPES, EDGE_TYPES, } from "@jamesaphoenix/tx-types";
+export type { TaskStatus, TaskId, Task, TaskWithDeps, TaskTree, TaskDependency, CreateTaskInput, UpdateTaskInput, TaskFilter, LearningSourceType, LearningId, Learning, LearningWithScore, CreateLearningInput, UpdateLearningInput, LearningQuery, ContextOptions, ContextResult, RetrievalOptions, AttemptOutcome, AttemptId, Attempt, CreateAttemptInput, RunId, RunStatus, Run, CreateRunInput, UpdateRunInput, } from "@jamesaphoenix/tx-types";
+export { TASK_STATUSES, VALID_TRANSITIONS, LEARNING_SOURCE_TYPES, ATTEMPT_OUTCOMES, RUN_STATUSES, } from "@jamesaphoenix/tx-types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,cAAc,wBAAwB,CAAC;AAGvC,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG/E,YAAY,EAEV,UAAU,EACV,MAAM,EACN,IAAI,EACJ,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,eAAe,EACf,eAAe,EACf,UAAU,EAEV,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,aAAa,EACb,gBAAgB,EAEhB,cAAc,EACd,SAAS,EACT,OAAO,EACP,kBAAkB,EAElB,KAAK,EACL,SAAS,EACT,GAAG,EACH,cAAc,EACd,cAAc,EAEd,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,MAAM,EACN,iBAAiB,EAEjB,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,eAAe,GAChB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,UAAU,GACX,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,cAAc,wBAAwB,CAAC;AAGvC,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG/E,YAAY,EAEV,UAAU,EACV,MAAM,EACN,IAAI,EACJ,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,eAAe,EACf,eAAe,EACf,UAAU,EAEV,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,aAAa,EACb,gBAAgB,EAEhB,cAAc,EACd,SAAS,EACT,OAAO,EACP,kBAAkB,EAElB,KAAK,EACL,SAAS,EACT,GAAG,EACH,cAAc,EACd,cAAc,GACf,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,GACb,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -39,5 +39,5 @@ export * from "@jamesaphoenix/tx-core";
 // Export createTx and related types
 export { createTx } from "./create-tx.js";
 // Re-export constants from types
-export { TASK_STATUSES, VALID_TRANSITIONS, LEARNING_SOURCE_TYPES, ATTEMPT_OUTCOMES, RUN_STATUSES, ANCHOR_TYPES, ANCHOR_STATUSES, NODE_TYPES, EDGE_TYPES, } from "@jamesaphoenix/tx-types";
+export { TASK_STATUSES, VALID_TRANSITIONS, LEARNING_SOURCE_TYPES, ATTEMPT_OUTCOMES, RUN_STATUSES, } from "@jamesaphoenix/tx-types";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,mDAAmD;AACnD,cAAc,wBAAwB,CAAC;AAEvC,oCAAoC;AACpC,OAAO,EAAE,QAAQ,EAAuC,MAAM,gBAAgB,CAAC;AAkD/E,iCAAiC;AACjC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,UAAU,EACV,UAAU,GACX,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,mDAAmD;AACnD,cAAc,wBAAwB,CAAC;AAEvC,oCAAoC;AACpC,OAAO,EAAE,QAAQ,EAAuC,MAAM,gBAAgB,CAAC;AAsC/E,iCAAiC;AACjC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,YAAY,GACb,MAAM,yBAAyB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jamesaphoenix/tx",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "TanStack for AI agents - headless primitives for memory, tasks, and orchestration",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,18 +25,12 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@jamesaphoenix/tx-core": "^0.4.2",
-    "@jamesaphoenix/tx-types": "^0.4.2"
+    "@jamesaphoenix/tx-core": "*",
+    "@jamesaphoenix/tx-types": "*"
   },
   "peerDependencies": {
-    "better-sqlite3": "^11.0.0",
     "effect": "^3.0.0"
   },
-  "peerDependenciesMeta": {
-    "better-sqlite3": {
-      "optional": false
-    }
-  },
   "repository": {
     "type": "git",
     "url": "https://github.com/jamesaphoenix/tx.git",