ndomo 0.1.0

package/.bun-version

@@ -0,0 +1 @@
+1.3.14

package/.dockerignore

@@ -0,0 +1,79 @@
+# VCS
+.git/
+.gitignore
+
+# Dependencies (regenerated in image)
+node_modules/
+.pnp/
+.pnp.js
+.yarn/
+
+# Build output
+dist/
+build/
+out/
+*.tsbuildinfo
+
+# OpenCode / ndomo runtime state
+.slim/
+.worktrees/
+.ndomo/
+.opencode/
+.opencode-mem/
+
+# DCP data
+.dcp/
+dcp-prompts/
+
+# Databases — never bake into image
+*.sqlite
+*.sqlite-journal
+*.sqlite-shm
+*.sqlite-wal
+
+# Environment / secrets — NEVER bake into image
+.env
+.env.*
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+logs/
+
+# Coverage
+coverage/
+.nyc_output/
+
+# OS artifacts
+.DS_Store
+Thumbs.db
+
+# Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Documentation (not needed at runtime)
+docs/
+CHANGELOG.md
+README.md
+README.es.md
+
+# Test files (not needed at runtime)
+*.test.ts
+*.test.js
+
+# Miscellaneous
+*.tgz
+.cache/
+.agents/
+skills-lock.json
+
+# Docker metadata (not needed in image)
+Dockerfile
+.dockerignore

package/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

package/.env.example

@@ -0,0 +1,19 @@
+# ndomo HTTP Server Configuration (Phase 1)
+# All settings have sensible defaults — only OPENCODE_SERVER_PASSWORD is required when auth is enabled.
+
+# Enable/disable the HTTP server (default: false)
+NDOMO_HTTP_ENABLED=false
+
+# HTTP server port (default: 4097, avoids conflict with OpenCode default 4096)
+NDOMO_HTTP_PORT=4097
+
+# CORS origins (comma-separated, default: * in dev, empty in prod)
+# Example: http://localhost:3000,https://dashboard.example.com
+NDOMO_HTTP_CORS_ORIGINS=*
+
+# HTTP Basic Auth password (required when http.auth.required=true)
+# If not set and auth.required=true, server returns 503 on startup
+OPENCODE_SERVER_PASSWORD=
+
+# OpenCode server URL for SDK client (default: http://localhost:4096)
+OPENCODE_SERVER_URL=http://localhost:4096

package/.github/CODEOWNERS

@@ -0,0 +1,8 @@
+# Default owners for everything in the repo
+* @nicosup98
+
+# CI/CD workflows and automation
+.github/ @nicosup98
+
+# Package and build configuration
+package.json @nicosup98

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,62 @@
+name: Bug Report
+description: Report a bug in ndomo
+title: "[bug]: "
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What went wrong?
+      placeholder: A clear description of the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: How can we reproduce the issue?
+      placeholder: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What should have happened?
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened?
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      description: What operating system are you using?
+      placeholder: e.g. Ubuntu 24.04, macOS 14
+    validations:
+      required: true
+  - type: input
+    id: bun-version
+    attributes:
+      label: Bun version
+      description: What bun version are you using? (run `bun --version`)
+      placeholder: e.g. 1.3.14
+    validations:
+      required: true
+  - type: input
+    id: ndomo-version
+    attributes:
+      label: ndomo version
+      description: What ndomo version are you using?
+      placeholder: e.g. 0.1.0
+    validations:
+      required: false

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+blank_issues_enabled: true
+contact_links: []

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,34 @@
+name: Feature Request
+description: Suggest a new feature for ndomo
+title: "[feature]: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What feature do you want?
+      placeholder: A clear description of the feature.
+    validations:
+      required: true
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem it solves
+      description: What problem does this solve that isn't possible today?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How would you implement this?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What other approaches did you think about?
+    validations:
+      required: false

package/.github/dependabot.yml

@@ -0,0 +1,36 @@
+# .github/dependabot.yml
+# Dependabot config: weekly auto-PRs for npm + github-actions
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    groups:
+      production:
+        applies-to: version-updates
+        dependency-type: "production"
+      development:
+        applies-to: version-updates
+        dependency-type: "development"
+    commit-message:
+      prefix: "chore(deps)"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "ci(actions)"
+    # Auto-merge patch updates for actions (they're already SHA-pinned,
+    # so updates only happen when we bump SHAs intentionally)
+    automerge: false  # keep manual review

package/.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Description
+
+<!-- What does this PR do? Why is this change needed? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] Feature
+- [ ] Breaking change
+- [ ] Documentation
+- [ ] Refactor
+- [ ] Chore (maintenance, deps, CI)
+
+## Checklist
+
+- [ ] Tests added/updated (if applicable)
+- [ ] Lint passes
+- [ ] Typecheck passes
+- [ ] Smoke test passes
+- [ ] Docs updated (if needed)
+
+## Related issue
+
+<!-- Closes #N or "No related issue" -->

package/.github/release.yml

@@ -0,0 +1,30 @@
+# Configures GitHub release notes auto-generation
+# See: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes
+changelog:
+  exclude:
+    labels:
+      - ignore-for-release
+      - duplicate
+      - invalid
+  categorize:
+    - title: Breaking Changes
+      labels:
+        - breaking-change
+        - breaking
+    - title: 🚀 Features
+      labels:
+        - enhancement
+        - feature
+    - title: 🐛 Bug Fixes
+      labels:
+        - bug
+        - fix
+    - title: 📚 Documentation
+      labels:
+        - documentation
+        - docs
+    - title: 🔧 Maintenance
+      labels:
+        - chore
+        - dependencies
+        - ci

package/.github/workflows/gitleaks.yml

@@ -0,0 +1,28 @@
+# .github/workflows/gitleaks.yml
+# Secret scanning via gitleaks
+name: gitleaks
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  scan:
+    name: gitleaks scan
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Run gitleaks
+        uses: gitleaks/gitleaks-action@ff98106e4c7b2bc287b24eaf42907196329070c7  # v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_ENABLE_UPLOAD_ARTIFACT: true
+          GITLEAKS_ENABLE_SUMMARY: true

package/.github/workflows/release-please.yml

@@ -0,0 +1,27 @@
+# Copyright 2026 — ndomo-v2 contributors
+# SPDX-License-Identifier: MIT
+#
+# Release-please workflow — automated versioning + GitHub Releases
+# Pinned to v5.0.0 commit SHA (audit MISSING-007 principle).
+# See: https://github.com/googleapis/release-please-action
+
+name: release-please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        with:
+          release-type: node
+          package-name: ndomo
+          config-file: release-please-config.json

package/.github/workflows/smoke.yml

@@ -0,0 +1,29 @@
+name: smoke
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  smoke:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04, macos-latest]
+        bun-version: ['1.3.14', 'latest']
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6  # v2
+        with:
+          bun-version: ${{ matrix.bun-version }}
+          cache: true
+      - run: bun install
+      - name: Security audit (bun audit)
+        run: bun audit --audit-level=high
+      - run: bun run lint
+      - run: bun run typecheck
+      - run: bun test
+      - run: bun run test:smoke

package/.husky/commit-msg

@@ -0,0 +1 @@
+bunx --no -- commitlint --edit ${1}

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Ranger agent** — 4th primary agent (`mode: primary`, `model:
+  minimax/MiniMax-M3`, `temp: 0.3`) for analysis/cartography/onboarding
+  workflows. Read-write guard rails: `edit: deny` for source code,
+  `write: ask`, `bash: ask` with read-only allowlist. Delegates to
+  `scout` / `sage` / `scribe` for mapping and research.
+- **`analyses` table + FTS5** — standalone SQLite table for persisted
+  research output (slug, title, project_path, summary, findings_json,
+  source_plan_id, agent, session_id, archived_at). External-content
+  FTS5 index over `title` + `summary` + `findings_json` with sync
+  triggers. Migration v14.
+- **Analysis CRUD module** (`src/db/analyses.ts`) — `createAnalysis`,
+  `getAnalysis`, `getAnalysisBySlug`, `listAnalyses`, `searchAnalyses`
+  (FTS), `updateAnalysis`, `archiveAnalysis`, `linkAnalysisToPlan`,
+  `unlinkAnalysisFromPlan`. 40 unit tests covering FK validation,
+  FTS sync, soft-delete, and slug uniqueness.
+- **7 analysis tools** registered in the OpenCode plugin:
+  `analysis_create`, `analysis_get`, `analysis_list`,
+  `analysis_search`, `analysis_update`, `analysis_archive`,
+  `analysis_link_plan`.
+- **`ndomo-analyses` CLI** — `list` / `get` / `search` / `archive`
+  subcommands reading from the project-local `.ndomo/state.db`.
+- **Integration test suite** (`tests/integration/ranger-flow.test.ts`)
+  — 13 end-to-end tests covering create→link→search→archive→unlink
+  flows and FK CASCADE behavior on plan deletion.
+
+### Changed
+
+- Updated `docs/agents.md` from 21 agents (3 primaries) to 22 agents
+  (4 primaries), including cross-primary routing table for the new
+  ranger entry point.
+- Routing tables in `foreman.md`, `craftsman.md`, and `warden.md`
+  now list ranger alongside the existing primary peers.
+
+### Fixed
+
+- DB hygiene: enable WAL journal mode, NORMAL synchronous, INCREMENTAL
+  auto_vacuum to prevent unbounded `.ndomo/state.db` growth on long-running
+  installs. Sticky one-time migration per DB on first open after upgrade.
+  New `ndomo vacuum` CLI subcommand (or `bun run src/cli/vacuum.ts`) for
+  manual space reclaim via `PRAGMA incremental_vacuum` + `wal_checkpoint(TRUNCATE)`.
+  WAL sidecars (`*.db-wal`, `*.db-shm`) added to `.gitignore`.
+- Shutdown cleanup: `src/db/shutdown.ts` now tracks every `openDb()` call in
+  a `Set<Database>` so each connection gets `SIGTERM`/`SIGINT`/`beforeExit`
+  cleanup. Replaces the module-level `registered` boolean that silently
+  skipped every call after the first (leaked file handles on hot-reload,
+  CLI tools alongside plugin, smoke tests).
+- Background task retention: `BackgroundDispatcher.finalize(maxAgeMs)` prunes
+  terminal tasks (completed/failed/cancelled) older than the threshold; auto-
+  called from plugin init when row count exceeds `backgroundRetention.softCap`
+  (default 1000). Stops unbounded growth of `background_tasks` on long-running
+  installs.
+- Write-tool lock leaks: replaced raw `Map<string, string>` for active writes
+  with a `FileLock` class that stamps each entry with `setAt` and prunes stale
+  locks via TTL sweep. SDK hook-chain breaks (where `tool.execute.after` never
+  fires) no longer block subsequent writes indefinitely. Admin tool
+  `ndomo_write_unlock` exposed for manual recovery.
+
+## [0.1.0] - 2026-06-20
+
+### Added
+
+- Initial ndomo orchestrator: `routeTask`, `canRunParallel`, and reconciler
+  primitives for multi-agent task dispatch and lifecycle management
+- Multi-agent fleet: `foreman` and `craftsman` primaries plus 19 specialist
+  subagents (scout, scribe, painter, smith, sage, guild, inspector,
+  chronicler, stack-smiths, and warden ops fleet)
+- OpenCode plugin layer with hooks, custom tools, hot-swap support, and
+  frontmatter sync for agent and skill metadata
+- DB module: SQLite-backed plans, tasks, and sessions tables with FTS5 search,
+  migrations v1 through v11, and dual plan system (global state.db +
+  per-project archive)
+- Memory system integration with `opencode-mem` including scoped tags,
+  cross-project retrieval, and project-scoped instincts to prevent
+  cross-project contamination
+- Worktree management under `.slim/worktrees/` for parallel, isolated coding
+  lanes
+- Flexible builder pipeline (v2 + v3-lows) and `craftsman` primary agent with
+  plan_db audit trail and pre-merge critical fixes
+- Curl-based install script with provider picker (ndomo vs stock OpenCode)
+- `reasoning_effort` configuration and bundled skills directory for offline
+  distribution
+- `state.db` CLI with 14 tools and 5 migrations covering plan/task/session
+  CRUD, FTS search, and checkpoint helpers
+
+### Changed
+
+- Biome-formatted source tree across all TypeScript modules
+- Documentation refresh covering DB module, flexible builder primary, and
+  ad-hoc flow spec
+
+### Fixed
+
+- Per-project plan archive: drop the global `~/.ndomo/mem/plans` default in
+  favor of project-local storage
+- Scoped session foreign-key upsert (Issue #1 hybrid) so session rows respect
+  plan scoping rules
+- DB query layer: `getPlan`, `getPlanBySlug`, and `listPlans` now JOIN with
+  `plan_files` so file links ship with every plan read
+- Seven medium-priority `craftsman` fixes shipped alongside the Bun skill
+  bootstrap for the `js-smith` specialist
+
+[Unreleased]: https://github.com/nicosup98/ndomo-v2/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nicosup98/ndomo-v2/releases/tag/v0.1.0

package/Dockerfile

@@ -0,0 +1,32 @@
+# ndomo — OpenCode multi-agent plugin container image
+# Entry point: bun run src/index.ts
+# Base image pinned to bun version from .bun-version (never use `latest`).
+# Multi-stage build keeps final image lean (distroless, no shell).
+
+# ---- Stage 1: Install dependencies ----
+FROM oven/bun:1.3.14-distroless AS deps
+WORKDIR /app
+
+# Copy package manifests first for layer caching (deps only rebuild when manifests change)
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile
+
+# Copy application source, bundled assets, and configuration
+COPY src/ ./src/
+COPY skills/ ./skills/
+COPY agents/ ./agents/
+COPY config/ ./config/
+COPY scripts/ ./scripts/
+COPY bin/ ./bin/
+COPY tools/ ./tools/
+COPY opencode.json tsconfig.json biome.json ./
+
+# ---- Stage 2: Runtime ----
+FROM oven/bun:1.3.14-distroless
+WORKDIR /app
+
+COPY --from=deps /app /app
+
+# Plugins are invoked by the OpenCode host; peer deps provided at runtime.
+# JSON-array form avoids shell dependency (distroless has no shell).
+ENTRYPOINT ["bun", "run", "src/index.ts"]