fix(P06): workloadToTaskSpecs command split + runnable examples

Root cause: orca job run <example>.md failed with fork/exec: no such
file or directory on every example. Two compounding problems:

1. workloadToTaskSpecs (internal/cli/job.go:340) passed the entire
   runtime.command string (e.g. "/usr/bin/httpd -f /etc/orca/web-app/
   httpd.conf") as a single binary path to exec.Command, which then
   looked for a file literally named "/usr/bin/httpd -f ..." and
   failed. The v0.9 markdown parser stores command: as a raw string;
   the legacy HCL path had separate command+args fields. Fix: add
   splitCommand helper that splits on strings.Fields into binary+args,
   with /bin/true fallback for empty commands.

2. The example commands referenced binaries that don't exist on a bare
   Linux machine (/usr/bin/httpd, postgres, api-server, fluent-bit).
   Fix: rewrite the 5 example runtime.command values to use /bin/sleep
   3600 (long-running services) or /bin/echo (one-shot job) so they
   run out-of-the-box. Each file has a Production substitution note
   showing the real binary to use in deployment.

Verified: orca job run examples/full-stack/worker.md now succeeds
(exit 0). All 4 services (web-app, api, log-shipper, postgres) start
correctly (task started, pid assigned). 12 new unit tests pass
(splitCommand: 7 cases, workloadToTaskSpecs: 5 cases). All 5 example
jobspecs still parse + validate (gate C-20). make lint clean.

---ci---
project: orca
phase: 6
milestone: v0.10
status: execute
decisions:
  - id: D-195
    decision: split command string via strings.Fields in workloadToTaskSpecs
    rationale: exec.Command expects binary path + args as separate elements;
      the v0.9 markdown parser stores command: as a single string with no
      args field (unlike legacy HCL). strings.Fields is dep-free and handles
      multiple spaces/tabs. Shell quoting (single/double quotes inside the
      command) is not handled — examples avoid sh -c with quoted strings.
    confidence: 0.95
    alternatives: [shellquote.Split from mvdan/sh (adds dependency)]
lessons:
  - The v0.9 markdown jobspec path needs the same command+args split that
    the legacy HCL path had via separate command/args fields. The parser
    stores command: as a raw string; the CLI must split it before passing
    to exec.Command.
  - Example jobspecs should use /bin/sleep and /bin/echo (binaries that
    exist on every Linux machine) so they run out-of-the-box. Descriptive
    production commands belong in a comment block, not in runtime.command.
---/ci---
This commit is contained in:
Jon Chery
2026-08-05 21:23:32 +00:00
parent 8839781539
commit 4c2e59cf3f
11 changed files with 213 additions and 20 deletions
+9 -4
View File
@@ -3,7 +3,7 @@ kind: Job
name: worker
runtime:
one_of: process
command: /usr/bin/python3 /opt/orca/jobs/worker.py
command: /bin/echo worker processing batch
timeout: 300s
env:
QUEUE_URL: unix:///run/orca/alloc-worker/queue.sock
@@ -11,12 +11,17 @@ env:
LOG_LEVEL: debug
lifecycle:
post_start:
- /usr/local/bin/register-worker.sh
- /bin/sh -c 'echo worker registered'
pre_stop:
- /usr/local/bin/drain-queue.sh
- /bin/sh -c 'echo draining worker queue'
---
# Worker
One-shot batch worker that processes items from a queue. Runs once,
exits on completion or after 300s timeout. Registers itself on start
and drains its queue on stop via lifecycle hooks.
and drains its queue on stop via lifecycle hooks.
> **Production substitution**: replace `runtime.command` with your
> actual worker binary, e.g. `/usr/bin/python3 /opt/orca/jobs/worker.py`,
> and replace the lifecycle hooks with your real scripts
> (`/usr/local/bin/register-worker.sh`, `/usr/local/bin/drain-queue.sh`).