feat(init): friendlier onboarding — quickstart instead of a dead-end error

[giancolombi]

Problem (reported)

prodcycle init with nothing to auto-configure printed a dense, hard-to-read paragraph and exited with code 2 (an error) — a hostile first-run experience:

init: nothing to do. Use --agent <name> to configure a coding agent (claude, cursor, codex, opencode, github-copilot, gemini-cli, or "all"), --ci <provider> to scaffold CI workflows (github, gitlab, circleci, or "all"), and/or --api-key <key> to save your credentials. Without --agent the CLI also auto-detects agents already in use.

After

init now prints a scannable, copy-pasteable quickstart and exits 0 (discovering the options isn't an error):

ProdCycle — set up compliance checks for this repo.

Nothing to configure here yet. Here's how to get started:

  Coding agents · block non-compliant edits as you code
    prodcycle init --agent claude     (or cursor, codex, opencode, github-copilot, gemini-cli)
    prodcycle init --agent all        every agent detected in this repo

  CI pipelines · gate pull requests
    prodcycle init --ci github        (or gitlab, circleci, all)

  API key · so hooks authenticate without an env var
    prodcycle init --api-key pc_...

  Scan now
    prodcycle scan .

Docs & API keys: https://docs.prodcycle.com

Plus two smaller onboarding wins from the audit:

• --help gains a "Quick start" examples block (commander addHelpText / argparse epilog).
• The missing-API-key error now points to where to get a key.

Parity & tests

Node + Python init output is byte-identical (verified by a new parity test that spawns both and diffs). +1 node / +1 python test; full suites green (121 node / 109 python). No version bump — release when ready.

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR improves first-run UX by replacing prodcycle init's terse exit-2 error with a scannable, copy-pasteable quickstart printed to stdout with exit 0, and adds a "Quick start" block to --help in both the Node and Python CLIs.

• init with nothing to configure now calls process.stdout.write / sys.stdout.write with a shared constant and exits 0; the constant is kept byte-identical across runtimes and verified by a new Node parity test that spawns both CLIs and diffs their stdout.
• The missing-API-key error message in both api-client.ts and api_client.py is updated to direct users to the docs URL for a key.
• A standalone Python unit test (test_init_quickstart.py) covers the exit-0 and content assertions; it mirrors the Node parity test but lacks a timeout on subprocess.run (see inline comment).

Confidence Score: 5/5

Safe to merge — changes are limited to CLI output text, exit codes, and test files; no production logic is altered.

All modified paths are user-facing message strings, exit-code adjustments, and new tests. The byte-identical invariant is enforced by the new parity test, and both runtimes received symmetric updates. The only rough edge is a missing timeout in the Python unit test, which is a test-reliability nit rather than anything that could regress the application.

python/tests/test_init_quickstart.py — subprocess.run has no timeout; add timeout=10 to match the Node parity test.

Important Files Changed

Filename	Overview
node/src/cli.ts	Replaces exit-2 error message with a friendly stdout quickstart and exit 0; adds --help examples block via addHelpText.
python/src/prodcycle/cli.py	Python-side parity: same exit-0 quickstart message and argparse epilog; byte-identical to the Node constant.
node/test/init-quickstart-parity.test.mjs	New parity test that spawns both runtimes with 10 s timeouts and diffs stdout; includes spawn-error surfacing via error.message.
python/tests/test_init_quickstart.py	New Python unit test mirrors the parity test; subprocess.run lacks a timeout, which could hang the test runner if the child process stalls.
node/src/api-client.ts	Tiny error message tweak to point users to docs for an API key; no logic change.
python/src/prodcycle/api_client.py	Same API-key error message update as the Node counterpart; no logic change.
CHANGELOG.md	Changelog entry accurately captures the onboarding improvements under [Unreleased].

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
python/tests/test_init_quickstart.py:24-26
The `subprocess.run` call has no `timeout` argument. If the spawned Python process deadlocks or blocks on I/O, this test (and the CI job running it) will hang indefinitely. The companion Node parity test already guards against this with `timeout: 10_000` — the same protection should apply here. `subprocess.run` raises `subprocess.TimeoutExpired` on timeout, which the test runner will surface as a failure rather than a hang.

```suggestion
            result = subprocess.run(
                [sys.executable, '-c', code], capture_output=True, text=True,
                timeout=10,
            )
```

_{Reviews (2): Last reviewed commit: "test(init): add spawnSync timeout + surf..." | Re-trigger Greptile}