Skip to content

feat(cli): add build needed check#2208

Merged
riderx merged 1 commit into
mainfrom
codex/build-needed-command
May 11, 2026
Merged

feat(cli): add build needed check#2208
riderx merged 1 commit into
mainfrom
codex/build-needed-command

Conversation

@riderx
Copy link
Copy Markdown
Member

@riderx riderx commented May 11, 2026

Summary (AI generated)

  • Add build needed to report whether local native dependency metadata requires a new native build.
  • Add verbose package diff output with version-change color coding and native checksum differences.
  • Document the command and record the lowercase/kebab-case CLI naming rule in agent instructions.

Motivation (AI generated)

Teams need a CI-friendly way to decide whether an OTA upload is enough or a native store build is required when native dependencies changed.

Business Impact (AI generated)

This reduces accidental OTA releases that cannot safely apply native dependency changes, while keeping automated release pipelines simple with yes/no output and exit codes.

Test Plan (AI generated)

  • bun run lint
  • bun run build
  • bun run test:build-needed
  • bun run test:mcp
  • bun run test:bundle
  • node dist/index.js build needed --help

Summary by CodeRabbit

  • New Features

    • Introduced build needed command to check if native builds are required based on dependency compatibility and native package changes. Returns "yes" or "no" with appropriate exit codes for programmatic use.
  • Documentation

    • Clarified native cloud build public beta status in CLI documentation.
    • Added comprehensive documentation for the new build needed command with all supported options and usage examples.

Review Change Stack

@chatgpt-codex-connector
Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 11, 2026

Warning

Rate limit exceeded

@riderx has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 9 minutes and 43 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e50fcea1-e8cf-4d62-928f-c89b921ab665

📥 Commits

Reviewing files that changed from the base of the PR and between b58d8fc and 7c3af4c.

📒 Files selected for processing (12)
  • AGENTS.md
  • cli/AGENTS.md
  • cli/README.md
  • cli/package.json
  • cli/skills/native-builds/SKILL.md
  • cli/skills/usage/SKILL.md
  • cli/src/build/needed.ts
  • cli/src/index.ts
  • cli/src/init/updater.ts
  • cli/src/schemas/build.ts
  • cli/test/test-build-needed.mjs
  • cli/webdocs/build.mdx
📝 Walkthrough

Walkthrough

This PR introduces a new build needed [appId] CLI command that determines whether a Capacitor app requires a native rebuild by comparing local dependency metadata against cloud compatibility data. It includes the core logic module, CLI integration, comprehensive tests, and documentation updates.

Changes

Build Needed Command Implementation

Layer / File(s) Summary
Command Options Schema
cli/src/schemas/build.ts
New buildNeededOptionsSchema extends base options with optional channel, packageJson, nodeModules, and verbose fields.
Build Needed Core Logic
cli/src/build/needed.ts
Implements channel resolution (explicit > configured > default), version change classification via semver comparison, native checksum diff detection, build necessity detection, and both short ("yes"/"no") and verbose (formatted table with colors) output modes. Main entry points are getBuildNeeded (workflow orchestration) and checkBuildNeeded (CLI wrapper with stdout/exit code handling).
CLI Command Registration
cli/src/index.ts
Imports checkBuildNeeded and registers new build needed [appId] subcommand under the build group, including options for API key, channel override, monorepo paths, verbose output, and Supabase connection override. Updates build command's beta warning to specify "Native cloud build requests."​
Command Testing
cli/test/test-build-needed.mjs, cli/package.json
New test script comprehensively validates formatting, exit codes, channel resolution, version classification (major/minor/patch/same/new/removed/changed), native diff labeling, ANSI color output, and error handling for ambiguous defaults. Wires test execution into the main test script chain.
Documentation and Guidelines
AGENTS.md, cli/AGENTS.md, cli/README.md, cli/skills/native-builds/SKILL.md, cli/skills/usage/SKILL.md, cli/webdocs/build.mdx
Updates CLI agent requirements to enforce lowercase kebab-case command names; adds build needed command documentation to README (with usage example and option reference), skill documentation, usage guide, and webdocs; clarifies build feature beta status across documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • Cap-go/capgo#1977: Introduces related CLI workspace and command wiring that the new build needed command extends.
  • Cap-go/capgo#1999: Both PRs add/modify node-modules path handling in the CLI build flow—this PR for the build needed command and the retrieved PR for build request/zipping support.

Poem

🐰 A command to build or not to build, that is the query,
We check the native deps with native tech fury,
Kebab-case names keep the CLI clean,
Now developers know if a rebuild's been seen!

🚥 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%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title 'feat(cli): add build needed check' clearly and concisely summarizes the main change—adding a new CLI command to check if a build is needed.
Description check ✅ Passed The PR description covers the required template sections: a clear summary of changes, motivation, business impact, and a comprehensive test plan with all steps checked.
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.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/build-needed-command

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🧹 Nitpick comments (2)
cli/src/index.ts (1)

766-770: ⚡ Quick win

Reuse the shared --verbose description here.

This adds a one-off --verbose help string even though optionDescriptions.verbose already exists. Keeping the shared text here avoids help and README drift for the same flag. As per coding guidelines "cli/src/index.ts: Reuse shared option descriptions from src/index.ts when an option already exists instead of introducing slightly different wording".

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cli/src/index.ts` around lines 766 - 770, Replace the inline help string for
the --verbose CLI option with the shared description constant to avoid drift:
locate the chain that registers the flag (the .option('--verbose', `Show
package-level native dependency changes`) call) and swap the literal string for
optionDescriptions.verbose so the flag uses the shared text; ensure you
import/retain the optionDescriptions object in this scope if not already
present.
cli/webdocs/build.mdx (1)

27-27: ⚡ Quick win

Clarify exit code behavior for both cases.

The description currently states "exit 1 when local native dependency metadata requires a new native build" but doesn't explicitly mention the exit code when no build is needed. For CI/CD automation, users need to understand both scenarios clearly.

Consider revising to something like:

  • "Print 'yes' and exit with code 1 if a native build is required, otherwise print 'no' and exit with code 0."

This makes the command's behavior unambiguous for pipeline integration.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cli/webdocs/build.mdx` at line 27, Update the single-line description so it
explicitly states both outcomes: change the current sentence that mentions only
"exit 1 when local native dependency metadata requires a new native build" to
something like: "Print 'yes' and exit with code 1 if a native build is required;
otherwise print 'no' and exit with code 0." Ensure the wording replaces the
existing line that begins with the emoji and short description so CI/CD users
can unambiguously detect both cases.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cli/src/build/needed.ts`:
- Around line 106-119: getPublicDefaultChannelName currently selects all rows
where public = true and then relies on selectDefaultChannelName to pick the
default; this fails when multiple public channels exist. Update the Supabase
query in getPublicDefaultChannelName to also filter by the actual
default-channel predicate (e.g., add .eq('is_default', true) or the real column
name used for default channels) so the query returns only the default public
channel before passing rows into selectDefaultChannelName (keep the table
'channels' and function names getPublicDefaultChannelName and
selectDefaultChannelName).
- Around line 302-318: The catch block in checkBuildNeeded currently rethrows
all errors which causes auth/network/config failures to produce the same exit
status as "build needed"; change the error path to set a distinct failure exit
code (e.g. process.exitCode = 2) and do not rethrow so callers can distinguish
command failure from build-needed semantics; update the catch in
checkBuildNeeded (which calls getBuildNeeded and uses getBuildNeededExitCode) to
log the error and set process.exitCode = 2 (and return) instead of throwing the
error.
- Around line 165-175: getNativeDiffLabel currently only considers a platform
changed if both local and remote checksums exist; update the change detection to
also treat checksum addition/removal as a change by computing iosChanged as
"(entry.localIosChecksum || entry.remoteIosChecksum) && entry.localIosChecksum
!== entry.remoteIosChecksum" and androidChanged similarly using
localAndroidChecksum/remoteAndroidChecksum, then keep the existing return logic
in getNativeDiffLabel to show 'iOS', 'Android', 'iOS + Android' or '-'
accordingly; reference the Compatibility type and the four fields
localIosChecksum, remoteIosChecksum, localAndroidChecksum, remoteAndroidChecksum
when making the change.

In `@cli/src/index.ts`:
- Line 748: The status message "⚠️ Native cloud build requests are currently in
PUBLIC BETA and cannot be used by anyone at this time." is contradictory; update
the CLI help string (currently containing that exact text) to either: 1) reflect
a gated beta by replacing "PUBLIC BETA and cannot be used by anyone at this
time" with "LIMITED/PRIVATE BETA — access is currently restricted" (if access is
gated), or 2) if it really is public, remove "and cannot be used by anyone at
this time" so it reads "⚠️ Native cloud build requests are currently in PUBLIC
BETA." Modify the string where it is defined in cli/src/index.ts accordingly
(the help/usage message that prints this warning).

---

Nitpick comments:
In `@cli/src/index.ts`:
- Around line 766-770: Replace the inline help string for the --verbose CLI
option with the shared description constant to avoid drift: locate the chain
that registers the flag (the .option('--verbose', `Show package-level native
dependency changes`) call) and swap the literal string for
optionDescriptions.verbose so the flag uses the shared text; ensure you
import/retain the optionDescriptions object in this scope if not already
present.

In `@cli/webdocs/build.mdx`:
- Line 27: Update the single-line description so it explicitly states both
outcomes: change the current sentence that mentions only "exit 1 when local
native dependency metadata requires a new native build" to something like:
"Print 'yes' and exit with code 1 if a native build is required; otherwise print
'no' and exit with code 0." Ensure the wording replaces the existing line that
begins with the emoji and short description so CI/CD users can unambiguously
detect both cases.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3a0fe302-6407-46e9-9caf-2e7928396f9e

📥 Commits

Reviewing files that changed from the base of the PR and between b0f3ab9 and b58d8fc.

📒 Files selected for processing (11)
  • AGENTS.md
  • cli/AGENTS.md
  • cli/README.md
  • cli/package.json
  • cli/skills/native-builds/SKILL.md
  • cli/skills/usage/SKILL.md
  • cli/src/build/needed.ts
  • cli/src/index.ts
  • cli/src/schemas/build.ts
  • cli/test/test-build-needed.mjs
  • cli/webdocs/build.mdx

Comment thread cli/src/build/needed.ts
Comment thread cli/src/build/needed.ts
Comment thread cli/src/build/needed.ts
Comment thread cli/src/index.ts Outdated
@codspeed-hq
Copy link
Copy Markdown
Contributor

codspeed-hq Bot commented May 11, 2026

Merging this PR will not alter performance

✅ 43 untouched benchmarks
⏩ 2 skipped benchmarks1


Comparing codex/build-needed-command (7c3af4c) with main (b0f3ab9)

Open in CodSpeed

Footnotes

  1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports.

@riderx riderx force-pushed the codex/build-needed-command branch from b58d8fc to 3e00bd1 Compare May 11, 2026 12:56
@riderx riderx force-pushed the codex/build-needed-command branch from 3e00bd1 to 7c3af4c Compare May 11, 2026 13:00
@sonarqubecloud
Copy link
Copy Markdown

@riderx riderx merged commit 30cedef into main May 11, 2026
52 checks passed
@riderx riderx deleted the codex/build-needed-command branch May 11, 2026 14:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant