Skip to content

feat(cli): group pdd --help and add pdd autopilot logs --follow (#3496, #3475) - #3506

Open
Serhan-Asad wants to merge 4 commits into
mainfrom
feat/grouped-help-and-autopilot-logs
Open

Serhan-Asad wants to merge 4 commits into
mainfrom
feat/grouped-help-and-autopilot-logs

Conversation

@Serhan-Asad

@Serhan-Asad Serhan-Asad commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

This pull request makes pdd --help easy to scan and adds a read-only pdd autopilot logs command for headless Autopilot workers.

Size: +2984 / -268 lines across 16 files.

Closes #3496
Closes #3475

Issues:

What Changed

  1. Grouped root pdd --help and focused command help (Make pdd --help easier to scan with grouped commands and focused help #3496)

    • Root help (pdd, pdd --help, pdd -h, pdd -help, pdd help) now opens with a short summary, a Usage: line, and a 4-line Quick start: section (pdd setup, pdd test, pdd simulate, pdd help prompting).
    • Commands are grouped by purpose in human-first order:
      1. Core PDD workflow (setup, test, lint, simulate, approve, files, owner, contracts, jobs, mcp, upgrade)
      2. Cloud accounts (pdd accounts --help)
      3. Workflows & product (pdd workflow --help, pdd product --help)
      4. Autopilot (pdd autopilot --help)
      5. Metrics, shell & help (pdd metrics --help)
    • Every line on root pdd --help (including closingLines) fits within 80 columns.
    • Detailed options, defaults, constraints, and quoted approval heredoc examples stay in focused command help (pdd <command> --help) without repeating on the root page.
    • Removed the stale full-engine migration sentence from pdd autopilot start --help.
    • Preserved the installed Prompting guide and RUNBOOK path lines and closing guidance.
  2. Read-only pdd autopilot logs and --follow ([alpha] A person cannot follow a headless Autopilot worker through a native attach or live-log command #3475)

    • Added prompts/cli/autopilot-logs.prompt.md (with ## Domain decisions, sole leaf [Secret redaction](secret-redaction.prompt.md) under ## Dependencies, and ## Caller navigation) and src/autopilot-logs.mjs, wired through runAutopilotSubcommand('logs', ...) in src/autopilot.mjs and src/pdd-cli.mjs.
    • Added two public forms to src/command-catalog.mjs, shell completion, and docs/cli.md (accepting N, #N, owner/repo#N, and GitHub issue URLs both positionally and via --issue):
      • pdd autopilot logs [ISSUE] [--follow|-f] [--lines N] [--json]
      • pdd autopilot logs --issue N [--follow|-f] [--lines N] [--json]
    • Without an issue argument, pdd autopilot logs lists current headless workers sorted by issue (stage, owned process state, shared suite queue position, blockers, last activity, and saved log and evidence paths), recent finished workers, and the exact --follow command.
    • Distinguishes waiting in the shared test-suite queue (suite-queued), live suite execution with validation logs (suite-running), repair passes (repair), and stale suite receipts or dead worker PIDs (suite-stale).
    • Enforces pid > 1 and treats any kill(pid, 0) error (ESRCH or EPERM) as not running so PID 1 or non-owned processes are never misclassified as Autopilot workers.
    • Formats Codex, Claude, and Gemini/agy JSONL logs and plain test logs into readable progress lines, coerces numeric token/exit fields individually, guards epoch timestamps with Number.isFinite(ts) && Math.abs(ts) <= 8.64e15, aligns tail and follow reads to \n byte boundaries without dropping trailing-newline tails or splitting UTF-8/secrets mid-line, strips ANSI/control codes, and redacts secrets with redactSecrets(..., knownSecretValues(env)) across human, --follow, and --json outputs.
    • --follow (-f) reuses the resolved gitRoot across polls, handles stdout close and EPIPE cleanly for piped callers (| head -n 5), enforces maxDurationMs (default 60 minutes), and detaches cleanly on Ctrl-C without stopping the worker or changing observe mode.

No Story: CLI help layout and read-only native Autopilot worker log viewer covered by unit and formal CLI tests.

Verification

Tested locally with isolated test-home.mjs and test-net-guard.mjs (103 focused tests passed, 0 failed):

  • pdd owner on src/autopilot-logs.mjs, src/autopilot.mjs, src/command-catalog.mjs, src/pdd-cli.mjs: all current, 0 warnings.
  • pdd files --json and pdd test --files on touched prompts and Stories: 0 refusals, 0 dependency cycles on autopilot-logs.prompt.md.
  • pdd lint --local --json: exit code 0.
  • test/grouped-help.test.mjs and test/autopilot-logs.test.mjs
  • test/docs-commands.test.mjs and test/docs-first-time.test.mjs
  • test/help-teaches-pdd.test.mjs, test/approval-help.test.mjs, test/cli-help-words.test.mjs, test/cli-preview-help.test.mjs, test/command-catalog.test.mjs, test/file-owner.test.mjs
  • test/new-command-names.formal.test.mjs, test/name-the-interpreter.formal.test.mjs, test/workflow-request-uptake.review.test.mjs
  • test/pdd-cli.test.mjs, test/autopilot-cli.test.mjs, test/autopilot.test.mjs, test/setup.test.mjs, test/interpreter-version.test.mjs
  • Targeted ALPHA1 (test/cli.test.mjs), SEAM5 (test/runtime-seam.test.mjs), and cli-catalog-dispatch (test/workflow-request-uptake.vectors.test.mjs).

Full npm test has not been run on the laptop and will run in CI.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant