feat(cli): remote-dev commands — sandbox + projectless connectors

[carmelc]

Note

Description

Adds a base44 sandbox command group for developing an app remotely through its server-side sandbox (list, read, write, edit, grep, run, and checkpoint), plus a projectless connectors initiate command that starts a connector's OAuth flow against any --app-id without a local project. It also introduces a global --json flag that turns stdout into a single machine-readable JSON document (with silent mode and a JSON error envelope) so the CLI can be driven by scripts and agents. To support the sandbox, the device-login flow now requests the sandbox:write scope and surfaces a re-login hint when that scope is missing.

Related Issue

None

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• sandbox command group — new remote-development commands: sandbox ls, read, write, edit, grep, run, and checkpoint, backed by a new core/resources/sandbox API + Zod schemas and a getSandboxClient(appId) HTTP client scoped to /sandbox-bridge/. Operates on a remote app via --app-id with no local project required.
• connectors initiate command — initializes a connector and starts its OAuth flow projectlessly; surfaces the authorize URL and polls until authorized (interactive) or prints the link (non-interactive/--json).
• Global --json flag — exposed as ctx.jsonMode; forces non-interactive wiring, routes status/logs to stderr, and emits a single JSON document on stdout. Base44Command provides a generic { "output": "<status>" } fallback and a JSON error envelope ({ error, code, details, hints }) so every command stays parseable.
• Auth scope — device login now requests sandbox:write; sandbox API errors add a "run base44 login again" hint only on a genuine missing-scope 401/403.
• readStdin — added an options.trim flag to preserve file bodies/trailing newlines verbatim (used by sandbox write/edit).
• Docs — updated README.md (command table, Global flags, --json section) and docs/AGENTS.md (rules for --json and silent mode).
• Test fixtures — normalized function fixtures from index.ts to entry.ts.

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

New tests cover the sandbox commands (tests/cli/sandbox.spec.ts) and connectors initiate (tests/cli/connectors_initiate.spec.ts); existing connector/function/logs/whoami specs were updated for the --json lifecycle and the entry.ts fixture rename.

---

_{🤖 Generated by Claude | 2026-06-25 09:08 UTC | db4783d}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.0.56-pr.547.db4783d

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.0.56-pr.547.db4783d"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.0.56-pr.547.db4783d"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.0.56-pr.547.db4783d
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}