trueref/docs/features/TRUEREF-0002.md

TRUEREF-0002 — Repository Management Service & REST API

Priority: P0 Status: Pending Depends On: TRUEREF-0001 Blocks: TRUEREF-0009, TRUEREF-0010, TRUEREF-0015

---

Overview

Implement the core RepositoryService that handles CRUD operations for repositories, and expose those operations via SvelteKit API routes. This feature establishes the management plane for all library sources.

---

Acceptance Criteria

• RepositoryService class with full CRUD operations
• GET /api/v1/libs — list all repositories with metadata
• POST /api/v1/libs — add a new repository (GitHub URL or local path)
• GET /api/v1/libs/:id — get single repository details
• PATCH /api/v1/libs/:id — update repository metadata
• DELETE /api/v1/libs/:id — delete repository and all associated data
• POST /api/v1/libs/:id/index — trigger indexing job (queues job, returns job ID)
• Input validation with descriptive error messages
• All endpoints return JSON with consistent error shape
• Unit tests for RepositoryService covering all operations

---

Repository ID Generation

GitHub repositories:

• Input URL: https://github.com/facebook/react or github.com/facebook/react
• Generated ID: /facebook/react

Local repositories:

• Input path: /home/user/projects/my-sdk
• Generated ID: /local/my-sdk (basename of path, slugified)
• Collision resolution: append -2, -3, etc.

Version-specific IDs: /facebook/react/v18.3.0

---

Service Interface

// src/lib/server/services/repository.service.ts

export interface AddRepositoryInput {
	source: 'github' | 'local';
	sourceUrl: string; // GitHub URL or absolute local path
	title?: string; // override auto-detected title
	description?: string;
	branch?: string; // GitHub: default branch; Local: n/a
	githubToken?: string; // for private GitHub repos
}

export interface UpdateRepositoryInput {
	title?: string;
	description?: string;
	branch?: string;
	githubToken?: string;
}

export class RepositoryService {
	constructor(private db: BetterSQLite3.Database) {}

	async list(options?: {
		state?: Repository['state'];
		limit?: number;
		offset?: number;
	}): Promise<Repository[]>;

	async get(id: string): Promise<Repository | null>;

	async add(input: AddRepositoryInput): Promise<Repository>;

	async update(id: string, input: UpdateRepositoryInput): Promise<Repository>;

	async remove(id: string): Promise<void>;

	async getStats(id: string): Promise<{
		totalSnippets: number;
		totalTokens: number;
		totalDocuments: number;
		lastIndexedAt: Date | null;
	}>;
}

---

API Route Specifications

GET /api/v1/libs

Query parameters:

• state (optional): filter by state (pending, indexed, error, etc.)
• limit (optional, default 50): max results
• offset (optional, default 0): pagination offset

Response 200:

{
	"libraries": [
		{
			"id": "/facebook/react",
			"title": "React",
			"description": "...",
			"source": "github",
			"state": "indexed",
			"totalSnippets": 1234,
			"totalTokens": 98000,
			"trustScore": 8.5,
			"stars": 228000,
			"lastIndexedAt": "2026-03-22T10:00:00Z",
			"versions": ["v18.3.0", "v17.0.2"]
		}
	],
	"total": 12,
	"limit": 50,
	"offset": 0
}

POST /api/v1/libs

Request body:

{
	"source": "github",
	"sourceUrl": "https://github.com/facebook/react",
	"branch": "main",
	"githubToken": "ghp_...",
	"autoIndex": true
}

Response 201:

{
  "library": { ...Repository },
  "job": { "id": "uuid", "status": "queued" }
}

autoIndex: true (default) immediately queues an indexing job.

Response 409 if repository already exists:

{ "error": "Repository /facebook/react already exists" }

GET /api/v1/libs/:id

:id must be URL-encoded (e.g., %2Ffacebook%2Freact for /facebook/react).

Response 200: single Repository object with versions array. Response 404: { "error": "Repository not found" }

PATCH /api/v1/libs/:id

Request body: partial UpdateRepositoryInput. Response 200: updated Repository.

DELETE /api/v1/libs/:id

Cascades: deletes all documents, snippets, embeddings, jobs for this repository. Response 204: no body. Response 404: not found.

POST /api/v1/libs/:id/index

Triggers a new indexing job. If a job is already running for this repo, returns the existing job.

Request body (optional):

{ "version": "v18.3.0" }

Response 202:

{
	"job": {
		"id": "uuid",
		"repositoryId": "/facebook/react",
		"status": "queued",
		"progress": 0,
		"createdAt": "2026-03-22T10:00:00Z"
	}
}

---

Error Response Shape

All error responses follow:

{
	"error": "Human-readable message",
	"code": "MACHINE_READABLE_CODE",
	"details": {}
}

Error codes:

• NOT_FOUND
• ALREADY_EXISTS
• INVALID_INPUT
• INVALID_URL
• INDEXING_IN_PROGRESS

---

ID Resolution Logic

function resolveGitHubId(url: string): string {
	// Parse owner/repo from URL variants:
	// https://github.com/facebook/react
	// https://github.com/facebook/react.git
	// github.com/facebook/react
	const match = url.match(/github\.com\/([^/]+)\/([^/\s.]+)/);
	if (!match) throw new Error('Invalid GitHub URL');
	return `/${match[1]}/${match[2]}`;
}

function resolveLocalId(path: string, existingIds: string[]): string {
	const base = slugify(path.split('/').at(-1)!);
	let id = `/local/${base}`;
	let counter = 2;
	while (existingIds.includes(id)) {
		id = `/local/${base}-${counter++}`;
	}
	return id;
}

---

Files to Create

• src/lib/server/services/repository.service.ts
• src/routes/api/v1/libs/+server.ts — GET (list), POST (add)
• src/routes/api/v1/libs/[id]/+server.ts — GET, PATCH, DELETE
• src/routes/api/v1/libs/[id]/index/+server.ts — POST (trigger indexing)
• src/lib/server/utils/id-resolver.ts — ID generation helpers
• src/lib/server/utils/validation.ts — input validators
• src/lib/server/services/repository.service.test.ts