# Dead URL Replacement Planner 1.0.0

Create a reviewable redirect plan from a catalog snapshot and dead product paths.
Node 20+ is required; no npm install, store connection, external API or subscription.
The complete local utility is included under LICENSE.

## Local app

Extract the ZIP and run `node app.mjs`. Open the complete loopback URL printed in the
terminal, including its session fragment. Load the sample, then **Build replacement plan**.
Review the table and download the full report and proposed-redirect CSV. Ctrl+C stops the app.
You can load your own JSON file or edit the sample structure in the page.

## Command line

```text
node cli.mjs examples/input.json new-report.json
node cli.mjs examples/input.json new-redirects.csv csv
node --test tests/product.test.mjs
```

Existing output files are refused. Invalid input exits 2; a successful report exits 0,
even if some rows remain unresolved. Inspect each row's status before importing a CSV.

## Input contract

See examples/input.json. Up to 5 MiB total, 1,000 dead paths, 10,000 products, 2,000
collections, 10,000 existing redirects and 100 literal keyword rules. Product status
and online flags must be explicit. Collection publication, hidden flag and product count
must be explicit. Handles use lowercase ASCII letters, digits and hyphens.

The supported storefront profile uses `/products/` and `/collections/` paths and
`category-` collection handles. No full URLs, query strings, encoded paths, blog posts or
arbitrary regular expressions. Export customer data into the sample's documented shape.
No additional software purchase or consulting engagement is required.

## Result rules

- Only active, explicitly online products may become replacement targets.
- Unlisted products already visible in the snapshot do not get a new redirect.
- Existing redirects are preserved; they are never overwritten.
- Matching uses names, numbers, category voting and optional literal keyword rules.
- Unresolved rows remain unresolved. Home-page fallback redirects are never proposed.
- Proposed targets entering a redirect chain or cycle are marked for review and omitted
  from the import CSV. Repeated input paths are accounted for separately.
- Each score is an explainable heuristic, not a calibrated likelihood or proof of equivalence.

The program makes no external network calls, verifies no live pages and performs no
store writes. Review the snapshot and proposed plan before importing it into your platform.
The local UI server is not a hosted API: keep it bound to loopback as supplied.