@palettelab/cli 0.3.21 → 0.3.23

package/README.md

@@ -21,6 +21,178 @@ npx @palettelab/cli <command>
 pltt <command>
 ```
 
+## Quick Start: Build And Test A Palette App
+
+Use this flow when a developer wants to create an app, run it locally, then test
+it inside the real Palette OS without Docker.
+
+```bash
+npx --yes @palettelab/cli@latest init simple-todo --template database
+cd simple-todo
+npm install
+npx --yes @palettelab/cli@latest dev
+```
+
+`pltt dev` runs the local SDK simulator. It is the fastest loop for frontend,
+backend, manifest, SDK hooks, and local database checks. It does not require
+Docker and does not publish anything to the platform.
+
+When the app is ready to test with real Palette OS services, configure a hosted
+sandbox environment and run:
+
+```bash
+npx --yes @palettelab/cli@latest login \
+  --env staging \
+  --url https://YOUR-PALETTE-STAGING-URL \
+  --token pltt_xxxxx
+
+npx --yes @palettelab/cli@latest dev --sandbox --env staging
+```
+
+The hosted sandbox flow packages the app, uploads it to the configured Palette
+environment, creates a preview publish, and prints a real OS preview URL. Use
+that URL to test routing, OS shell behavior, login context, organization
+context, Data Room APIs, storage, install/review behavior, logs, permissions,
+and platform APIs.
+
+## Staging URL
+
+The staging URL is the base URL of the Palette platform backend/API
+environment. The CLI appends the API paths itself, for example:
+
+- `/api/v1/appstore/sign-upload`
+- `/api/v1/appstore/publish`
+- `/api/v1/developer/publish-tokens`
+- `/api/superadmin/publish-tokens`
+
+Use the same public origin only if that origin proxies API routes to the
+backend. For example, `https://apps.pltt.xyz` is valid only when these paths are
+served by the backend, not by the frontend catch-all route:
+
+```text
+/api/v1/*
+/api/superadmin/*
+```
+
+Validate a staging URL before giving it to developers:
+
+```bash
+curl https://YOUR-PALETTE-STAGING-URL/api/v1/health
+```
+
+A valid staging URL returns a backend health JSON response. If it returns the
+Palette frontend HTML, it is a frontend-only URL and the CLI cannot publish to
+it. In that case either use the real backend domain, for example
+`https://api.your-domain.example`, or update the web server/reverse proxy so
+`/api/v1/*` and `/api/superadmin/*` go to the backend.
+
+## Publish Token
+
+Every developer needs a publish token before they can use hosted sandbox or
+publish commands. Tokens start with `pltt_`.
+
+Developers can create their own token after logging in to Palette:
+
+1. Open Palette OS in the browser.
+2. Open Settings.
+3. Go to Developer.
+4. Create a developer publish token.
+5. Copy the token immediately. The raw token is shown only once.
+
+Superadmins can also allocate tokens from the superadmin publish-token section.
+Use superadmin allocation for service accounts, CI, or developers who should
+not create their own token.
+
+Do not commit tokens to a repository. Store them through `pltt login` or an
+environment variable.
+
+## Configure A Hosted Sandbox
+
+The recommended setup is `pltt login`, which writes
+`~/.palette/config.json` with file mode `0600`:
+
+```bash
+npx --yes @palettelab/cli@latest login \
+  --env staging \
+  --url https://YOUR-PALETTE-STAGING-URL \
+  --token pltt_xxxxx
+```
+
+You can verify the saved environment with:
+
+```bash
+cat ~/.palette/config.json
+```
+
+You can also use environment variables instead of storing the token:
+
+```bash
+export PALETTE_STAGING_URL=https://YOUR-PALETTE-STAGING-URL
+export PALETTE_STAGING_TOKEN=pltt_xxxxx
+npx --yes @palettelab/cli@latest dev --sandbox --env staging
+```
+
+Environment variable precedence:
+
+1. `PALETTE_<ENV>_URL` and `PALETTE_<ENV>_TOKEN`
+2. `PALETTE_PUBLISH_TOKEN` as a token fallback
+3. `~/.palette/config.json`
+4. `./palette.config.json` for repo-local overrides
+
+## Test Inside The Real Palette OS Without Docker
+
+Use hosted sandbox for real OS testing:
+
+```bash
+npx --yes @palettelab/cli@latest dev --sandbox --env staging
+```
+
+This is the correct flow for internal teams that need real platform features
+without pushing the app to production approval and without running Docker on the
+developer machine.
+
+Expected behavior:
+
+1. The CLI runs local contract checks.
+2. The CLI bundles frontend and backend artifacts.
+3. The CLI uploads the package to the staging Palette environment.
+4. The platform creates a preview/review publish.
+5. The CLI prints the preview URL, status command, and logs command.
+6. The developer opens the preview URL inside the real Palette OS.
+
+For developer sandboxes where manual review should not block testing, the
+backend environment should run with:
+
+```bash
+APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS=true
+```
+
+With that backend setting enabled, passing sandbox preview publishes are marked
+active automatically, so developers can test OS shell, auth, Data Room,
+organization, install, permission, log, and platform API behavior immediately.
+
+Useful follow-up commands:
+
+```bash
+npx --yes @palettelab/cli@latest status --env staging
+npx --yes @palettelab/cli@latest logs simple-todo --env staging --follow
+```
+
+## Local-Only Versus OS Testing
+
+Use the right command for the kind of test you need:
+
+| Goal | Command | Docker | Uses real OS services |
+|---|---|---:|---:|
+| Fast SDK/frontend/backend loop | `pltt dev` | No | No |
+| Real OS preview in hosted cloud sandbox | `pltt dev --sandbox --env staging` | No | Yes |
+| Alias for hosted cloud sandbox | `pltt dev --cloud --env staging` | No | Yes |
+| Internal full local platform parity | `pltt dev --platform` | Yes | Local platform container |
+| Production/review publish | `pltt publish --env production` | No | Yes |
+
+For normal app developers, Docker is not required. Docker is only needed for
+internal platform parity checks with `pltt dev --platform`.
+
 ## Commands
 
 ### `pltt init <name>`
@@ -75,6 +247,8 @@ the declared Alembic migrations and platform-managed Postgres/RLS.
 
 `pltt dev --sandbox` skips Docker and publishes a reviewable preview to a configured Palette sandbox. This is the payment-gateway-style flow: your app uses local SDKs, while real platform services such as login, Data Room, storage, database policies, logs, review, and publish lifecycle run in the hosted sandbox. It defaults to `--env staging` unless `--env` or `PALETTE_ENV` is set, adds a 24-hour preview TTL by default, and prints the preview/status/log commands returned by the platform.
 
+For developer sandboxes where manual approval should not block OS testing, run the sandbox backend with `APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS=true`. Preview publishes are still checked by the automated review gates; passing preview publishes are marked active and synced immediately so backend routes, installs, logs, permissions, and platform APIs can be tested in the OS without Docker.
+
 `pltt dev --cloud` is kept as an alias for `--sandbox`.
 
 `pltt sandbox --env staging` is the same hosted preview flow as
@@ -90,6 +264,7 @@ Environment variables:
 | `PALETTE_FRONTEND_PORT` | `3000` | Preferred starting host port for the frontend |
 | `PALETTE_BACKEND_PORT` | `8000` | Preferred starting host port for the backend |
 | `PALETTE_DEV_DATABASE_URL` | `.palette/dev/<plugin-id>.sqlite3` | Override the local dev database URL |
+| `APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS` | `false` | Backend setting for hosted sandboxes; auto-approve passing preview publishes so developers can test full OS behavior without manual review |
 
 ### `pltt login`
 

package/lib/commands/publish.js

@@ -210,8 +210,12 @@ async function run(argv, { cwd }) {
   console.log(
     `[pltt] published ${record.plugin_id}@${record.version} (status=${record.status})`,
   )
-  console.log(`[pltt] awaiting superadmin review on ${env.url}`)
-  if (record.review_url) {
+  if (record.status === "active") {
+    console.log(`[pltt] active on ${env.url}`)
+  } else {
+    console.log(`[pltt] awaiting superadmin review on ${env.url}`)
+  }
+  if (record.review_url && record.status !== "active") {
     console.log(`[pltt] review queue: ${record.review_url}`)
   }
   if (record.preview_url) {
@@ -220,7 +224,11 @@ async function run(argv, { cwd }) {
   if (record.preview_expires_at) {
     console.log(`[pltt] preview expires: ${record.preview_expires_at}`)
   }
-  console.log(`[pltt] once approved, live at ${env.url}${record.catalog_url}`)
+  if (record.status === "active") {
+    console.log(`[pltt] live at ${env.url}${record.catalog_url}`)
+  } else {
+    console.log(`[pltt] once approved, live at ${env.url}${record.catalog_url}`)
+  }
   return record
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"