@knowledgine/cli 0.1.0 → 0.2.0

package/fixtures/demo/notes/api-design-decisions.md

@@ -0,0 +1,79 @@
+---
+tags:
+  - api
+  - rest
+  - design
+author: demo-user
+project: backend-api
+---
+# REST API Design Decisions
+
+## Issue: Pagination Strategy
+Needed to decide between offset-based and cursor-based pagination
+for the search results endpoint.
+
+### Decision: Cursor-based pagination
+Offset pagination breaks when items are inserted/deleted during browsing.
+
+```typescript
+// Cursor-based pagination
+interface PaginatedResponse<T> {
+  data: T[];
+  cursor: string | null;  // null means no more pages
+  hasMore: boolean;
+}
+
+app.get("/api/notes", (req, res) => {
+  const { cursor, limit = 20 } = req.query;
+  const decoded = cursor ? decodeCursor(cursor) : null;
+
+  const notes = db.query(
+    `SELECT * FROM notes
+     WHERE ($1::text IS NULL OR id < $1)
+     ORDER BY id DESC LIMIT $2`,
+    [decoded?.id, limit + 1]
+  );
+
+  const hasMore = notes.length > limit;
+  const data = notes.slice(0, limit);
+
+  res.json({
+    data,
+    cursor: hasMore ? encodeCursor(data.at(-1)) : null,
+    hasMore,
+  });
+});
+```
+
+## Issue: Error Response Format
+Standardized error responses across all endpoints.
+
+### Solution: RFC 7807 Problem Details
+
+```typescript
+interface ProblemDetail {
+  type: string;
+  title: string;
+  status: number;
+  detail: string;
+  instance?: string;
+}
+
+// Error handler middleware
+app.use((err, req, res, _next) => {
+  const problem: ProblemDetail = {
+    type: `https://api.example.com/errors/${err.code}`,
+    title: err.title || "Internal Server Error",
+    status: err.status || 500,
+    detail: err.message,
+    instance: req.originalUrl,
+  };
+  res.status(problem.status).json(problem);
+});
+```
+
+## Learnings
+- Cursor-based pagination is more reliable for real-time data
+- Consistent error formats reduce client-side error handling complexity
+- Always version your API from the start (`/v1/`)
+- Document decisions in ADRs for future team members

package/fixtures/demo/notes/auth-debugging.md

@@ -0,0 +1,52 @@
+---
+tags:
+  - authentication
+  - jwt
+  - debugging
+author: demo-user
+project: backend-api
+---
+# Authentication Debugging Session
+
+## Problem
+JWT token validation was failing intermittently in production.
+Users reported being logged out randomly after 10-15 minutes,
+even though the token expiry was set to 1 hour.
+
+### Error Log
+```
+Error: TokenExpiredError: jwt expired
+  at /app/middleware/auth.ts:42:11
+  at processTicksAndRejections (node:internal/process/task_queues:95:5)
+```
+
+## Investigation
+- Checked server clock sync — NTP was configured correctly
+- Compared token `iat` (issued at) timestamps with server time
+- Found a 45-minute clock skew between API server and auth service
+
+## Solution
+The auth service was running in a container with a drifted system clock.
+
+```typescript
+// Added clock tolerance to JWT verification
+const decoded = jwt.verify(token, SECRET, {
+  clockTolerance: 60, // allow 60 seconds of clock skew
+});
+```
+
+Also fixed the root cause by enabling NTP sync in the Docker container:
+```dockerfile
+RUN apt-get update && apt-get install -y ntpdate
+CMD ntpdate -s pool.ntp.org && node server.js
+```
+
+## Learnings
+- Always configure clock tolerance for distributed JWT validation
+- Container clocks can drift if the host NTP is not propagated
+- Add monitoring for clock skew between services
+- The `clockTolerance` option is safer than extending token expiry
+
+## Time Spent
+Investigation: 2 hours
+Fix + deployment: 30 minutes

package/fixtures/demo/notes/ci-cd-pipeline.md

@@ -0,0 +1,90 @@
+---
+tags:
+  - ci-cd
+  - github-actions
+  - testing
+author: demo-user
+project: infrastructure
+---
+# CI/CD Pipeline Setup and Debugging
+
+## Problem
+The CI pipeline was taking 25 minutes per push, blocking the
+development workflow. Flaky tests caused unnecessary re-runs.
+
+## Investigation
+Analyzed GitHub Actions run logs:
+- Dependency install: 4 minutes (no caching)
+- Build: 3 minutes
+- Tests: 15 minutes (sequential, with 3 flaky tests)
+- Deploy: 3 minutes
+
+## Solution: Optimized Pipeline
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "pnpm"
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm build
+
+      - run: pnpm test:run --reporter=verbose
+        env:
+          CI: true
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+```
+
+### Flaky Test Fix
+```typescript
+// Before: timing-dependent test
+it("should debounce input", async () => {
+  fireEvent.change(input, { target: { value: "test" } });
+  await new Promise((r) => setTimeout(r, 300));
+  expect(onSearch).toHaveBeenCalledTimes(1);
+});
+
+// After: deterministic with fake timers
+it("should debounce input", () => {
+  vi.useFakeTimers();
+  fireEvent.change(input, { target: { value: "test" } });
+  vi.advanceTimersByTime(300);
+  expect(onSearch).toHaveBeenCalledTimes(1);
+  vi.useRealTimers();
+});
+```
+
+## Results
+- Pipeline time: 25 min → 8 min (68% reduction)
+- Flaky test rate: 15% → 0%
+- Developer satisfaction significantly improved
+
+## Learnings
+- Cache dependencies aggressively in CI
+- Run lint and tests in parallel jobs
+- Flaky tests erode trust — fix them immediately
+- Use `--frozen-lockfile` to catch dependency drift
+- Fake timers eliminate timing-based flakiness

package/fixtures/demo/notes/code-review-notes.md

@@ -0,0 +1,71 @@
+---
+tags:
+  - code-review
+  - best-practices
+  - team
+author: demo-user
+project: team-process
+---
+# Code Review Guidelines and Common Issues
+
+## Problem
+Code reviews were inconsistent. Some PRs got rubber-stamped while
+others received 50+ nitpick comments. Reviews took 2-3 days on average.
+
+## Solution: Review Checklist
+
+### What to Check
+1. **Correctness**: Does the code do what the PR description says?
+2. **Edge cases**: Null handling, empty arrays, boundary conditions
+3. **Security**: Input validation, SQL injection, XSS
+4. **Tests**: Are new behaviors covered? Are edge cases tested?
+5. **Naming**: Do variable/function names convey intent?
+
+### Common Issues Found in Reviews
+
+#### Error handling gaps
+```typescript
+// Bad: swallows errors silently
+try {
+  await saveUser(data);
+} catch {
+  // ignore
+}
+
+// Good: handle or propagate with context
+try {
+  await saveUser(data);
+} catch (error) {
+  logger.error("Failed to save user", { userId: data.id, error });
+  throw new ServiceError("User save failed", { cause: error });
+}
+```
+
+#### Missing input validation
+```typescript
+// Bad: trusts external input
+app.post("/api/users", (req, res) => {
+  db.query("INSERT INTO users (name) VALUES ($1)", [req.body.name]);
+});
+
+// Good: validate before processing
+app.post("/api/users", (req, res) => {
+  const { name } = req.body;
+  if (!name || typeof name !== "string" || name.length > 255) {
+    return res.status(400).json({ error: "Invalid name" });
+  }
+  db.query("INSERT INTO users (name) VALUES ($1)", [name]);
+});
+```
+
+## Process Improvements
+- Max review turnaround: 4 hours for small PRs, 1 day for large
+- Use "Request changes" only for blocking issues
+- Prefix comments: `nit:`, `question:`, `suggestion:`, `blocking:`
+- Author should self-review before requesting review
+
+## Learnings
+- Checklists reduce review inconsistency
+- Small PRs (< 300 lines) get better reviews and faster merges
+- Automate what you can (linting, formatting, type checking)
+- Focus reviews on logic and design, not style

package/fixtures/demo/notes/database-optimization.md

@@ -0,0 +1,73 @@
+---
+tags:
+  - database
+  - sql
+  - performance
+author: demo-user
+project: backend-api
+---
+# SQL Query Optimization and Indexing
+
+## Problem
+The notes search endpoint was timing out with 100k+ rows.
+Average query time was 4.2 seconds, causing user-visible latency.
+
+### Slow Query
+```sql
+SELECT n.*, COUNT(p.id) as pattern_count
+FROM notes n
+LEFT JOIN patterns p ON p.note_id = n.id
+WHERE n.content LIKE '%typescript%'
+  AND n.created_at > '2024-01-01'
+GROUP BY n.id
+ORDER BY n.created_at DESC
+LIMIT 20;
+```
+
+## Investigation
+Used `EXPLAIN ANALYZE` to identify bottlenecks:
+```sql
+EXPLAIN ANALYZE SELECT ...;
+-- Seq Scan on notes  (cost=0.00..12847.00 rows=100234 width=412)
+-- Filter: (content ~~ '%typescript%')
+-- Rows Removed by Filter: 95102
+```
+
+The sequential scan was reading every row.
+
+## Solution: Indexing Strategy
+
+```sql
+-- 1. B-tree index for date range queries
+CREATE INDEX idx_notes_created_at ON notes (created_at DESC);
+
+-- 2. Full-text search index instead of LIKE
+CREATE INDEX idx_notes_content_fts ON notes
+  USING GIN (to_tsvector('english', content));
+
+-- 3. Covering index for the common query pattern
+CREATE INDEX idx_patterns_note_id ON patterns (note_id);
+```
+
+### Rewritten Query
+```sql
+SELECT n.*, COUNT(p.id) as pattern_count
+FROM notes n
+LEFT JOIN patterns p ON p.note_id = n.id
+WHERE to_tsvector('english', n.content) @@ plainto_tsquery('typescript')
+  AND n.created_at > '2024-01-01'
+GROUP BY n.id
+ORDER BY n.created_at DESC
+LIMIT 20;
+```
+
+## Results
+- Query time: 4.2s → 18ms (233x improvement)
+- Index storage overhead: ~45MB (acceptable for 100k rows)
+
+## Learnings
+- `LIKE '%term%'` cannot use indexes — always use full-text search
+- `EXPLAIN ANALYZE` is the first tool to reach for
+- Covering indexes avoid table lookups for frequently joined columns
+- Monitor index bloat in write-heavy tables
+- Partial indexes can save space when queries filter on a condition

package/fixtures/demo/notes/docker-troubleshooting.md

@@ -0,0 +1,74 @@
+---
+tags:
+  - docker
+  - networking
+  - devops
+author: demo-user
+project: microservices
+---
+# Docker Container Networking Issues
+
+## Problem
+Containers in docker-compose could not communicate with each other.
+The API service failed to connect to the database container.
+
+```
+Error: connect ECONNREFUSED 127.0.0.1:5432
+```
+
+## Investigation
+- Verified both containers were running: `docker ps` showed healthy status
+- Checked network: `docker network ls` showed custom bridge network
+- The API was using `localhost` instead of the service name
+
+## Solution
+Docker containers have their own network namespace. Use the service
+name as the hostname, not `localhost`.
+
+```yaml
+# docker-compose.yml
+services:
+  api:
+    build: ./api
+    environment:
+      # Wrong: DB_HOST=localhost
+      DB_HOST: postgres  # Use service name
+      DB_PORT: 5432
+    depends_on:
+      postgres:
+        condition: service_healthy
+
+  postgres:
+    image: postgres:16
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U app"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+```
+
+## Additional Fix: DNS Resolution Timing
+Even with correct hostnames, the API started before DNS was ready.
+
+```typescript
+// Added retry logic for database connection
+async function connectWithRetry(maxRetries = 5): Promise<Pool> {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const pool = new Pool({ host: process.env.DB_HOST });
+      await pool.query("SELECT 1");
+      return pool;
+    } catch (err) {
+      console.log(`DB connection attempt ${i + 1} failed, retrying...`);
+      await new Promise((r) => setTimeout(r, 2000));
+    }
+  }
+  throw new Error("Could not connect to database");
+}
+```
+
+## Learnings
+- Never use `localhost` for inter-container communication
+- Use `depends_on` with health checks, not just service ordering
+- Add connection retry logic for resilience
+- `docker network inspect` is useful for debugging DNS issues

package/fixtures/demo/notes/react-performance.md

@@ -0,0 +1,66 @@
+---
+tags:
+  - react
+  - performance
+  - frontend
+author: demo-user
+project: dashboard-app
+---
+# React Performance Optimization
+
+## Issue
+The dashboard page was taking 3+ seconds to render with 500 items.
+React DevTools Profiler showed excessive re-renders on every state change.
+
+## Root Cause Analysis
+1. Parent component state changes triggered full list re-render
+2. Inline arrow functions in JSX created new references each render
+3. Large bundle size from importing entire icon library
+
+## Fix: Memoization
+
+```tsx
+// Before: re-renders on every parent state change
+const ListItem = ({ item, onClick }) => (
+  <div onClick={() => onClick(item.id)}>{item.name}</div>
+);
+
+// After: memoized with stable callback
+const ListItem = React.memo(({ item, onClick }) => (
+  <div onClick={onClick}>{item.name}</div>
+));
+
+// Parent: stable callback reference
+const handleClick = useCallback((id: string) => {
+  setSelectedId(id);
+}, []);
+```
+
+## Fix: Code Splitting
+
+```tsx
+// Before: eager import
+import { AnalyticsChart } from "./AnalyticsChart";
+
+// After: lazy loaded
+const AnalyticsChart = React.lazy(() => import("./AnalyticsChart"));
+
+function Dashboard() {
+  return (
+    <Suspense fallback={<Skeleton />}>
+      <AnalyticsChart data={data} />
+    </Suspense>
+  );
+}
+```
+
+## Results
+- Initial render: 3.2s → 0.8s (75% improvement)
+- Re-render on selection: 450ms → 12ms
+- Bundle size: 1.2MB → 680KB
+
+## Learnings
+- Profile before optimizing — measure actual bottlenecks
+- React.memo only helps when props are actually stable
+- Lazy loading is most effective for below-the-fold content
+- Tree-shaking icon libraries saves significant bundle size

package/fixtures/demo/notes/typescript-migration.md

@@ -0,0 +1,80 @@
+---
+tags:
+  - typescript
+  - migration
+  - refactoring
+author: demo-user
+project: legacy-app
+---
+# JavaScript to TypeScript Migration
+
+## Problem
+The legacy Express app (50+ files) had no type safety. Runtime errors
+were discovered only in production, and onboarding new developers
+took weeks due to lack of type documentation.
+
+## Migration Strategy
+Adopted an incremental approach instead of a big-bang rewrite.
+
+### Phase 1: Setup (Day 1)
+```jsonc
+// tsconfig.json - permissive start
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": false,
+    "strict": false,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"]
+}
+```
+
+### Phase 2: Rename files (Week 1)
+```bash
+# Renamed .js → .ts one directory at a time
+# Started with utility files that had no dependencies
+find src/utils -name "*.js" -exec bash -c 'mv "$0" "${0%.js}.ts"' {} \;
+```
+
+### Phase 3: Add types gradually (Week 2-4)
+```typescript
+// Before: implicit any everywhere
+function processUser(user) {
+  return { name: user.name, role: user.role || "viewer" };
+}
+
+// After: explicit types
+interface User {
+  id: string;
+  name: string;
+  role?: "admin" | "editor" | "viewer";
+}
+
+function processUser(user: User): { name: string; role: string } {
+  return { name: user.name, role: user.role ?? "viewer" };
+}
+```
+
+### Phase 4: Enable strict mode (Week 5)
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+## Results
+- Runtime type errors: 12/month → 0/month
+- Onboarding time: 3 weeks → 1 week
+- Refactoring confidence: significantly improved with IDE support
+
+## Learnings
+- Incremental migration is key — never stop shipping features
+- Start with leaf files (utilities), move inward to core logic
+- `@ts-expect-error` is better than `any` for tracking tech debt
+- Enable `strict` as soon as possible to avoid accumulating debt
+- The build time increase was negligible (< 2 seconds)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowledgine/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -16,11 +16,13 @@
   "dependencies": {
     "chokidar": "^5.0.0",
     "commander": "^14.0.3",
-    "@knowledgine/core": "0.1.0",
-    "@knowledgine/mcp-server": "0.1.0"
+    "@knowledgine/core": "0.2.0",
+    "@knowledgine/mcp-server": "0.2.0",
+    "@knowledgine/ingest": "0.2.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "fixtures"
   ],
   "description": "CLI for indexing markdown files and serving MCP knowledge tools",
   "mcpName": "io.github.3062-in-zamud/knowledgine",