ctxpkg 0.0.1

package/src/backend/backend.schemas.ts

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+
+import {
+  referenceDocumentSchema,
+  searchChunksOptionsSchema,
+  searchChunkItemSchema,
+  listDocumentsParamsSchema,
+  listDocumentsResultSchema,
+  getOutlineParamsSchema,
+  outlineResultSchema,
+  getSectionParamsSchema,
+  sectionResultSchema,
+  findRelatedParamsSchema,
+  searchBatchParamsSchema,
+  searchBatchResultSchema,
+} from '#root/documents/documents.schemas.ts';
+
+// Collection info schema (enhanced with metadata for MCP tools v2)
+const collectionInfoSchema = z.object({
+  collection: z.string(),
+  document_count: z.number(),
+  description: z.string().nullable(),
+  version: z.string().nullable(),
+});
+
+type CollectionInfo = z.infer<typeof collectionInfoSchema>;
+
+// Update collection options
+const updateCollectionOptionsSchema = z.object({
+  pattern: z.string(),
+  cwd: z.string(),
+  collection: z.string().optional(),
+});
+
+type UpdateCollectionOptions = z.infer<typeof updateCollectionOptionsSchema>;
+
+// Drop collection params
+const dropCollectionParamsSchema = z.object({
+  collection: z.string(),
+});
+
+// Get document params
+const getDocumentParamsSchema = z.object({
+  collection: z.string(),
+  id: z.string(),
+});
+
+// System status schema
+const systemStatusSchema = z.object({
+  uptime: z.number(),
+  connections: z.number(),
+  services: z.array(z.string()),
+});
+
+type SystemStatus = z.infer<typeof systemStatusSchema>;
+
+// Ping response
+const pingResponseSchema = z.object({
+  pong: z.literal(true),
+  timestamp: z.number(),
+});
+
+// Collections schemas
+const syncCollectionParamsSchema = z.object({
+  name: z.string(),
+  spec: z.object({ url: z.string() }),
+  cwd: z.string(),
+  force: z.boolean().optional(),
+});
+
+type SyncCollectionParams = z.infer<typeof syncCollectionParamsSchema>;
+
+const syncResultSchema = z.object({
+  added: z.number(),
+  updated: z.number(),
+  removed: z.number(),
+  total: z.number(),
+});
+
+type SyncResult = z.infer<typeof syncResultSchema>;
+
+const collectionRecordInfoSchema = z.object({
+  id: z.string(),
+  url: z.string(),
+  name: z.string().nullable(),
+  version: z.string().nullable(),
+  lastSyncAt: z.string().nullable(),
+});
+
+type CollectionRecordInfo = z.infer<typeof collectionRecordInfoSchema>;
+
+export type {
+  CollectionInfo,
+  UpdateCollectionOptions,
+  SystemStatus,
+  SyncCollectionParams,
+  SyncResult,
+  CollectionRecordInfo,
+};
+export {
+  referenceDocumentSchema,
+  searchChunksOptionsSchema,
+  searchChunkItemSchema,
+  collectionInfoSchema,
+  updateCollectionOptionsSchema,
+  dropCollectionParamsSchema,
+  getDocumentParamsSchema,
+  systemStatusSchema,
+  pingResponseSchema,
+  syncCollectionParamsSchema,
+  syncResultSchema,
+  collectionRecordInfoSchema,
+  // New schemas for MCP tools v2
+  listDocumentsParamsSchema,
+  listDocumentsResultSchema,
+  getOutlineParamsSchema,
+  outlineResultSchema,
+  getSectionParamsSchema,
+  sectionResultSchema,
+  findRelatedParamsSchema,
+  searchBatchParamsSchema,
+  searchBatchResultSchema,
+};

package/src/backend/backend.services.ts

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+
+import { procedure } from './backend.protocol.ts';
+import {
+  searchChunksOptionsSchema,
+  updateCollectionOptionsSchema,
+  dropCollectionParamsSchema,
+  getDocumentParamsSchema,
+  syncCollectionParamsSchema,
+  listDocumentsParamsSchema,
+  getOutlineParamsSchema,
+  getSectionParamsSchema,
+  findRelatedParamsSchema,
+  searchBatchParamsSchema,
+} from './backend.schemas.ts';
+import type { CollectionInfo, SystemStatus, SyncResult, CollectionRecordInfo } from './backend.schemas.ts';
+
+import type { Services } from '#root/utils/utils.services.ts';
+import { DocumentsService } from '#root/documents/documents.ts';
+import { CollectionsService } from '#root/collections/collections.ts';
+import type {
+  ReferenceDocument,
+  SearchChunkItem,
+  ListDocumentsResult,
+  OutlineResult,
+  SectionResult,
+  SearchBatchResult,
+} from '#root/documents/documents.schemas.ts';
+
+// Factory to create service procedures with access to Services container
+const createBackendServices = (services: Services, getStatus: () => { uptime: number; connections: number }) => {
+  // Documents service procedures
+  const documents = {
+    listCollections: procedure(z.object({}), async (): Promise<CollectionInfo[]> => {
+      const docService = services.get(DocumentsService);
+      return docService.listCollections();
+    }),
+
+    dropCollection: procedure(dropCollectionParamsSchema, async (params): Promise<void> => {
+      const docService = services.get(DocumentsService);
+      await docService.dropCollection(params.collection);
+    }),
+
+    updateCollection: procedure(updateCollectionOptionsSchema, async (params): Promise<void> => {
+      const docService = services.get(DocumentsService);
+      await docService.updateCollectionFromGlob(params);
+    }),
+
+    search: procedure(searchChunksOptionsSchema, async (params): Promise<SearchChunkItem[]> => {
+      const docService = services.get(DocumentsService);
+      return docService.search(params);
+    }),
+
+    getDocument: procedure(getDocumentParamsSchema, async (params): Promise<ReferenceDocument | null> => {
+      const docService = services.get(DocumentsService);
+      return docService.getDocument(params.collection, params.id);
+    }),
+
+    // New procedures for MCP tools v2
+    listDocuments: procedure(listDocumentsParamsSchema, async (params): Promise<ListDocumentsResult> => {
+      const docService = services.get(DocumentsService);
+      return docService.listDocuments(params);
+    }),
+
+    getOutline: procedure(getOutlineParamsSchema, async (params): Promise<OutlineResult | null> => {
+      const docService = services.get(DocumentsService);
+      return docService.getOutline(params);
+    }),
+
+    getSection: procedure(getSectionParamsSchema, async (params): Promise<SectionResult | null> => {
+      const docService = services.get(DocumentsService);
+      return docService.getSection(params);
+    }),
+
+    findRelated: procedure(findRelatedParamsSchema, async (params): Promise<SearchChunkItem[]> => {
+      const docService = services.get(DocumentsService);
+      return docService.findRelated(params);
+    }),
+
+    searchBatch: procedure(searchBatchParamsSchema, async (params): Promise<SearchBatchResult> => {
+      const docService = services.get(DocumentsService);
+      return docService.searchBatch(params);
+    }),
+  };
+
+  // Collections service procedures
+  const collections = {
+    sync: procedure(syncCollectionParamsSchema, async (params): Promise<SyncResult> => {
+      const colService = services.get(CollectionsService);
+      return colService.syncCollection(params.name, params.spec, params.cwd, {
+        force: params.force,
+      });
+    }),
+
+    list: procedure(z.object({}), async (): Promise<CollectionRecordInfo[]> => {
+      const colService = services.get(CollectionsService);
+      const records = await colService.listCollections();
+      return records.map((r) => ({
+        id: r.id,
+        url: r.url,
+        name: r.name,
+        version: r.version,
+        lastSyncAt: r.last_sync_at,
+      }));
+    }),
+
+    getSyncStatus: procedure(
+      z.object({
+        spec: z.object({ url: z.string() }),
+      }),
+      async (params): Promise<'synced' | 'not_synced' | 'stale'> => {
+        const colService = services.get(CollectionsService);
+        return colService.getSyncStatus(params.spec);
+      },
+    ),
+
+    delete: procedure(z.object({ id: z.string() }), async (params): Promise<void> => {
+      const colService = services.get(CollectionsService);
+      await colService.deleteCollection(params.id);
+    }),
+  };
+
+  // System procedures
+  const system = {
+    ping: procedure(z.object({}), async (): Promise<{ pong: true; timestamp: number }> => {
+      return { pong: true, timestamp: Date.now() };
+    }),
+
+    status: procedure(z.object({}), async (): Promise<SystemStatus> => {
+      const status = getStatus();
+      return {
+        uptime: status.uptime,
+        connections: status.connections,
+        services: ['documents', 'collections'],
+      };
+    }),
+
+    shutdown: procedure(z.object({}), async (): Promise<void> => {
+      // Shutdown is handled by the daemon, this just signals intent
+      process.emit('SIGTERM');
+    }),
+  };
+
+  return { documents, collections, system };
+};
+
+// Type for the services object returned by createBackendServices
+type BackendServices = ReturnType<typeof createBackendServices>;
+
+export type { BackendServices };
+export { createBackendServices };

package/src/backend/backend.ts

@@ -0,0 +1,111 @@
+import { z } from 'zod';
+
+import {
+  requestSchema,
+  ErrorCodes,
+  createSuccessResponse,
+  createErrorResponse,
+  type Request,
+  type Response,
+  type Procedure,
+} from './backend.protocol.ts';
+import { createBackendServices, type BackendServices } from './backend.services.ts';
+
+import { Services, destroy } from '#root/utils/utils.services.ts';
+
+type BackendOptions = {
+  services?: Services;
+};
+
+class Backend {
+  #services: Services;
+  #backendServices: BackendServices;
+  #startTime: number;
+  #connectionCount = 0;
+
+  constructor(options?: BackendOptions) {
+    this.#services = options?.services ?? new Services();
+    this.#startTime = Date.now();
+    this.#backendServices = createBackendServices(this.#services, () => ({
+      uptime: Date.now() - this.#startTime,
+      connections: this.#connectionCount,
+    }));
+  }
+
+  // Update connection count (called by daemon)
+  setConnectionCount(count: number) {
+    this.#connectionCount = count;
+  }
+
+  // Get the services definition for type inference
+  getServices(): BackendServices {
+    return this.#backendServices;
+  }
+
+  // Handle incoming request
+  async handleRequest(raw: unknown): Promise<Response> {
+    // Parse request
+    const parseResult = requestSchema.safeParse(raw);
+    if (!parseResult.success) {
+      return createErrorResponse(
+        'unknown',
+        ErrorCodes.ParseError,
+        'Invalid request format',
+        parseResult.error.format(),
+      );
+    }
+
+    const request = parseResult.data;
+    return this.#routeRequest(request);
+  }
+
+  async #routeRequest(request: Request): Promise<Response> {
+    const { id, method, params } = request;
+
+    // Parse method as "service.method"
+    const [serviceName, methodName] = method.split('.');
+    if (!serviceName || !methodName) {
+      return createErrorResponse(id, ErrorCodes.MethodNotFound, `Invalid method format: ${method}`);
+    }
+
+    // Get procedure using explicit lookup
+    const procedure = this.#getProcedure(serviceName, methodName);
+    if (!procedure) {
+      return createErrorResponse(id, ErrorCodes.MethodNotFound, `Unknown method: ${method}`);
+    }
+
+    // Validate input
+    const inputResult = procedure.input.safeParse(params ?? {});
+    if (!inputResult.success) {
+      return createErrorResponse(id, ErrorCodes.InvalidParams, 'Invalid parameters', inputResult.error.format());
+    }
+
+    // Execute handler
+    try {
+      const result = await procedure.handler(inputResult.data);
+      return createSuccessResponse(id, result);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      return createErrorResponse(id, ErrorCodes.ServiceError, message);
+    }
+  }
+
+  #getProcedure(serviceName: string, methodName: string): Procedure<z.ZodTypeAny, unknown> | null {
+    const services = this.#backendServices;
+    if (!(serviceName in services)) {
+      return null;
+    }
+    const service = services[serviceName as keyof typeof services];
+    if (!(methodName in service)) {
+      return null;
+    }
+
+    return service[methodName as keyof typeof service] as unknown as Procedure<z.ZodTypeAny, unknown>;
+  }
+
+  [destroy] = async () => {
+    await this.#services.destroy();
+  };
+}
+
+export { Backend };

package/src/backend/backend.types.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared type definitions for backend services.
+ * These types define the contract between backend and client.
+ */
+
+import type { BackendServices } from './backend.services.ts';
+import type { ProcedureToFunction } from './backend.protocol.ts';
+
+/**
+ * Complete backend API definition.
+ * This is the main interface that clients use.
+ */
+export type BackendAPI = {
+  [Namespace in keyof BackendServices]: {
+    [Method in keyof BackendServices[Namespace]]: ProcedureToFunction<BackendServices[Namespace][Method]>;
+  };
+};
+
+/**
+ * Extract the parameter type for a specific API method.
+ * Returns the first parameter type, or undefined if the method takes no parameters.
+ */
+export type GetBackendAPIParams<
+  Namespace extends keyof BackendAPI,
+  Method extends keyof BackendAPI[Namespace],
+> = Parameters<BackendAPI[Namespace][Method]>[0];
+
+/**
+ * Extract the response type (unwrapped from Promise) for a specific API method.
+ */
+export type GetBackendAPIResponse<
+  Namespace extends keyof BackendAPI,
+  Method extends keyof BackendAPI[Namespace],
+> = Awaited<ReturnType<BackendAPI[Namespace][Method]>>;

package/src/cli/AGENTS.md

@@ -0,0 +1,213 @@
+# CLI — Agent Guidelines
+
+This document describes the CLI module architecture for AI agents working on this codebase.
+
+## Overview
+
+The CLI module provides the `ctxpkg` command-line interface using [Commander.js](https://github.com/tj/commander.js). Commands are organized by domain, with shared utilities for formatting and error handling.
+
+## File Structure
+
+| File | Purpose |
+|------|---------|
+| `cli.ts` | Main entry point, creates program and mounts subcommand groups |
+| `cli.utils.ts` | Shared formatting utilities and error handling |
+| `cli.client.ts` | Factory for creating `BackendClient` with auto mode detection |
+| `cli.collections.ts` | Collection management commands (`init`, `add`, `sync`, etc.) |
+| `cli.documents.ts` | Document commands (`search`, `list-collections`, etc.) |
+| `cli.config.ts` | Configuration commands (`set`, `get`, `list`, `edit`) |
+| `cli.daemon.ts` | Daemon management commands (`start`, `stop`, `status`) |
+| `cli.mcp.ts` | MCP server commands |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     createProgram()                         │
+│                         cli.ts                              │
+├─────────────────────────────────────────────────────────────┤
+│   collections    documents     config    daemon    mcp      │
+│   ───────────    ──────────    ──────    ──────    ───      │
+│   init           search        set       start     start    │
+│   add            list-cols     get       stop               │
+│   remove         drop-col      list      status             │
+│   list           isearch       edit                         │
+│   sync                         reset                        │
+│   pack                                                      │
+└─────────────────────────────────────────────────────────────┘
+                          │
+            ┌─────────────┴─────────────┐
+            ▼                           ▼
+    ┌───────────────┐          ┌───────────────┐
+    │  cli.utils.ts │          │ cli.client.ts │
+    │  (formatting) │          │ (BackendClient│
+    └───────────────┘          │    factory)   │
+                               └───────────────┘
+```
+
+## Command Structure
+
+Commands follow this pattern:
+
+```
+ctxpkg <group> <command> [args] [options]
+
+# Examples:
+ctxpkg collections add my-docs ./docs
+ctxpkg documents search "how to authenticate"
+ctxpkg config set openai.apiKey sk-...
+ctxpkg daemon status
+```
+
+## Adding a New Command
+
+### 1. Add to Existing Domain
+
+Add command in the appropriate `cli.<domain>.ts`:
+
+```typescript
+command
+  .command('my-command')
+  .alias('mc')                              // Optional short alias
+  .argument('<required>', 'Description')
+  .argument('[optional]', 'Description')
+  .description('What this command does')
+  .option('-f, --flag', 'Boolean flag')
+  .option('-v, --value <val>', 'With value', 'default')
+  .action(
+    withErrorHandling(async (required, optional, options) => {
+      // Implementation
+      formatSuccess('Done!');
+    }),
+  );
+```
+
+### 2. Add a New Domain
+
+1. Create `cli.<domain>.ts`:
+
+```typescript
+import type { Command } from 'commander';
+import { formatHeader, formatSuccess, withErrorHandling, chalk } from './cli.utils.ts';
+
+const create<Domain>Cli = (command: Command) => {
+  command.description('Description of command group');
+
+  command
+    .command('subcommand')
+    .description('What this does')
+    .action(withErrorHandling(async () => {
+      // Implementation
+    }));
+};
+
+export { create<Domain>Cli };
+```
+
+2. Mount in `cli.ts`:
+
+```typescript
+import { create<Domain>Cli } from './cli.<domain>.ts';
+
+// In createProgram():
+create<Domain>Cli(program.command('<domain>').description('...'));
+```
+
+## Key Patterns
+
+### Error Handling
+
+Always wrap actions with `withErrorHandling()`:
+
+```typescript
+.action(
+  withErrorHandling(async (args, options) => {
+    // Errors are caught and formatted with formatError()
+    // process.exitCode is set to 1 on error
+  }),
+)
+```
+
+### Formatting Output
+
+Use utilities from `cli.utils.ts` for consistent output:
+
+```typescript
+formatHeader('Section Title');     // Cyan bordered header
+formatSuccess('Done!');            // Green ✔ prefix
+formatError('Failed');             // Red ✖ prefix
+formatInfo('Note');                // Blue ℹ prefix
+formatWarning('Careful');          // Yellow ⚠ prefix
+
+// Tables
+formatTableHeader([
+  { name: 'Name', width: 20 },
+  { name: 'Value', width: 30 },
+]);
+formatTableRow([
+  { value: 'foo', width: 20, color: chalk.cyan },
+  { value: 'bar', width: 30 },
+]);
+```
+
+### Backend Client
+
+Use `createCliClient()` from `cli.client.ts`:
+
+```typescript
+const client = await createCliClient();
+try {
+  const results = await client.documents.search({ query: 'foo' });
+  // ...
+} finally {
+  await client.disconnect();
+}
+```
+
+Auto mode tries daemon first, falls back to direct (in-process).
+
+### Services Cleanup
+
+Always clean up services in `finally` blocks:
+
+```typescript
+const services = new Services();
+const client = await createCliClient();
+try {
+  // ...
+} finally {
+  await client.disconnect();
+  await services.destroy();
+}
+```
+
+### Interactive Prompts
+
+Use `@inquirer/prompts` for interactive input:
+
+```typescript
+import { input, confirm, select } from '@inquirer/prompts';
+
+const name = await input({ message: 'Enter name:' });
+const confirmed = await confirm({ message: 'Continue?', default: false });
+const choice = await select({
+  message: 'Pick one:',
+  choices: [
+    { name: 'Option A', value: 'a' },
+    { name: 'Option B', value: 'b' },
+  ],
+});
+```
+
+## Testing Commands
+
+```bash
+# Run directly during development
+./bin/cli.js collections list
+./bin/cli.js documents search "query"
+./bin/cli.js config list
+
+# With options
+./bin/cli.js collections sync --force
+./bin/cli.js documents search "query" --limit 5
+```