claude-code-swarm 0.3.2 → 0.3.4

package/references/opentasks/src/index.ts

@@ -1,270 +0,0 @@
-/**
- * OpenTasks
- *
- * A graph-based task management system with agent-first design.
- *
- * @packageDocumentation
- */
-
-// =============================================================================
-// Config
-// =============================================================================
-
-export {
-  loadConfig,
-  getDefaults,
-  parseEnvConfig,
-  mergeConfigs,
-  validateConfig,
-  parseConfig,
-  ConfigParseError,
-  ConfigValidationError,
-  DEFAULT_CONFIG,
-} from './config/index.js';
-
-export type {
-  OpenTasksConfig,
-  PartialOpenTasksConfig,
-  StorageConfig,
-  DaemonConfig as DaemonConfigOptions,
-  ProvidersConfig,
-  BeadsProviderConfig,
-  ClaudeTasksProviderConfig,
-  LoggingConfig,
-  LoggingLevel,
-  ValidationResult as ConfigValidationResult,
-} from './config/index.js';
-
-// =============================================================================
-// Core
-// =============================================================================
-
-export { generateId, type IdNodeType } from './core/id.js';
-export { sha256, computeContentHash } from './core/hash.js';
-
-// =============================================================================
-// Schema
-// =============================================================================
-
-export type {
-  Node,
-  NodeType,
-  Context,
-  Task,
-  Feedback,
-  ExternalNode,
-  Edge,
-  EdgeType,
-  CoreEdgeType,
-  ExtendedEdgeType,
-  Anchor,
-  BaseNode,
-  StoredNode,
-  StoredEdge,
-  PersistedGraph,
-  GraphMetadata,
-  GraphChanges,
-  ValidationResult,
-} from './schema/index.js';
-
-export {
-  ValidationError,
-  isContext,
-  isTask,
-  isFeedback,
-  isExternal,
-  validateStoredNode,
-  parseNode,
-  tryParseNode,
-  hasKnownType,
-} from './schema/index.js';
-
-// =============================================================================
-// Storage
-// =============================================================================
-
-export type {
-  Storage,
-  Transaction,
-  NodeFilter as StorageNodeFilter,
-  ResolvedNodeFilter,
-  JSONLPersisterConfig,
-  LoadResult,
-  SQLitePersisterConfig,
-} from './storage/index.js';
-
-export {
-  JSONLPersister,
-  createJSONLPersister,
-  SQLitePersister,
-  createSQLitePersister,
-  resolveNodeFilter,
-  atomicWrite,
-  appendToFile,
-  fileExists,
-  readFileOrEmpty,
-} from './storage/index.js';
-
-// =============================================================================
-// Graph
-// =============================================================================
-
-export type {
-  GraphStore,
-  CreateNodeInput,
-  UpdateNodeInput,
-  CreateEdgeInput,
-  DeleteOptions,
-  NodeFilter,
-  EdgeFilter,
-  ReadyOptions,
-  BlockerOptions,
-  FeedbackOptions,
-} from './graph/index.js';
-
-export { createGraphStore } from './graph/index.js';
-
-// =============================================================================
-// Daemon
-// =============================================================================
-
-export type {
-  Daemon,
-  DaemonConfig,
-  DaemonState,
-  DaemonStatus,
-  IPCServer,
-  IPCClient,
-  FileWatcher,
-  WatcherConfig,
-  DaemonFlushManager,
-  FlushManagerConfig,
-  DaemonWithStoreConfig,
-  MultiLocationDaemonFromGitConfig,
-} from './daemon/index.js';
-
-export {
-  createDaemon,
-  checkExistingDaemon,
-  createIPCServer,
-  createIPCClient,
-  createFileWatcher,
-  createDaemonFlushManager,
-  registerLifecycleMethods,
-  registerGraphMethods,
-  registerToolsMethods,
-  DaemonError,
-  createDaemonWithStore,
-  createMultiLocationDaemonFromGit,
-} from './daemon/index.js';
-
-// =============================================================================
-// Tools (3-Tool Agent Interface)
-// =============================================================================
-
-export type {
-  LinkParams,
-  LinkResult,
-  QueryParams,
-  QueryResult,
-  AnnotateParams,
-  AnnotateResult,
-  NodeSummary,
-  EdgeSummary,
-  FeedbackSummary,
-  BlockerQueryParams,
-  FeedbackQueryParams,
-  CreateFeedbackParams,
-  FeedbackAnchor,
-  FeedbackType,
-  ToolErrorCode,
-} from './tools/index.js';
-
-export { link, query, annotate, ToolError } from './tools/index.js';
-
-// =============================================================================
-// Client
-// =============================================================================
-
-export type { ClientOptions } from './client/index.js';
-
-export { OpenTasksClient, ClientError, createClient } from './client/index.js';
-
-// =============================================================================
-// Providers
-// =============================================================================
-
-export type {
-  Provider,
-  ProviderCapabilities,
-  ProviderNode,
-  ProviderNodeType,
-  ProviderCreateInput,
-  ProviderUpdateInput,
-  ProviderFilter,
-  ParsedUri,
-  UriOptions,
-  WatchCallback,
-  WatchEvent,
-  Unsubscribe,
-  SearchOptions,
-  MaterializationStrategy,
-  MaterializationConfig,
-  ProviderRegistry,
-  ProviderErrorCode,
-  MaterializationManager,
-  MaterializationContext,
-  BeadsConfig,
-  NativeProviderConfig,
-  ClaudeTasksConfig,
-  ClaudeTask,
-  ClaudeTaskStore,
-  // Watchable trait
-  Watchable,
-  WatchGranularity,
-  WatchMechanism,
-  WatchChangeCallback,
-  ProviderChangeEvent,
-  ProviderNodeChangeEvent,
-  ProviderEdgeChangeEvent,
-} from './providers/index.js';
-
-export {
-  ProviderError,
-  DEFAULT_MATERIALIZATION_CONFIG,
-  createProviderRegistry,
-  createNativeProvider,
-  createBeadsProvider,
-  createClaudeTasksProvider,
-  createInMemoryTaskStore,
-  createMaterializationManager,
-  isWatchable,
-} from './providers/index.js';
-
-// Provider-Aware Store
-export type { ProviderAwareStore, ProviderStoreConfig, ResolveOptions } from './graph/index.js';
-
-export { createProviderAwareStore } from './graph/index.js';
-
-// =============================================================================
-// Tracking (Skill Usage)
-// =============================================================================
-
-export type {
-  SkillName,
-  SkillInvocation,
-  SkillUsageStats,
-  SkillUsageSummary,
-  SkillTrackerOptions,
-  SkillTracker,
-  SkillTrackerRegistry,
-} from './tracking/index.js';
-
-export { createSkillTracker, createSkillTrackerRegistry } from './tracking/index.js';
-
-// =============================================================================
-// Entire (Native TypeScript Implementation)
-// =============================================================================
-
-// Re-export entire module as a namespace for clean boundary
-export * as entire from './entire/index.js';

package/references/opentasks/src/materialization/CLAUDE.md

@@ -1,88 +0,0 @@
-# Materialization — development guide
-
-## Module structure
-
-- `types.ts` — all interfaces and type definitions; the source of truth for the module's contracts
-- `archiver.ts` — `createMaterializationArchiver()` coordinator; fans out snapshots to git + remote stores
-- `snapshot.ts` — `buildSnapshot()`, `buildSessionSnapshot()`, `buildCheckpointSnapshot()`, `buildProvenance()`
-- `git-archive-store.ts` — `createGitArchiveStore()`; uses git plumbing commands (no working tree)
-- `http-remote-store.ts` — `createHttpRemoteStore()`; POSTs snapshots to HTTP endpoints (write-only)
-- `git-remote-store.ts` — `createGitRemoteStore()`; archives to a remote git repo via local bare clone (read + write)
-- `remote-store-factory.ts` — `registerRemoteStoreFactory()` plugin registry + `createRemoteStoresFromConfig()`
-- `graph-id.ts` — `resolveGraphId()` with 4-level fallback chain + slug helpers
-- `index.ts` — barrel file; all public exports go through here
-
-## Key patterns
-
-### Git plumbing (no porcelain)
-
-`git-archive-store.ts` never checks out files. It uses:
-- `git hash-object -w` to write blobs
-- `git update-index` with a temporary `GIT_INDEX_FILE` to avoid touching the working tree
-- `git write-tree` / `git commit-tree` / `git update-ref` for atomic commits
-
-Temporary index files are created at `.git/index-archive-<timestamp>` to allow concurrent operations without conflicts.
-
-### Store fan-out
-
-The archiver runs the git store first, then all enabled remote stores in parallel. Each store is error-isolated — a remote store failure never blocks the git archive or other remote stores.
-
-### Snapshot immutability
-
-Snapshots are immutable once committed. The `archivedAt` field is set at archive time; everything else comes from the graph node at that moment. `version: 1` is always set for forward compatibility.
-
-### Remote store plugin interface
-
-To add a new remote store type:
-1. Implement `RemoteStore` from `types.ts` (extends `MaterializationStore` with `events: string[]`)
-2. Create a factory function `(config: RemoteStoreConfig) => RemoteStore`
-3. Register it: `registerRemoteStoreFactory('mytype', factory)`
-
-The HTTP store is write-only (`retrieve()` returns null, `list()` returns `[]`). The git remote store supports both reads and writes via a local bare repo cache. New stores can implement reads if the backend supports it.
-
-## Testing
-
-Tests are in `__tests__/` and cover:
-- `snapshot.test.ts` — snapshot assembly from various node types
-- `archiver.test.ts` — fan-out, error isolation, rematerialization flows
-- `git-archive-store.test.ts` — (via `archive-methods.test.ts`) storage and retrieval
-- `http-remote-store.test.ts` — HTTP webhook integration
-- `git-remote-store.test.ts` — git remote store with real bare repo operations
-- `remote-store-factory.test.ts` — factory registration and config parsing
-- `graph-id.test.ts` — ID derivation, slug helpers, remote URL parsing
-- `config.test.ts` — config schema validation
-- `materialize-before-archive.test.ts` — provider integration for pre-archive materialization
-
-## Common tasks
-
-### Adding a field to snapshots
-
-1. Add the field to the relevant interface in `types.ts` (`MaterializationSnapshot`, `SessionSnapshot`, or `CheckpointSnapshot`)
-2. Populate it in `snapshot.ts` (`buildSnapshot` / `buildSessionSnapshot` / `buildCheckpointSnapshot`)
-3. Update tests in `__tests__/snapshot.test.ts`
-4. If the field affects archive layout, update `git-archive-store.ts` path logic
-
-### Adding a new remote store type
-
-1. Create `my-store.ts` implementing `RemoteStore`
-2. Export the factory from `index.ts`
-3. Register in `remote-store-factory.ts` or let consumers call `registerRemoteStoreFactory()`
-4. Add tests in `__tests__/my-store.test.ts`
-
-### Changing archive policy defaults
-
-Defaults are in `types.ts` at `DEFAULT_ARCHIVE_POLICY`. The archiver reads these from config via `MaterializationArchiverConfig.policy`.
-
-### Changing the git tree layout
-
-Paths are constructed in `git-archive-store.ts` and `git-remote-store.ts`. The pattern is `<graphId>/sessions/<session-id>/session.json` (and `edges.json`, `checkpoints/<id>.json`). Both stores must use the same layout. Changing this requires a migration strategy for existing archives.
-
-## Important constraints
-
-- The git archive branch (`opentasks/archive`) is an orphan branch — it shares no history with the main branch
-- `pushToRemote()` handles conflicts via fetch + rebase; this is safe because paths are namespaced by graphId and don't overlap across repos
-- Snapshots use `version: 1` — bump this if making breaking schema changes
-- The archiver depends on `GraphStore` for node/edge queries — it cannot run without a store instance
-- `materializeBeforeArchive` requires a `MaterializationProvider` to be set on the archiver; without one, it archives whatever is already in the graph node
-- `git-remote-store.ts` manages its own bare repo cache; the cache path can be configured or defaults to a temp directory. The `fetchBeforeRead` option (default: true) fetches from the remote before `retrieve()` and `list()` operations
-- The git remote store uses the same tree layout and plumbing approach as the local git archive store — changes to one should be reflected in the other

package/references/opentasks/src/materialization/README.md

@@ -1,187 +0,0 @@
-# Materialization Stores
-
-Pluggable archival layer for materialized external node snapshots. When an Entire session ends (or at other configured lifecycle points), a full snapshot of the session — its checkpoints, edges, and provenance — is archived to durable storage that survives cloning, forking, and repo transfers.
-
-## What this provides
-
-1. **Git-native local store** — Archives session snapshots as commits on an orphan branch (`opentasks/archive`), using git's content-addressed storage for deduplication and versioning
-2. **Remote store interface** — Pluggable backends for non-git storage (HTTP webhooks, analytics pipelines, data warehouses)
-3. **Rematerialization** — Reconstruct graph nodes from archived snapshots after clone, fork, or data loss
-4. **Cross-repo traceability** — Shared archive repos can aggregate session data from multiple source repos
-
-## Architecture
-
-```
-EntireAutoLinker
-  │  (session lifecycle events)
-  ▼
-MaterializationArchiver
-  │  Builds snapshots from GraphStore nodes + edges
-  │  Fans out to all enabled stores (errors isolated per-store)
-  │
-  ├──▶ GitArchiveStore (local orphan branch)
-  │      Commits to opentasks/archive branch
-  │      Optional push to remote
-  │
-  └──▶ RemoteStore[] (pluggable)
-         HTTP webhook, analytics API, custom implementations
-```
-
-## File overview
-
-| File | Purpose |
-|---|---|
-| `types.ts` | All type definitions — snapshots, store interfaces, policies, config |
-| `index.ts` | Public API barrel file |
-| `archiver.ts` | `MaterializationArchiver` — coordinates between event sources and stores |
-| `snapshot.ts` | Snapshot assembly — builds self-contained snapshots from graph nodes/edges |
-| `git-archive-store.ts` | `GitArchiveStore` — git orphan branch archive using plumbing commands |
-| `http-remote-store.ts` | `HttpRemoteStore` — POSTs snapshots to an HTTP endpoint |
-| `git-remote-store.ts` | `GitRemoteStore` — archives to a remote git repo via bare clone |
-| `remote-store-factory.ts` | Factory + registry for creating remote stores from config |
-| `graph-id.ts` | Graph ID resolution with 4-level fallback chain |
-
-## Key concepts
-
-### Snapshots
-
-A `MaterializationSnapshot` is a self-contained record with everything needed to reconstruct a node:
-
-- **URI** — canonical identifier (`entire://session/<id>` or `entire://checkpoint/<id>`)
-- **Node data** — title, content, status, external_data, tags
-- **Provenance** — graphId, graphPath, git remote/branch/HEAD at archive time
-
-Specialized variants: `SessionSnapshot` (adds edges + checkpoint IDs) and `CheckpointSnapshot` (adds code commit correlation + parent session URI).
-
-### Git archive store
-
-Uses pure git plumbing (no working tree) to commit snapshots:
-
-1. `git hash-object -w` — write snapshot JSON as a blob
-2. `git update-index` — add blob to a temporary index
-3. `git write-tree` — create a tree object
-4. `git commit-tree` — commit with explicit parent tracking
-5. `git update-ref` — advance the branch ref
-
-Tree layout inside the archive branch:
-```
-<graphId>/
-  sessions/
-    <session-id>/
-      session.json
-      edges.json
-      checkpoints/
-        <checkpoint-id>.json
-```
-
-Supports pushing to a remote with configurable policy (`immediate`, `on-session-end`, `manual`) and automatic conflict resolution via fetch + rebase.
-
-### Remote stores
-
-Pluggable backends that implement the `RemoteStore` interface (extends `MaterializationStore` with event filtering). Built-in types:
-
-- **`http` / `webhook`** — POSTs snapshot JSON to a URL with configurable headers, timeout, and batch mode. Write-only (no retrieve/list support).
-- **`git-remote`** — Archives to a separate remote git repository. Manages a local bare repo cache, commits using git plumbing, and pushes to the remote. Supports both reads and writes — `retrieve()` and `list()` fetch from the remote before reading.
-
-Custom store types can be registered:
-```typescript
-registerRemoteStoreFactory('mytype', createMyStore)
-```
-
-### Graph ID resolution
-
-Determines the namespace for archive paths. Fallback chain:
-
-1. Explicit config (`materialization.graphId`)
-2. Location name from config
-3. Slugified git remote URL (e.g., `github.com:org/repo` -> `org--repo`)
-4. Slugified directory name
-
-### Archive policy
-
-Controls when archival happens:
-
-| Policy | Default | Description |
-|---|---|---|
-| `archiveOnStart` | `false` | Archive when a session starts |
-| `archiveOnCheckpoint` | `true` | Archive on each checkpoint |
-| `archiveOnEnd` | `true` | Archive when a session ends |
-| `materializeBeforeArchive` | `true` | Fetch fresh data from provider before building snapshot |
-
-### Rematerialization
-
-When the daemon detects missing nodes (URIs referenced in edges but no corresponding node), it can reconstruct them from the git archive:
-
-1. `GitArchiveStore.retrieve(uri)` reads the snapshot from the orphan branch
-2. `Archiver.rematerialize()` recreates the `ExternalNode` in the graph
-
-`rematerializeAll()` scans for all orphaned edge references and restores them in bulk.
-
-## Configuration
-
-Minimal (local archive in same repo):
-```json
-{
-  "materialization": {
-    "git": { "enabled": true }
-  }
-}
-```
-
-With remote push and HTTP webhook:
-```json
-{
-  "materialization": {
-    "graphId": "payments-service",
-    "git": {
-      "enabled": true,
-      "remote": "origin",
-      "pushPolicy": "on-session-end"
-    },
-    "remoteStores": [
-      {
-        "type": "http",
-        "name": "analytics",
-        "enabled": true,
-        "config": {
-          "url": "https://analytics.internal/opentasks/ingest",
-          "headers": { "Authorization": "Bearer ${OPENTASKS_ANALYTICS_TOKEN}" }
-        },
-        "events": ["session.ended"]
-      }
-    ]
-  }
-}
-```
-
-With a git remote store:
-```json
-{
-  "materialization": {
-    "git": { "enabled": true },
-    "remoteStores": [
-      {
-        "type": "git-remote",
-        "name": "archive-repo",
-        "enabled": true,
-        "config": {
-          "url": "git@github.com:org/opentasks-archive.git",
-          "branch": "opentasks/archive",
-          "cachePath": "/tmp/opentasks/archive-cache",
-          "pushPolicy": "immediate",
-          "fetchBeforeRead": true
-        },
-        "events": ["session.ended"]
-      }
-    ]
-  }
-}
-```
-
-## Integration points
-
-- **`src/daemon/entire-linker.ts`** — Auto-linker calls `archiver.onSessionEvent()` on session lifecycle events
-- **`src/daemon/location-state.ts`** — Creates and wires the archiver during daemon startup
-- **`src/graph/store.ts`** — Queries nodes/edges for snapshot building and reconstruction
-- **`src/providers/materialization.ts`** — Provider for `materializeBeforeArchive` (fetches fresh external data)
-- **`src/config/schema.ts`** — Config validation for materialization settings