suaveplan/openspec/archive/2026-05-19-add-api-plugin-export/tasks.md

Tasks — Ship @suaveplan/api-plugin-export

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/api-plugin-export.md end-to-end
• 1.2 Read upstream ../suaveplan/packages/server/api-plugin-export/src/ end-to-end
• 1.3 Read openspec/AGENTS.md §§ 2a, 6a, 7, 12, 13, 14
• 1.4 Draft proposal.md from template
• 1.5 Fill ## Source mapping table — every requirement cites a line range or appears in the no-source-line table
• 1.6 Draft specs/api-plugin-export/spec.md from template with **Verified by:** lines on every requirement

2. Implementation

• 2.1 package.json v0.1.0, sideEffects: false, subpath exports, workspace:^ peers, istanbul, vite build
• 2.2 tsconfig.json + tsconfig.lib.json extending tsconfig.base.json
• 2.3 vite.config.ts (dts + preserveModules, externals)
• 2.4 vitest.config.ts via createTestConfig style — istanbul, forks, 100/100/100/100
• 2.5 tests/setup/polyfills.ts — real MeterProvider
• 2.6 src/error-codes/error-codes.ts — defineCodes("EXPORT", [...]) + ExportError
• 2.7 src/types/types.ts + Zod schemas (ExportFormatSchema etc.)
• 2.8 src/exporters/csv/csv.ts — CsvExporter + escapeCsvField + formatCellValue + convertToCsv
• 2.9 src/exporters/json/json.ts — JsonExporter + projectRow + convertToJson
• 2.10 src/exporters/xlsx/xlsx.ts — XlsxExporter + escapeXml + columnIndexToLetter + formatXlsxCell + buildSpreadsheetXml
• 2.11 src/services/export/export-service.ts — getExporter / inferColumns / runExport / DEFAULT_EXPORT_CONFIG
• 2.12 src/routes/exports/exports.ts — createExportRoutes with GET /, POST /, GET /:id, DELETE /:id
• 2.13 src/otel/instruments.ts — ExportInstruments + getExportInstruments + resetExportInstruments
• 2.14 src/services/registry-augmentation.ts — exportProviders + exportJobs slots
• 2.15 src/plugin/plugin.ts — createExportPlugin honouring caller-supplied options, mounting routes via ctx.getService("app")
• 2.16 src/index.ts — explicit named re-exports, side-effect import of error-codes + registry-augmentation

3. Tests

• 3.1 Unit tests per feature module
• 3.2 Spec-conformance test pinning every EXPORT_* code to a production throw site + side-effect imports in index.ts
• 3.3 Every it(...) carries { timeout: 5000 } (or 30000 for genuinely async)

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥ 200 words, basic + advanced examples, full API reference)
• 4.2 README.md at package root only
• 4.3 No CLAUDE.md changes (out of scope — forbidden path)

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome clean
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/api-plugin-export — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/api-plugin-export — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/api-plugin-export — 0 errors
• 5.5 bunx turbo build --filter=@suaveplan/api-plugin-export — green

6. Pre-archive 9-row checklist (AGENTS.md §13 + skill §7)

• 6.1 Generics threaded
• 6.2 Zod schemas wired at every declared boundary (CreateExportJobSchema, ExportPluginOptionsSchema, ExportJobListQuerySchema)
• 6.3 Every error code thrown from ≥ 1 production path (asserted by spec-conformance test)
• 6.4 Strict-mode behaviours tested (row cap + size cap throws ExportError; provider missing → 404; bad options → ExportError(INVALID_CONFIG))
• 6.5 OTel instruments emitted from production paths, asserted with real in-memory MeterProvider
• 6.6 Lifecycle dedup — onClose clears both maps; onInit registers services exactly once
• 6.7 No retroactive tick — every box reflects work in this change
• 6.8 No export * in any feature-module barrel (no feature barrels exist; root barrel uses named exports)
• 6.9 No direct vitest / bun:test imports — all tests import from @suaveplan/testing/runner

7. Archive

• 7.1 Fold spec delta into openspec/specs/api-plugin-export/spec.md
• 7.2 Move openspec/changes/add-api-plugin-export/ → openspec/archive/2026-05-19-add-api-plugin-export/
• 7.3 No MANIFEST.md refresh (forbidden path per task brief)