lhumina_code/hero_proc
2
0
Fork 0
Code Issues 26 Pull requests Projects Releases 2 Packages Wiki Activity Actions

check documentation #5

New issue
Closed
opened 2026-03-19 07:49:01 +00:00 by despiegk · 5 comments
despiegk commented 2026-03-19 07:49:01 +00:00
Owner
Copy link

hero_proc/docs

check against reality, deep research
and make sure schema's are complete

fix all docs/specs

hero_proc/docs check against reality, deep research and make sure schema's are complete fix all docs/specs
despiegk commented 2026-03-19 07:58:15 +00:00
Author
Owner
Copy link

Implementation Spec: Documentation Audit for hero_proc

Objective

Audit all documentation and schema files against the actual Rust implementation. Fix every discrepancy so docs are accurate, complete, and consistent with code at v0.4.0.

Summary of Findings

# File Issues Found
1 docs/hero_proc_db_oschema/actions.oschema Missing exec interpreter variant and tty field
2 docs/hero_proc_db_oschema/jobs.oschema Legacy zinit_service_name field name
3 crates/hero_proc_server/openrpc.json Missing job.process_stats method
4 docs/hero_proc_openrpc/openrpc.md 1 phantom method, 3 missing methods, wrong params, incomplete schemas
5 docs/SDK.md Wrong return type (ServiceConfig vs ServiceBuildResult), 5 missing builder methods
6 docs/SDK_EXAMPLES.md Wrong return type in examples
7 docs/BUILDERS.md Wrong return type for build()
8 docs/CLI_REFERENCE.md 3 phantom commands, 2 missing commands, wrong output format, wrong version
9 docs/CLI.md Same CLI issues + wrong repository URL
10 docs/SERVICE_SPECS.md Documents legacy [jobs] TOML section and non-existent oneshot field
11 crates/hero_proc_ui/docs/* 10 stale duplicate docs that have drifted

Implementation Plan (11 Steps)

  1. Fix actions.oschema — add exec interpreter, add tty field
  2. Fix jobs.oschema — rename zinit_service_name
  3. Fix openrpc.json — add job.process_stats method
  4. Fix openrpc.md — remove phantom method, add 3 missing methods, fix params/schemas
  5. Fix SDK.md — correct return type to ServiceBuildResult, add 5 missing methods
  6. Fix SDK_EXAMPLES.md — update examples for ServiceBuildResult
  7. Fix BUILDERS.md — correct return type
  8. Fix CLI_REFERENCE.md — remove phantom commands, add missing ones, fix output format, update version
  9. Fix CLI.md — same CLI fixes + correct repository URL
  10. Fix SERVICE_SPECS.md — replace legacy jobs/oneshot docs with action-based architecture
  11. Sync or remove crates/hero_proc_ui/docs/* stale copies

Acceptance Criteria

  • Every RPC method in dispatch has an entry in openrpc.json
  • openrpc.md matches openrpc.json — no phantoms, no missing
  • OSchema files match Rust model structs
  • SDK.md documents ServiceBuildResult and all public builder methods
  • CLI docs list exactly the commands in args.rs
  • No references to version 0.2.x (all updated to 0.4.0)
  • No references to github.com/threefoldtech
  • SERVICE_SPECS.md describes action-based architecture
  • UI docs synchronized with main docs
  • All existing tests still pass
## Implementation Spec: Documentation Audit for hero_proc ### Objective Audit all documentation and schema files against the actual Rust implementation. Fix every discrepancy so docs are accurate, complete, and consistent with code at v0.4.0. ### Summary of Findings | # | File | Issues Found | |---|------|--------------| | 1 | `docs/hero_proc_db_oschema/actions.oschema` | Missing `exec` interpreter variant and `tty` field | | 2 | `docs/hero_proc_db_oschema/jobs.oschema` | Legacy `zinit_service_name` field name | | 3 | `crates/hero_proc_server/openrpc.json` | Missing `job.process_stats` method | | 4 | `docs/hero_proc_openrpc/openrpc.md` | 1 phantom method, 3 missing methods, wrong params, incomplete schemas | | 5 | `docs/SDK.md` | Wrong return type (`ServiceConfig` vs `ServiceBuildResult`), 5 missing builder methods | | 6 | `docs/SDK_EXAMPLES.md` | Wrong return type in examples | | 7 | `docs/BUILDERS.md` | Wrong return type for `build()` | | 8 | `docs/CLI_REFERENCE.md` | 3 phantom commands, 2 missing commands, wrong output format, wrong version | | 9 | `docs/CLI.md` | Same CLI issues + wrong repository URL | | 10 | `docs/SERVICE_SPECS.md` | Documents legacy `[jobs]` TOML section and non-existent `oneshot` field | | 11 | `crates/hero_proc_ui/docs/*` | 10 stale duplicate docs that have drifted | ### Implementation Plan (11 Steps) 1. Fix `actions.oschema` — add `exec` interpreter, add `tty` field 2. Fix `jobs.oschema` — rename `zinit_service_name` 3. Fix `openrpc.json` — add `job.process_stats` method 4. Fix `openrpc.md` — remove phantom method, add 3 missing methods, fix params/schemas 5. Fix `SDK.md` — correct return type to `ServiceBuildResult`, add 5 missing methods 6. Fix `SDK_EXAMPLES.md` — update examples for `ServiceBuildResult` 7. Fix `BUILDERS.md` — correct return type 8. Fix `CLI_REFERENCE.md` — remove phantom commands, add missing ones, fix output format, update version 9. Fix `CLI.md` — same CLI fixes + correct repository URL 10. Fix `SERVICE_SPECS.md` — replace legacy jobs/oneshot docs with action-based architecture 11. Sync or remove `crates/hero_proc_ui/docs/*` stale copies ### Acceptance Criteria - [ ] Every RPC method in dispatch has an entry in openrpc.json - [ ] openrpc.md matches openrpc.json — no phantoms, no missing - [ ] OSchema files match Rust model structs - [ ] SDK.md documents ServiceBuildResult and all public builder methods - [ ] CLI docs list exactly the commands in args.rs - [ ] No references to version 0.2.x (all updated to 0.4.0) - [ ] No references to github.com/threefoldtech - [ ] SERVICE_SPECS.md describes action-based architecture - [ ] UI docs synchronized with main docs - [ ] All existing tests still pass
despiegk commented 2026-03-19 08:09:54 +00:00
Author
Owner
Copy link

Test Results

  • Total: 386 (370 ran + 16 ignored)
  • Passed: 370
  • Failed: 0
  • Ignored: 16

All tests passing. No failures detected.

## Test Results - Total: 386 (370 ran + 16 ignored) - Passed: 370 - Failed: 0 - Ignored: 16 All tests passing. No failures detected.
despiegk commented 2026-03-19 08:10:30 +00:00
Author
Owner
Copy link

Final Implementation Summary

Schema Fixes

  • docs/hero_proc_db_oschema/actions.oschema — Added exec interpreter variant and tty: bool field
  • docs/hero_proc_db_oschema/jobs.oschema — Renamed zinit_service_name to hero_proc_service_name

OpenRPC Fixes

  • crates/hero_proc_server/openrpc.json — Added job.process_stats method, documented log.query and log.count aliases
  • docs/hero_proc_openrpc/openrpc.md — Removed phantom service.reload, added 6 missing methods (system.stats, job.process_stats, log.query, log.count, schedule.list, schedule.status), fixed system.shutdown params, fixed DependencyDef schema, updated ActionSpec fields

SDK Fixes

  • docs/SDK.md — Corrected return type to ServiceBuildResult, documented 5 missing builder methods
  • docs/SDK_EXAMPLES.md — Updated all 8 examples for ServiceBuildResult, fixed 2 compilation bugs
  • docs/BUILDERS.md — Corrected return type, documented ServiceBuildResult struct

CLI Fixes

  • docs/CLI_REFERENCE.md — Removed 3 phantom commands, added 2 missing commands, fixed list output format, updated version to 0.4.0
  • docs/CLI.md — Same CLI fixes, corrected repository URL to forge.ourworld.tf

Service Spec Fixes

  • docs/SERVICE_SPECS.md — Replaced legacy [jobs] TOML section with action-based architecture, removed non-existent oneshot field, rewrote with correct JSON data model

UI Docs Sync

  • Synchronized 7 files from main docs to crates/hero_proc_ui/docs/

Test Results

  • 370 tests passed, 0 failed, 16 ignored
## Final Implementation Summary ### Schema Fixes - `docs/hero_proc_db_oschema/actions.oschema` — Added `exec` interpreter variant and `tty: bool` field - `docs/hero_proc_db_oschema/jobs.oschema` — Renamed `zinit_service_name` to `hero_proc_service_name` ### OpenRPC Fixes - `crates/hero_proc_server/openrpc.json` — Added `job.process_stats` method, documented `log.query` and `log.count` aliases - `docs/hero_proc_openrpc/openrpc.md` — Removed phantom `service.reload`, added 6 missing methods (system.stats, job.process_stats, log.query, log.count, schedule.list, schedule.status), fixed system.shutdown params, fixed DependencyDef schema, updated ActionSpec fields ### SDK Fixes - `docs/SDK.md` — Corrected return type to `ServiceBuildResult`, documented 5 missing builder methods - `docs/SDK_EXAMPLES.md` — Updated all 8 examples for `ServiceBuildResult`, fixed 2 compilation bugs - `docs/BUILDERS.md` — Corrected return type, documented `ServiceBuildResult` struct ### CLI Fixes - `docs/CLI_REFERENCE.md` — Removed 3 phantom commands, added 2 missing commands, fixed list output format, updated version to 0.4.0 - `docs/CLI.md` — Same CLI fixes, corrected repository URL to forge.ourworld.tf ### Service Spec Fixes - `docs/SERVICE_SPECS.md` — Replaced legacy [jobs] TOML section with action-based architecture, removed non-existent oneshot field, rewrote with correct JSON data model ### UI Docs Sync - Synchronized 7 files from main docs to `crates/hero_proc_ui/docs/` ### Test Results - **370 tests passed, 0 failed, 16 ignored**
despiegk commented 2026-03-19 08:23:12 +00:00
Author
Owner
Copy link

Implementation committed: 15ee3a3

Browse: 15ee3a3

Implementation committed: `15ee3a3` Browse: https://forge.ourworld.tf/lhumina_code/hero_proc/commit/15ee3a3
despiegk commented 2026-03-19 08:41:54 +00:00
Author
Owner
Copy link

Claude Skill Files Fixed

Two external skill files were audited against the hero_proc implementation and corrected:

hero_proc_sdk Skill (hero_skills/claude/skills/hero_proc_sdk/SKILL.md)

Fixed:

  • Preset functions (simple_service, oneshot_service, system_service, sleep_service) return type corrected from ServiceConfig to ServiceBuildResult
  • Added 4 missing ActionBuilder methods: tty(), interpreter(), depends_on(), depends_on_with_type()
  • Added missing ServiceBuilder method: action_name()
  • Added exec interpreter variant to documentation
  • Fixed stop_timeout_ms default from 5000ms to 10000ms
  • Fixed Cargo.toml branch from development_kristof_ttyd to development
  • Added complete Quick Service RPC namespace documentation (7 methods)
  • Fixed system_service() example that incorrectly chained methods on ServiceBuildResult

hero_proc_cmd Skill (hero_skills/claude/skills/hero_proc_cmd/SKILL.md)

Removed phantom features:

  • reload command (doesn't exist)
  • xinet command group (doesn't exist)
  • --persist, --ephemeral, --oneshot flags (don't exist on add service)
  • --exec flag on add service (only exists on add job)
  • TOML service file format (didn't match action-based architecture)

Fixed:

  • add-service syntax corrected to add service (subcommand, not hyphenated)
  • add service flags corrected to actual: name, --description, --class, --after, --requires, --wants, --conflicts

Added missing command groups:

  • add job, job, run, secret, action, config, build, lint, schedules, stats, attach, demo, completion, logs-cmd
  • Global flags: --format, --output, --quiet, --verbose
## Claude Skill Files Fixed Two external skill files were audited against the hero_proc implementation and corrected: ### hero_proc_sdk Skill (`hero_skills/claude/skills/hero_proc_sdk/SKILL.md`) **Fixed:** - Preset functions (`simple_service`, `oneshot_service`, `system_service`, `sleep_service`) return type corrected from `ServiceConfig` to `ServiceBuildResult` - Added 4 missing ActionBuilder methods: `tty()`, `interpreter()`, `depends_on()`, `depends_on_with_type()` - Added missing ServiceBuilder method: `action_name()` - Added `exec` interpreter variant to documentation - Fixed `stop_timeout_ms` default from 5000ms to 10000ms - Fixed Cargo.toml branch from `development_kristof_ttyd` to `development` - Added complete Quick Service RPC namespace documentation (7 methods) - Fixed `system_service()` example that incorrectly chained methods on `ServiceBuildResult` ### hero_proc_cmd Skill (`hero_skills/claude/skills/hero_proc_cmd/SKILL.md`) **Removed phantom features:** - `reload` command (doesn't exist) - `xinet` command group (doesn't exist) - `--persist`, `--ephemeral`, `--oneshot` flags (don't exist on `add service`) - `--exec` flag on `add service` (only exists on `add job`) - TOML service file format (didn't match action-based architecture) **Fixed:** - `add-service` syntax corrected to `add service` (subcommand, not hyphenated) - `add service` flags corrected to actual: name, --description, --class, --after, --requires, --wants, --conflicts **Added missing command groups:** - `add job`, `job`, `run`, `secret`, `action`, `config`, `build`, `lint`, `schedules`, `stats`, `attach`, `demo`, `completion`, `logs-cmd` - Global flags: `--format`, `--output`, `--quiet`, `--verbose`
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
development_sameh_hp02
main
latest
lab-latest
v0.5.0-rc2
v0.5.0-rc1
v0.4.4
v0.4.1
v0.1.1
Labels
Clear labels   
prio_critical

   
prio_low

   
type_bug

   
type_contact

   
type_issue

   
type_lead

   
type_question

   
type_story

   
type_task
No labels
prio_critical
prio_low
type_bug
type_contact
type_issue
type_lead
type_question
type_story
type_task
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_proc#5
No description provided.