inkdex 0.0.1

package/test/unit/db.test.ts

@@ -0,0 +1,190 @@
+import assert from "node:assert";
+import { rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import {
+  closeDb,
+  dbPath,
+  getAllChunks,
+  getAllDocumentHashes,
+  getChunkCount,
+  insertChunk,
+  openDb,
+  removeDocument,
+  runInTransaction,
+  searchFts,
+  setDocumentHash,
+} from "../../src/store/db.js";
+
+const TEST_DOCS_PATH = join(tmpdir(), "inkdex-test-db-" + process.pid);
+
+describe("dbPath", () => {
+  it("should return the same path for the same docs directory", () => {
+    assert.strictEqual(dbPath("/home/user/docs"), dbPath("/home/user/docs"));
+  });
+
+  it("should return different paths for different docs directories", () => {
+    assert.notStrictEqual(
+      dbPath("/home/user/docs-a"),
+      dbPath("/home/user/docs-b"),
+    );
+  });
+
+  it("should end with .db", () => {
+    assert.ok(dbPath("/any/path").endsWith(".db"));
+  });
+});
+
+describe("db operations", () => {
+  beforeEach(() => {
+    openDb(TEST_DOCS_PATH);
+  });
+
+  afterEach(() => {
+    closeDb();
+    try {
+      rmSync(dbPath(TEST_DOCS_PATH), { force: true });
+      rmSync(`${dbPath(TEST_DOCS_PATH)}-wal`, { force: true });
+      rmSync(`${dbPath(TEST_DOCS_PATH)}-shm`, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  });
+
+  it("should start with zero chunks", () => {
+    assert.strictEqual(getChunkCount(), 0);
+  });
+
+  it("should start with no document hashes", () => {
+    const hashes = getAllDocumentHashes();
+    assert.deepStrictEqual(hashes, {});
+  });
+
+  it("should store and retrieve document hashes", () => {
+    setDocumentHash("readme.md", "abc123");
+    const hashes = getAllDocumentHashes();
+    assert.strictEqual(hashes["readme.md"], "abc123");
+  });
+
+  it("should upsert document hashes", () => {
+    setDocumentHash("readme.md", "abc123");
+    setDocumentHash("readme.md", "def456");
+    const hashes = getAllDocumentHashes();
+    assert.strictEqual(hashes["readme.md"], "def456");
+  });
+
+  it("should insert and retrieve chunks", () => {
+    setDocumentHash("doc.md", "hash1");
+    const embedding = [0.1, 0.2, 0.3];
+    insertChunk("doc.md", "Doc Title", "Section", "Some text", {}, embedding);
+
+    const chunks = getAllChunks();
+    assert.strictEqual(chunks.length, 1);
+    assert.strictEqual(chunks[0].path, "doc.md");
+    assert.strictEqual(chunks[0].fileHeading, "Doc Title");
+    assert.strictEqual(chunks[0].heading, "Section");
+    assert.strictEqual(chunks[0].text, "Some text");
+    assert.deepStrictEqual(chunks[0].metadata, {});
+  });
+
+  it("should round-trip embeddings through blob conversion", () => {
+    setDocumentHash("doc.md", "hash1");
+    const embedding = [0.1, 0.2, 0.3, -0.5, 1.0];
+    insertChunk("doc.md", "Title", "Heading", "text", {}, embedding);
+
+    const chunks = getAllChunks();
+    assert.strictEqual(chunks[0].embedding.length, embedding.length);
+    for (let i = 0; i < embedding.length; i++) {
+      assert.ok(
+        Math.abs(chunks[0].embedding[i] - embedding[i]) < 1e-6,
+        `embedding[${i}] mismatch`,
+      );
+    }
+  });
+
+  it("should preserve chunk metadata", () => {
+    setDocumentHash("doc.md", "hash1");
+    const meta = { title: "Test", version: "1.0" };
+    insertChunk("doc.md", "Title", "Heading", "text", meta, [0.1]);
+
+    const chunks = getAllChunks();
+    assert.deepStrictEqual(chunks[0].metadata, meta);
+  });
+
+  it("should count chunks correctly", () => {
+    setDocumentHash("doc.md", "hash1");
+    insertChunk("doc.md", "T", "H", "text1", {}, [0.1]);
+    insertChunk("doc.md", "T", "H", "text2", {}, [0.2]);
+    assert.strictEqual(getChunkCount(), 2);
+  });
+
+  it("should remove document and its chunks", () => {
+    setDocumentHash("doc.md", "hash1");
+    insertChunk("doc.md", "T", "H", "text", {}, [0.1]);
+
+    removeDocument("doc.md");
+    assert.strictEqual(getChunkCount(), 0);
+    assert.deepStrictEqual(getAllDocumentHashes(), {});
+  });
+
+  it("should only remove chunks for the specified document", () => {
+    setDocumentHash("a.md", "hash1");
+    setDocumentHash("b.md", "hash2");
+    insertChunk("a.md", "T", "H", "text-a", {}, [0.1]);
+    insertChunk("b.md", "T", "H", "text-b", {}, [0.2]);
+
+    removeDocument("a.md");
+    assert.strictEqual(getChunkCount(), 1);
+    assert.strictEqual(getAllChunks()[0].text, "text-b");
+  });
+
+  it("should search via FTS", () => {
+    setDocumentHash("doc.md", "hash1");
+    insertChunk("doc.md", "T", "H", "the quick brown fox", {}, [0.1]);
+    insertChunk("doc.md", "T", "H", "lazy sleeping dog", {}, [0.2]);
+
+    const results = searchFts("quick fox", 10);
+    assert.ok(results.length > 0);
+  });
+
+  it("should return empty for FTS with no matches", () => {
+    setDocumentHash("doc.md", "hash1");
+    insertChunk("doc.md", "T", "H", "hello world", {}, [0.1]);
+
+    const results = searchFts("zzzznotfound", 10);
+    assert.strictEqual(results.length, 0);
+  });
+
+  it("should return empty for empty FTS query", () => {
+    const results = searchFts("", 10);
+    assert.strictEqual(results.length, 0);
+  });
+
+  it("should handle FTS queries with special characters", () => {
+    setDocumentHash("doc.md", "hash1");
+    insertChunk("doc.md", "T", "H", "some text", {}, [0.1]);
+
+    const results = searchFts('AND OR NOT "quotes"', 10);
+    assert.ok(Array.isArray(results));
+  });
+
+  it("should commit transaction on success", () => {
+    setDocumentHash("doc.md", "hash1");
+    runInTransaction(() => {
+      insertChunk("doc.md", "T", "H", "text", {}, [0.1]);
+    });
+    assert.strictEqual(getChunkCount(), 1);
+  });
+
+  it("should rollback transaction on error", () => {
+    setDocumentHash("doc.md", "hash1");
+    assert.throws(() => {
+      runInTransaction(() => {
+        insertChunk("doc.md", "T", "H", "text", {}, [0.1]);
+        throw new Error("deliberate failure");
+      });
+    });
+    assert.strictEqual(getChunkCount(), 0);
+  });
+});

package/test/unit/index-docs.test.ts

@@ -0,0 +1,120 @@
+import assert from "node:assert";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import type { Embedder } from "../../src/embedder/embedder.js";
+import { indexDocs } from "../../src/ingest/index-docs.js";
+import {
+  closeDb,
+  dbPath,
+  getAllChunks,
+  getAllDocumentHashes,
+  getChunkCount,
+  openDb,
+} from "../../src/store/db.js";
+
+const TEST_DIR = join(tmpdir(), "inkdex-test-index-" + process.pid);
+const DOCS_DIR = join(TEST_DIR, "docs");
+
+function createMockEmbedder(): Embedder {
+  return {
+    maxTokens: 256,
+    tokenize: (text: string) => text.split(/\s+/).map((_, i) => i),
+    embed: async (_text: string) => [0.1, 0.2, 0.3],
+    embedBatch: async (texts: string[]) => texts.map(() => [0.1, 0.2, 0.3]),
+  } as unknown as Embedder;
+}
+
+describe("indexDocs", () => {
+  beforeEach(() => {
+    mkdirSync(DOCS_DIR, { recursive: true });
+    openDb(DOCS_DIR);
+  });
+
+  afterEach(() => {
+    closeDb();
+    try {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+      rmSync(dbPath(DOCS_DIR), { force: true });
+      rmSync(`${dbPath(DOCS_DIR)}-wal`, { force: true });
+      rmSync(`${dbPath(DOCS_DIR)}-shm`, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  });
+
+  it("should index markdown files", async () => {
+    writeFileSync(join(DOCS_DIR, "test.md"), "# Title\n\n## Section\n\nHello");
+    await indexDocs(createMockEmbedder(), DOCS_DIR);
+    assert.ok(getChunkCount() > 0);
+  });
+
+  it("should handle empty directory", async () => {
+    await indexDocs(createMockEmbedder(), DOCS_DIR);
+    assert.strictEqual(getChunkCount(), 0);
+  });
+
+  it("should skip unchanged files on second run", async () => {
+    writeFileSync(join(DOCS_DIR, "test.md"), "# Title\n\n## Section\n\nHello");
+    const embedder = createMockEmbedder();
+
+    await indexDocs(embedder, DOCS_DIR);
+    const countAfterFirst = getChunkCount();
+
+    await indexDocs(embedder, DOCS_DIR);
+    assert.strictEqual(getChunkCount(), countAfterFirst);
+  });
+
+  it("should re-index changed files", async () => {
+    const embedder = createMockEmbedder();
+    writeFileSync(join(DOCS_DIR, "test.md"), "# Title\n\n## Section\n\nOld");
+    await indexDocs(embedder, DOCS_DIR);
+
+    writeFileSync(
+      join(DOCS_DIR, "test.md"),
+      "# Title\n\n## Section\n\nUpdated content",
+    );
+    await indexDocs(embedder, DOCS_DIR);
+
+    const chunks = getAllChunks();
+    const texts = chunks.map((c) => c.text).join(" ");
+    assert.ok(texts.includes("Updated content"));
+    assert.ok(!texts.includes("Old"));
+  });
+
+  it("should remove deleted files from index", async () => {
+    const embedder = createMockEmbedder();
+    writeFileSync(join(DOCS_DIR, "a.md"), "# A\n\n## Section\n\nFile A");
+    writeFileSync(join(DOCS_DIR, "b.md"), "# B\n\n## Section\n\nFile B");
+    await indexDocs(embedder, DOCS_DIR);
+    assert.strictEqual(Object.keys(getAllDocumentHashes()).length, 2);
+
+    rmSync(join(DOCS_DIR, "b.md"));
+    await indexDocs(embedder, DOCS_DIR);
+
+    const hashes = getAllDocumentHashes();
+    assert.strictEqual(Object.keys(hashes).length, 1);
+    assert.ok(hashes["a.md"]);
+  });
+
+  it("should index files in subdirectories", async () => {
+    mkdirSync(join(DOCS_DIR, "sub"), { recursive: true });
+    writeFileSync(
+      join(DOCS_DIR, "sub", "nested.md"),
+      "# Nested\n\n## Section\n\nNested content",
+    );
+    await indexDocs(createMockEmbedder(), DOCS_DIR);
+    assert.ok(getChunkCount() > 0);
+  });
+
+  it("should store document hashes", async () => {
+    writeFileSync(join(DOCS_DIR, "test.md"), "# Title\n\n## Section\n\nHello");
+    await indexDocs(createMockEmbedder(), DOCS_DIR);
+
+    const hashes = getAllDocumentHashes();
+    assert.ok(hashes["test.md"]);
+    assert.strictEqual(typeof hashes["test.md"], "string");
+    assert.strictEqual(hashes["test.md"].length, 64); // SHA-256 hex
+  });
+});

package/test/unit/logger.test.ts

@@ -0,0 +1,11 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { logger } from "../../src/logger.js";
+
+describe("logger", () => {
+  it("should return a logger instance", () => {
+    assert.ok(logger);
+    assert.strictEqual(typeof logger.info, "function");
+    assert.strictEqual(typeof logger.error, "function");
+  });
+});

package/test/unit/search.test.ts

@@ -0,0 +1,93 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { cosineSimilarity, rankChunksHybrid } from "../../src/search/search.js";
+import type { ChunkRow } from "../../src/types.js";
+
+function makeChunk(id: number, embedding: number[]): ChunkRow {
+  return {
+    id,
+    path: `doc${id}.md`,
+    fileHeading: `Doc ${id}`,
+    heading: `Section ${id}`,
+    text: `text ${id}`,
+    metadata: {},
+    embedding,
+  };
+}
+
+describe("cosineSimilarity", () => {
+  it("should return 1 for identical vectors", () => {
+    const v = [1, 2, 3];
+    const sim = cosineSimilarity(v, v);
+    assert.ok(Math.abs(sim - 1) < 1e-6);
+  });
+
+  it("should return 0 for orthogonal vectors", () => {
+    const a = [1, 0, 0];
+    const b = [0, 1, 0];
+    const sim = cosineSimilarity(a, b);
+    assert.ok(Math.abs(sim) < 1e-6);
+  });
+
+  it("should return -1 for opposite vectors", () => {
+    const a = [1, 0];
+    const b = [-1, 0];
+    const sim = cosineSimilarity(a, b);
+    assert.ok(Math.abs(sim + 1) < 1e-6);
+  });
+});
+
+describe("rankChunksHybrid", () => {
+  const queryEmbedding = [1, 0, 0];
+  const chunks: ChunkRow[] = [
+    makeChunk(1, [1, 0, 0]), // best vector match
+    makeChunk(2, [0, 1, 0]), // orthogonal
+    makeChunk(3, [0.5, 0.5, 0]), // moderate vector match
+  ];
+
+  it("should boost results that appear in both rankings", () => {
+    // FTS ranks chunk 1 first too — both signals agree
+    const results = rankChunksHybrid(chunks, queryEmbedding, [1, 3, 2], 3);
+    assert.strictEqual(results[0].path, "doc1.md");
+  });
+
+  it("should include results from only one signal", () => {
+    // FTS returns no results — pure vector ranking
+    const results = rankChunksHybrid(chunks, queryEmbedding, [], 3);
+    assert.strictEqual(results.length, 3);
+    assert.strictEqual(results[0].path, "doc1.md");
+  });
+
+  it("should rank FTS-only match above absent chunks", () => {
+    // Chunk 4 only exists in FTS results (not in chunks array) — should be ignored
+    const results = rankChunksHybrid(chunks, queryEmbedding, [4, 2], 3);
+    assert.strictEqual(results.length, 3);
+  });
+
+  it("should respect limit", () => {
+    const results = rankChunksHybrid(chunks, queryEmbedding, [1, 2, 3], 1);
+    assert.strictEqual(results.length, 1);
+  });
+
+  it("should rank dual-signal result higher than single-signal", () => {
+    // Chunk 2 is orthogonal (bad vector) but FTS rank 1
+    // Chunk 1 is best vector but not in FTS
+    // Chunk 3 is moderate vector and FTS rank 2
+    const results = rankChunksHybrid(chunks, queryEmbedding, [2, 3], 3);
+    // Chunk 1: vector rank 1 only → 1/(60+1) = 0.01639
+    // Chunk 2: vector rank 3 + FTS rank 1 → 1/(60+3) + 1/(60+1) = 0.01587 + 0.01639 = 0.03226
+    // Chunk 3: vector rank 2 + FTS rank 2 → 1/(60+2) + 1/(60+2) = 0.01613 + 0.01613 = 0.03226
+    // Both chunk 2 and 3 (dual signal) should rank above chunk 1 (single signal)
+    const chunk1Idx = results.findIndex((r) => r.path === "doc1.md");
+    const chunk2Idx = results.findIndex((r) => r.path === "doc2.md");
+    const chunk3Idx = results.findIndex((r) => r.path === "doc3.md");
+    assert.ok(
+      chunk2Idx < chunk1Idx,
+      "dual-signal chunk 2 should rank above single-signal chunk 1",
+    );
+    assert.ok(
+      chunk3Idx < chunk1Idx,
+      "dual-signal chunk 3 should rank above single-signal chunk 1",
+    );
+  });
+});

package/test/unit/version.test.ts

@@ -0,0 +1,16 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { getVersion } from "../../src/version.js";
+
+describe("version", () => {
+  it("should return a version string", () => {
+    const version = getVersion();
+    assert.ok(version);
+    assert.strictEqual(typeof version, "string");
+  });
+
+  it("should match package.json version format", () => {
+    const version = getVersion();
+    assert.match(version, /^\d+\.\d+\.\d+$|^unknown$/);
+  });
+});

package/test-docs/api-reference.md

@@ -0,0 +1,76 @@
+# API Reference
+
+## Authentication
+
+All API requests require a Bearer token in the Authorization header.
+
+```
+Authorization: Bearer <your-api-key>
+```
+
+Keys are generated from the dashboard under Settings > API Keys. Each key is scoped to a single project.
+
+## Endpoints
+
+### GET /api/users
+
+Returns a paginated list of users.
+
+**Query parameters:**
+
+| Param | Type | Description |
+|-------|------|-------------|
+| page | number | Page number (default: 1) |
+| limit | number | Results per page (default: 20, max: 100) |
+| search | string | Filter by name or email |
+
+**Response:**
+
+```json
+{
+  "data": [
+    { "id": "u_123", "name": "Alice", "email": "alice@example.com" }
+  ],
+  "total": 42,
+  "page": 1
+}
+```
+
+### POST /api/users
+
+Create a new user.
+
+**Request body:**
+
+```json
+{
+  "name": "Bob",
+  "email": "bob@example.com",
+  "role": "member"
+}
+```
+
+**Response:** Returns the created user object with a generated `id`.
+
+### DELETE /api/users/:id
+
+Delete a user by ID. Returns 204 on success. Requires admin role.
+
+## Rate Limiting
+
+The API enforces a rate limit of 100 requests per minute per API key. Exceeding the limit returns a 429 status with a `Retry-After` header.
+
+## Error Responses
+
+All errors follow a consistent format:
+
+```json
+{
+  "error": {
+    "code": "not_found",
+    "message": "User not found"
+  }
+}
+```
+
+Common error codes: `bad_request`, `unauthorized`, `not_found`, `rate_limited`, `internal_error`.

package/test-docs/deployment.md

@@ -0,0 +1,55 @@
+# Deployment
+
+## Building for Production
+
+Run the build command to generate optimized output:
+
+```bash
+acme-cli build
+```
+
+This compiles TypeScript, bundles assets, and writes everything to the `outDir` specified in your config (default: `dist/`).
+
+## Docker
+
+A minimal Dockerfile for production:
+
+```dockerfile
+FROM node:22-alpine
+WORKDIR /app
+COPY dist/ ./dist/
+COPY package.json ./
+RUN npm install --production
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+Build and run:
+
+```bash
+docker build -t my-app .
+docker run -p 3000:3000 my-app
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| DATABASE_URL | Yes | PostgreSQL connection string |
+| REDIS_URL | No | Redis URL for caching (falls back to in-memory) |
+| API_KEY_SECRET | Yes | Secret used to sign API keys |
+| LOG_LEVEL | No | Logging verbosity: debug, info, warn, error |
+
+## Health Check
+
+The `/healthz` endpoint returns 200 when the service is ready. Use this for load balancer and Kubernetes liveness probes.
+
+## Rollback
+
+If a deployment goes wrong, revert to the previous version:
+
+```bash
+acme-cli rollback --to v1.2.3
+```
+
+This restores the previous build artifacts and runs any reverse migrations automatically.

package/test-docs/getting-started.md

@@ -0,0 +1,52 @@
+# Getting Started
+
+## Installation
+
+Install the CLI globally using npm:
+
+```bash
+npm install -g acme-cli
+```
+
+Or use it directly with npx:
+
+```bash
+npx acme-cli init my-project
+```
+
+## Quick Start
+
+Create a new project by running the init command. This scaffolds a directory with a default configuration file and example templates.
+
+```bash
+acme-cli init my-app
+cd my-app
+acme-cli dev
+```
+
+The dev server starts on port 3000 by default. Open your browser to http://localhost:3000 to see the welcome page.
+
+## Configuration
+
+All settings live in `acme.config.json` at the project root.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| port | number | 3000 | Dev server port |
+| outDir | string | "dist" | Build output directory |
+| minify | boolean | true | Minify production builds |
+
+## Project Structure
+
+A typical project looks like this:
+
+```
+my-app/
+  acme.config.json
+  src/
+    index.ts
+    routes/
+    components/
+  public/
+    favicon.ico
+```

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test"]
+}