Data-import repair — Shopify product CSV

This README is the promise, verbatim. No marketing copy.

Written before the code. Every line is either sourced (to a snapshotted first-party page, by hash) or marked v0 choice.

Destination. Shopify's product import CSV as defined by Shopify's own page Using CSV files to import and export products (Shopify Help Center), snapshotted as browser-rendered text. The destination version is that page's content at sha256 7fc9dd43a916a4b9689aab9120ac0ba8cef630b529130436191cda795f33ef9a, pinned in this Actor's metadata. If the extract disagrees with the snapshot, the tests fail. (sourced)

Inputs. One CSV or XLSX file, UTF-8 (the page: "save your CSV file in UTF-8 format using LF-style linefeeds"; sourced), at most 5,000 rows (v0 choice), exactly one header row, any column order. Scope note: the reviewer's example was one specific supplier's catalog format. No supplier exists yet, so v0's alias table covers (a) Shopify's own older column names, which the page says it "maintains backward compatibility with" (sourced), and (b) a hand-written list of generic non-Shopify product headers (v0 choice, marked in aliases.py). The specific supplier format arrives with the first customer and narrows the alias table, not the other way round.

Permitted transformations. Each is a named, deterministic, pure function in repair.py, and each is listed with its rule source in spec_extract.json under permitted_rules:

• map_header — header mapping by the explicit alias table only. (alias table: sourced for legacy names, v0 choice for generic names)
• derive_handle_from_title — only when URL handle is absent for a product with no variants: lowercase, spaces to dashes, letters/digits/dashes only. (sourced: "based on the value in the Title column ... black-sunglasses by default"; "letters, dashes, and numbers, but it can't contain any spaces")
• derive_option1_default — Option1 name = Default Title only when a product has one row and the column is blank. (sourced: "If a product has only one option, then this value should be Default Title")
• derive_fulfillment_manual — Fulfillment service = manual only when the column is present and blank. (sourced: "manual (default)"; and the common-import-issues page: "If you're not using a fulfillment service, then this should be set to manual")
• normalize_money — strip a leading currency symbol and thousands separators from Price, Compare-at price, Cost per item. (sourced: "Only include the monetary value without a currency symbol. For example, 9.99")
• normalize_integer — strip thousands separators and surrounding whitespace from integer columns. (sourced: "specify only the numerical value")
• normalize_bool — yes/no, 1/0, TRUE/FALSE to true/false in boolean columns. (v0 choice; valid values sourced)
• normalize_enum — case-fold enum columns to their documented valid values. (v0 choice; valid values sourced)
• straighten_quotes — curly quotes to straight quotes. (sourced: common-import-issues page, "change “ “ into quotes that look like this: " "")
• variant_row_layout — on the second and later rows of a handle, blank Title, Description, Vendor, Tags when they repeat the first row's values. (sourced: "In the following rows, enter the URL handle. Then skip the Title, Description, Vendor, and Tags columns")

Preserved. URL handle, SKU, Barcode, and every source value that maps to a destination column — byte-for-byte unless a permitted transformation above names it. URL handle, SKU and Barcode are named by no transformation except derive_handle_from_title, which only fills an absent handle and never changes a present one. (v0 choice, enforced by the checker)

Never done. Inventing a missing value: a blank Price, Inventory quantity, Weight value (grams) stays blank even though the page states Shopify's own default for it; this pipeline never fills a default. Guessing an ambiguous header. Dropping a row silently. (v0 choice)

Rejection conditions. A required destination column that cannot be derived by a stated rule (Title; URL handle when a product has variants). A header matching two aliases, or two input headers mapping to one destination column. A header matching no alias (the page: "You can't add any other columns to your CSV file", Collection excepted). More than 5,000 rows. Input not decodable as UTF-8, or not parseable as CSV. A row that fails validation after all permitted transformations. Rejection returns the row, the reason, and the rule that failed. (sourced where quoted; v0 choice otherwise)

Output. The repaired CSV in the destination's column names, plus a JSON validation report listing the header mapping, every transformation applied per row and column, every rejection with reason and rule, and every warning.

Destination. Shopify's product import CSV as defined by Shopify's own page Using CSV files to import and export products (Shopify Help Center), snapshotted as browser-rendered text. The destination version is that page's content at sha256 7fc9dd43a916a4b9689aab9120ac0ba8cef630b529130436191cda795f33ef9a, pinned in this Actor's metadata. If the extract disagrees with the snapshot, the tests fail. (sourced)

Price and refund rule

• Price: $5 per job (event job_accepted), charged only when a repaired file is delivered. A rejected file costs nothing.
• Refund rule: rejected jobs are never charged; delivered jobs are not refunded. The deliverable is the repaired CSV and the validation report.
• Output is validated against Shopify's documented format and not tested against a live store.