@sprintdock/backend 0.4.2

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# @sprintdock/backend
+
+## 0.4.2
+
+### Patch Changes
+
+- chore: republish @sprintdock after auth token fix
+- Updated dependencies
+  - @sprintdock/env-manager@0.2.2
+  - @sprintdock/shared@0.2.2
+
+## 0.4.1
+
+### Patch Changes
+
+- chore: bump 7 workspace package(s) with a patch release.
+- Updated dependencies
+  - @sprintdock/env-manager@0.2.1
+  - @sprintdock/shared@0.2.1
+
+## Unreleased
+
+### Patch Changes
+
+- **REST:** **`GET /api/v1/dashboard-overview`** returns **200** with **`execution: { plan: null, activeSprints: [] }`** and **`throughput`** when there is no active plan (instead of surfacing **404**). Root **`GET /`** discovery JSON notes the separate **`@sprintdock/webui`** app and **`SPRINTDOCK_API_BASE_URL`**.
+- **MCP:** `create_task` and `bulk_create_tasks` use a single **`sprintIdOrSlug`** field (full UUID or sprint slug under the resolved plan), matching `get_sprint` / `get_sprint_detail` and producing JSON Schema that strict MCP clients accept. `list_sprints` lines include `| sprintId:<uuid>` and the footer points agents at **`sprintIdOrSlug`**.
+- **Tooling:** `drizzle.config.ts` uses an explicit **`Config`** type from `drizzle-kit` so the default export does not infer non-portable internal types (TypeScript / IDE clean).
+
+## 0.4.0
+
+### Minor Changes
+
+- **Sprints:** `markdownContent` on sprint entity, schema, HTTP `PATCH`, and MCP (`create_sprint` / `update_sprint` / `update_sprint_markdown`).
+- **Tasks:** `task_touched_files` table (repo-relative paths + `fileType`: test, implementation, doc, config, other), hydration on list/get, `create_task` / `update_task` / `PATCH /tasks/:id`, MCP `touchedFiles` on create/update.
+- **Plans:** `GET /plans/:slug/analytics` and plan–sprint task rollup DTO; MCP text formatters adjusted.
+- **Migrations:** `0001_sprint_markdown_content.sql`, `0002_task_touched_files.sql` (single-statement migration for SQLite drivers).
+
+### Patch Changes
+
+- Updated dependencies
+  - @sprintdock/env-manager@0.2.0
+  - @sprintdock/shared@0.2.0
+
+## 0.3.0
+
+### Minor Changes
+
+- MCP plugin architecture with 29 tools: rich actionable text, pagination, plan/sprint/task CRUD extensions, bulk create/status, task dependencies and progress tools; exports for registerSprintdockMcpTools and defaultSprintdockMcpPlugins; development guide in README.
+
+## 0.2.0
+
+### Breaking
+
+- **Package identity:** This package is now the **Drizzle + SQLite** implementation (REST `/api/v1`, `runSprintdockMcpServer`, nineteen MCP tools). The previous **JSON plan-tree–only** MCP stack that lived under the same name has been **removed** from the repository.
+
+### Added (carried forward from former `@sprintdock/backend-v2`)
+
+- SQLite at `.sprintdock/sprintdock.db` (optional `SPRINTDOCK_DB_PATH`), migrations under `drizzle/`, application services, Express HTTP API, MCP stdio and streamable HTTP transports.
+
+## 0.1.1 (historical — plan-tree MCP only)
+
+### Patch Changes
+
+- fix: improve init overwrite handling, align env resolution sources, and clean backend MCP runtime naming/defaults.
+- Updated dependencies
+  - @sprintdock/env-manager@0.1.1
+  - @sprintdock/shared@0.1.1
+
+## 0.1.0 (historical)
+
+### Minor Changes
+
+- chore: bump 7 workspace package(s) with a minor release.
+
+### Patch Changes
+
+- Updated dependencies
+  - @sprintdock/env-manager@0.1.0
+  - @sprintdock/shared@0.1.0
+
+## 0.0.1 (historical)
+
+### Patch Changes
+
+- chore: bump 7 workspace package(s) with a patch release.
+- Updated dependencies
+  - @sprintdock/env-manager@0.0.1
+  - @sprintdock/shared@0.0.1

package/README.md

@@ -0,0 +1,252 @@
+# `@sprintdock/backend`
+
+Sprintdock’s **SQLite-backed** backend: **Drizzle ORM**, **Express REST** under `/api/v1`, and a **Model Context Protocol (MCP)** server with **29** plan/sprint/task tools (rich agent-facing text, bulk helpers, and dependency tools). This package replaces the older JSON plan-tree implementation that previously shipped under the same name (see [CHANGELOG.md](./CHANGELOG.md)).
+
+**Version:** `0.3.0` (see `package.json`).  
+**Author:** Vikash Sharma.
+
+---
+
+## What you get
+
+| Layer | Responsibility |
+|--------|----------------|
+| **Domain** | Entities, repositories (interfaces), domain services (validation, transitions). |
+| **Application** | `PlanService`, `SprintService`, `TaskService` orchestrating repositories. |
+| **Infrastructure** | Drizzle repositories on **better-sqlite3**. |
+| **HTTP** | Express app factory, JSON body, CORS (optional), request IDs, Zod validation. |
+| **MCP** | Tool registration, stdio or HTTP transport, SQLite bootstrap and migrations. |
+
+---
+
+## Install & consume (workspace)
+
+This repo treats `@sprintdock/backend` as a **private** workspace package. Depend on it from other packages with:
+
+```json
+"@sprintdock/backend": "workspace:*"
+```
+
+Entry is ESM-only: `dist/index.js` + `dist/index.d.ts` (build before tools that read types from `dist`).
+
+---
+
+## Public API (`src/index.ts`)
+
+| Export | Purpose |
+|--------|---------|
+| `createApplicationServices` / `ServiceSet` | Wire app services from a `RepositorySet`. |
+| `createRepositories` / `RepositorySet` / `StorageConfig` | Build repositories (e.g. `sqlite`). |
+| `createHttpApp` / `HttpAppOptions` | Express app with `/api/v1` routes. |
+| `runSprintdockMcpServer` | One-shot MCP process (used by `apps/server`). |
+| `SprintdockMcpRuntime` / `SprintdockMcpRuntimeOptions` / `SprintdockMcpTransportMode` | Class-based MCP lifecycle (`stdio` \| `http`). |
+| `bootstrapSprintdockSqlite` / `SprintdockSqliteBootstrapResult` | Open DB, run migrations, return `ServiceSet` + paths. |
+| `registerSprintdockMcpTools` / `RegisterSprintdockMcpToolsOptions` | Register MCP tools on an SDK `McpServer` (uses `defaultSprintdockMcpPlugins` unless overridden). |
+| `defaultSprintdockMcpPlugins` / `SprintdockMcpToolPlugin` / related types | Plugin list and contract for custom or extended tool registration. |
+| `createSprintdockMcpToolKit` / `SprintdockMcpToolKit` | Shared Zod helpers (`optionalPlanSlug`, pagination, `jsonStructured`) for plugin authors. |
+
+---
+
+## Development guide
+
+Use this when you change domain logic, HTTP routes, or MCP tools.
+
+### Layout (`src/`)
+
+| Area | Path | Notes |
+| --- | --- | --- |
+| Domain | `domain/entities`, `domain/repositories`, `domain/services` | Entities, repo interfaces, status transitions & validation. |
+| Application | `application/*.service.ts`, `container.ts` | Orchestration; call domain services + repos. |
+| Infrastructure | `infrastructure/repositories/drizzle/` | SQLite implementations; row mappers. |
+| HTTP | `http/routes/v1/`, `http/middleware/` | Express + Zod (`schemas.ts`). |
+| MCP | `mcp/plugins/*.plugin.ts`, `mcp/register-sprintdock-mcp-tools.ts` | Tool registration; bootstrap/runtime/transports alongside. |
+| Text for agents | `mcp/mcp-text-formatters.ts` | Human-readable `content[0].text` for list/context tools; keep in sync with plugins. |
+| DB schema | `db/schema/` | Drizzle tables; pair changes with `pnpm --filter @sprintdock/backend run db:generate`. |
+
+### Workflow
+
+1. **Edit code** in `src/` (prefer small, focused changes per layer).
+2. **Schema change?** Update `db/schema/`, run `db:generate`, commit generated SQL under `drizzle/`.
+3. **New or changed behavior?** Add or extend tests under `tests/` (application, http, infrastructure, `tests/mcp/`).
+4. **Verify** (from repo root or this package):
+
+   ```bash
+   pnpm --filter @sprintdock/backend run build
+   pnpm --filter @sprintdock/backend run typecheck
+   pnpm --filter @sprintdock/backend test
+   ```
+
+5. **Consumers** (`apps/server`, etc.) resolve types from **`dist/`** after `build` — run build before relying on new exports.
+
+### Adding or changing MCP tools
+
+- Prefer a **plugin** under `src/mcp/plugins/` (or extend `defaultSprintdockMcpPlugins` in `default-plugins.ts`). Each plugin implements `SprintdockMcpToolPlugin` (`register(server, { deps, kit })`).
+- Use **`kit`** from `mcp-tool-kit.ts` for `optionalPlanSlug`, pagination fields, and `jsonStructured` for `structuredContent`.
+- **List/read tools** should return **actionable text** (slugs, titles, short ids) via helpers in `mcp-text-formatters.ts`, not only counts.
+- **Mutations** should call **`guardToolExecution`** (see existing plugins) so rate limit / auth stay consistent.
+- After adding a tool, update **`tests/mcp/register-sprintdock-mcp-tools.test.ts`** (`EXPECTED_TOOL_NAMES`) and this README’s tool list.
+
+### REST vs MCP
+
+REST and MCP share the same services and domain rules. If you add a capability only to MCP, consider whether `/api/v1` should expose it too for parity (see route files under `http/routes/v1/`).
+
+### Further docs
+
+- Root repo **Local Development** (requirements, `pnpm build`, smoke tests): [../../README.md](../../README.md).
+- Runtime wiring for MCP: [SERVER.md](./SERVER.md).
+
+---
+
+## Environment
+
+Resolution order (low → high): `~/.sprintdock/.env` → `<workspace>/.sprintdock/.env` → `process.env` (via `@sprintdock/env-manager`). See **[`packages/env-manager/.env.example`](../env-manager/.env.example)** for a full template.
+
+| Variable | Role |
+|----------|------|
+| `SPRINTDOCK_DB_PATH` | Optional SQLite file path. Absolute, or relative to workspace root. Default: `<workspace>/.sprintdock/sprintdock.db`. |
+| `SPRINTDOCK_MCP_TRANSPORT` | `stdio` (default) or `http`. |
+| `SPRINTDOCK_MCP_HTTP_HOST` | Bind host when transport is `http` (default `127.0.0.1`). |
+| `SPRINTDOCK_MCP_HTTP_PORT` | Port when transport is `http` (default `3030`). |
+
+---
+
+## Database & migrations
+
+- **Driver:** [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) (requires a compatible Node version; prebuilds cover current LTS targets).
+- **ORM:** [Drizzle](https://orm.drizzle.team/).
+- **Migrations:** SQL files under [`drizzle/`](./drizzle/). At runtime, `runMigrations` locates `drizzle/meta/_journal.json` by walking up from the loaded module so it works from both `src` and bundled `dist`.
+- **Schema:** `src/db/schema/` — plans, sprints, tasks (and relations).
+
+Generate new migrations after schema changes:
+
+```bash
+pnpm --filter @sprintdock/backend run db:generate
+```
+
+---
+
+## REST API
+
+Base path: **`/api/v1`** (mount `createHttpApp` at the server root so routes are `/api/v1/...`).
+
+### Health
+
+| Method | Path |
+|--------|------|
+| `GET` | `/health` |
+
+### Plans & context
+
+| Method | Path |
+|--------|------|
+| `GET` | `/plans` |
+| `POST` | `/plans` |
+| `GET` | `/plans/:idOrSlug` |
+| `PATCH` | `/plans/:idOrSlug` |
+| `POST` | `/plans/:idOrSlug/activate` |
+| `GET` | `/execution-context` |
+
+### Sprints
+
+| Method | Path |
+|--------|------|
+| `GET` | `/plans/:planId/sprints` |
+| `POST` | `/plans/:planId/sprints` |
+| `GET` | `/sprints/:id` |
+| `PATCH` | `/sprints/:id/status` |
+
+### Tasks
+
+| Method | Path |
+|--------|------|
+| `GET` | `/sprints/:sprintId/tasks` |
+| `POST` | `/sprints/:sprintId/tasks` |
+| `GET` | `/tasks/:id` |
+| `PATCH` | `/tasks/:id/status` |
+| `PATCH` | `/tasks/:id/assign` |
+| `POST` | `/tasks/:id/move` |
+| `DELETE` | `/tasks/:id` |
+
+Request/response shapes are validated with Zod in `src/http/routes/v1/schemas.ts`.
+
+### Domain enums (API / MCP)
+
+- **Plan status:** `draft` \| `active` \| `completed` \| `archived` (see domain entity).
+- **Sprint status:** `planned` \| `active` \| `completed` \| `archived` (transitions enforced in domain).
+- **Task status:** `todo` \| `in_progress` \| `blocked` \| `done`.
+- **Task priority:** `low` \| `medium` \| `high` \| `critical`.
+
+---
+
+## MCP
+
+- **Server name:** `sprintdock-backend` (SDK `McpServer` metadata).
+- **Transports:** **stdio** (default) or **HTTP** (streamable HTTP entry in `src/mcp/transports/`).
+- **Bootstrap:** Opens SQLite, ensures `.sprintdock` directory as needed, runs migrations, wires `registerSprintdockMcpTools` with in-memory rate limiting, local auth context, request correlation, and console audit logging.
+
+### Tools (29)
+
+**Plans:** `list_plans` (optional `limit`/`offset`, `total`), `create_plan`, `set_active_plan`, `get_active_plan`, `get_plan_summary`, `update_plan_markdown`, `delete_plan`, `update_plan`, `get_plan_progress`.
+
+**Context:** `get_execution_context`, `get_sprint_detail`.
+
+**Sprints:** `create_sprint`, `list_sprints` (optional pagination), `get_sprint` (`sprintIdOrSlug`), `update_sprint_status` (`sprintIdOrSlug`), `delete_sprint` (`sprintIdOrSlug`), `update_sprint` (`sprintIdOrSlug`).
+
+**Tasks:** `create_task`, `list_tasks` (optional pagination), `get_task`, `update_task_status`, `assign_task`, `move_task`, `delete_task`, `update_task`, `bulk_create_tasks`, `bulk_update_task_status`, `get_task_dependencies`, `update_task_dependencies`.
+
+List/read tools format **actionable lines** in `content[0].text` (slugs, titles, short ids, counts). Many tools accept optional **`planSlug`** to target a non-active plan. Mutations go through **`guardToolExecution`** (rate limit / auth).
+
+### Plugin-style registration
+
+Tools are registered from small **plugins** under `src/mcp/plugins/` (plan, context, sprint, task, task-workflow). `registerSprintdockMcpTools(server, deps)` runs `defaultSprintdockMcpPlugins` in order. To add tools, pass a custom list (or append to the default):
+
+```ts
+import {
+  defaultSprintdockMcpPlugins,
+  registerSprintdockMcpTools,
+  type SprintdockMcpToolPlugin
+} from "@sprintdock/backend";
+
+const myPlugin: SprintdockMcpToolPlugin = {
+  id: "acme/extra-tools",
+  register(server, { deps, kit }) {
+    server.registerTool(/* name, schema, handler */);
+  }
+};
+
+registerSprintdockMcpTools(server, deps, {
+  plugins: [...defaultSprintdockMcpPlugins, myPlugin]
+});
+```
+
+Shared Zod fields and helpers live in `mcp/plugins/mcp-tool-kit.ts` (`kit` on the plugin context). Advanced use: import `createSprintdockMcpToolKit` from `./mcp/plugins/mcp-tool-kit.js` in-repo.
+
+---
+
+## Scripts (`package.json`)
+
+| Script | Command |
+|--------|---------|
+| `build` | `tsup` ESM bundle + `.d.ts` to `dist/`. |
+| `typecheck` | `tsc --noEmit`. |
+| `test` | Node test runner with `tsx` import hook (`tests/**/*.test.ts`). |
+| `db:generate` | `drizzle-kit generate`. |
+| `clean` | Remove `dist/`. |
+
+---
+
+## Verify locally
+
+```bash
+pnpm --filter @sprintdock/backend run build
+pnpm --filter @sprintdock/backend run typecheck
+pnpm --filter @sprintdock/backend test
+```
+
+---
+
+## Further reading
+
+- **[Development guide](#development-guide)** — Package layout, MCP plugins, tests, and workflow (above).
+- **[SERVER.md](./SERVER.md)** — Runtime notes (what calls `runSprintdockMcpServer`, verify commands).
+- **[CHANGELOG.md](./CHANGELOG.md)** — Version history and breaking changes (`0.2.0` migration from plan-tree MCP).

package/SERVER.md

@@ -0,0 +1,25 @@
+# `@sprintdock/backend` runtime notes
+
+## What this package is
+
+`@sprintdock/backend` provides:
+
+- **SQLite** persistence (default `.sprintdock/sprintdock.db`, override with `SPRINTDOCK_DB_PATH`)
+- **REST** via `createHttpApp` → `/api/v1/*`
+- **MCP** via `runSprintdockMcpServer` / `SprintdockMcpRuntime` (stdio or HTTP)
+
+`apps/server` MCP mode calls **`runSprintdockMcpServer`** from this package.
+
+**REST** can be started from the same binary with **`sprintdock serve`**, which mounts **`createHttpApp`** and listens on **`SPRINTDOCK_REST_HTTP_HOST`** / **`SPRINTDOCK_REST_HTTP_PORT`** (default `127.0.0.1:8787`). See `packages/env-manager/.env.example`.
+
+## Environment
+
+See **`packages/env-manager/.env.example`**. Resolution: `~/.sprintdock/.env` → `<workspace>/.sprintdock/.env` → `process.env`.
+
+## Verify
+
+```bash
+pnpm --filter @sprintdock/backend typecheck
+pnpm --filter @sprintdock/backend test
+pnpm --filter @sprintdock/backend run build
+```