internet-archive-wayback-machine-link-fixer

Imported from a8cteam51/internet-archive-wayback-machine-link-fixer (AGENTS.md). Install upstream with npx skills add a8cteam51/internet-archive-wayback-machine-link-fixer. Copyright stays with the author.

Agent Instructions: Internet Archive Wayback Machine Link Fixer

This document provides context for AI agents working on this WordPress plugin. Read it before making changes.

Project Overview

Internet Archive Wayback Machine Link Fixer is a WordPress plugin that:

• Scans post content for outbound links and checks them against the Internet Archive's Wayback Machine
• Creates snapshots for links that aren't yet archived
• Replaces broken links with archived versions
• Auto-archives your own content on create/update

Repository: a8cteam51/wayback-link-fixer
Plugin slug: internet-archive-wayback-machine-link-fixer

Tech Stack

CRITICAL: Do not edit WordPress core files. This is a plugin—all code lives in the plugin directory.

Directory Structure

├── assets/                    # Built JS/CSS (compile from assets/*/src/)
│   ├── css/src/               # SCSS source
│   ├── js/src/                # JS source
│   └── images/
├── blocks/                    # Block editor components
│   ├── src/                   # Block source
│   └── build/                 # Compiled blocks
├── dependencies/              # Scoped PHP deps (generated by php-scoper)
├── languages/                 # i18n .pot, .po, .json
├── migrations/                # Database migrations (Migration_1, etc.)
├── src/                       # Main PHP plugin code
│   ├── Action/                # Bulk/list table actions
│   ├── Ajax/                  # AJAX handlers
│   ├── Dashboard/             # Admin dashboard, wizard, settings
│   ├── Event/                 # Action Scheduler events
│   ├── Link/                  # Link model, repository, exclusions
│   ├── Migration/             # Migration framework
│   ├── Processor/             # Content scanning
│   ├── Report/                # Link report/list table UI
│   ├── Settings/              # Settings model
│   ├── Util/                  # Utilities
│   └── Wayback_Machine/       # Archive.org API clients
├── templates/                 # Admin templates (PHP)
├── tests/                     # PHPUnit tests
└── vendor/                    # Composer dependencies

Commands

Must-run before any PHP work

composer install --ignore-platform-reqs

Build

# Frontend (required before deployment or testing)
npm install
npm run build

Runs: blocks, asset scripts, styles. Use npm run start for watch mode during development.

Lint & Format

# PHP
composer lint:php      # phpcs
composer format:php   # phpcbf

# JS/CSS
npm run lint          # JS + style lint
npm run format        # Auto-fix where possible

Tests

# PHPUnit (requires MySQL + WP PHPUnit environment)
composer test:php

Test setup: Tests use wp-phpunit (WordPress test library). Ensure:

1. WP_PHPUNIT__DIR is set (typically via vendor/bin/wp-phpunit or manual install)
2. Database credentials in tests/.env (copy from tests/.env_sample)
3. MySQL service running

The CI workflow installs deps and builds assets before running tests.

Full pre-PR / production build

composer run:php      # install → test → format → lint → prod autoloader

Internationalization

composer internationalize   # make-pot → update-po → make-json

Conventions

Code Style

• PHP: WordPress coding standards + Team51 ruleset. Prefix globals with iawmlf_ or Internet_Archive\Wayback_Machine_Link_Fixer.
• Text domain: internet-archive-wayback-machine-link-fixer (MUST be used for all translatable strings).
• JS/CSS: @wordpress/scripts lint/format rules.

Branch & PR

• Main branches: trunk, develop
• PRs: Use the PR template; include testing instructions.
• Tests MUST pass before merge (CI enforces this).

Tests

• Place tests in tests/ mirroring src/ structure.
• Prefix test files with Test_.
• Use WP_PHPUNIT__DIR for the WordPress test bootstrap.
• Some tests hit live Archive.org APIs; if the API is offline, they are skipped via $GLOBALS['iawmlf_skip_live_api_tests'].

Architectural Decisions

1. Action Scheduler for all async work — Snapshot creation, link checks, post scanning, and status polling run as scheduled events. Do not perform long-running or external API calls inline in request handlers.

2. Client interfaces — Link_Checker_Client and Snapshot_Client are injectable via filters (iawmlf_link_checker_client, iawmlf_snapshot_client). Default implementations call external services; tests can replace them.

3. Scoped dependencies — Production uses php-scoped dependencies in dependencies/ to avoid conflicts. composer run:php produces an optimized autoloader without dev deps.

4. Migrations — Database changes go through migrations/ and Migration\Migrations. Add new migration classes to the $migrations array in the main plugin file.

5. Settings filters override admin UI — Filters like iawmlf_link_exclusions take precedence over stored options. Use filters for programmatic overrides.

Common Pitfalls

1. Editing core WordPress files — NEVER modify WordPress core. All changes stay in the plugin directory.

2. Skipping asset build — Frontend changes in assets/*/src/ or blocks/src/ require npm run build. Unbuilt changes will not appear in deployment.

3. Inline API calls — Do not call Archive.org or external link-checker APIs directly in HTTP request handlers. Queue an Action Scheduler event instead.

4. Forgetting text domain — All __(), _e(), etc. MUST use internet-archive-wayback-machine-link-fixer. PHPCS will flag violations.

5. Wrong global prefix — Use iawmlf_ or the plugin namespace for functions/classes. Avoid generic names that could conflict.

6. Modifying vendor/ — Do not edit Composer packages. Override behavior with filters or new implementations wired via filters.

7. 403 false positives — Some URLs block bots; they may be reported as broken (403) even when live. The Link_Access_Validator_Event handles this; use "Verify link allows checking" for manual verification.

8. Wizard re-run — To reset the setup wizard during testing: wp-admin/admin.php?page=iawmlf-setup-wizard&rerun-wizard=1 (admin only).

Key Files

Deployment

Deployment to WordPress.org is via GitHub Actions (push-deploy.yml), using .distignore to exclude files from the packaged plugin. Agent/development files (e.g. AGENTS.md, CLAUDE.md, .agents/) are listed in .distignore and do not ship to production.

Where to Find More

• Plugin behavior & hooks: README.md (Developer Documentation, Events, Hooks)
• External APIs: src/Wayback_Machine/ (interfaces and HTTP clients)
• Action Scheduler events: Action names use iawmlf_ prefix; see README Event sections for arguments and filters.