@allpepper/task-orchestrator 0.1.0

package/src/repos/sections.ts

@@ -0,0 +1,505 @@
+import {
+  db,
+  generateId,
+  now,
+  queryOne,
+  queryAll,
+  execute,
+  ok,
+  err,
+  toDate,
+} from './base';
+import type { Result, Section } from '../domain/types';
+import { ContentFormat, EntityType, NotFoundError, ValidationError } from '../domain/types';
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+interface SectionRow {
+  id: string;
+  entity_type: string;
+  entity_id: string;
+  title: string;
+  usage_description: string;
+  content: string;
+  content_format: string;
+  ordinal: number;
+  tags: string;
+  version: number;
+  created_at: string;
+  modified_at: string;
+}
+
+interface AddSectionParams {
+  entityType: string;
+  entityId: string;
+  title: string;
+  usageDescription: string;
+  content: string;
+  contentFormat?: string;
+  ordinal?: number;
+  tags?: string;
+}
+
+interface GetSectionsParams {
+  includeContent?: boolean;
+  tags?: string;
+  sectionIds?: string[];
+}
+
+interface UpdateSectionParams {
+  title?: string;
+  usageDescription?: string;
+  content?: string;
+  contentFormat?: string;
+  tags?: string;
+  version: number;
+}
+
+interface BulkCreateSectionParams {
+  entityType: string;
+  entityId: string;
+  title: string;
+  usageDescription: string;
+  content: string;
+  contentFormat?: string;
+  tags?: string;
+}
+
+// ============================================================================
+// Mapper Functions
+// ============================================================================
+
+function rowToSection(row: SectionRow): Section {
+  return {
+    id: row.id,
+    entityType: row.entity_type as EntityType,
+    entityId: row.entity_id,
+    title: row.title,
+    usageDescription: row.usage_description,
+    content: row.content,
+    contentFormat: row.content_format as ContentFormat,
+    ordinal: row.ordinal,
+    tags: row.tags,
+    version: row.version,
+    createdAt: toDate(row.created_at),
+    modifiedAt: toDate(row.modified_at),
+  };
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+function getNextOrdinal(entityId: string, entityType: string): number {
+  const result = queryOne<{ max_ordinal: number | null }>(
+    'SELECT MAX(ordinal) as max_ordinal FROM sections WHERE entity_id = ? AND entity_type = ?',
+    [entityId, entityType]
+  );
+  return (result?.max_ordinal ?? -1) + 1;
+}
+
+function validateContentFormat(format: string): boolean {
+  return Object.values(ContentFormat).includes(format as ContentFormat);
+}
+
+// ============================================================================
+// Repository Functions
+// ============================================================================
+
+/**
+ * Add a new section to an entity
+ */
+export function addSection(params: AddSectionParams): Result<Section> {
+  try {
+    // Validate content format if provided
+    const contentFormat = params.contentFormat ?? ContentFormat.MARKDOWN;
+    if (!validateContentFormat(contentFormat)) {
+      return err(`Invalid content format: ${contentFormat}`);
+    }
+
+    // Get ordinal
+    const ordinal = params.ordinal ?? getNextOrdinal(params.entityId, params.entityType);
+
+    // Check for ordinal conflict
+    const existing = queryOne<{ id: string }>(
+      'SELECT id FROM sections WHERE entity_type = ? AND entity_id = ? AND ordinal = ?',
+      [params.entityType, params.entityId, ordinal]
+    );
+
+    if (existing) {
+      return err(`Section with ordinal ${ordinal} already exists for this entity`, 'CONFLICT');
+    }
+
+    const id = generateId();
+    const timestamp = now();
+    const tags = params.tags ?? '';
+
+    execute(
+      `INSERT INTO sections (
+        id, entity_type, entity_id, title, usage_description,
+        content, content_format, ordinal, tags, version,
+        created_at, modified_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)`,
+      [
+        id,
+        params.entityType,
+        params.entityId,
+        params.title,
+        params.usageDescription,
+        params.content,
+        contentFormat,
+        ordinal,
+        tags,
+        timestamp,
+        timestamp,
+      ]
+    );
+
+    const row = queryOne<SectionRow>('SELECT * FROM sections WHERE id = ?', [id]);
+    if (!row) {
+      return err('Failed to create section');
+    }
+
+    return ok(rowToSection(row));
+  } catch (error) {
+    return err(`Failed to add section: ${error}`);
+  }
+}
+
+/**
+ * Get sections for an entity
+ */
+export function getSections(
+  entityId: string,
+  entityType: string,
+  params?: GetSectionsParams
+): Result<Section[]> {
+  try {
+    let sql = 'SELECT * FROM sections WHERE entity_id = ? AND entity_type = ?';
+    const sqlParams: any[] = [entityId, entityType];
+
+    // Filter by tags if provided
+    if (params?.tags) {
+      const tagList = params.tags.split(',').map(t => t.trim());
+      const tagConditions = tagList.map(() => 'tags LIKE ?').join(' OR ');
+      sql += ` AND (${tagConditions})`;
+      tagList.forEach(tag => sqlParams.push(`%${tag}%`));
+    }
+
+    // Filter by section IDs if provided
+    if (params?.sectionIds && params.sectionIds.length > 0) {
+      const placeholders = params.sectionIds.map(() => '?').join(',');
+      sql += ` AND id IN (${placeholders})`;
+      sqlParams.push(...params.sectionIds);
+    }
+
+    sql += ' ORDER BY ordinal ASC';
+
+    const rows = queryAll<SectionRow>(sql, sqlParams);
+
+    // If includeContent is false, clear content field for token savings
+    if (params?.includeContent === false) {
+      const sections = rows.map(row => rowToSection({ ...row, content: '' }));
+      return ok(sections);
+    }
+
+    const sections = rows.map(rowToSection);
+    return ok(sections);
+  } catch (error) {
+    return err(`Failed to get sections: ${error}`);
+  }
+}
+
+/**
+ * Update a section
+ */
+export function updateSection(id: string, params: UpdateSectionParams): Result<Section> {
+  try {
+    // Validate version
+    const existing = queryOne<SectionRow>('SELECT * FROM sections WHERE id = ?', [id]);
+    if (!existing) {
+      return err(`Section not found: ${id}`, 'NOT_FOUND');
+    }
+
+    if (existing.version !== params.version) {
+      return err(
+        `Version mismatch: expected ${existing.version}, got ${params.version}`,
+        'VERSION_CONFLICT'
+      );
+    }
+
+    // Validate content format if provided
+    if (params.contentFormat && !validateContentFormat(params.contentFormat)) {
+      return err(`Invalid content format: ${params.contentFormat}`);
+    }
+
+    // Build update query dynamically
+    const updates: string[] = [];
+    const sqlParams: any[] = [];
+
+    if (params.title !== undefined) {
+      updates.push('title = ?');
+      sqlParams.push(params.title);
+    }
+    if (params.usageDescription !== undefined) {
+      updates.push('usage_description = ?');
+      sqlParams.push(params.usageDescription);
+    }
+    if (params.content !== undefined) {
+      updates.push('content = ?');
+      sqlParams.push(params.content);
+    }
+    if (params.contentFormat !== undefined) {
+      updates.push('content_format = ?');
+      sqlParams.push(params.contentFormat);
+    }
+    if (params.tags !== undefined) {
+      updates.push('tags = ?');
+      sqlParams.push(params.tags);
+    }
+
+    if (updates.length === 0) {
+      return err('No fields to update');
+    }
+
+    // Always update version and modified_at
+    updates.push('version = version + 1');
+    updates.push('modified_at = ?');
+    sqlParams.push(now());
+
+    // Add id for WHERE clause
+    sqlParams.push(id);
+
+    const sql = `UPDATE sections SET ${updates.join(', ')} WHERE id = ?`;
+    const changes = execute(sql, sqlParams);
+
+    if (changes === 0) {
+      return err(`Section not found: ${id}`, 'NOT_FOUND');
+    }
+
+    const updated = queryOne<SectionRow>('SELECT * FROM sections WHERE id = ?', [id]);
+    if (!updated) {
+      return err('Failed to retrieve updated section');
+    }
+
+    return ok(rowToSection(updated));
+  } catch (error) {
+    return err(`Failed to update section: ${error}`);
+  }
+}
+
+/**
+ * Update only the text content of a section
+ */
+export function updateSectionText(id: string, content: string, version: number): Result<Section> {
+  try {
+    // Validate version
+    const existing = queryOne<SectionRow>('SELECT * FROM sections WHERE id = ?', [id]);
+    if (!existing) {
+      return err(`Section not found: ${id}`, 'NOT_FOUND');
+    }
+
+    if (existing.version !== version) {
+      return err(
+        `Version mismatch: expected ${existing.version}, got ${version}`,
+        'VERSION_CONFLICT'
+      );
+    }
+
+    const changes = execute(
+      'UPDATE sections SET content = ?, version = version + 1, modified_at = ? WHERE id = ?',
+      [content, now(), id]
+    );
+
+    if (changes === 0) {
+      return err(`Section not found: ${id}`, 'NOT_FOUND');
+    }
+
+    const updated = queryOne<SectionRow>('SELECT * FROM sections WHERE id = ?', [id]);
+    if (!updated) {
+      return err('Failed to retrieve updated section');
+    }
+
+    return ok(rowToSection(updated));
+  } catch (error) {
+    return err(`Failed to update section text: ${error}`);
+  }
+}
+
+/**
+ * Delete a section
+ */
+export function deleteSection(id: string): Result<boolean> {
+  try {
+    // Check if section exists
+    const existing = queryOne<{ id: string }>('SELECT id FROM sections WHERE id = ?', [id]);
+    if (!existing) {
+      return err(`Section not found: ${id}`, 'NOT_FOUND');
+    }
+
+    const changes = execute('DELETE FROM sections WHERE id = ?', [id]);
+    return ok(changes > 0);
+  } catch (error) {
+    return err(`Failed to delete section: ${error}`);
+  }
+}
+
+/**
+ * Reorder sections for an entity
+ *
+ * Uses a two-phase approach to avoid UNIQUE constraint violations:
+ * 1. First, set all ordinals to temporary negative values
+ * 2. Then update them to their final values
+ */
+export function reorderSections(
+  entityId: string,
+  entityType: string,
+  orderedIds: string[]
+): Result<boolean> {
+  try {
+    // Use transaction for atomic updates
+    db.run('BEGIN TRANSACTION');
+
+    try {
+      const timestamp = now();
+
+      // Phase 1: Set all sections to temporary negative ordinals to avoid UNIQUE constraint conflicts
+      for (let i = 0; i < orderedIds.length; i++) {
+        const changes = execute(
+          'UPDATE sections SET ordinal = ?, modified_at = ? WHERE id = ? AND entity_id = ? AND entity_type = ?',
+          [-(i + 1), timestamp, orderedIds[i], entityId, entityType]
+        );
+
+        if (changes === 0) {
+          throw new Error(`Section not found or does not belong to entity: ${orderedIds[i]}`);
+        }
+      }
+
+      // Phase 2: Set final ordinal values
+      for (let i = 0; i < orderedIds.length; i++) {
+        execute(
+          'UPDATE sections SET ordinal = ? WHERE id = ? AND entity_id = ? AND entity_type = ?',
+          [i, orderedIds[i], entityId, entityType]
+        );
+      }
+
+      db.run('COMMIT');
+      return ok(true);
+    } catch (error) {
+      db.run('ROLLBACK');
+      throw error;
+    }
+  } catch (error) {
+    return err(`Failed to reorder sections: ${error}`);
+  }
+}
+
+/**
+ * Bulk create sections
+ */
+export function bulkCreateSections(
+  sections: BulkCreateSectionParams[]
+): Result<Section[]> {
+  try {
+    if (sections.length === 0) {
+      return ok([]);
+    }
+
+    // Use transaction for atomic bulk insert
+    db.run('BEGIN TRANSACTION');
+
+    try {
+      const created: Section[] = [];
+
+      // Group by entity to get proper ordinals
+      const entityMap = new Map<string, number>();
+
+      for (const section of sections) {
+        const entityKey = `${section.entityType}:${section.entityId}`;
+
+        // Get or calculate starting ordinal for this entity
+        if (!entityMap.has(entityKey)) {
+          const startOrdinal = getNextOrdinal(section.entityId, section.entityType);
+          entityMap.set(entityKey, startOrdinal);
+        }
+
+        const ordinal = entityMap.get(entityKey)!;
+        entityMap.set(entityKey, ordinal + 1);
+
+        const contentFormat = section.contentFormat ?? ContentFormat.MARKDOWN;
+        if (!validateContentFormat(contentFormat)) {
+          throw new Error(`Invalid content format: ${contentFormat}`);
+        }
+
+        const id = generateId();
+        const timestamp = now();
+        const tags = section.tags ?? '';
+
+        execute(
+          `INSERT INTO sections (
+            id, entity_type, entity_id, title, usage_description,
+            content, content_format, ordinal, tags, version,
+            created_at, modified_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)`,
+          [
+            id,
+            section.entityType,
+            section.entityId,
+            section.title,
+            section.usageDescription,
+            section.content,
+            contentFormat,
+            ordinal,
+            tags,
+            timestamp,
+            timestamp,
+          ]
+        );
+
+        const row = queryOne<SectionRow>('SELECT * FROM sections WHERE id = ?', [id]);
+        if (!row) {
+          throw new Error('Failed to retrieve created section');
+        }
+
+        created.push(rowToSection(row));
+      }
+
+      db.run('COMMIT');
+      return ok(created);
+    } catch (error) {
+      db.run('ROLLBACK');
+      throw error;
+    }
+  } catch (error) {
+    return err(`Failed to bulk create sections: ${error}`);
+  }
+}
+
+/**
+ * Bulk delete sections
+ */
+export function bulkDeleteSections(ids: string[]): Result<number> {
+  try {
+    if (ids.length === 0) {
+      return ok(0);
+    }
+
+    // Use transaction for atomic bulk delete
+    db.run('BEGIN TRANSACTION');
+
+    try {
+      const placeholders = ids.map(() => '?').join(',');
+      const changes = execute(`DELETE FROM sections WHERE id IN (${placeholders})`, ids);
+
+      db.run('COMMIT');
+      return ok(changes);
+    } catch (error) {
+      db.run('ROLLBACK');
+      throw error;
+    }
+  } catch (error) {
+    return err(`Failed to bulk delete sections: ${error}`);
+  }
+}

package/src/repos/tags.example.ts

@@ -0,0 +1,125 @@
+/**
+ * Example usage of the tags repository
+ *
+ * Run with: bun run src/repos/tags.example.ts
+ */
+
+import { runMigrations } from '../db/migrate';
+import { db, generateId, now } from '../db/client';
+import { listTags, getTagUsage, renameTag } from './tags';
+
+// Initialize the database
+runMigrations();
+
+// Clean up any existing test data
+db.run('DELETE FROM entity_tags');
+
+console.log('=== Tags Repository Examples ===\n');
+
+// Example 1: Add some tags
+console.log('1. Adding tags to entities...');
+const projectId = generateId();
+const featureId = generateId();
+const taskId = generateId();
+
+db.run(
+  'INSERT INTO entity_tags (id, entity_id, entity_type, tag, created_at) VALUES (?, ?, ?, ?, ?)',
+  [generateId(), projectId, 'PROJECT', 'backend', now()]
+);
+db.run(
+  'INSERT INTO entity_tags (id, entity_id, entity_type, tag, created_at) VALUES (?, ?, ?, ?, ?)',
+  [generateId(), projectId, 'PROJECT', 'api', now()]
+);
+db.run(
+  'INSERT INTO entity_tags (id, entity_id, entity_type, tag, created_at) VALUES (?, ?, ?, ?, ?)',
+  [generateId(), featureId, 'FEATURE', 'authentication', now()]
+);
+db.run(
+  'INSERT INTO entity_tags (id, entity_id, entity_type, tag, created_at) VALUES (?, ?, ?, ?, ?)',
+  [generateId(), featureId, 'FEATURE', 'api', now()]
+);
+db.run(
+  'INSERT INTO entity_tags (id, entity_id, entity_type, tag, created_at) VALUES (?, ?, ?, ?, ?)',
+  [generateId(), taskId, 'TASK', 'bugfix', now()]
+);
+console.log('Added 5 tags across 3 entities\n');
+
+// Example 2: List all tags
+console.log('2. Listing all tags with counts...');
+const allTags = listTags();
+if (allTags.success) {
+  console.table(allTags.data);
+} else {
+  console.error('Error:', allTags.error);
+}
+
+// Example 3: List tags filtered by entity type
+console.log('\n3. Listing tags for PROJECT entities only...');
+const projectTags = listTags({ entityType: 'PROJECT' });
+if (projectTags.success) {
+  console.table(projectTags.data);
+} else {
+  console.error('Error:', projectTags.error);
+}
+
+// Example 4: Get usage of a specific tag
+console.log('\n4. Getting usage of "api" tag...');
+const apiUsage = getTagUsage('api');
+if (apiUsage.success) {
+  console.table(apiUsage.data);
+} else {
+  console.error('Error:', apiUsage.error);
+}
+
+// Example 5: Rename a tag (dry run)
+console.log('\n5. Dry run: Renaming "api" to "rest-api"...');
+const dryRunResult = renameTag('api', 'rest-api', { dryRun: true });
+if (dryRunResult.success) {
+  console.log(`Would affect ${dryRunResult.data.affected} entities:`);
+  console.table(dryRunResult.data.entities);
+} else {
+  console.error('Error:', dryRunResult.error);
+}
+
+// Example 6: Rename a tag (actual)
+console.log('\n6. Actually renaming "api" to "rest-api"...');
+const renameResult = renameTag('api', 'rest-api');
+if (renameResult.success) {
+  console.log(`Renamed tag on ${renameResult.data.affected} entities`);
+} else {
+  console.error('Error:', renameResult.error);
+}
+
+// Example 7: Verify the rename
+console.log('\n7. Verifying the rename...');
+const afterRename = listTags();
+if (afterRename.success) {
+  console.table(afterRename.data);
+} else {
+  console.error('Error:', afterRename.error);
+}
+
+// Example 8: Handle conflict scenario
+console.log('\n8. Testing conflict handling...');
+db.run(
+  'INSERT INTO entity_tags (id, entity_id, entity_type, tag, created_at) VALUES (?, ?, ?, ?, ?)',
+  [generateId(), projectId, 'PROJECT', 'server', now()]
+);
+console.log('Added "server" tag to project that has "backend"');
+
+const conflictRename = renameTag('backend', 'server');
+if (conflictRename.success) {
+  console.log(`Handled conflict, affected ${conflictRename.data.affected} entities`);
+  console.log('(Deleted old tag instead of creating duplicate)');
+} else {
+  console.error('Error:', conflictRename.error);
+}
+
+// Verify no duplicates
+const finalTags = db
+  .query('SELECT * FROM entity_tags WHERE entity_id = ? AND entity_type = ?')
+  .all(projectId, 'PROJECT') as any[];
+console.log(`\nProject now has ${finalTags.length} tags (no duplicates):`);
+console.table(finalTags.map(t => ({ tag: t.tag })));
+
+console.log('\n=== Examples Complete ===');