emdash-plugin-relink 0.2.2

package/docs/recovery.md

@@ -0,0 +1,27 @@
+# Link evidence, archive recovery and exceptions
+
+## Checking originals
+
+Relink tries HEAD first and confirms unsuccessful or HTML responses with GET. Redirects are bounded to five and ten-second request timeouts apply. Inspected bodies are limited to 512 KB. A successful HEAD cannot override a failing GET. Sign-in pages, bot challenges and suspicious soft-error titles are marked unverifiable.
+
+404/410 and repeated server or transport failures can contribute to a broken-link decision. 401/407, 403/451 and 429 remain distinct authentication, blocked and rate-limited results. `Retry-After` is honoured with bounds. For transport/5xx failures, independent network probes must answer successfully enough to establish connectivity before a failure counts. If both probes fail, Relink records a local outage, retries in an hour and does not advance archive eligibility.
+
+Failures count at most once per 24 hours, including manual retries. The default schedule is first check, +24 hours, +72 hours from initial failure. The third confirmed failure permits archive discovery. Healthy originals reset the failure series. Originals behind an active archive return after two successful checks at least 24 hours apart; an intervening confirmed broken check resets recovery evidence.
+
+## Wayback
+
+Relink queries the Internet Archive CDX endpoint for up to three of the latest exact-URL captures before the failure period. It requires a successful recorded status, a supported document MIME type, an accessible playback URL for that exact timestamp/resource, and all referenced section anchors. Calendar pages, errors, mismatching resources and missing sections are unsuitable. It records the capture date, original URL, verified fragments, playback evidence, decision reason and history.
+
+Discovery never submits pages to Save Page Now. Missing captures leave the original in place and schedule discovery in 30 days. Archive API/playback outages are retryable service failures and are retried in one day. An archive that subsequently gives a confirmed broken response is removed and flagged; authentication or bot-blocking alone does not prove a previously verified archive is gone.
+
+## Grokipedia
+
+Disabled by default. The initial provider considers canonical Wikipedia `/wiki/` article URLs. Query-bearing/historical revisions and special namespaces are held for review. A candidate Grokipedia slug is only a discovery hint.
+
+Automatic eligibility additionally requires a reachable exact canonical Grokipedia URL, matching visible article titles, matching source/target language, a canonical Wikipedia source, sufficient independent introductory-content overlap, no disambiguation evidence, and matching section identifiers. The current overlap rule requires at least six shared significant words and 60% overlap relative to the smaller introduction vocabulary. This conservative heuristic is not a universal semantic identity proof; ambiguous or insufficient evidence stays unchanged. German sources cannot be redirected to English destinations.
+
+If a Grokipedia replacement becomes unavailable while Wikipedia is reachable, Relink restores Wikipedia. If both are broken, the normal archive workflow applies. **Check again** permits another matching attempt. Reviewers can always set a verified manual destination or retain the original with an undo exception. No undocumented paid API or account is required.
+
+## Network safety
+
+Production requests use EmDash's DNS-aware restricted HTTP bridge, with the unrestricted-public-network capability needed for arbitrary external links. Local/private addresses, credentials in URLs and unsafe redirects are rejected. Relink also rejects unsafe literals before calling the bridge. Literal IPv6 URLs are conservatively excluded in this release; ordinary hostnames with public IPv6 DNS are handled by EmDash. No cookies, browser credentials or incoming authorization headers are forwarded to link destinations.

package/docs/testing.md

@@ -0,0 +1,31 @@
+# Validation and known limitations
+
+## Reproducible checks
+
+`pnpm check` runs strict TypeScript checking, typed ESLint rules, Vitest and declaration/package builds. The suite exercises HTTP status distinctions, HEAD/GET disagreement, redirects, timeouts, response limits, archive evidence/outages, Grokipedia ambiguity/language/sections, recovery intervals, duplicate targets, removed occurrences, restart state, undo exceptions, publication checks, output replacement and cache headers. Catalog tests cover regional locales, fallback and pluralization.
+
+Platform tests use the actual EmDash `PluginStorageRepository` and native Node SQLite adapter. The D1 test uses the actual EmDash D1 adapter against a local workerd D1 binding supplied by stable Miniflare 4.20260730.0. Only the binding import is substituted. Both platforms run EmDash 0.37.0's real atomic cron claim/recovery implementation. That pinned internal scheduler import is confined to tests; the shipped plugin uses only public EmDash APIs.
+
+The workspace and isolated example pin vulnerable transitive versions of sharp to 0.35.4 and Undici 7 to 7.29.0. These patches address upstream [sharp](https://github.com/lovell/sharp/security/advisories/GHSA-rgj7-g3m4-5g8c) and [Undici](https://github.com/nodejs/undici/security/advisories/GHSA-4cwx-7wf7-3272) advisories. The plugin's own runtime dependencies are parse5 and Zod; consuming sites manage their EmDash/Astro dependency updates independently.
+
+`pnpm test:package` builds a tarball, installs it into `work/package-site` with a separate dependency boundary, seeds EmDash, builds Astro, and checks its published page and authenticated plugin API. Test-only loopback authentication is copied into this isolated fixture and is not included in the package or normal examples. `--prepare-only` prepares that site for the browser suite. Never deploy `work/package-site`.
+
+Run `node scripts/seed-browser.mjs` after the package test to populate a deterministic pending-link index from the fixture's actual published content, then run `pnpm test:browser`. The browser suite checks native navigation, dashboard/editor extensions, English/German and regional language detection, live host language switching, unsupported-language fallback, light/dark accessibility, keyboard focus, scoped RTL, CSV downloads and authenticated routes. A separate mounted React test exercises language activation without remounting. No synthetic link-health result is seeded.
+
+Cache integration tests use Astro's actual memory provider and simulate elapsed time: a replacement and a rollback appear after the capped 300-second lifetime even when the page asks for a 24-hour cache and stale revalidation. Browser HTTP tests inspect server HTML with no JavaScript and compare actual CMS entries and revisions before/after replacement.
+
+`pnpm --filter relink-example-cloudflare build` validates the Cloudflare example and supported scheduled Worker entry. CI runs these checks and uploads the package artifact. It does not publish to npm, create Cloudflare resources or deploy a production site.
+
+## Scope and limits
+
+- Only published content in configured collections/fields is indexed. Theme-only targets, JavaScript-generated links and embedded media are outside the initial scanner. Root Portable Text fields and explicit nested/wildcard URL selectors are supported.
+- Path templates must match actual public URLs, including locale prefixes and trailing slashes. A slug containing path separators needs a compatible theme/template; placeholders are URL-encoded.
+- Dynamic HTML is required. Previously cached content must be purged at installation, and overriding CDN policies must respect the freshness bound. See [cache operation](installation.md#cache-behaviour).
+- HTTP evidence can be inconclusive. Authentication, anti-bot responses, missing metadata, oversized pages and uncertain article identity intentionally remain review items. No provider's uptime or coverage is guaranteed.
+- Literal IPv6 targets and special-purpose IPv4 ranges are conservatively excluded. Normal public hostnames can resolve to IPv4 or IPv6 through EmDash's DNS-aware network guard. Self-hosted deployments retain EmDash's network-egress requirements; the plugin does not bypass that guard.
+- Grokipedia matching uses visible content evidence and is intentionally conservative. It does not promise semantic equivalence across every encyclopedia article and does not translate articles or section names.
+- Lists are paginated, but filtered counts and collection sweeps currently read the relevant plugin index in memory. Capacity testing is required for very large sites. The admin detail dialog shows the latest 100 events; the global History view paginates retained events. History has no automatic retention deletion.
+- Notifications stay inside EmDash. No email or external messaging integration is included.
+- This validation covers local Node/SQLite, local workerd/D1, built package installation and example builds. Production Cloudflare account configuration, real Cron delivery, CDN overrides and sustained load require deployment-specific checks.
+
+English documentation is maintained alongside the code. Behavioural changes require matching tests and release notes; compatibility beyond EmDash 0.37.0 must be verified rather than assumed.

package/docs/translations.md

@@ -0,0 +1,24 @@
+# Translation and RTL contributions
+
+All documentation, comments and release notes are written in English. The admin currently ships English and German. It listens to the active EmDash Lingui instance; browser language detection and user language changes remain owned by EmDash. Relink has no separate language selector.
+
+`src/admin/messages.ts` contains both catalogs. German regional variants resolve to the German messages and English variants to English; other languages use English. Valid supported regional locales are retained for date/number formatting. Every key is required in both catalogs at compile time, and tests verify completeness and plural forms. Lingui's compiled plural representation is used for counts. Host catalogs are not overwritten.
+
+To contribute a translation:
+
+First arrange the contribution rights described in [CONTRIBUTING.md](../CONTRIBUTING.md). This also applies to translations and documentation so that gekko can include them in commercial distributions.
+
+1. Add the catalog with exactly the keys of the English catalog, including errors, notifications, empty states, reasons and accessibility labels.
+2. Extend the explicit locale resolver and supported catalog map.
+3. Add regional/fallback/plural tests and an actual browser language-switch test.
+4. Review long text, keyboard order, dialog focus and both colour themes.
+
+Keep article language separate from interface language. Switching the UI to English must not make an English replacement eligible for a German article.
+
+## Direction
+
+Settings offers **Automatic / Left-to-right / Right-to-left**. Automatic inherits EmDash's direction. An override sets direction on Relink's root and its local Kumo direction provider. Dialogs are native modal dialogs inside that root; select menus inherit the same direction. Relink never changes the host document's `dir` or its language.
+
+CSS uses logical dimensions, margins, padding, borders and text alignment. URLs are displayed with `<bdi dir="ltr">`; identifiers are isolated as well. Native dialog behaviour supplies a focus trap, Escape dismissal and focus return. Visible focus styles are supplied for interactive elements and horizontally scrollable tables. The browser suite checks forced RTL, readable URLs, keyboard navigation and dialog focus.
+
+Forced RTL is layout support only. This version does not claim Arabic or Hebrew translation coverage.

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "emdash-plugin-relink",
+  "version": "0.2.2",
+  "description": "Keep EmDash links alive with verified archives and scheduled reviews.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/giffeler/relink.git"
+  },
+  "engines": {
+    "node": ">=22.16"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "LICENSES",
+    "CONTRIBUTING.md",
+    "THIRD_PARTY_NOTICES.md",
+    "docs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
+    "./astro": {
+      "types": "./dist/integration.d.ts",
+      "import": "./dist/integration.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "import": "./dist/admin/index.js"
+    },
+    "./styles.css": "./dist/admin/styles.css",
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@cloudflare/kumo": "^2.6.0",
+    "@emdash-cms/admin": "0.37.0",
+    "@lingui/core": "^5.0.0",
+    "@lingui/react": "^5.0.0",
+    "astro": "^7.3.1",
+    "emdash": "0.37.0",
+    "react": "^19.2.0"
+  },
+  "dependencies": {
+    "parse5": "8.0.1",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@astrojs/cloudflare": "14.3.1",
+    "@astrojs/node": "11.1.5",
+    "@astrojs/react": "6.0.5",
+    "@axe-core/playwright": "4.11.1",
+    "@cloudflare/kumo": "^2.6.0",
+    "@emdash-cms/admin": "0.37.0",
+    "@emdash-cms/cloudflare": "0.37.0",
+    "@eslint/js": "10.0.1",
+    "@lingui/core": "^5.9.5",
+    "@lingui/react": "^5.9.5",
+    "@playwright/test": "1.63.0",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "22.20.1",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.7",
+    "astro": "^7.3.1",
+    "emdash": "0.37.0",
+    "esbuild": "0.28.1",
+    "eslint": "10.10.0",
+    "jsdom": "30.0.1",
+    "kysely": "0.29.5",
+    "miniflare": "4.20260730.0",
+    "prettier": "3.6.2",
+    "react": "^19.2.8",
+    "react-dom": "19.2.8",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.70.0",
+    "vitest": "5.0.0"
+  },
+  "homepage": "https://github.com/giffeler/relink#readme",
+  "bugs": {
+    "url": "https://github.com/giffeler/relink/issues"
+  },
+  "author": {
+    "name": "gekko, Gesellschaft für Kommunikation und Kooperation mbH",
+    "url": "https://gekko.de"
+  },
+  "keywords": [
+    "emdash",
+    "astro",
+    "links",
+    "link-checker",
+    "wayback",
+    "archive",
+    "cms"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm build",
+    "test:browser": "playwright test",
+    "test:package": "node scripts/test-package.mjs"
+  }
+}