Initial Commit

openspec/archive/2026-05-19-add-api-plugin-export/specs/api-plugin-export/spec.md

@@ -0,0 +1,193 @@
+# Capability Spec Delta: api-plugin-export (add-api-plugin-export)
+
+**Package**: `@suaveplan/api-plugin-export`
+**Status**: PROPOSED
+
+## ADDED Requirements
+
+### Requirement: Plugin descriptor and lifecycle
+
+`createExportPlugin(options?)` SHALL return an immutable `PluginDescriptor` named `"export"` at version `"0.1.0"` with `optionalDependencies: ["database", "events"]` and `tags: ["export","data","csv","json","xlsx"]`. Construction-time Zod validation of `options` SHALL surface `ExportError(EXPORT_CODES.INVALID_CONFIG)` carrying the `ZodError` as `cause` on rejection. The `onInit` hook SHALL register `exportProviders: Map<string, DataProvider>` and `exportJobs: Map<string, ExportJob>` on the `ServiceRegistry`. The `onReady` hook SHALL look up the host `app` via `ctx.getService("app")` and mount routes built by `createExportRoutes(...)` at the configured `basePath`. The `onClose` hook SHALL clear both maps.
+
+#### Scenario: invalid options reject at construction time
+
+- **WHEN** `createExportPlugin({ maxRows: 0 })` is called
+- **THEN** `ExportError` is thrown with `code === EXPORT.INVALID_CONFIG` and the `ZodError` is attached as `cause`
+
+#### Scenario: caller-supplied options flow through to onReady
+
+- **WHEN** the registry calls `onReady(ctx)` after `createExportPlugin({ basePath: "/v1/exports", maxRows: 100 })`
+- **THEN** the routes are mounted at `/v1/exports` and `runExport` against a 101-row provider rejects with `EXPORT.ROW_LIMIT_EXCEEDED`
+
+#### Scenario: onClose drains plugin state
+
+- **WHEN** `onClose()` is invoked after providers and jobs have been populated
+- **THEN** both maps are empty
+
+**Verified by:** `src/plugin/plugin.test.ts::"createExportPlugin rejects invalid options"` AND `src/plugin/plugin.test.ts::"createExportPlugin honours caller-supplied options through onReady"` AND `src/plugin/plugin.test.ts::"onClose drains providers and jobs"`
+
+---
+
+### Requirement: CSV exporter (RFC 4180)
+
+`CsvExporter.export(data, columns, options?)` SHALL produce an `ExportResult` whose `content` is a CSV string conforming to RFC 4180. Field values containing the configured `delimiter`, `"`, `\n`, or `\r` SHALL be wrapped in double quotes with embedded `"` doubled. The header row SHALL be included unless `options.includeHeaders === false`. `Date` instances SHALL serialise via `Date.prototype.toISOString()`; `null`/`undefined` SHALL serialise to the empty string; plain objects SHALL serialise via `JSON.stringify`.
+
+#### Scenario: quoting rules
+
+- **WHEN** a row contains `'a"b'`, `'a,b'`, and `'a\nb'`
+- **THEN** each field appears double-quoted with `"` doubled
+
+#### Scenario: header opt-out
+
+- **WHEN** `options.includeHeaders === false`
+- **THEN** the output starts with the first data row
+
+**Verified by:** `src/exporters/csv/csv.test.ts::"escapes quote / delimiter / newline per RFC 4180"` AND `src/exporters/csv/csv.test.ts::"omits the header row when includeHeaders is false"`
+
+---
+
+### Requirement: JSON exporter
+
+`JsonExporter.export(data, columns, options?)` SHALL project each row to a `Record<string, unknown>` keyed by `column.header`, applying `column.transform` when present, and return a string from `JSON.stringify(projected, null, options?.pretty ? 2 : undefined)`. The MIME type SHALL be `application/json`.
+
+#### Scenario: pretty-print
+
+- **WHEN** `options.pretty === true`
+- **THEN** the output contains a newline immediately after `[`
+
+#### Scenario: transform applied
+
+- **WHEN** a column declares `transform: (v) => Number(v) * 2`
+- **THEN** the projected value is the doubled number
+
+**Verified by:** `src/exporters/json/json.test.ts::"pretty-prints when options.pretty is true"` AND `src/exporters/json/json.test.ts::"applies column.transform"`
+
+---
+
+### Requirement: XLSX (SpreadsheetML) exporter
+
+`XlsxExporter.export(data, columns, options?)` SHALL produce a SpreadsheetML XML document carrying one `worksheet/sheetData` element. Column letters SHALL follow the Excel scheme: index 0 → `A`, 25 → `Z`, 26 → `AA`. Numbers SHALL emit `<c><v>…</v></c>`, booleans `<c t="b"><v>0|1</v></c>`, everything else `<c t="inlineStr"><is><t>…</t></is></c>` with XML special characters escaped. The MIME type SHALL be `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`.
+
+#### Scenario: column-letter overflow
+
+- **WHEN** the 27th column is emitted
+- **THEN** its cell reference uses the `AA` letter
+
+#### Scenario: numeric vs. inline-string cells
+
+- **WHEN** a row contains a number `42` and a string `"forty-two"`
+- **THEN** the numeric cell has no `t="…"` attribute and the string cell has `t="inlineStr"`
+
+**Verified by:** `src/exporters/xlsx/xlsx.test.ts::"emits AA for column index 26"` AND `src/exporters/xlsx/xlsx.test.ts::"distinguishes numeric from inline-string cells"`
+
+---
+
+### Requirement: Export service helpers
+
+`getExporter(format)` SHALL return a fresh instance of the matching exporter (`csv` / `json` / `xlsx`) and SHALL throw `ExportError(EXPORT_CODES.UNSUPPORTED_FORMAT)` on any other value. `inferColumns(data)` SHALL return one `ColumnDefinition` per distinct key across all rows, in first-seen order, with `key === header`. `runExport(provider, format, columns?, filters?, options?, config?)` SHALL fetch data through `provider.fetch(filters)`, reject with `ExportError(EXPORT_CODES.ROW_LIMIT_EXCEEDED)` when `data.length > config.maxRows`, run the exporter, then reject with `ExportError(EXPORT_CODES.FILE_SIZE_EXCEEDED)` when `result.byteSize > config.maxFileSizeBytes`.
+
+#### Scenario: row limit guard
+
+- **WHEN** `provider.fetch` resolves with 51 rows and `config.maxRows === 50`
+- **THEN** `runExport` rejects with `EXPORT.ROW_LIMIT_EXCEEDED`
+
+#### Scenario: file-size guard
+
+- **WHEN** the exporter result `byteSize` exceeds `config.maxFileSizeBytes`
+- **THEN** `runExport` rejects with `EXPORT.FILE_SIZE_EXCEEDED`
+
+#### Scenario: unsupported format
+
+- **WHEN** `getExporter("parquet" as ExportFormat)` is called
+- **THEN** it throws `EXPORT.UNSUPPORTED_FORMAT`
+
+**Verified by:** `src/services/export/export-service.test.ts::"runExport rejects when row count exceeds the configured maximum"` AND `src/services/export/export-service.test.ts::"runExport rejects when result byteSize exceeds the configured maximum"` AND `src/services/export/export-service.test.ts::"getExporter throws on unsupported format"`
+
+---
+
+### Requirement: Export routes
+
+`createExportRoutes(deps)` SHALL return an `OpenAPIHono` exposing four routes:
+
+- `GET /` SHALL apply `status` / `format` / `resource` filters from `ExportJobListQuerySchema`, then `offset`/`limit` window the in-memory `jobs` map.
+- `POST /` SHALL look up `deps.providers.get(body.resource)`, return `404 { error }` on miss, record a fresh `ExportJob`, fire `deps.onExportStarted`, run the export through `provider.fetch` → `inferColumns` → `getExporter` → `exporter.export`, enforce row + size caps (`400 { error }` on breach), update the job to `completed`, fire `deps.onExportCompleted`, and respond `200 { job, downloadUrl }`.
+- `GET /:id` SHALL return the job or `404 { error: "Export job not found" }`.
+- `DELETE /:id` SHALL remove the job (`200 { success: true }`) or `404 { error }`.
+
+All input parsing SHALL flow through `@hono/zod-openapi` validators on `ExportJobListQuerySchema`, `CreateExportJobSchema`, and `z.object({ id: z.string() })`.
+
+#### Scenario: POST with missing provider
+
+- **WHEN** `POST /` body references a `resource` not in `deps.providers`
+- **THEN** the response is `404` with `{ error: "No data provider registered for resource: <name>" }`
+
+#### Scenario: POST honours row + size caps
+
+- **WHEN** the provider returns 51 rows and `exportConfig.maxRows === 50`
+- **THEN** the response is `400` and the job ends in `status: "failed"` with a row-limit error message
+
+#### Scenario: GET list filter + pagination
+
+- **WHEN** three jobs exist (two `completed`, one `failed`) and the query is `?status=completed&limit=1`
+- **THEN** the response carries `total: 2` and `items.length === 1`
+
+#### Scenario: DELETE missing job
+
+- **WHEN** `DELETE /missing-id` is called and the id is absent
+- **THEN** the response is `404 { error: "Export job not found" }`
+
+**Verified by:** `src/routes/exports/exports.test.ts::"POST /exports returns 404 when no provider is registered"` AND `src/routes/exports/exports.test.ts::"POST /exports rejects when row count exceeds the configured maximum"` AND `src/routes/exports/exports.test.ts::"GET /exports applies status filter and pagination"` AND `src/routes/exports/exports.test.ts::"DELETE /exports/{id} returns 404 when the job is missing"`
+
+---
+
+### Requirement: Error-code registry
+
+`EXPORT_CODES` SHALL be built via `defineCodes("EXPORT", […])` and include exactly these codes: `INVALID_CONFIG`, `PROVIDER_NOT_FOUND`, `ROW_LIMIT_EXCEEDED`, `FILE_SIZE_EXCEEDED`, `UNSUPPORTED_FORMAT`, `PROVIDER_FETCH_FAILED`, `JOB_NOT_FOUND`. `ExportError` SHALL extend `SuaveplanError<ExportErrorCode>` so `error.code` narrows to the union and `instanceof ExportError` narrows by class. Every code in the registry SHALL be thrown by at least one production code path (pinned by `api-plugin-export.spec-conformance.test.ts`).
+
+#### Scenario: code narrowing
+
+- **WHEN** `throw new ExportError(EXPORT_CODES.ROW_LIMIT_EXCEEDED, "…")` is caught
+- **THEN** `error.code === "EXPORT.ROW_LIMIT_EXCEEDED"` and `error.exportCode` narrows to the union
+
+#### Scenario: spec-conformance pin
+
+- **WHEN** the conformance test enumerates `EXPORT_CODES`
+- **THEN** every value is referenced from at least one non-test source file
+
+**Verified by:** `src/error-codes/error-codes.test.ts::"ExportError narrows code via the public type union"` AND `src/api-plugin-export.spec-conformance.test.ts::"every EXPORT_* code is thrown from a production path"`
+
+---
+
+### Requirement: OpenTelemetry instruments
+
+`getExportInstruments()` SHALL lazily resolve a `Meter` named `@suaveplan/api-plugin-export` from the global `MeterProvider` and return a cached bundle of four instruments: `jobsTotal: Counter` (with `outcome: "completed" | "failed"`), `rowsTotal: Counter`, `bytesTotal: Counter`, `durationMs: Histogram`. `resetExportInstruments()` SHALL drop the cache so the next call rebinds against the current global provider. The production POST route SHALL emit `jobsTotal` on every job outcome and `rowsTotal` / `bytesTotal` / `durationMs` on every `completed` outcome.
+
+#### Scenario: completed-job metrics emitted
+
+- **WHEN** a successful export completes
+- **THEN** an in-memory `MeterProvider`'s exporter sees one increment of `export.jobs_total{outcome=completed}` plus the row/byte/duration metrics
+
+#### Scenario: failed-job metric emitted on row-limit breach
+
+- **WHEN** an export exceeds `maxRows`
+- **THEN** the exporter sees one increment of `export.jobs_total{outcome=failed}`
+
+**Verified by:** `src/otel/instruments.test.ts::"emits completed-job metrics through an in-memory MeterProvider"` AND `src/otel/instruments.test.ts::"emits failed-job metric on row-limit breach"`
+
+---
+
+### Requirement: Public surface and side-effect imports
+
+The package root barrel SHALL import `./error-codes/error-codes.js` and `./services/registry-augmentation.js` for their side effects, and SHALL re-export every public symbol by name (no `export *` in any feature-module barrel). `package.json` SHALL declare `sideEffects: false` and ship subpath exports for `./plugin/plugin`, `./services/export/export-service`, `./routes/exports/exports`, `./exporters/csv/csv`, `./exporters/json/json`, `./exporters/xlsx/xlsx`, `./error-codes/error-codes`, `./otel/instruments`, `./types/types`.
+
+#### Scenario: side-effect imports present
+
+- **WHEN** `src/index.ts` is read
+- **THEN** the file contains both `./error-codes/error-codes.js` and `./services/registry-augmentation.js` import statements
+
+#### Scenario: no `export *` in feature barrels
+
+- **WHEN** `grep -rn "^\s*export\s\+\(type\s\+\)\?\*\s\+from" src/` is run against the package
+- **THEN** no matches are found
+
+**Verified by:** `src/api-plugin-export.spec-conformance.test.ts::"side-effect imports of error-codes and registry-augmentation are present in index.ts"`