@mc1global/opencode-jarvis 0.3.1 → 0.6.0

package/QUICK-GUIDE.md

@@ -0,0 +1,53 @@
+# JARVIS Plugin — Quick Reference Card
+
+> Full documentation: see [README.md](README.md) or https://www.npmjs.com/package/@mc1global/opencode-jarvis
+
+## Setup in 60 Seconds
+
+```bash
+# 1. Prerequisites (macOS)
+curl -fsSL https://bun.sh/install | bash
+brew install ollama && ollama serve && ollama pull embeddinggemma
+
+# 2. Add plugin to your project
+echo '{ "plugin": ["@mc1global/opencode-jarvis"] }' > opencode.json
+
+# 3. Launch OpenCode — JARVIS auto-bootstraps everything
+opencode
+```
+
+## First Session Checklist
+
+| Step | Tool / Command |
+|---|---|
+| Run diagnostics | `/healthcheck` |
+| Index codebase | `rag-index` tool |
+| Index docs | `rag-oracle-index` tool with `directory="obsidian-vault"` |
+| View board | `kanban-board-view` tool |
+
+## Key Commands
+
+| Command | What it does |
+|---|---|
+| `/healthcheck` | Diagnose environment + show fix commands |
+| `/sync-azure` | Sync kanban with Azure DevOps |
+| `/start-card CD-XXX` | Start working on a card (full lifecycle) |
+
+## Key Skills (load via `skill()` tool)
+
+| Skill | What it teaches |
+|---|---|
+| `jarvis-onboarding` | Setup, tools, orientation |
+| `jarvis-kanban` | Card lifecycle, grooming, sprints |
+| `jarvis-azure-sync` | Azure DevOps sync workflow |
+
+## Files Created by JARVIS
+
+| Path | In Git? | Purpose |
+|---|---|---|
+| `config/jarvis.yaml` | Yes | Configuration |
+| `AGENTS.md` | Yes | Agent instructions |
+| `obsidian-vault/` | Yes | Documentation |
+| `.jarvis/jarvis.db` | No | Local database |
+| `.jarvis/rag/` | No | RAG embeddings |
+| `~/.jarvis/registry.db` | No | Global workspace registry |

package/README.md

@@ -1,84 +1,54 @@
 # @mc1global/opencode-jarvis
 
-A native [OpenCode](https://opencode.ai) plugin providing multi-agent development infrastructure: session memory, kanban project management, governance guardrails, token metrics tracking, RAG semantic search, Obsidian vault management, domain map analysis, workspace registry, environment management, and structured data tools.
+A native [OpenCode](https://opencode.ai) plugin providing multi-agent development infrastructure: session memory, kanban project management, governance guardrails, token metrics tracking, RAG semantic search, Obsidian vault management, domain map analysis, workspace registry, environment management, CI/CD pipelines, Azure DevOps sync, and structured data tools.
 
 Built with **Domain-Driven Design**, **SOLID principles**, and strict TypeScript.
 
-## Features
+## Prerequisites
 
-### 82 Tools across 11 categories
+| Requirement | Purpose | Required? |
+|---|---|---|
+| [OpenCode](https://opencode.ai) CLI | Host runtime for the plugin | **Yes** |
+| [Bun](https://bun.sh) >= 1.0 | Production runtime (bun:sqlite, MCP server) | **Yes** |
+| Node.js >= 20 | Test runner (Jest + ESM) | Dev only |
+| [Ollama](https://ollama.ai) | Local embedding generation for RAG | For RAG features |
+| `embeddinggemma` model | Default embedding model (768 dims) | For RAG features |
+| [Dagger CLI](https://docs.dagger.io/install) | Container-based CI/CD gate execution | Optional |
+| [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) | Azure DevOps board sync | Optional |
 
-| Category                | Count | Tools                                                                                                                                                                                                                                                                                 | Description                                                                                   |
-| ----------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| **Context Memory**      | 8     | `context-session-*`, `context-todo-*`, `context-note-*`, `context-search`                                                                                                                                                                                                             | Session lifecycle, todos, notes, cross-context search                                         |
-| **Kanban Cards**        | 12    | `kanban-card-create`, `kanban-card-move`, `kanban-card-list`, `kanban-card-get`, `kanban-card-assign`, `kanban-card-assign-sprint`, `kanban-card-assign-epic`, `kanban-card-estimate`, `kanban-card-criteria`, `kanban-card-criteria-meet`, `kanban-card-delete`, `kanban-card-brief` | Card state machine, assignments, estimation, acceptance criteria, deletion, context briefings |
-| **Kanban Board**        | 15    | `kanban-sprint-*`, `kanban-epic-*`, `kanban-board-*`, `kanban-wip-check`                                                                                                                                                                                                              | Sprint lifecycle, epic lifecycle (start/complete/update), board views, WIP limit checks       |
-| **Governance**          | 2     | `governance-validate`, `governance-policies`                                                                                                                                                                                                                                          | Policy validation and rule introspection                                                      |
-| **Token Metrics**       | 7     | `metrics-record`, `metrics-history`, `metrics-agent-report`, `metrics-card-report`, `metrics-sprint-report`, `metrics-summary`, `metrics-estimate`                                                                                                                                    | Usage tracking, cost reports by agent/card/sprint, workspace summaries with recommendations   |
-| **RAG**                 | 8     | `rag-search`, `rag-index`, `rag-snippet`, `rag-update`, `rag-delete`, `rag-status`, `rag-oracle-search`, `rag-oracle-index`                                                                                                                                                           | Semantic code search via Vectra + Ollama embeddings                                           |
-| **Data**                | 3     | `data-yaml-get`, `data-json-get`, `data-csv-query`                                                                                                                                                                                                                                    | Structured data file access with dot-notation paths and CSV filtering                         |
-| **Vault**               | 11    | `vault-doc-*`, `vault-frontmatter-*`, `vault-table-*`, `vault-manage`                                                                                                                                                                                                                 | Obsidian vault document management, frontmatter, tables, smart facade                         |
-| **Agent Communication** | 4     | `agent-sessions`, `agent-send`, `agent-notify`, `agent-dispatch`                                                                                                                                                                                                                      | Inter-session communication, card dispatch to other agents                                    |
-| **Domain Map**          | 2     | `domain-map-analyze`, `domain-map-view`                                                                                                                                                                                                                                               | DDD domain map analysis (greenfield + legacy modes)                                           |
-| **Workspace Registry**  | 4     | `workspace-info`, `workspace-list`, `workspace-update`, `workspace-link`                                                                                                                                                                                                              | Cross-project workspace registry with dependency tracking                                     |
-| **Environment**         | 6     | `env-init`, `env-create`, `env-list`, `env-status`, `env-merge`, `env-delete`                                                                                                                                                                                                         | Isolated container-use environments with kanban card linkage                                  |
+## Quick Start
 
-### 4 Hooks
+### 1. Install prerequisites
 
-| Hook                   | Type                              | Description                                           |
-| ---------------------- | --------------------------------- | ----------------------------------------------------- |
-| **Context Compacting** | `experimental.session.compacting` | Injects session context when context window compacts  |
-| **Shell Environment**  | `shell.env`                       | Injects JARVIS env vars into shell sessions           |
-| **Guardrails**         | `tool.execute.before`             | Governance policy enforcement on tool invocations     |
-| **Event Handlers**     | `event`                           | Token usage tracking and cross-context event handling |
+**macOS:**
 
-### 10 Governance Policies
+```bash
+# Bun (required — SQLite runtime)
+curl -fsSL https://bun.sh/install | bash
 
-6 core policies (file size, tool validation, grooming, WIP limits, test requirements, naming conventions) + 4 security policies (env dump prevention, shell env file access, sensitive file protection, shell sensitive command blocking).
+# Ollama (required — RAG semantic search)
+brew install ollama
+ollama serve                    # start the server
+ollama pull embeddinggemma      # download the embedding model
 
-## Architecture
+# Optional: Azure DevOps sync
+brew install azure-cli && az login
 
+# Optional: CI/CD pipeline execution
+brew install dagger/tap/dagger
 ```
-jarvis-plugin/
-  src/
-    domain/                  # Pure business logic, zero external deps
-      shared/                # WorkspaceId, EntityId, Result<T>
-      context-memory/        # Session, Todo, Note entities + services
-      kanban/                # Card state machine, Sprint, Epic, Grooming
-      governance/            # 10 policy rules, validation service
-      token-metrics/         # Token usage tracking entities
-      rag/                   # RAG value objects, configuration
-      vault/                 # Vault document, section, table entities
-      domain-map/            # Bounded context detection, domain analysis
-      workspace-registry/    # Cross-project workspace registration
-      environment/           # Container-use environment management
-    application/             # Use cases with DTOs (9 bounded contexts)
-    infrastructure/          # SQLite repos, Vectra, Ollama, filesystem adapters
-    tools/                   # 13 tool modules (82 tools total)
-    hooks/                   # 4 hooks (guardrails, compacting, events, shell-env)
-    tests/                   # 1145+ tests across 37 test suites
-  obsidian-vault/            # 62+ documentation files
-```
-
-**Key constraints:**
-
-- Max 500 lines per file (no exceptions)
-- Domain layer has zero external dependencies
-- ESM modules (`"type": "module"`)
-- `exactOptionalPropertyTypes: true` + `verbatimModuleSyntax: true`
-- 9 bounded contexts with strict DDD boundaries
-
-## Installation
 
-### Prerequisites
+**Linux:**
 
-- [OpenCode](https://opencode.ai) CLI installed
-- Node.js >= 20
-- For RAG tools: [Ollama](https://ollama.ai) with `embeddinggemma` model
+```bash
+curl -fsSL https://bun.sh/install | bash
+curl -fsSL https://ollama.ai/install.sh | sh
+ollama serve && ollama pull embeddinggemma
+```
 
-### From npm (recommended)
+### 2. Add the plugin to your project
 
-Add to your project's `opencode.json`:
+Create `opencode.json` in your project root:
 
 ```json
 {
@@ -88,7 +58,96 @@ Add to your project's `opencode.json`:
 
 OpenCode installs npm plugins automatically at startup. Requires access to the `@mc1global` org on npm.
 
-### From local files (development)
+### 3. First launch (automatic)
+
+Run `opencode` in your project directory. JARVIS initializes everything:
+
+```
+What JARVIS creates automatically on first load:
+
+  .jarvis/                SQLite database + RAG indexes (local, gitignored)
+  config/jarvis.yaml      Default configuration (commit this)
+  obsidian-vault/         Documentation skeleton (commit this)
+  AGENTS.md               Agent operational guide (commit this)
+```
+
+On the **first session**, the agent receives automatic guidance via system prompt injection to run initial diagnostics.
+
+### 4. First session — recommended steps
+
+The agent should run these on first use (JARVIS prompts automatically):
+
+1. **`/healthcheck`** — Verify all subsystems
+2. **`rag-index`** tool — Index the codebase for semantic search
+3. **`rag-oracle-index`** tool with `directory="obsidian-vault"` — Index documentation
+4. **`kanban-board-view`** tool — See the kanban board
+
+### 5. Verify your setup
+
+The `jarvis-healthcheck` tool shows all dependencies with **copy-paste fix commands**:
+
+```
+[PASS] Bun Runtime: Bun is available (v1.1.38)
+[PASS] Ollama Connectivity: Ollama is reachable at http://localhost:11434
+[PASS] Embedding Model: Model "embeddinggemma" is available
+[PASS] SQLite Database: Database file exists
+[PASS] Configuration: config/jarvis.yaml exists
+[PASS] RAG Index: RAG index contains 42006 documents
+[WARN] Dagger CLI (optional): Dagger is not installed
+  FIX: brew install dagger/tap/dagger
+[WARN] Azure CLI (optional): Azure CLI is not installed
+  FIX: brew install azure-cli && az login
+
+Summary: 6 pass, 2 warn, 0 fail (8 total)
+Status: HEALTHY
+```
+
+## What Lives Where
+
+### In Git (committed, shared with team)
+
+```
+opencode.json              Plugin declaration
+config/jarvis.yaml         Configuration (auto-created, then customized)
+AGENTS.md                  Agent operational guide (auto-generated)
+obsidian-vault/            Documentation vault
+.opencode/skills/          Workflow skills for the agent
+.opencode/commands/        Slash commands (/healthcheck, /sync-azure, /start-card)
+```
+
+### Local per machine (NOT in git)
+
+```
+.jarvis/jarvis.db          SQLite: kanban, sessions, metrics, sync mappings
+.jarvis/rag/               Vectra vector store (RAG embeddings)
+```
+
+### Global (shared across all projects)
+
+```
+~/.jarvis/registry.db      Workspace registry (cross-project)
+~/.cache/opencode/         Plugin npm cache (managed by OpenCode)
+```
+
+## Available Skills and Commands
+
+### Skills (loaded on demand via `skill()` tool)
+
+| Skill | Description |
+|---|---|
+| `jarvis-onboarding` | Setup, healthcheck, RAG indexing, tool reference |
+| `jarvis-kanban` | Card lifecycle, grooming, sprints, gate tasks |
+| `jarvis-azure-sync` | Azure DevOps push/pull/sync, PR creation |
+
+### Commands (slash commands in any session)
+
+| Command | Description |
+|---|---|
+| `/healthcheck` | Run diagnostics with actionable fix guidance |
+| `/sync-azure` | Execute Azure DevOps sync workflow |
+| `/start-card CD-XXX` | Start working on a kanban card (full lifecycle) |
+
+## Installation (Local Development)
 
 ```bash
 # Clone
@@ -111,59 +170,219 @@ npm run build
 }
 ```
 
-### RAG Setup (Optional)
+## MCP Server Mode
+
+JARVIS also runs as a standalone MCP server (stdio transport) for Claude Desktop, Cursor, or other MCP clients:
 
 ```bash
-# Pull embedding model for semantic search
-ollama pull embeddinggemma
+bun run src/mcp-server.ts --directory /path/to/project
+```
+
+Configure tool filtering in `config/jarvis.yaml`:
+
+```yaml
+mcp-server:
+  transport: "stdio"
+  enabledTools: null  # null = all tools, or list specific tool names
+```
+
+## Features
+
+### 112 Tools across 13 categories
+
+| Category | Count | Key Tools |
+|---|---|---|
+| **Context Memory** | 8 | `context-session-*`, `context-todo-*`, `context-note-*`, `context-search` |
+| **Kanban Cards** | 12 | `kanban-card-create/move/list/get/assign/estimate/criteria/delete/brief` |
+| **Kanban Board** | 15 | `kanban-sprint-*`, `kanban-epic-*`, `kanban-board-*`, `kanban-wip-check` |
+| **Governance** | 2 | `governance-validate`, `governance-policies` |
+| **Token Metrics** | 7 | `metrics-record/history/agent-report/card-report/sprint-report/summary/estimate` |
+| **RAG** | 8 | `rag-search/index/snippet/update/delete/status/oracle-search/oracle-index` |
+| **Data** | 3 | `data-yaml-get`, `data-json-get`, `data-csv-query` |
+| **Vault** | 11 | `vault-doc-*`, `vault-frontmatter-*`, `vault-table-*`, `vault-manage` |
+| **Agent** | 8 | `agent-sessions/send/notify/dispatch`, `agent-register/profile/list/spawn` |
+| **Domain Map** | 2 | `domain-map-analyze`, `domain-map-view` |
+| **Workspace** | 4 | `workspace-info/list/update/link` |
+| **Environment** | 6 | `env-init/create/list/status/merge/delete` |
+| **Pipeline** | 12 | `pipeline-init/activate/cancel/retry/run/gate/status/list/template/scaffold` |
+| **Azure Sync** | 10 | `azure-sync-*`, `azure-pr-*` |
+| **Bootstrap** | 2 | `jarvis-bootstrap`, `jarvis-healthcheck` |
+
+### 5 Hooks
+
+| Hook | Type | Description |
+|---|---|---|
+| **Context Compacting** | `experimental.session.compacting` | Injects session context when context window compacts |
+| **First-Run Guide** | `experimental.chat.system.transform` | Injects setup instructions on first session |
+| **Shell Environment** | `shell.env` | Injects JARVIS env vars into shell sessions |
+| **Guardrails** | `tool.execute.before` | Governance policy enforcement on tool invocations |
+| **Event Handlers** | `event` | Token usage tracking and cross-context event handling |
+
+### 13 Governance Policies
+
+Runtime-enforced via `tool.execute.before` hook. Covers: CSV/YAML/env file access, force push protection, SQLite CLI blocking, destructive shell ops, credential file protection, and more.
+
+## Configuration
+
+All settings live in `config/jarvis.yaml`. The `ConfigService` deep-merges YAML overrides over hardcoded defaults. Available sections:
+
+```yaml
+# RAG embedding settings
+rag:
+  ollama:
+    url: "http://localhost:11434"
+    model: "embeddinggemma"
+    dimensions: 768
+  markdownSplitByHeaders: true
+
+# Azure DevOps integration
+azure-sync:
+  organization: ""      # Set to enable Azure sync
+  project: ""
+  repository: ""
+  authMethod: "az-cli"
+  pollEnabled: false
+  pollIntervalSecs: 60
+
+# Kanban workflow enforcement
+kanban:
+  minTransitionIntervalSecs: 30
+  gateTasks:              # Per-phase gate definitions
+
+# MCP server settings
+mcp-server:
+  transport: "stdio"
+  enabledTools: null      # null = all tools
+
+# Pipeline CI/CD
+pipeline:
+  defaultTimeoutMs: 300000
+```
+
+Never read YAML files directly — use `data-yaml-get` tool or `ConfigService` getters.
+
+## Architecture
 
-# Index your workspace (from within OpenCode)
-# Use the rag-index tool
 ```
+jarvis-plugin/
+  src/
+    domain/                  # Pure business logic, zero external deps
+      shared/                # WorkspaceId, EntityId, Result<T>
+      context-memory/        # Session, Todo, Note entities + services
+      kanban/                # Card state machine, Sprint, Epic, Grooming
+      governance/            # 13 policy rules, validation service
+      token-metrics/         # Token usage tracking entities
+      rag/                   # RAG value objects, domain services
+      vault/                 # Vault document, section, table entities
+      domain-map/            # Bounded context detection, domain analysis
+      workspace-registry/    # Cross-project workspace registration
+      environment/           # Container-use environment management
+      agent-registry/        # Agent profile management
+      pipeline/              # CI/CD pipeline entities, gate enforcement
+      config/                # Configuration value objects + defaults
+    application/             # Use cases with DTOs (11 bounded contexts)
+    infrastructure/          # SQLite repos, Vectra, Ollama, FS adapters
+    tools/                   # 15 tool modules (112 tools total)
+    hooks/                   # 5 hooks (guardrails, compacting, first-run, events, shell-env)
+    tests/                   # 2435+ tests across 80 test suites
+  obsidian-vault/            # Structured documentation
+  config/                    # jarvis.yaml configuration
+```
+
+**Key constraints:**
+
+- Max 500 lines per file (no exceptions)
+- Domain layer has zero external dependencies
+- ESM modules (`"type": "module"`)
+- `exactOptionalPropertyTypes: true` + `verbatimModuleSyntax: true`
+- 11 bounded contexts with strict DDD boundaries
+- Production runtime: Bun (`bun:sqlite`); Tests: Node.js + Jest
+
+## Storage
+
+All data is stored locally:
+
+- `.jarvis/jarvis.db` — SQLite database (sessions, todos, notes, kanban, metrics, environments, pipelines)
+- `.jarvis/rag/<workspace>/` — Vectra vector stores (RAG indexes)
+- `.jarvis/rag/<workspace>/index-manifest.json` — File index registry (incremental indexing)
+- `~/.jarvis/registry.db` — Central workspace registry (cross-project)
+
+The `JARVIS_HOME` environment variable overrides `~/.jarvis/` default.
 
 ## Development
 
 ```bash
-# Run tests
+# Run all tests
 npm test
 
-# Type check
+# Type check (zero errors required)
 npm run lint
 
+# Build
+npm run build
+
+# Single test file
+node --experimental-vm-modules node_modules/.bin/jest src/tests/application/healthcheck.test.ts --no-coverage
+
 # Watch mode
 npm run dev
 
-# Check file line counts
-npm run check:lines
+# RAG index (standalone, bypasses MCP timeouts)
+npx tsx scripts/rag-index.ts --clear
 ```
 
-## Storage
+## Troubleshooting
 
-All data is stored locally:
+**Ollama connection refused**
+- Ensure Ollama is running: `ollama serve`
+- Check URL in `config/jarvis.yaml` under `rag.ollama.url` (default: `http://localhost:11434`)
 
-- `.jarvis/jarvis.db` — SQLite database (sessions, todos, notes, kanban, metrics, environments)
-- `.jarvis/rag/<workspace>/` — Vectra vector stores (RAG indexes)
-- `~/.jarvis/registry.db` — Central workspace registry (cross-project)
+**Embedding model not found**
+- Pull the model: `ollama pull embeddinggemma`
+- Verify: `ollama list` should show `embeddinggemma`
 
-The `JARVIS_HOME` environment variable overrides `~/.jarvis/` default.
+**RAG index empty after rag-index**
+- Run `jarvis-healthcheck` to verify Ollama connectivity
+- Try full reindex: use `rag-index` tool with `clear: true`
+
+**Plugin not loading in OpenCode**
+- Verify `opencode.json` has `"plugin": ["@mc1global/opencode-jarvis"]`
+- Check `~/.cache/opencode/node_modules/` for the installed package
+- Ensure Bun is installed (required for production runtime)
+
+**MCP server fails to start**
+- Ensure Bun is installed: `bun --version`
+- Run manually: `bun run src/mcp-server.ts --directory .`
+
+**Azure sync not working**
+- Set `organization` and `project` in `config/jarvis.yaml` under `azure-sync`
+- Ensure Azure CLI is authenticated: `az login`
+- Test connectivity: use `azure-sync-config` tool
+
+**tsc errors in development**
+- Remember: `exactOptionalPropertyTypes` requires conditional spreading for optional props
+- Use `import type` for type-only imports (`verbatimModuleSyntax`)
+- Array indexing returns `T | undefined` (`noUncheckedIndexedAccess`)
 
 ## Dependencies
 
-| Dependency                 | Purpose                                        |
-| -------------------------- | ---------------------------------------------- |
-| `better-sqlite3`           | Local SQLite database for all persistent state |
-| `js-yaml`                  | YAML file parsing for data tools               |
-| `vectra`                   | Local vector store for RAG semantic search     |
-| `ollama`                   | Embedding generation via local Ollama models   |
-| `@langchain/textsplitters` | Code-aware text chunking for RAG indexing      |
-| `@opencode-ai/plugin`      | OpenCode plugin SDK (peer dependency)          |
+| Dependency | Purpose |
+|---|---|
+| `bun:sqlite` | Local SQLite database (production) |
+| `better-sqlite3` | SQLite for tests (Node.js) |
+| `js-yaml` | YAML file parsing |
+| `vectra` | Local vector store for RAG |
+| `ollama` | Embedding generation via local Ollama |
+| `@langchain/textsplitters` | Code-aware text chunking for RAG |
+| `@opencode-ai/plugin` | OpenCode plugin SDK (peer dependency) |
+| `@modelcontextprotocol/sdk` | MCP server protocol (optional) |
 
 ## Test Coverage
 
-- **1145+ tests** across 37 test suites
+- **2,435+ tests** across 80 test suites
 - Domain, application, infrastructure, and tools layers tested
 - In-memory SQLite for fast, isolated integration tests
-- `tsc --noEmit` zero errors
+- `tsc --noEmit` zero errors with all strict flags
 
 ## License
 

package/dist/application/azure-sync/index.d.ts

@@ -12,5 +12,7 @@ export { TaskPushUseCases, buildTaskLocalId, parseTaskLocalId } from "./task-pus
 export type { CardForTaskPush, TaskPushDeps, TaskPushResult } from "./task-push-use-cases.js";
 export type { EpicFieldInput, CardFieldInput, TaskFieldInput } from "./field-builders.js";
 export type { ExtractedCardData, ExtractedEpicData } from "./reverse-field-builder.js";
+export { AzurePollService, SyncEventUseCases } from "./poll-service.js";
+export type { PollServiceDeps, PollNotification, PollEventSummary, SyncEventResponse } from "./poll-service.js";
 export type { DiscoverRequest, DiscoverResponse, PushRequest, PushResponse, PullRequest, PullResponse, BidiSyncRequest, BidiSyncResponse, SyncStatusRequest, SyncStatusResponse, ConfigStatusResponse, CreatePrRequest, PrResponse, PrReviewerInfo, ListPrRequest, ListPrResponse, CommentRequest, CommentResponse, } from "./dtos.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/application/azure-sync/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/application/azure-sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAChG,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC9F,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1F,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACvF,YAAY,EACV,eAAe,EAAE,gBAAgB,EACjC,WAAW,EAAE,YAAY,EACzB,WAAW,EAAE,YAAY,EACzB,eAAe,EAAE,gBAAgB,EACjC,iBAAiB,EAAE,kBAAkB,EAAE,oBAAoB,EAC3D,eAAe,EAAE,UAAU,EAAE,cAAc,EAC3C,aAAa,EAAE,cAAc,EAC7B,cAAc,EAAE,eAAe,GAChC,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/application/azure-sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAChG,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC9F,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1F,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACxE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAChH,YAAY,EACV,eAAe,EAAE,gBAAgB,EACjC,WAAW,EAAE,YAAY,EACzB,WAAW,EAAE,YAAY,EACzB,eAAe,EAAE,gBAAgB,EACjC,iBAAiB,EAAE,kBAAkB,EAAE,oBAAoB,EAC3D,eAAe,EAAE,UAAU,EAAE,cAAc,EAC3C,aAAa,EAAE,cAAc,EAC7B,cAAc,EAAE,eAAe,GAChC,MAAM,WAAW,CAAC"}

package/dist/application/azure-sync/index.js

@@ -7,4 +7,5 @@ export { AzurePrUseCases } from "./pr-use-cases.js";
 export { AzureFieldBuilder } from "./field-builders.js";
 export { ReverseFieldBuilder } from "./reverse-field-builder.js";
 export { TaskPushUseCases, buildTaskLocalId, parseTaskLocalId } from "./task-push-use-cases.js";
+export { AzurePollService, SyncEventUseCases } from "./poll-service.js";
 //# sourceMappingURL=index.js.map

package/dist/application/azure-sync/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/azure-sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/azure-sync/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIhG,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/application/azure-sync/poll-service.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Azure Sync Application — Poll Service
+ *
+ * Background service that periodically queries Azure DevOps for changes
+ * to mapped work items. Detects field edits, state changes, and revision
+ * bumps by comparing current rev against stored azureRevision in mappings.
+ *
+ * Emits events via a callback when changes are detected, and persists
+ * SyncEvent entities for later inspection by the agent.
+ *
+ * SOLID: SRP — polling orchestration and change detection only
+ * SOLID: OCP — new event types can be added without modifying detection loop
+ * SOLID: DIP — depends on repository/port abstractions
+ */
+import type { AzureDevOpsPort } from "../../domain/azure-sync/ports.js";
+import type { SyncMappingRepository, SyncEventRepository } from "../../domain/azure-sync/repositories.js";
+import type { SyncEventType } from "../../domain/azure-sync/value-objects.js";
+/** Notification payload emitted when changes are detected. */
+export interface PollNotification {
+    readonly eventCount: number;
+    readonly summary: string;
+    readonly events: readonly PollEventSummary[];
+}
+/** Individual event summary for notifications. */
+export interface PollEventSummary {
+    readonly workItemId: number;
+    readonly eventType: SyncEventType;
+    readonly changedBy: string;
+    readonly localId: string;
+}
+/** Dependencies for the poll service. */
+export interface PollServiceDeps {
+    readonly azureClient: AzureDevOpsPort;
+    readonly syncMappingRepo: SyncMappingRepository;
+    readonly syncEventRepo: SyncEventRepository;
+    readonly org: string;
+    readonly project: string;
+    /** Callback invoked when changes are detected. */
+    readonly onChangesDetected?: (notification: PollNotification) => void;
+    /** Callback for error logging. */
+    readonly onError?: (error: string) => void;
+}
+/**
+ * Background polling service for Azure DevOps change detection.
+ * Call start() to begin periodic polling, stop() to halt.
+ */
+export declare class AzurePollService {
+    private readonly deps;
+    private readonly intervalSecs;
+    private timer;
+    private _running;
+    private _pollCount;
+    private _lastPollAt;
+    constructor(deps: PollServiceDeps, intervalSecs: number);
+    /** Whether the service is currently running. */
+    get running(): boolean;
+    /** Number of completed poll cycles. */
+    get pollCount(): number;
+    /** ISO timestamp of the last poll. */
+    get lastPollAt(): string | undefined;
+    /** Start the polling loop. No-op if already running. */
+    start(): void;
+    /** Stop the polling loop. */
+    stop(): void;
+    /** Execute a single poll cycle. Exposed for testing. */
+    poll(): Promise<PollNotification | undefined>;
+}
+/** DTOs for event tool responses. */
+export interface SyncEventResponse {
+    readonly id: string;
+    readonly mappingId: string;
+    readonly azureWorkItemId: number;
+    readonly eventType: string;
+    readonly status: string;
+    readonly changedBy: string;
+    readonly changedFields: string;
+    readonly previousRevision: number;
+    readonly newRevision: number;
+    readonly detectedAt: string;
+}
+/** Use cases for managing sync events (list, acknowledge, dismiss). */
+export declare class SyncEventUseCases {
+    private readonly eventRepo;
+    constructor(eventRepo: SyncEventRepository);
+    /** List pending events. */
+    listPending(limit?: number): Promise<readonly SyncEventResponse[]>;
+    /** List recent events (all statuses). */
+    listRecent(limit?: number): Promise<readonly SyncEventResponse[]>;
+    /** Acknowledge an event by ID. */
+    acknowledge(eventId: string): Promise<string>;
+    /** Dismiss an event by ID. */
+    dismiss(eventId: string): Promise<string>;
+}
+//# sourceMappingURL=poll-service.d.ts.map

package/dist/application/azure-sync/poll-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-service.d.ts","sourceRoot":"","sources":["../../../src/application/azure-sync/poll-service.ts"],"names":[],"mappings":"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"}