Expose missing Docusaurus DocSite methods over OpenRPC #101

New issue

Closed

opened 2026-04-26 12:22:24 +00:00 by mahmoud · 1 comment

mahmoud commented

2026-04-26 12:22:24 +00:00

Owner

Overview

hero_books_docusaurus exposes more capabilities on the DocSite struct than are currently surfaced over RPC. Only 3 methods are wired today (docs.new, docs.generate, docs.jobStatus). Six more need to be added.

Files to work in

crates/hero_books_server/src/web/rpc.rs — handlers + dispatcher (match at line 155)
crates/hero_books_server/openrpc.json — spec (bump info.version on change)
crates/hero_books_docusaurus/src/lib.rs — DocSite struct being wrapped
hero_docs binary — must have matching subcommands before writing handlers

Handler pattern to follow

fn handle_docs_new(
    id: Option<Value>,
    params: Option<Value>,
    config: &ServerConfig,
) -> RpcResponse

Shell out via hero_docs binary (never call DocSite in-process). Use submit_or_dedup_docs_job(id, config, "docs_<verb>_<hash>", &script).
Use calculate_docs_input_hash, shell_quote, get_docusaurus_cache_dir as helpers.

Child Issues

#102 — docs.installTemplate
#103 — docs.updateTemplate
#104 — docs.build
#105 — docs.dev (long-running)
#106 — docs.publish
#107 — docs.publishDev

## Overview `hero_books_docusaurus` exposes more capabilities on the `DocSite` struct than are currently surfaced over RPC. Only 3 methods are wired today (`docs.new`, `docs.generate`, `docs.jobStatus`). Six more need to be added. ## Files to work in - `crates/hero_books_server/src/web/rpc.rs` — handlers + dispatcher (match at line 155) - `crates/hero_books_server/openrpc.json` — spec (bump `info.version` on change) - `crates/hero_books_docusaurus/src/lib.rs` — DocSite struct being wrapped - `hero_docs` binary — must have matching subcommands before writing handlers ## Handler pattern to follow ```rust fn handle_docs_new( id: Option<Value>, params: Option<Value>, config: &ServerConfig, ) -> RpcResponse ``` Shell out via `hero_docs` binary (never call DocSite in-process). Use `submit_or_dedup_docs_job(id, config, "docs_<verb>_<hash>", &script)`. Use `calculate_docs_input_hash`, `shell_quote`, `get_docusaurus_cache_dir` as helpers. ## Child Issues - [x] #102 — docs.installTemplate - [x] #103 — docs.updateTemplate - [x] #104 — docs.build - [x] #105 — docs.dev (long-running) - [x] #106 — docs.publish - [x] #107 — docs.publishDev

mahmoud referenced this issue

2026-04-26 12:23:50 +00:00

Add docs.installTemplate RPC method #102

mahmoud referenced this issue

2026-04-26 12:24:20 +00:00

Add docs.updateTemplate RPC method #103

mahmoud referenced this issue

2026-04-26 12:25:14 +00:00

Add docs.build RPC method #104

mahmoud referenced this issue

2026-04-26 12:25:50 +00:00

Add docs.dev RPC method (long-running) #105

mahmoud referenced this issue

2026-04-26 12:26:18 +00:00

Add docs.publish RPC method #106

mahmoud referenced this issue

2026-04-26 12:26:40 +00:00

Add docs.publishDev RPC method #107

rawdaGastan self-assigned this

2026-04-26 12:30:38 +00:00

rawdaGastan added this to the ACTIVE project

2026-04-26 12:30:39 +00:00

mahmoud added this to the now milestone

2026-04-26 13:57:18 +00:00

rawdaGastan referenced this issue from a pull request that will close it,

2026-04-26 14:47:27 +00:00

feat(rpc): expose Docusaurus DocSite methods over OpenRPC #108

rawdaGastan referenced this issue

2026-04-26 14:48:05 +00:00

Add docs.installTemplate RPC method #102

rawdaGastan referenced this issue

2026-04-27 09:07:49 +00:00

Add docs.publish RPC method #106

rawdaGastan referenced this issue

2026-04-27 09:46:44 +00:00

Add docs.publishDev RPC method #107

rawdaGastan referenced this issue from a commit

2026-04-27 09:47:04 +00:00

feat(rpc): expose docs.publishDev over OpenRPC

rawdaGastan commented

2026-04-27 09:47:27 +00:00

Member

All 6 child issues complete. Rolling PR #108 is now ready to merge.

PR: #108
Branch: development_docs_rpc_methods
Commits: 6 (one per child issue), all linear on top of development.

Final state:

#102 — docs.installTemplate
#103 — docs.updateTemplate
#104 — docs.build (with output_path recovery via base64url-encoded action names)
#105 — docs.dev (long-running, no timeout, cancel via hero_proc job.cancel JSON-RPC)
#106 — docs.publish (build-dir path, default production rsync target)
#107 — docs.publishDev (heroscript path, dev destinations from !!site.publish_dev)

Verification at PR head:

26/26 lib tests pass (debug + release)
cargo clippy silent on both hero_books_server and hero_docs
INSTRUCTIONS_OPENRPC.md §Verification diff empty
Live rpc.discover lists all 9 docs.* methods (3 originals + 6 new)
info.version bumped once: 0.1.5 -> 0.1.6 (in #102; subsequent children reuse)

All 6 child issues complete. Rolling PR #108 is now ready to merge. PR: https://forge.ourworld.tf/lhumina_code/hero_books/pulls/108 Branch: `development_docs_rpc_methods` Commits: 6 (one per child issue), all linear on top of `development`. Final state: - [x] #102 — `docs.installTemplate` - [x] #103 — `docs.updateTemplate` - [x] #104 — `docs.build` (with output_path recovery via base64url-encoded action names) - [x] #105 — `docs.dev` (long-running, no timeout, cancel via hero_proc `job.cancel` JSON-RPC) - [x] #106 — `docs.publish` (build-dir path, default production rsync target) - [x] #107 — `docs.publishDev` (heroscript path, dev destinations from `!!site.publish_dev`) Verification at PR head: - 26/26 lib tests pass (debug + release) - `cargo clippy` silent on both `hero_books_server` and `hero_docs` - INSTRUCTIONS_OPENRPC.md §Verification diff empty - Live `rpc.discover` lists all 9 `docs.*` methods (3 originals + 6 new) - info.version bumped once: 0.1.5 -> 0.1.6 (in #102; subsequent children reuse)

rawdaGastan referenced this issue from a commit

2026-04-27 09:57:45 +00:00

chore(docs): remove INSTRUCTIONS_OPENRPC.md

rawdaGastan closed this issue

2026-04-27 09:58:55 +00:00