fix(cli): support JSON output on the default alias command

[oocheol]

Summary

• ocx alias defaults to listing, but ocx alias --json treats the flag as an action and fails. Consume the output flag before selecting the action so default and explicit list forms work in either order.
• Add focused regression coverage and update the source-owner contract plus English/Korean user documentation.
• Independent branch from dev 8b23fe340a53799aac5ad7654582a75df7ade7c8; this PR contains only this change.

Verification

Validated on Windows with Bun 1.4.0 at current head d54ce4964792dea5a3e6a0331733b5517228c085. The layout and file-size guards run from a fresh worktree with the default test budget; no guard, fixture directory, baseline cap, or timeout was changed.

• bun run scripts/test.ts tests/cli/cli-alias-json.test.ts: PASS, 4 pass / 0 fail.
• bun node_modules/typescript/bin/tsc --noEmit: PASS, exit 0.
• bun scripts/structure-ssot.ts: PASS, exit 0.
• bun scripts/privacy-scan.ts: PASS, exit 0.
• bun run scripts/test.ts tests/test-layout.test.ts tests/test-layout-tooling.test.ts tests/ci-workflows/file-size-ratchet.test.ts: PASS, 27 pass / 0 fail.

The first validation from the original Windows checkout failed on a pre-existing EPERM fixture directory and, in some runs, a five-second subprocess timeout. Those attempts remain historical failures; the fresh-worktree current-head guard result above replaces neither the failure record nor a required CI run. The first cold file-size scan for #6429 also exceeded five seconds, then passed at the same head on the same default budget. No inaccessible fixture was deleted and no test budget was raised.

Integration validation used actual local merges of all ten PR heads onto dev 03ed9a3b1c1535d25f8f47c3d6bf38db8ffc1fc9 (local-only assembled commit dd7d1fe254c3fc86144a2c3cce0ae483332b55bb). Owner-contract edits in runtime/config/usage now merge independently; shared observe.ts consumers merge without a source conflict. Additive EN/KO document-append conflicts and test-map insertion conflicts were reconciled by retaining both sections/registrations, not choosing one PR over another.

• The combined 24-file focused regression set: 331 pass / 3 platform skips / 0 fail.
• Combined layout and file-size guards: 27 pass / 0 fail with the default budget.
• Combined typecheck, structure SSOT, privacy scan, generated operating surface check, and docs-site build: PASS.

Full bun run test and bun run test:changed remain unrun: nine small independently validated revisions plus a combined 24-file run share one Windows machine, so repeated full repository runs on each draft would be disproportionate. The explicit regression files cover the touched behavior and source-oracle consumers; broader platform/integration coverage remains for exact-head CI. Updated-head CI and automated review must be confirmed separately; older-head results, queued jobs, skipped jobs, and approval-pending runs are not passing evidence.

Review response: Documented alias management and moved its contract next to alias resolution, avoiding the shared readiness-diagnostics edit. Added function documentation addresses the warning in source; the remote coverage percentage is not claimed as rerun. All descriptions retain only the gate-managed canonical readiness checklist.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. No credential values, authentication policy, dependency installation, or workflow permissions are changed.

Review readiness checklist

This PR stays in draft until every box below is ticked. Tick all four boxes once the requirements are met:

• Required local validation passed; commands, results, and any full-suite exception are documented.

• I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features
  • The CLI alias list supports JSON output with ocx alias --json or ocx alias list --json.
  • For explicit alias actions, --json can appear before or after the action.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 9 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 3bc9910b-ed4b-430c-b275-7d2bd98014b0

📥 Commits

Reviewing files that changed from the base of the PR and between 56c5fc6 and d54ce49.

📒 Files selected for processing (2)

• src/cli/alias.ts
• structure/runtime.md

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: lidge-jun/opencodex/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ef893e5c-8526-4200-930b-dfe5868cf66a

📥 Commits

Reviewing files that changed from the base of the PR and between 3d77e3d and 56c5fc6.

📒 Files selected for processing (7)

• docs-site/src/content/docs/ko/reference/cli.md
• docs-site/src/content/docs/reference/cli.md
• scripts/test-layout/layout.json
• src/cli/alias.ts
• structure/runtime.md
• tests/cli/cli-alias-json.test.ts
• tests/fixtures/test-layout-expected.json

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

The alias CLI now handles JSON output alongside default alias listing and explicit alias actions. Tests cover listing and setting aliases with the flag. The English and Korean CLI references and runtime documentation describe the argument behavior.

Changes

Alias JSON flag handling

Layer / File(s)	Summary
Argument handling and documented usage src/cli/alias.ts, tests/cli/cli-alias-json.test.ts, scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json, docs-site/src/content/docs/reference/cli.md, docs-site/src/content/docs/ko/reference/cli.md, structure/runtime.md	The handler selects the action before processing --json. Tests cover alias listing with --json alone or before or after list, and setting an alias with the flag before set. The test-layout mapping and fixture include the new test. The CLI references and runtime documentation describe the argument behavior.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix

Suggested reviewers: lidge-jun

Merge Risk: ⚪ Minimal · up to 56c5f

The documented alias JSON listing forms are supported, with regression tests covering the flag positions. No concrete merge-blocking risk is established.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (5 skipped: 5 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: enabling JSON output for the default ocx alias command.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files. (5 skipped: 5 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ Required local validation passed; commands, results, and any full-suite exception are documented.
• ⬜ I pushed my PR to a recent dev commit (at most 10 behind; a maintainer may still ask for the exact tip before merge).
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

This PR stays in draft until every box above is ticked.

[oocheol]

Please review the current head 56c5fc6f267b86748a368c038f294e871d17cc5c. The initial automatic review was skipped while the PR is in draft.

@coderabbitai review

@codex review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[oocheol]

Please review the current head d54ce4964792dea5a3e6a0331733b5517228c085. The initial automatic review was skipped while the PR is in draft.

@coderabbitai review

@codex review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[lidge-jun]

Thanks @oocheol — this landed on dev through the batch carry #6447 (one commit per source PR, Co-authored-by credit). Closing as superseded.