@capgo/cli 8.99.0 → 8.99.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@capgo/cli",
3
3
  "type": "module",
4
- "version": "8.99.0",
4
+ "version": "8.99.3",
5
5
  "description": "A CLI to upload to capgo servers",
6
6
  "author": "Martin martin@capgo.app",
7
7
  "license": "Apache 2.0",
@@ -107,11 +107,11 @@
107
107
  "test:preview-qr": "bun test/test-preview-qr.mjs",
108
108
  "test:bundle-pages": "bun test test/test-bundle-pages.test.ts",
109
109
  "test:bundle-single-requests": "bun test test/test-bundle-single-requests.test.ts",
110
- "test:mcp-analytics": "bun test/test-mcp-analytics.mjs",
110
+ "test:mcp-analytics": "bun test/test-mcp-analytics.mjs && bun test/test-mcp-telemetry-project.mjs",
111
111
  "test:mcp-instructions": "bun test/test-mcp-instructions.mjs",
112
112
  "test:mcp-error-guidance": "bun test/test-mcp-error-guidance.mjs",
113
113
  "test:mcp-stdout-guard": "bun test/test-mcp-stdout-guard.mjs",
114
- "test:mcp-project-dir": "bun test/test-mcp-project-dir.mjs",
114
+ "test:mcp-project-dir": "bun test/test-mcp-project-dir.mjs && bun test/test-cwd.mjs && bun test/test-project-context.mjs",
115
115
  "test:mcp-host-fields": "bun test/test-mcp-host-fields.mjs",
116
116
  "test:mcp-platform-select": "bun test/test-mcp-platform-select.mjs",
117
117
  "test:mcp-explain-scopes": "bun test/test-mcp-explain-scopes.mjs",
@@ -135,7 +135,7 @@
135
135
  "test:no-redirect-error": "bun test/test-no-redirect-error.mjs",
136
136
  "test:onboarding-recovery": "bun test/test-onboarding-recovery.mjs",
137
137
  "test:onboarding-progress": "bun test/test-onboarding-progress.mjs",
138
- "test:onboarding-run-targets": "bun test/test-onboarding-run-targets.mjs",
138
+ "test:onboarding-run-targets": "bun test/test-onboarding-run-targets.mjs && bun test ./test/test-ios-simulator-compatibility.mjs",
139
139
  "test:run-device-command": "bun test/test-run-device-command.mjs",
140
140
  "test:init-app-conflict": "bun test/test-init-app-conflict.mjs",
141
141
  "test:channel-add-exists": "bun test/test-channel-add-exists.mjs",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: native-builds
3
- description: Use when working with Capgo Cloud native iOS and Android build requests, onboarding, credential storage, credential updates, and build output upload settings.
3
+ description: Use when working with Capgo Cloud native iOS and Android build requests, cloud simulators, onboarding, credential storage, credential updates, and build output upload settings.
4
4
  ---
5
5
 
6
6
  # Capgo CLI Native Builds
@@ -333,6 +333,38 @@ npx @capgo/cli@latest build credentials export ANDROID_KEYSTORE_FILE \
333
333
  - `--platform <platform>`: only `ios`
334
334
  - `--local`
335
335
 
336
+ ## Cloud simulator
337
+
338
+ A running simulator uses one native builder slot, the same limit as a native build. Stopping it records the open time as build minutes. Each session has its own URL.
339
+
340
+ ### `simulator start [appId]`
341
+
342
+ ```bash
343
+ npx @capgo/cli@latest simulator start com.example.app --platform ios
344
+ npx @capgo/cli@latest simulator start com.example.app --platform android --name "Checkout"
345
+ ```
346
+
347
+ - `--platform <platform>`: `ios` or `android`. Defaults to `ios`.
348
+ - `-n, --name <name>`: optional session name.
349
+ - `--json`: print the session JSON instead of the session id and URL.
350
+ - `-a, --apikey <apikey>` and `--api-host <apiHost>`: same authentication override as the other commands.
351
+
352
+ The command prints the session id, then the session URL. `simulator get` and `simulator stop` need that id. An iOS session boots a slim device. An Android session uses a small profile: 1536 MB RAM, 2 cores, no audio, no snapshot, and no boot animation.
353
+
354
+ ### `simulator get [sessionId] [appId]`
355
+
356
+ ```bash
357
+ npx @capgo/cli@latest simulator get <session-id> com.example.app
358
+ ```
359
+
360
+ ### `simulator stop [sessionId] [appId]`
361
+
362
+ ```bash
363
+ npx @capgo/cli@latest simulator stop <session-id> com.example.app
364
+ ```
365
+
366
+ Stop ends the device and records build minutes. If the device host is still running, or the minute write fails, the session stays open so the same command can be retried. A session also ends by itself after its duration, which releases the builder slot and records the capped time.
367
+
336
368
  ## Supporting docs
337
369
 
338
370
  - iOS setup: `https://capgo.app/docs/cli/cloud-build/ios/`
@@ -45,7 +45,7 @@ Use this skill for OTA update workflows in Capgo Cloud.
45
45
  - Bundle version must be greater than `0.0.0` and unique.
46
46
  - Deleted versions cannot be reused.
47
47
  - External URL mode is useful for very large or privacy-sensitive bundles.
48
- - Encryption is recommended for trustless distribution.
48
+ - Most apps can skip bundle encryption. Enable it for an explicit user request or a concrete requirement for end-to-end encrypted delivery of the code/assets. Handling sensitive runtime/API data alone is not a reason to enable it. Plan for private-key backup, CI key configuration, and a native rebuild to ship the public key.
49
49
  - Interactive prompts are disabled automatically in CI and other non-interactive sessions so uploads do not block automation.
50
50
  - Optional upload prompts can remember the user's answer on the current machine so future uploads can skip the same question.
51
51
  - `--channel` accepts a single channel or a comma-separated list such as `production,beta`.
@@ -39,7 +39,8 @@ TanStack Intent skills should stay focused and under the validator line limit, s
39
39
 
40
40
  ### Project setup and diagnostics
41
41
 
42
- - `init [apikey] [appId]`: when the app has a supported Builder-only checklist assigned by Capgo, continues with `build init` and its existing credential/resume flow before OTA setup. OTA-only and dual-assigned apps retain the existing setup flow. For other assignments, provides guided first-time setup for Capgo in a Capacitor app. The interactive flow now runs as a real Ink-based fullscreen onboarding so it uses the same UI stack as `build init` (alias: `build onboarding`), with a persistent dashboard, phase roadmap, progress cards, shared log area, and resume support. At startup, onboarding still recommends a clean git worktree before file edits; dirty repos show `Check again` first and also offer a non-recommended `Continue anyway` override. When dependency auto-detection fails on macOS, the flow opens a native file picker for `package.json` before falling back to manual path entry. If the onboarding bundle upload fails, recovery can retry immediately or ask for the monorepo/workspace root `package.json` and hoisted `node_modules` paths (not the app package folder) and then retry. If the local bundle ID already exists in the selected Capgo account, onboarding offers to reuse that app, then offers to delete and recreate it, then falls back to alternate bundle ID suggestions. If the user reuses a pending app that was already created in the web onboarding flow, the CLI syncs that selected dashboard app ID back into `capacitor.config.*` before the remaining steps continue. Outside that reused pending-app path, the CLI keeps using the local Capacitor app ID. It writes the new `autoUpdate` policy modes into config: `"atBackground"` for the default flow and `"always"` for instant updates. It can also offer a final `npx skills add https://github.com/Cap-go/capgo-skills -g -y` install step before the GitHub support prompt; if accepted, the support menu includes `Cap-go/capgo-skills` alongside the updater-only and all-Capgo choices. If native platforms are missing, the onboarding can offer to run `cap add` for you. The updater step now verifies that `@capgo/capacitor-updater` is both declared in the selected `package.json` and resolvable from `node_modules`; if automatic install or later build/sync fails, onboarding prints the manual command, waits for the user to type `ready`, re-checks, and only then continues. If the user enables instant updates, onboarding requires `@capacitor/splash-screen` for `autoSplashscreen`, offers to install it with the same auto-install/retry flow, and waits until it is declared and resolvable before writing config. During the iOS run-on-device step, onboarding asks whether to use a physical iPhone/iPad or a simulator; for physical devices, it asks the user to connect and unlock the device, then offers a check-again loop before launching with the detected target. If iOS sync validation fails during onboarding, the CLI can offer to run a one-line native reset command, wait for you to type `ready` after a manual fix, surface `doctor`, and save a support bundle before you leave the flow.
42
+ - For MCP OTA setup, call `start_capgo_live_update_onboarding` first and follow `next`. At `setup-encryption`, use the app purpose and bundle contents already known from the conversation or project to explain a recommendation; do not ask the user to repeat known details. Recommend `skip` for most apps, including public quotes, news, and catalogs. Recommend `enable` only for an explicit user request or a concrete requirement for end-to-end encrypted delivery of the code/assets. Sensitive runtime/API data alone does not require bundle encryption. Explain private-key backup, CI key configuration, and the native rebuild, then wait for the user's choice. Never enable encryption just as a conservative default.
43
+ - `init [apikey] [appId]`: when the app has a supported Builder-only checklist assigned by Capgo, continues with `build init` and its existing credential/resume flow before OTA setup. OTA-only and dual-assigned apps retain the existing setup flow. For other assignments, provides guided first-time setup for Capgo in a Capacitor app. The interactive flow now runs as a real Ink-based fullscreen onboarding so it uses the same UI stack as `build init` (alias: `build onboarding`), with a persistent dashboard, phase roadmap, progress cards, shared log area, and resume support. At startup, onboarding still recommends a clean git worktree before file edits; dirty repos show `Check again` first and also offer a non-recommended `Continue anyway` override. When dependency auto-detection fails on macOS, the flow opens a native file picker for `package.json` before falling back to manual path entry. If the onboarding bundle upload fails, recovery can retry immediately or ask for the app's `package.json` and optional installed-dependency paths (app-local or hoisted `node_modules`) and then retry. If the local bundle ID already exists in the selected Capgo account, onboarding offers to reuse that app, then offers to delete and recreate it, then falls back to alternate bundle ID suggestions. If the user reuses a pending app that was already created in the web onboarding flow, the CLI syncs that selected dashboard app ID back into `capacitor.config.*` before the remaining steps continue. Outside that reused pending-app path, the CLI keeps using the local Capacitor app ID. It writes the new `autoUpdate` policy modes into config: `"atBackground"` for the default flow and `"always"` for instant updates. It can also offer a final `npx skills add https://github.com/Cap-go/capgo-skills -g -y` install step before the GitHub support prompt; if accepted, the support menu includes `Cap-go/capgo-skills` alongside the updater-only and all-Capgo choices. If native platforms are missing, the onboarding can offer to run `cap add` for you. The updater step now verifies that `@capgo/capacitor-updater` is both declared in the selected `package.json` and resolvable from `node_modules`; if automatic install or later build/sync fails, onboarding prints the manual command, waits for the user to type `ready`, re-checks, and only then continues. If the user enables instant updates, onboarding requires `@capacitor/splash-screen` for `autoSplashscreen`, offers to install it with the same auto-install/retry flow, and waits until it is declared and resolvable before writing config. During the iOS run-on-device step, onboarding asks whether to use a physical iPhone/iPad or a simulator; for physical devices, it asks the user to connect and unlock the device, then offers a check-again loop before launching with the detected target. If iOS sync validation fails during onboarding, the CLI can offer to run a one-line native reset command, wait for you to type `ready` after a manual fix, surface `doctor`, and save a support bundle before you leave the flow.
43
44
  - When `init` enters OTA setup, it enables the app's missing OTA dashboard checklist without resetting existing progress or removing Builder tasks. Checklist activation is independent of analytics; Builder-only handoffs do not activate OTA.
44
45
  - `init --no-analytics`: disables init onboarding analytics and terminal replay for that run.
45
46
  - After successful OTA `init`, detected AI sessions receive the plain next-steps notice (or the trial line alone) after the terminal UI closes. It uses the final selected app and authenticated API client, waits at most five seconds, and remains visible even if a trial warning appeared earlier. Ordinary terminal sessions receive no additional footer; analytics opt-out does not suppress it.
@@ -48,6 +49,7 @@ TanStack Intent skills should stay focused and under the validator line limit, s
48
49
  - `run device [platform]`: run a Capacitor app on a connected device or simulator. In an interactive terminal, omitting `[platform]` asks whether to start on iOS or Android. The command lists available devices and simulators, includes a reload option, and resolves the `cap run` command. Use `npx @capgo/cli@latest run device ios --no-launch` to exercise iOS physical/simulator target selection and print the resolved command without launching the app.
49
50
  - `login [apikey]`: store an API key locally.
50
51
  - `doctor`: inspect installation health and gather troubleshooting details.
52
+ - For Xcode 27 simulator failures, check the `native-run` resolved by the app's `@capacitor/cli`, not an unrelated top-level install. Xcode 27 replaced `Simulator.app` with Device Hub. As of 2026-10-29, native-run 2.0.3 is latest and lacks the merged fix, so there is no released minimum Capacitor version to recommend. Updating to Capacitor CLI 8.6.0 alone does not fix it. `doctor` reports the incompatibility; `init`, `run device`, and MCP live-update onboarding provide a manual Xcode launch. Run `npx cap open ios`, select the simulator, and choose Product > Run. Confirm the baseline app runs before continuing OTA setup or sending `deviceRunConfirmed: true`; opening Xcode alone is not success. Physical devices and older selected Xcode installations with `Simulator.app` remain alternatives. The upstream issue includes a package-manager patch: https://github.com/ionic-team/capacitor/issues/8620. Once released, update Capacitor's resolved native-run and lockfile, then re-run `npx @capgo/cli@latest doctor`. Keep Capacitor packages on the same major; do not upgrade majors solely for this launch fix.
51
53
  - `probe`: test whether the update endpoint would deliver an update.
52
54
  - `observe summary|metrics|events|device|versions|routes`: query Observe findings, timings, device timelines, and per-screen routes. Start with `observe summary`. Use `observe device DEVICE_ID` as the session timeline. Navigation uses `app_nav` + `metadata.route` (history/popstate/hashchange/appUrlOpen, no Expo Router). Pass `--json` for agents.
53
55
 
@@ -64,7 +66,7 @@ TanStack Intent skills should stay focused and under the validator line limit, s
64
66
  ### Docs and agent integrations
65
67
 
66
68
  - MCP live-update onboarding (`start_capgo_live_update_onboarding`, then `capgo_live_update_onboarding_next_step`): before the test update it asks who makes the visible change (`testChangeChoice`). With `manual`, it waits until the user saved their own change (`testChangeReady: true`); the agent must not edit app files for them. With `agent`, the result gives the AI assistant guidelines (one small text or label change on the first screen in the app's own style, no banners, web files only, no `cap sync`); the assistant reports `testChangeReady`, `testChangeFiles` and `testChangeDescription`, the device check asks the user to look for that description, and completion tells the assistant to revert those files. Devices keep the test bundle until the next upload. A clean git check done before the test change still counts after the edit.
67
- - `mcp`: start the Capgo MCP server for AI-agent integrations; pass `--capacitor-config <path>` when its config-writing tools should target an app-specific source. Observe queries use `capgo_observe` (start at `view=summary`). The server resolves the project from the client's MCP roots (the agent's workspace), not the folder it was spawned in, so a user-scoped install works across projects; clients without roots support call `capgo_set_project_dir` with the app folder.
69
+ - `mcp`: start the Capgo MCP server for AI-agent integrations; pass `--capacitor-config <path>` when its config-writing tools should target an app-specific source. Observe queries use `capgo_observe` (start at `view=summary`). The server resolves the project from the client's MCP roots (the agent's workspace), not the folder it was spawned in, so a user-scoped install works across projects; clients without roots support call `capgo_set_project_dir` with the absolute app folder. Workspace roots with exactly one Capacitor app automatically select that app, including at startup without roots support. Multiple apps require an explicit app path. Every local MCP tool accepts `projectDir` or its `cwd` alias with the absolute app folder, including doctor, bundle/channel operations, builds, credentials, and both onboarding flows; it selects the project for this and subsequent calls. If both are supplied, they must select the same app. Relative tool paths resolve from that app. Calls and project switches are serialized, and nested build operations share the same CWD lock. The server's previous CWD is restored after every call without losing the selected app. All app metadata, scripts, source/config files, and dependency declarations use the selected app's own `package.json`, while installed dependencies can remain hoisted. Explicit package/dependency paths still override discovery. Hosted MCP tools cannot inspect local files: pass `projectDir` or `cwd` to `capgo_get_upload_command`, and run offline bundle/build packaging from the app directory. If `@capacitor/core` appears missing, verify the app folder before installing dependencies.
68
70
 
69
71
  ### GitHub support commands
70
72
 
@@ -96,6 +98,7 @@ Load `skills/native-builds/SKILL.md` when working with:
96
98
 
97
99
  - `build request`
98
100
  - `build needed`
101
+ - `simulator start`, `simulator get`, `simulator stop`
99
102
  - `build credentials save`
100
103
  - `build credentials list`
101
104
  - `build credentials clear`