KnoTrack v1: initial 5-tool MCP scaffold, dogfooding, adversarial-review fixes

.env.example

@@ -0,0 +1,54 @@
+# KnoTrack environment configuration.
+# Copy to .env for local development. See docs/TRD.md §7 for full details
+# on every variable below.
+
+# --- Required ---
+
+# Postgres connection string. postgres://user:pass@host:port/db
+DATABASE_URL=postgres://knotrack_app:knotrack_dev_pw@127.0.0.1:5432/knotrack_scratch
+
+# Comma-separated list of accepted bearer tokens (TRD §4). The server
+# refuses to boot if this is unset or empty. Generate one with:
+#   npm run generate-token
+KNOTRACK_API_TOKENS=kt_dev_local_token_change_me
+
+# Base64-encoded 32-byte key for AES-256-GCM adapter-credential
+# encryption (TRD §5). Generate with: openssl rand -base64 32
+KNOTRACK_ENCRYPTION_KEY=
+
+# --- Optional (defaults shown) ---
+
+NODE_ENV=development
+PORT=8080
+HOST=0.0.0.0
+
+# "require" in production, "disable" otherwise.
+DATABASE_SSL_MODE=disable
+
+# Verify the Postgres server's TLS certificate when DATABASE_SSL_MODE=require
+# (default: true). Only set to false for a broken/self-signed local dev
+# certificate — never in production, or the TLS channel is encrypted but
+# unauthenticated (vulnerable to MITM).
+KNOTRACK_DB_SSL_REJECT_UNAUTHORIZED=true
+
+# Postgres statement_timeout in ms — bounds how long any single query may
+# run before Postgres cancels it, so a slow/deadlocked query can't hang a
+# request indefinitely.
+KNOTRACK_DB_STATEMENT_TIMEOUT_MS=30000
+
+KNOTRACK_DB_POOL_MAX=10
+
+KNOTRACK_DRIFT_SCAN_TRACK_CAP=500
+KNOTRACK_DRIFT_SCAN_ITEM_CAP=5000
+KNOTRACK_DRIFT_SCAN_TIMEOUT_MS=5000
+
+KNOTRACK_ROADMAP_TRACK_CAP=200
+KNOTRACK_ROADMAP_ITEM_PER_TRACK_CAP=100
+
+KNOTRACK_STALE_TRACK_DAYS=14
+KNOTRACK_NEXT_STEPS_LIMIT=5
+
+KNOTRACK_GITHUB_SYNC_TIMEOUT_MS=8000
+KNOTRACK_LINEAR_SYNC_TIMEOUT_MS=8000
+
+LOG_LEVEL=info

.gitignore

@@ -1,143 +1,8 @@
-# Logs
-logs
-*.log
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-lerna-debug.log*
-
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
-# Dependency directories
 node_modules/
-jspm_packages/
-
-# Snowpack dependency directory (https://snowpack.dev/)
-web_modules/
-
-# TypeScript cache
-*.tsbuildinfo
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Optional stylelint cache
-.stylelintcache
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variable files
+dist/
+coverage/
 .env
-.env.*
-!.env.example
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-.parcel-cache
-
-# Next.js build output
-.next
-out
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-.output
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and not Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# vuepress v2.x temp directory
-.temp
-
-# Sveltekit cache directory
-.svelte-kit/
-
-# vitepress build output
-**/.vitepress/dist
-
-# vitepress cache directory
-**/.vitepress/cache
-
-# Docusaurus cache and generated files
-.docusaurus
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# Firebase cache directory
-.firebase/
-
-# TernJS port file
-.tern-port
-
-# Stores VSCode versions used for testing VSCode extensions
-.vscode-test
-
-# pnpm
-.pnpm-store
-
-# yarn v3
-.pnp.*
-.yarn/*
-!.yarn/patches
-!.yarn/plugins
-!.yarn/releases
-!.yarn/sdks
-!.yarn/versions
-
-# Vite files
-vite.config.js.timestamp-*
-vite.config.ts.timestamp-*
-.vite/
+*.log
+.adversarial-review/
+.stryker-tmp/
+stryker-report.json

.prettierignore

@@ -0,0 +1,4 @@
+dist
+node_modules
+coverage
+docs

.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always"
+}

Dockerfile

@@ -0,0 +1,34 @@
+# KnoTrack — self-hosted MCP server
+# Multi-stage build: compile TypeScript, then run the plain JS output on a
+# slim Node 20 base with only production dependencies installed.
+
+FROM node:20.20-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY tsconfig.json ./
+COPY src ./src
+COPY scripts ./scripts
+RUN npm run build
+
+FROM node:20.20-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+COPY --from=build /app/dist ./dist
+# scripts/migrate.ts resolves MIGRATIONS_DIR relative to its own compiled
+# location (dist/scripts/migrate.js -> dist/migrations), so the SQL files
+# must land there, not at /app/migrations.
+COPY migrations ./dist/migrations
+
+# Run as the non-root user node:20.20-slim already ships (uid 1000), not root.
+USER node
+
+# Migrations are run as a separate deploy-time step (docs/TRD.md §7/§8),
+# never automatically on container start, e.g.:
+#   docker run --rm --env-file .env <image> node dist/scripts/migrate.js
+EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
+  CMD node -e "require('http').get('http://127.0.0.1:8080/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"
+CMD ["node", "dist/src/index.js"]

NOTICE

@@ -0,0 +1,21 @@
+KnoTrack
+Copyright 2026 Paul Poulose
+
+This product includes software developed as part of the KnoTrack project
+(https://github.com/SathiaAI/KnoTrack).
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License. You may obtain a copy
+of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+If you redistribute KnoTrack or a derivative work, in source or binary
+form, §4(d) of the License requires that the attribution notices below
+remain available to recipients — in a NOTICE file, in source-file headers,
+in accompanying documentation, or wherever a display of third-party
+notices would normally appear. You may add your own attribution notices
+alongside these; NOTICE-file content does not modify the License's terms.
+Retaining these notices (in whatever form) is how downstream users find
+their way back to the original project and its license terms — please
+don't strip them, even in a fork.