@capgo/cli 7.84.10 → 7.86.0

package/dist/src/utils/safeWrites.d.ts

@@ -1,7 +1,7 @@
-type WriteOptions = {
+interface WriteOptions {
     mode?: number;
     encoding?: BufferEncoding;
-};
+}
 /**
  * Create (or reuse) a directory and enforce safe permissions.
  */

package/dist/src/utils.d.ts

@@ -1889,7 +1889,9 @@ export declare function createSupabaseClient(apikey: string, supaHost?: string,
                 credits_estimated: number;
                 details?: import("./types/supabase.types").Json | null;
                 id?: string;
-                metric: Database["public"]["Enums"]["credit_metric_type"];
+                metric: Database["public"]["Enums"] /**
+                 * Read directory recursively and return full paths for all files
+                 */["credit_metric_type"];
                 org_id: string;
                 overage_amount: number;
             };
@@ -3658,6 +3660,10 @@ export declare function getPMAndCommand(): {
     installCommand: string;
     runner: PackageManagerRunner;
 };
+export declare function getNativeProjectResetAdvice(platformRunner: string, nativePlatform: 'ios' | 'android'): {
+    summary: string;
+    command: string;
+};
 export declare function getLocalDependencies(packageJsonPath: string | undefined, nodeModulesString: string | undefined): Promise<{
     name: string;
     version: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@capgo/cli",
   "type": "module",
-  "version": "7.84.10",
+  "version": "7.86.0",
   "description": "A CLI to upload to capgo servers",
   "author": "Martin martin@capgo.app",
   "license": "Apache 2.0",
@@ -23,7 +23,8 @@
     "cli",
     "upload",
     "capgo-cli",
-    "sdk"
+    "sdk",
+    "tanstack-intent"
   ],
   "exports": {
     ".": {
@@ -40,6 +41,11 @@
   "bin": {
     "capgo": "dist/index.js"
   },
+  "files": [
+    "!skills/_artifacts",
+    "dist",
+    "skills"
+  ],
   "engines": {
     "npm": ">=8.0.0",
     "node": ">=20.0.0"
@@ -83,6 +89,7 @@
     "@sauber/table": "npm:@jsr/sauber__table",
     "@std/semver": "npm:@jsr/std__semver@1.0.8",
     "@supabase/supabase-js": "^2.79.0",
+    "@tanstack/intent": "^0.0.23",
     "@types/adm-zip": "^0.5.7",
     "@types/node": "^25.0.0",
     "@types/prettyjson": "^0.0.33",
@@ -97,11 +104,11 @@
     "is-wsl": "^3.1.0",
     "micromatch": "^4.0.8",
     "open": "^11.0.0",
+    "partysocket": "^1.1.11",
     "prettyjson": "^1.2.5",
     "tmp": "^0.2.5",
     "tus-js-client": "^4.3.1",
     "typescript": "^5.9.3",
-    "partysocket": "^1.1.11",
     "ws": "^8.18.3",
     "zod": "^4.3.6"
   }

package/skills/_artifacts/domain_map.yaml

@@ -0,0 +1,32 @@
+domains:
+  - name: cli-usage
+    summary: High-level command routing, setup, diagnostics, app management, docs generation, MCP, and GitHub support commands.
+    primary_sources:
+      - webdocs/init.mdx
+      - webdocs/doctor.mdx
+      - webdocs/login.mdx
+      - webdocs/app.mdx
+      - webdocs/account.mdx
+      - webdocs/probe.mdx
+      - webdocs/star.mdx
+      - webdocs/star-all.mdx
+      - src/index.ts
+  - name: ota-release-management
+    summary: OTA bundle uploads, channel operations, compatibility checks, cleanup, and encryption-key workflows.
+    primary_sources:
+      - webdocs/bundle.mdx
+      - webdocs/channel.mdx
+      - webdocs/key.mdx
+      - src/index.ts
+  - name: native-builds
+    summary: Native cloud build requests and local build credential management for iOS and Android.
+    primary_sources:
+      - webdocs/build.mdx
+      - src/index.ts
+  - name: organization-management
+    summary: Account lookup, organization administration, and deprecated organisation aliases.
+    primary_sources:
+      - webdocs/account.mdx
+      - webdocs/organization.mdx
+      - webdocs/organisation.mdx
+      - src/index.ts

package/skills/_artifacts/skill_spec.md

@@ -0,0 +1,30 @@
+# Capgo CLI skill spec
+
+## Goal
+
+Provide a small Capgo CLI skill set that helps an agent choose and invoke the correct CLI commands for app setup, OTA release operations, organization administration, MCP setup, GitHub support commands, and native cloud builds without exceeding TanStack Intent size limits.
+
+## Sources
+
+- `webdocs/*.mdx` for published command descriptions, examples, and option tables.
+- `src/index.ts` for the currently registered commands, aliases, and flags that may not yet be fully reflected in the web docs.
+- `AGENTS.md` for repository-specific maintenance requirements.
+
+## Skill set
+
+- `usage`: routing, setup, diagnostics, app commands, docs generation, MCP, and GitHub support commands.
+- `release-management`: bundle, channel, compatibility, cleanup, and encryption-key workflows.
+- `native-builds`: native cloud build requests and build credential storage/update flows.
+- `organization-management`: account ID lookup, organization admin flows, and deprecated `organisation` aliases.
+
+## Scope
+
+- Include the documented command purpose, invocation patterns, key options, and important caveats.
+- Prefer the public user-facing examples already used by the project.
+- Keep the skills aligned with the published docs and current CLI registration.
+
+## Maintenance rules
+
+- Any CLI command or option change should update the relevant `skills/*/SKILL.md` file in the same pull request.
+- Use `webdocs/` as the primary wording source and `src/index.ts` as the completeness check.
+- Validate the skills with `bunx @tanstack/intent@latest validate` before release.

package/skills/_artifacts/skill_tree.yaml

@@ -0,0 +1,17 @@
+skills:
+  - name: usage
+    path: skills/usage/SKILL.md
+    domain: cli-usage
+    focus: High-level routing and shared invocation rules.
+  - name: release-management
+    path: skills/release-management/SKILL.md
+    domain: ota-release-management
+    focus: OTA bundle, channel, compatibility, cleanup, and encryption workflows.
+  - name: native-builds
+    path: skills/native-builds/SKILL.md
+    domain: native-builds
+    focus: Native build request flows and local build credential management.
+  - name: organization-management
+    path: skills/organization-management/SKILL.md
+    domain: organization-management
+    focus: Account and organization administration commands, including deprecated aliases.

package/skills/native-builds/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: native-builds
+description: Use when working with Capgo Cloud native iOS and Android build requests, credential storage, credential updates, and build output upload settings.
+---
+
+# Capgo CLI Native Builds
+
+Use this skill for Capgo Cloud native iOS and Android build workflows.
+
+## Core build request
+
+### `build request [appId]`
+
+- Example: `npx @capgo/cli@latest build request com.example.app --platform ios --path .`
+- Notes:
+  - Zips the current project directory and uploads it to Capgo for building.
+  - Builds are processed for store distribution.
+  - Credentials are never stored permanently on Capgo servers.
+  - Build outputs can be uploaded for time-limited download links.
+  - Before requesting a build, save credentials with `build credentials save`.
+- Core options:
+  - `--path <path>`
+  - `--platform <platform>`: `ios` or `android`, required.
+  - `--build-mode <buildMode>`: `debug` or `release`.
+  - `-a, --apikey <apikey>`
+  - `--verbose`
+
+#### iOS request options
+
+- `--build-certificate-base64 <cert>`
+- `--p12-password <password>`
+- `--apple-id <email>`
+- `--apple-app-specific-password <password>`
+- `--apple-key-id <id>`
+- `--apple-issuer-id <id>`
+- `--apple-key-content <content>`
+- `--app-store-connect-team-id <id>`
+- `--ios-scheme <scheme>`
+- `--ios-target <target>`
+- `--ios-distribution <mode>`: `app_store` or `ad_hoc`
+- `--ios-provisioning-profile <mapping>`: repeatable path or `bundleId=path`
+
+#### Android request options
+
+- `--android-keystore-file <keystore>`
+- `--keystore-key-alias <alias>`
+- `--keystore-key-password <password>`
+- `--keystore-store-password <password>`
+- `--play-config-json <json>`
+- `--android-flavor <flavor>`
+
+#### Output behavior options
+
+- `--no-playstore-upload`: skip Play Store upload for the build, requires `--output-upload`
+- `--output-upload`
+- `--no-output-upload`
+- `--output-retention <duration>`: `1h` to `7d`
+- `--skip-build-number-bump`
+- `--no-skip-build-number-bump`
+
+## Local credential management
+
+Credentials are stored locally, either globally in `~/.capgo-credentials/credentials.json` or locally in `.capgo-credentials.json`.
+
+### `build credentials save`
+
+- Required before build requests.
+- Supports global storage by default and local storage with `--local`.
+- Example iOS flow:
+
+```bash
+npx @capgo/cli build credentials save --platform ios \
+  --certificate ./cert.p12 --p12-password "password" \
+  --ios-provisioning-profile ./profile.mobileprovision \
+  --apple-key ./AuthKey.p8 --apple-key-id "KEY123" \
+  --apple-issuer-id "issuer-uuid" --apple-team-id "team-id"
+```
+
+- Example multi-target iOS flow:
+
+```bash
+npx @capgo/cli build credentials save --platform ios \
+  --ios-provisioning-profile ./App.mobileprovision \
+  --ios-provisioning-profile com.example.widget=./Widget.mobileprovision
+```
+
+- Example Android flow:
+
+```bash
+npx @capgo/cli build credentials save --platform android \
+  --keystore ./release.keystore --keystore-alias "my-key" \
+  --keystore-key-password "key-pass" \
+  --play-config ./service-account.json
+```
+
+- Core options:
+  - `--appId <appId>`
+  - `--platform <platform>`
+  - `--local`
+  - `--output-upload`, `--no-output-upload`
+  - `--output-retention <duration>`
+  - `--skip-build-number-bump`, `--no-skip-build-number-bump`
+
+#### iOS credential save options
+
+- `--certificate <path>`
+- `--ios-provisioning-profile <mapping>`
+- `--p12-password <password>`
+- `--apple-key <path>`
+- `--apple-key-id <id>`
+- `--apple-issuer-id <id>`
+- `--apple-team-id <id>`
+- `--ios-distribution <mode>`
+- `--apple-id <email>`
+- `--apple-app-password <password>`
+
+#### Android credential save options
+
+- `--keystore <path>`
+- `--keystore-alias <alias>`
+- `--keystore-key-password <password>`
+- `--keystore-store-password <password>`
+- `--play-config <path>`
+- `--android-flavor <flavor>`
+
+### `build credentials list`
+
+- Examples:
+  - `npx @capgo/cli build credentials list`
+  - `npx @capgo/cli build credentials list --appId com.example.app`
+- Options:
+  - `--appId <appId>`
+  - `--local`
+
+### `build credentials clear`
+
+- Examples:
+  - `npx @capgo/cli build credentials clear`
+  - `npx @capgo/cli build credentials clear --local`
+  - `npx @capgo/cli build credentials clear --appId com.example.app --platform ios`
+- Options:
+  - `--appId <appId>`
+  - `--platform <platform>`
+  - `--local`
+
+### `build credentials update`
+
+- Use to update specific credential fields without re-entering all data.
+- Platform is auto-detected from the supplied options.
+- Examples:
+  - `npx @capgo/cli build credentials update --ios-provisioning-profile ./new-profile.mobileprovision`
+  - `npx @capgo/cli build credentials update --local --keystore ./new-keystore.jks`
+- Core options:
+  - `--appId <appId>`
+  - `--platform <platform>`
+  - `--local`
+  - `--overwrite-ios-provisioning-map`
+  - `--output-upload`, `--no-output-upload`
+  - `--output-retention <duration>`
+  - `--skip-build-number-bump`, `--no-skip-build-number-bump`
+- Supports the same iOS and Android credential fields as `build credentials save`.
+
+### `build credentials migrate`
+
+- Example: `npx @capgo/cli build credentials migrate --platform ios`
+- Notes:
+  - Converts `BUILD_PROVISION_PROFILE_BASE64` to `CAPGO_IOS_PROVISIONING_MAP`.
+  - Discovers the main bundle ID from the Xcode project automatically.
+- Options:
+  - `--appId <appId>`
+  - `--platform <platform>`: only `ios`
+  - `--local`
+
+## Supporting docs
+
+- iOS setup: `https://capgo.app/docs/cli/cloud-build/ios/`
+- Android setup: `https://capgo.app/docs/cli/cloud-build/android/`

package/skills/organization-management/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: organization-management
+description: Use when working with Capgo account lookup, organization administration, member security settings, and deprecated organisation aliases.
+---
+
+# Capgo CLI Organization Management
+
+Use this skill for account and organization administration commands.
+
+## Account command
+
+### `account id`
+
+- Example: `npx @capgo/cli@latest account id`
+- Use to retrieve an account ID that is safe to share for collaboration or support.
+- Key option:
+  - `-a, --apikey <apikey>`
+
+## Organization commands
+
+### `organization list`
+
+- Alias: `l`
+- Example: `npx @capgo/cli@latest organization list`
+- Lists all organizations the current user can access.
+
+### `organization add`
+
+- Alias: `a`
+- Example: `npx @capgo/cli@latest organization add --name "My Company" --email admin@mycompany.com`
+- Key options:
+  - `-n, --name <name>`
+  - `-e, --email <email>`
+
+### `organization members [orgId]`
+
+- Alias: `m`
+- Example: `npx @capgo/cli@latest organization members ORG_ID`
+- Notes:
+  - Lists members, roles, and 2FA status.
+  - Useful before enabling 2FA enforcement.
+  - Viewing 2FA status requires `super_admin` rights.
+
+### `organization set [orgId]`
+
+- Alias: `s`
+- Example: `npx @capgo/cli@latest organization set ORG_ID --name "New Name"`
+- Security examples:
+  - `npx @capgo/cli@latest organization set ORG_ID --enforce-2fa`
+  - `npx @capgo/cli@latest organization set ORG_ID --password-policy --min-length 12`
+  - `npx @capgo/cli@latest organization set ORG_ID --require-apikey-expiration --max-apikey-expiration-days 90`
+  - `npx @capgo/cli@latest organization set ORG_ID --enforce-hashed-api-keys`
+- Notes:
+  - Security settings require `super_admin` role.
+- Key options:
+  - `-n, --name <name>`
+  - `-e, --email <email>`
+  - `--enforce-2fa`, `--no-enforce-2fa`
+  - `--password-policy`, `--no-password-policy`
+  - `--min-length <minLength>`
+  - `--require-uppercase`, `--no-require-uppercase`
+  - `--require-number`, `--no-require-number`
+  - `--require-special`, `--no-require-special`
+  - `--require-apikey-expiration`, `--no-require-apikey-expiration`
+  - `--max-apikey-expiration-days <days>`
+  - `--enforce-hashed-api-keys`, `--no-enforce-hashed-api-keys`
+
+### `organization delete [orgId]`
+
+- Alias: `d`
+- Example: `npx @capgo/cli@latest organization delete ORG_ID`
+- Notes:
+  - This action cannot be undone.
+  - Only organization owners can delete organizations.
+
+## Deprecated aliases
+
+The `organisation` command group is deprecated in favor of `organization` and will be removed in a future version.
+
+### Deprecated commands
+
+- `organisation list`
+- `organisation add`
+- `organisation set [orgId]`
+- `organisation delete [orgId]`
+
+Use the `organization` equivalents for all new documentation and examples.
+
+## Shared options
+
+Most account and organization commands support:
+
+- `-a, --apikey <apikey>`

package/skills/release-management/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: release-management
+description: Use when working on Capgo OTA release workflows including bundle uploads, compatibility checks, channel management, cleanup, and encryption key setup.
+---
+
+# Capgo CLI Release Management
+
+Use this skill for OTA update workflows in Capgo Cloud.
+
+## Shared notes
+
+- Prefer `npx @capgo/cli@latest ...` examples.
+- `appId` can often be inferred from the current Capacitor project.
+- Shared public flags often include `-a, --apikey`.
+
+## Bundle workflows
+
+### `bundle upload [appId]`
+
+- Alias: `u`
+- Example: `npx @capgo/cli@latest bundle upload com.example.app --path ./dist --channel production`
+- Key behavior:
+  - Bundle version must be greater than `0.0.0` and unique.
+  - Deleted versions cannot be reused.
+  - External URL mode is useful for very large or privacy-sensitive bundles.
+  - Encryption is recommended for trustless distribution.
+- Important options:
+  - `-p, --path <path>`
+  - `-c, --channel <channel>`
+  - `-e, --external <url>`
+  - `--iv-session-key <key>`
+  - `-b, --bundle <bundle>`
+  - `--link <link>`
+  - `--comment <comment>`
+  - `--min-update-version <minUpdateVersion>`
+  - `--auto-min-update-version`
+  - `--ignore-metadata-check`
+  - `--ignore-checksum-check`
+  - `--force-crc32-checksum`
+  - `--timeout <timeout>`
+  - `--zip`
+  - `--tus`
+  - `--tus-chunk-size <tusChunkSize>`
+  - `--delta`
+  - `--delta-only`
+  - `--no-delta`
+  - `--encrypted-checksum <encryptedChecksum>`
+  - `--auto-set-bundle`
+  - `--dry-upload`
+  - `--package-json <packageJson>`
+  - `--node-modules <nodeModules>`
+  - `--encrypt-partial`
+  - `--delete-linked-bundle-on-upload`
+  - `--no-brotli-patterns <patterns>`
+  - `--disable-brotli`
+  - `--version-exists-ok`
+  - `--self-assign`
+  - S3 options: `--s3-region`, `--s3-apikey`, `--s3-apisecret`, `--s3-endpoint`, `--s3-bucket-name`, `--s3-port`, `--no-s3-ssl`
+  - Signing options: `--key-v2`, `--key-data-v2`, `--bundle-url`, `--no-key`, `--display-iv-session`
+  - Deprecated options still supported: `--multipart`, `--partial`, `--partial-only`
+
+### `bundle compatibility [appId]`
+
+- Example: `npx @capgo/cli@latest bundle compatibility com.example.app --channel production`
+- Use to check whether a bundle is safe for a given channel.
+- Key options:
+  - `-c, --channel <channel>`
+  - `--text`
+  - `--package-json <packageJson>`
+  - `--node-modules <nodeModules>`
+
+### `bundle releaseType [appId]`
+
+- Example: `npx @capgo/cli@latest bundle releaseType com.example.app --channel production`
+- Prints `native` or `OTA` based on channel compatibility.
+- Key options:
+  - `-c, --channel <channel>`
+  - `--package-json <packageJson>`
+  - `--node-modules <nodeModules>`
+
+### `bundle list [appId]`
+
+- Alias: `l`
+- Example: `npx @capgo/cli@latest bundle list com.example.app`
+
+### `bundle delete [bundleId] [appId]`
+
+- Alias: `d`
+- Example: `npx @capgo/cli@latest bundle delete BUNDLE_ID com.example.app`
+
+### `bundle cleanup [appId]`
+
+- Alias: `c`
+- Example: `npx @capgo/cli@latest bundle cleanup com.example.app --bundle=1.0 --keep=3`
+- Notes:
+  - Linked bundles are preserved unless `--ignore-channel` is used.
+- Key options:
+  - `-b, --bundle <bundle>`
+  - `-k, --keep <keep>`
+  - `-f, --force`
+  - `--ignore-channel`
+
+### `bundle zip [appId]`
+
+- Example: `npx @capgo/cli@latest bundle zip com.example.app --path ./dist`
+- Notes:
+  - Produces a checksum for encryption workflows.
+  - Use `--json` for machine-readable output.
+- Key options:
+  - `-p, --path <path>`
+  - `-b, --bundle <bundle>`
+  - `-n, --name <name>`
+  - `-j, --json`
+  - `--no-code-check`
+  - `--key-v2`
+  - `--package-json <packageJson>`
+
+### `bundle encrypt [zipPath] [checksum]`
+
+- Example: `npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM`
+- Notes:
+  - Returns the `ivSessionKey` needed for upload and later decryption.
+- Key options:
+  - `--key <key>`
+  - `--key-data <keyData>`
+  - `-j, --json`
+  - `--package-json <packageJson>`
+
+### `bundle decrypt [zipPath] [checksum]`
+
+- Example: `npx @capgo/cli@latest bundle decrypt ./myapp_encrypted.zip CHECKSUM`
+- Notes:
+  - Mainly for testing.
+  - Prints the base64 session key for verification.
+- Key options:
+  - `--key <key>`
+  - `--key-data <keyData>`
+  - `--checksum <checksum>`
+  - `--package-json <packageJson>`
+
+## Channel workflows
+
+### `channel add [channelId] [appId]`
+
+- Alias: `a`
+- Example: `npx @capgo/cli@latest channel add production com.example.app --default`
+- Key options:
+  - `-d, --default`
+  - `--self-assign`
+
+### `channel list [appId]`
+
+- Alias: `l`
+- Example: `npx @capgo/cli@latest channel list com.example.app`
+
+### `channel delete [channelId] [appId]`
+
+- Alias: `d`
+- Example: `npx @capgo/cli@latest channel delete production com.example.app`
+- Key options:
+  - `--delete-bundle`
+  - `--success-if-not-found`
+
+### `channel currentBundle [channel] [appId]`
+
+- Example: `npx @capgo/cli@latest channel currentBundle production com.example.app`
+- Key options:
+  - `-c, --channel <channel>`
+  - `--quiet`
+
+### `channel set [channelId] [appId]`
+
+- Alias: `s`
+- Example: `npx @capgo/cli@latest channel set production com.example.app --bundle 1.0.0 --state default`
+- Notes:
+  - One channel must remain default.
+  - Supports update policies `major`, `minor`, `metadata`, `patch`, and `none`.
+  - Supports platform and device targeting.
+- Key options:
+  - `-b, --bundle <bundle>`
+  - `-s, --state <state>`
+  - `--latest-remote`
+  - `--latest`
+  - `--downgrade`, `--no-downgrade`
+  - `--ios`, `--no-ios`
+  - `--android`, `--no-android`
+  - `--self-assign`, `--no-self-assign`
+  - `--disable-auto-update <disableAutoUpdate>`
+  - `--dev`, `--no-dev`
+  - `--prod`, `--no-prod`
+  - `--emulator`, `--no-emulator`
+  - `--device`, `--no-device`
+  - `--package-json <packageJson>`
+  - `--ignore-metadata-check`
+
+## Encryption key workflows
+
+### `key save`
+
+- Example: `npx @capgo/cli@latest key save --key ./path/to/key.pub`
+- Notes:
+  - Saves the public key in Capacitor config.
+  - Useful for CI.
+  - Recommended not to commit the key.
+- Key options:
+  - `-f, --force`
+  - `--key <key>`
+  - `--key-data <keyData>`
+
+### `key create`
+
+- Example: `npx @capgo/cli@latest key create`
+- Notes:
+  - Creates `.capgo_key_v2` and `.capgo_key_v2.pub`.
+  - Saves the public key to Capacitor config.
+  - Never commit the private key.
+- Key options:
+  - `-f, --force`
+
+### `key delete_old`
+
+- Example: `npx @capgo/cli@latest key delete_old`