Gapeka Wiki

A WordPress plugin for a searchable historical Indonesian GAPEKA timetable archive and editable railway wiki, developed for jadwalkeretaapi.com.

Development version: 0.1.1 (first functional build; staging validation required before production use).

• Repository: https://github.com/byteeater/gapeka-wiki
• Storage model: Own tables (wp_gw_*) and own gw_train / gw_station custom post types.
• Independence: Never reads or changes jkr_station, the KRL Manager plugin's tables, or jadwal-krl/v1.
• Optional future improvement: Verified cross-links between KRL and long-distance station identities; deliberately not coupled in this release.

Included in 0.1.1

• Editor-friendly train and station posts, Classic Editor/Gutenberg compatible, with permanent train URLs and editable FAQ fields.
• GAPEKA edition and revision-specific immutable imported JSON timetable records.
• Admin JSON import in resumable batches of 50, with source row validation, row-level logs, warnings, review records and error-code retry.
• Explicit admin activation of a finished historical GAPEKA edition; importing alone does not make it public/default.
• Search by name/number and origin/destination endpoints, category and gw_year=2025 (actual GAPEKA year), including overnight arrival +1 / +2 markers. The latest published year is selected initially; unpublished data is never silently substituted.
• Train detail pages automatically list their latest available GAPEKA timetable first, followed by all available historical years in descending order, not only a manually selected edition.
• Yoast page-sitemap.xml integration for /gapeka/{year}/ archives; WordPress core fallback sitemap provider for year archives when Yoast is inactive. Native public train, station, and hub page sitemap handling remains with the active sitemap provider.
• Lower-query rendering: batch-loaded station links, cached directory/year/per-train views and station timetable fragments, fast path for uncorrected schedules, and cache invalidation on content or schedule changes.
• Hardened private dataset read access, bounded public search strings/pagination, and conditional noindex on filter-result URLs.
• Region/category train directory and annual /gapeka/{year}/ archive.
• Server-rendered shortcodes and Gutenberg blocks, visible breadcrumbs, FAQ, basic TrainTrip structured data, links to related directories and Yoast-compatible canonical handling.
• Verified station-code mapping registry and independent station pages, with ChatGPT-usable custom REST routes.
• Schedule correction overlays with reason, expected revision, idempotency key, original-source preservation, audit trail and restricted revert.
• Emergency switch for remote data mutations, leaving public search and WordPress CPT editing intact.

Historical-data notice

Do not use 2025 data as a current departure guarantee. Imported JSON contains train endpoints and route codes, not all station stopping times, operating-day calendars or realtime disruption information. REGULER does not necessarily imply everyday service. The source includes local, airport and other passenger trains in addition to intercity trains. FAKULTATIF services may operate only on designated dates.

Install and import

1. In WordPress Plugins → Add New → Upload Plugin, upload the gapeka-wiki-v0.1.1.zip archive and activate it on a staging clone first.
2. WordPress creates four draft hub pages, if their slugs are free: /jadwal-kereta-api/, /kereta-api/, /gapeka/, /stasiun/. Review and publish only the pages you need. Existing pages are left untouched; if a slug is occupied, insert the shortcode into the existing page instead.
3. Open Gapeka Wiki → Import & Logs, choose year 2025, revision original, and upload gapeka_2025_trains.json (1,002 records). Leave Publish train pages unchecked if you want to review them as drafts first.
4. The import UI automatically runs the job in batches. Its log records original warnings and errors. A job with unresolved failures is not activatable. Retry failed source IDs by error code, or upload a corrected file under a new revision when the source itself is invalid/changed.
5. After the job succeeds, click Make default in the edition table. This publishes the historical edition for search, but never asserts that it is a live timetable.
6. Review generated train drafts; publish the useful pages and add editorial content, images, sources and FAQs. WordPress admin can also use Gapeka Wiki → Station Codes after creating station posts.
7. Test frontend URLs, Yoast compatibility, existing KRL pages, actual login permissions, caching, and custom REST endpoints before promoting to the production site.

Sitemap prerequisites: Publish the /gapeka/ archive hub and relevant train/station pages. In Yoast, enable XML sitemaps and allow the train/station content types to appear in search results. Verify /sitemap_index.xml, /page-sitemap.xml and the custom post type sitemaps on staging. Draft, private and noindex content is intentionally excluded. Year archive URLs appear only when their parent hub is published.

Performance and security: The plugin adds targeted transient caches and invalidates them after imports, edition activation, schedule corrections, station mappings, or train/station edits. Existing page/CDN caching remains separate. All mutations require authorized WordPress users; import forms use admin nonces. PHP lint, fixture checks and a dependency-free archive/sitemap smoke test run in CI; a live WordPress/Yoast integration test and external security review remain necessary before production deployment.

Dataset file: The source JSON is supplied separately, not installed automatically. The plugin does not need the original Excel workbook at runtime.

Shortcodes / Gutenberg blocks

[gapeka_train_schedule train_id="123"] lets you place a specific train's schedule table on another page. year="2025" selects a published edition by year (if available). The train CPT automatically appends its schedule table and FAQ; do not add the same shortcode inside the same train post unless you want duplicate output.

ChatGPT / Easy MCP AI

The preinstalled Easy MCP AI can operate on the WordPress gw_train and gw_station CPT through existing wp_create_cpt_item, wp_update_cpt_item, etc. For SQL-backed schedules and station mappings, discover gapeka-wiki/v1 with its generic wp_rest_routes, wp_rest_read and wp_rest_write tools.

Use an authorized WordPress account. gw_correct_schedules is granted to the administrator role on activation. Admin users manage imports, station mappings and edition activation. The REST remote-data-mutation emergency switch is under Gapeka Wiki → Settings & Easy MCP AI.

See docs/MCP_API_CONTRACT.md for sample REST payloads, permissions and safety boundaries. You should read the exact edition_id and schedule_id before correcting a timetable, rather than editing by train name alone.

Data integrity

The original JSON row is preserved in raw_json and raw_hash; corrections are append-only history records plus derived indexed fields for searching. Every correction requires the expected current revision and a reason. The correction endpoint never permits editing raw_json. Re-importing the same year/revision cannot rewrite a changed source row; start a new revision instead.

One source record with validation_status=review is retained but excluded from public results until explicitly corrected. Warnings remain in raw records. A train number such as 29F, 32-33, a, or 2501-2504-2505-2508 remains a string. Source journeys can arrive the following day or two days later.

Known limitations and next work

• Not production certified. PHP lint and full JSON contract tests pass, but a WordPress staging runtime, real database migration tests, plugin/theme compatibility, frontend accessibility, and Easy MCP AI write round trips still require verification.
• Full stopping-station timetables and date-specific operating calendars are not in the input, so boarding-point searches are intentionally not implemented.
• Station codes need independent manual verification; GAPEKA route codes are not auto-converted into station pages.
• Bulk import is an admin file-upload workflow. ChatGPT can monitor/retry jobs and correct individual schedules via REST, but the full 682 KB source JSON is not intended to be passed through an MCP tool call.
• Historical revision comparison and advanced SEO indexation rules are candidates for the next release.
• Rollback only supports the last active correction for a schedule; older corrections require a new compensating correction, preserving the full audit trail.
• This release does not detect unexpected pre-existing taxonomy rewrites and permalink policies in production; test them in staging.

Development QA

find . -name '*.php' -print0 | xargs -0 -n1 php -l
php tests/validate-fixture.php tests/fixture-2025-sample.json
php tests/validate-fixture.php /path/to/gapeka_2025_trains.json

Uninstall

Deleting the plugin retains its tables and wiki posts by design. Historical archives should never disappear through an accidental uninstall. To delete data permanently, take a backup and perform a deliberate database/post cleanup separately.

License: GPL-2.0-or-later.