# JSDaj Import Preflight

Free conservative Shopify product-CSV checker. Release target: https://jsdaj.com/import-preflight/ . Public offer: free local checking and an inquiry to support@jsdaj.com for recurring workflows. No paid offer is approved.

## Run

Node 24+, `npm ci`, then `npm test`. This workspace uses `ELECTRON_RUN_AS_NODE=1 /opt/t3code-bin/t3code` as Node. Serve public/ with any static server and open /import-preflight/. The UI uses no network processing, storage, analytics or account connection. File contents remain in page memory; downloads are explicit. Close/reload to clear. Reports contain header names from supplied data.

`node src/cli.mjs check < examples/request.json` returns JSON. `node src/cli.mjs report < examples/request.json` returns formula-escaped findings CSV. `node src/cli.mjs openapi` generates OpenAPI. `node src/stdio.mjs` runs MCP. `node src/http.mjs` runs REST and Streamable HTTP MCP on 127.0.0.1:3210. These are explicitly separate local/self-hosted modes, with no JSDAJ-hosted processing endpoint.

`curl -H 'Content-Type: application/json' --data-binary @examples/request.json http://127.0.0.1:3210/v1/check`

`python3 examples/check.py` calls the same endpoint. `node examples/mcp.mjs` runs a real SDK stdio client. Configure agent hosts with command `node`, args `["/absolute/kit/src/stdio.mjs"]`; host UI compatibility is not certified. MCP SDK server/client 2.4.0, node adapter 2.1.2; real legacy and auto negotiation tested.

## Contracts and limits

Core operations: check_product_csv (/v1/check) and export_preflight_csv (/v1/report.csv). OpenAPI at /openapi.json, MCP at /mcp and resource jsdaj-import-preflight://openapi. All use public/import-preflight/core.js. Input: CSV text, create/update mode, overwrite intention, offset and limit (1–1000). No paths, URLs or credentials accepted. 5 MiB UTF-8 CSV, 25,000 records, 100 columns, 24 MiB HTTP/frame input, 1 MiB JSON output. Page totals count all findings. Row numbers refer to CSV records, not physical lines. No persistence, outgoing requests, jobs or webhooks.

HTTP: JSDAJ_HOST/PORT, JSDAJ_API_TOKEN (32+ chars), JSDAJ_ALLOWED_HOSTS and JSDAJ_ALLOWED_ORIGINS (comma separated). Token optional only for loopback; non-loopback requires one. Shared bearer grants both read-only operations; no account scopes. Explicit Host/Origin allowlists, no wildcard hosts; no CORS by default. 60 requests/minute per instance, four concurrent, 16 connections. Health is unauthenticated. TLS/reverse-proxy controls are operator responsibility. Never enable a hosted mode silently.

Stable errors: INVALID_REQUEST/INVALID_CSV (422), INVALID_JSON (400), UNAUTHORIZED (401), INVALID_HOST/INVALID_ORIGIN (403), NOT_FOUND (404), METHOD_NOT_ALLOWED (405), REQUEST_TOO_LARGE/RESULT_TOO_LARGE (413), UNSUPPORTED_MEDIA_TYPE/UNSUPPORTED_ENCODING (415), RATE_LIMITED (429), INTERNAL_ERROR (500). MCP wraps tool errors in isError; protocol validation uses MCP envelopes. v1 changes remain additive; incompatible behavior requires v2. No deprecation date is set.

## Integration matrix and launch checklist

| Interface | Status / reason |
|---|---|
| REST/OpenAPI | Both core operations, self-hosted, versioned v1 |
| MCP stdio/HTTP | Same operations and OpenAPI resource; real clients tested |
| CLI/batch | stdin JSON to bounded JSON/CSV, no filesystem access from payload |
| Portable import/export | Comma-separated UTF-8 Shopify input; JSON/CSV findings, no repairs |
| Events/webhooks | Inapplicable: synchronous operations, no jobs or event state |
| Shopify connector | CSV interoperability only; no authenticated account connector |
| Other protocols | GraphQL/gRPC not justified by current file-checking workflow |

- [x] Owner standard retained in AGENTS.md and business/product-standards.md
- [x] One shared validator, real domain and interface tests, auth/limits documented
- [x] Download kit, schemas, examples and public static product path
- [ ] Parent reviews and deploys only public/import-preflight/; never root index.html
- [ ] Parent reviews UI behavior and reconciles outreach suppression before dispatch
- [ ] Demand and willingness to pay validated; paid pricing approved separately

## Boundaries

Supported current and common legacy headers are normalized only internally; original strings including SKU/barcode leading zeros stay intact. Unknown fields warn rather than fail. No taxonomy/metafield/market validation, remote image fetching, live handle/variant comparison or acceptance guarantee. Included blanks warn conservatively; continuation image rows are permitted. No mutation, imports, deletion, inventory synchronization or accounting conclusions. Source research and objections: business/research.md.

Download is built with `python3 scripts/package.py`; allowlisted source only, no secrets, node_modules or git. Extract then npm ci; private GitHub access is unnecessary. Parent deploys static directory and configures cache headers; no backend deployment required. Optional self-hosted servers are customer-operated.
