@palettelab/cli 0.3.18 → 0.3.19

package/README.md

@@ -8,7 +8,8 @@ The installed executable is `pltt`.
 
 - Node.js 18+
 - Python 3.12+ for local backend simulation
-- Docker Desktop only for `pltt dev --platform`
+- No Docker is required for normal app development, testing, or publishing.
+- Docker Desktop is only for internal `pltt dev --platform` parity checks.
 
 ## Install
 
@@ -48,8 +49,10 @@ Run a no-Docker local SDK simulator with your plugin mounted live. Run this from
 
 ```bash
 pltt dev
-pltt dev --platform
+pltt sandbox --env staging
+pltt dev --sandbox --env staging
 pltt dev --cloud --env staging
+pltt dev --platform
 ```
 
 By default this starts:
@@ -70,11 +73,14 @@ the declared Alembic migrations and platform-managed Postgres/RLS.
 
 `3000` and `8000` are preferred defaults, not hard requirements. If either port is already in use, `pltt dev` automatically picks the next free port and prints the actual URLs.
 
-`pltt dev --platform` runs the full Docker `platform-dev` image for deeper
-integration/parity testing. It pulls `ghcr.io/palette-lab/platform-dev:latest`
-and mounts your plugin at `/plugins/<your-id>`.
+`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.
+
+`pltt dev --cloud` is kept as an alias for `--sandbox`.
+
+`pltt sandbox --env staging` is the same hosted preview flow as
+`pltt dev --sandbox --env staging`.
 
-`pltt dev --cloud` skips Docker and publishes a reviewable preview to a configured cloud 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.
+`pltt dev --platform` runs the full Docker `platform-dev` image for internal platform parity testing. App developers should not need it. It pulls `ghcr.io/palette-lab/platform-dev:latest` and mounts your plugin at `/plugins/<your-id>`.
 
 Environment variables:
 
@@ -85,6 +91,15 @@ Environment variables:
 | `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 |
 
+### `pltt login`
+
+Save a Palette sandbox or production environment URL plus token in `~/.palette/config.json` with file mode `0600`. Environment variables still override the stored token when present.
+
+```bash
+pltt login --env staging --url https://sandbox.pltt.ai --token <publish-token>
+pltt dev --sandbox --env staging
+```
+
 ### `pltt doctor`
 
 Check local tooling and common setup problems.
@@ -93,7 +108,15 @@ Check local tooling and common setup problems.
 pltt doctor
 ```
 
-Checks include Node version, Docker availability, platform image availability, port availability, manifest validity, entry files, and frontend bundling.
+Checks include Node version, port availability, manifest validity, entry files, and frontend bundling.
+
+Docker is intentionally skipped by default:
+
+```bash
+pltt doctor --platform
+```
+
+Use `--platform` only when validating the internal Docker parity harness.
 
 ### `pltt build`
 
@@ -142,7 +165,7 @@ pltt publish --env staging --ttl-hours 24
 
 Publishing first runs the same contract checks as `pltt test`. If preflight passes, it bundles frontend/backend artifacts, uploads them, creates a `pending_review` publish record, and prints review/preview URLs when the platform returns them.
 
-`--ttl-hours` sets an expiration on the preview URL. It is mainly used by `pltt dev --cloud`, which defaults previews to 24 hours.
+`--ttl-hours` sets an expiration on the preview URL. It is mainly used by `pltt dev --sandbox`, which defaults previews to 24 hours.
 
 Environment config is read from `./palette.config.json`, `~/.palette/config.json`, or `PALETTE_<ENV>_URL` plus `PALETTE_<ENV>_TOKEN` / `PALETTE_PUBLISH_TOKEN`.
 
@@ -183,7 +206,7 @@ If no plugin ID is provided, the CLI uses the current `palette-plugin.json` or `
 - `bin/pltt.js` — entry point
 - `backend-sdk/` — backend SDK files used by local contract tests and simulator
 - `lib/` — pure-Node command implementations (no runtime dependencies)
-- `platform-dev/docker-compose.yml` — compose file for `pltt dev --platform`
+- `platform-dev/docker-compose.yml` — compose file for internal `pltt dev --platform` parity checks
 - `template-fallback/` — offline fallback for `pltt init` if git is unavailable
 
 ## See also

package/lib/cli.js

@@ -6,6 +6,7 @@ const doctor = require("./commands/doctor")
 const build = require("./commands/build")
 const test = require("./commands/test")
 const publish = require("./commands/publish")
+const login = require("./commands/login")
 const pkg = require("./commands/package")
 const status = require("./commands/status")
 const logs = require("./commands/logs")
@@ -14,11 +15,16 @@ const COMMANDS = {
   init: { run: init, help: "Scaffold a new plugin directory from the template" },
   dev: {
     run: dev,
-    help: "Run the local SDK simulator; use --platform for Docker platform parity",
+    help: "Run the no-Docker SDK simulator; use --sandbox for hosted preview",
   },
+  sandbox: {
+    run: (args, ctx) => dev([...args, "--sandbox"], ctx),
+    help: "Publish a no-Docker hosted sandbox preview",
+  },
+  login: { run: login, help: "Save a Palette sandbox environment for publish/dev preview" },
   doctor: {
     run: doctor,
-    help: "Check local tooling, ports, manifest, Docker, and frontend bundling",
+    help: "Check local tooling, ports, manifest, and frontend bundling",
   },
   build: { run: build, help: "Validate palette-plugin.json and check entry points exist" },
   test: { run: test, help: "Run local plugin contract checks before publishing" },
@@ -50,8 +56,13 @@ function printHelp() {
   console.log("  --env <name>     Target environment from ~/.palette/config.json (default: local)")
   console.log("  -y, --yes        Skip interactive confirmation for production pushes")
   console.log("\nDev flags:")
-  console.log("  --platform       Run the full Docker platform-dev container")
-  console.log("  --cloud          Publish a reviewable preview to a configured cloud sandbox")
+  console.log("  --sandbox        Publish a reviewable preview to a configured Palette sandbox (no Docker)")
+  console.log("  --cloud          Alias for --sandbox")
+  console.log("  --platform       Internal only: run the Docker platform-dev parity container")
+  console.log("\nLogin flags:")
+  console.log("  --url <url>      Palette platform URL for pltt login")
+  console.log("  --token <token>  Publish token for pltt login")
+  console.log("  --no-default     Do not make this environment the default")
   console.log("\nInit flags:")
   console.log("  --template <name>  One of: dashboard, agent-tool, external-service, database, frontend-only")
   console.log("\nLogs flags:")
@@ -59,7 +70,10 @@ function printHelp() {
   console.log("  -f, --follow     Stream events (poll every 3s)")
   console.log("\nExamples:")
   console.log("  pltt init my-app --template database")
+  console.log("  pltt login --env staging --url https://sandbox.pltt.ai --token <token>")
   console.log("  cd my-app && pltt dev")
+  console.log("  pltt sandbox --env staging")
+  console.log("  pltt dev --sandbox --env staging")
   console.log("  pltt package")
   console.log("  pltt publish --env staging")
   console.log("  pltt status")

package/lib/commands/dev.js

@@ -76,7 +76,7 @@ function imagePullHelp(image, output) {
 
 async function run(args, { cwd }) {
   const { flags, rest } = parseFlags(args)
-  const cloud = rest.includes("--cloud")
+  const cloud = rest.includes("--cloud") || rest.includes("--sandbox")
   const platform = rest.includes("--platform")
   if (cloud) {
     const json = args.includes("--json")
@@ -92,7 +92,7 @@ async function run(args, { cwd }) {
     if (!flags.env && !process.env.PALETTE_ENV) publishArgs.push("--env", "staging")
     if (!json) {
       console.log(
-        "[pltt] cloud dev publishes a reviewable preview to the configured cloud sandbox.",
+        "[pltt] sandbox dev publishes a reviewable preview to the configured Palette sandbox.",
       )
     }
     const record = await publish(publishArgs, { cwd })
@@ -146,6 +146,7 @@ async function run(args, { cwd }) {
   }
 
   console.log(`[pltt] starting ${DEFAULT_IMAGE} via docker compose`)
+  console.log("[pltt] --platform is for internal parity testing; app developers should use `pltt dev` or `pltt dev --sandbox`.")
   console.log(`[pltt] mounting ${cwd} → /plugins/${pluginId}`)
   if (ports.frontend !== ports.preferredFrontend) {
     console.log(`[pltt] frontend port ${ports.preferredFrontend} is busy; using ${ports.frontend}`)

package/lib/commands/doctor.js

@@ -51,27 +51,39 @@ function checkEntry(cwd, label, rel) {
 
 async function run(args, { cwd }) {
   let failures = 0
+  const platform = args.includes("--platform")
 
   if (nodeMajor() >= 18) ok(`Node ${process.versions.node}`)
   else failures += fail("Node 18+ is required", "Install Node.js 18 or newer.")
 
-  if (dockerRunning()) ok("Docker is running")
-  else failures += fail(
-    "Docker is not running",
-    "Start Docker Desktop, then rerun pltt doctor.",
-  )
+  if (platform) {
+    if (dockerRunning()) ok("Docker is running")
+    else failures += fail(
+      "Docker is not running",
+      "Start Docker Desktop, then rerun pltt doctor --platform.",
+    )
 
-  if (imageExistsLocally(DEFAULT_IMAGE)) {
-    ok(`platform image is available locally: ${DEFAULT_IMAGE}`)
+    if (imageExistsLocally(DEFAULT_IMAGE)) {
+      ok(`platform image is available locally: ${DEFAULT_IMAGE}`)
+    } else {
+      warn(
+        `platform image is not present locally: ${DEFAULT_IMAGE}`,
+        "pltt dev --platform will try to pull it. If that fails, run docker login ghcr.io or set PALETTE_DEV_IMAGE.",
+      )
+    }
   } else {
     warn(
-      `platform image is not present locally: ${DEFAULT_IMAGE}`,
-      "pltt dev will try to pull it. If that fails, run docker login ghcr.io or set PALETTE_DEV_IMAGE.",
+      "Docker check skipped",
+      "Normal app development uses no Docker. Run `pltt doctor --platform` only for internal platform parity testing.",
     )
   }
 
   try {
-    const ports = await resolveDevPorts({ frontend: FRONTEND_PORT, backend: BACKEND_PORT })
+    const ports = await resolveDevPorts({
+      frontend: FRONTEND_PORT,
+      backend: BACKEND_PORT,
+      host: platform ? "0.0.0.0" : "127.0.0.1",
+    })
     if (ports.frontend === FRONTEND_PORT) ok(`frontend port ${FRONTEND_PORT} is available`)
     else warn(`frontend port ${FRONTEND_PORT} is already in use`, `pltt dev will use ${ports.frontend}`)
     if (ports.backend === BACKEND_PORT) ok(`backend port ${BACKEND_PORT} is available`)

package/lib/commands/login.js

@@ -0,0 +1,51 @@
+"use strict"
+
+const { parseFlags, writeUserEnvironment } = require("../environments")
+
+function tokenEnvFor(name) {
+  if (name === "production") return "PALETTE_PROD_TOKEN"
+  return `PALETTE_${name.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_TOKEN`
+}
+
+async function run(argv) {
+  const { flags } = parseFlags(argv)
+  const name = flags.env || process.env.PALETTE_ENV || "staging"
+  const url = flags.url || process.env.PALETTE_PLATFORM_URL || process.env[`PALETTE_${name.toUpperCase()}_URL`]
+  const token = flags.token || process.env.PALETTE_PUBLISH_TOKEN || process.env[tokenEnvFor(name)]
+
+  if (!url) {
+    console.error(
+      `[pltt] missing platform URL for "${name}".\n` +
+        `          Usage: pltt login --env ${name} --url https://palette.example.com --token <publish-token>`,
+    )
+    process.exit(1)
+  }
+  if (!token) {
+    console.error(
+      `[pltt] missing publish token for "${name}".\n` +
+        `          Pass --token <token> or set $PALETTE_PUBLISH_TOKEN.`,
+    )
+    process.exit(1)
+  }
+
+  const tokenEnv = tokenEnvFor(name)
+  const configPath = writeUserEnvironment({
+    name,
+    url,
+    token,
+    tokenEnv,
+    defaultEnvironment: flags.default,
+  })
+
+  if (flags.json) {
+    console.log(JSON.stringify({ ok: true, env: name, url: url.replace(/\/+$/, ""), token_env: tokenEnv, config: configPath }, null, 2))
+    return
+  }
+
+  console.log(`[pltt] saved ${name} → ${url.replace(/\/+$/, "")}`)
+  console.log(`[pltt] config: ${configPath}`)
+  console.log(`[pltt] token stored in user config with file mode 0600`)
+  console.log(`[pltt] env override: ${tokenEnv}`)
+}
+
+module.exports = run

package/lib/environments.js

@@ -65,6 +65,40 @@ function loadConfig(cwd) {
   return DEFAULTS
 }
 
+function mergeConfig(cfg) {
+  return {
+    ...DEFAULTS,
+    ...cfg,
+    environments: {
+      ...DEFAULTS.environments,
+      ...(cfg.environments || {}),
+    },
+  }
+}
+
+function userConfigPath() {
+  return path.join(os.homedir(), ".palette", "config.json")
+}
+
+function writeUserEnvironment({ name, url, token, tokenEnv, defaultEnvironment = true }) {
+  const target = userConfigPath()
+  const existing = readJsonIfExists(target) || {}
+  const cfg = mergeConfig(existing)
+  cfg.environments[name] = {
+    ...(cfg.environments[name] || {}),
+    url: url.replace(/\/+$/, ""),
+    token,
+    token_env: tokenEnv,
+    production: Boolean(cfg.environments[name]?.production),
+  }
+  if (defaultEnvironment) cfg.default_environment = name
+
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 })
+  fs.writeFileSync(target, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 })
+  fs.chmodSync(target, 0o600)
+  return target
+}
+
 /**
  * Resolve the effective environment.
  *
@@ -106,7 +140,7 @@ function resolveEnvironment({ cwd, flags }) {
 
   const token = useLegacy
     ? process.env.PALETTE_PUBLISH_TOKEN || ""
-    : process.env[envCfg.token_env] || process.env.PALETTE_PUBLISH_TOKEN || ""
+    : process.env[envCfg.token_env] || process.env.PALETTE_PUBLISH_TOKEN || envCfg.token || ""
 
   if (!url) {
     throw new Error(
@@ -130,7 +164,16 @@ function resolveEnvironment({ cwd, flags }) {
  * Leaves positional args in `rest`.
  */
 function parseFlags(argv) {
-  const flags = { env: undefined, yes: false, ttlHours: undefined, wait: false }
+  const flags = {
+    env: undefined,
+    yes: false,
+    ttlHours: undefined,
+    wait: false,
+    json: false,
+    url: undefined,
+    token: undefined,
+    default: true,
+  }
   const rest = []
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
@@ -146,6 +189,18 @@ function parseFlags(argv) {
       flags.ttlHours = Number.parseInt(a.slice("--ttl-hours=".length), 10)
     } else if (a === "--wait") {
       flags.wait = true
+    } else if (a === "--json") {
+      flags.json = true
+    } else if (a === "--url") {
+      flags.url = argv[++i]
+    } else if (a.startsWith("--url=")) {
+      flags.url = a.slice("--url=".length)
+    } else if (a === "--token") {
+      flags.token = argv[++i]
+    } else if (a.startsWith("--token=")) {
+      flags.token = a.slice("--token=".length)
+    } else if (a === "--no-default") {
+      flags.default = false
     } else {
       rest.push(a)
     }
@@ -168,4 +223,10 @@ async function confirmProduction(env) {
   })
 }
 
-module.exports = { resolveEnvironment, parseFlags, confirmProduction, loadConfig }
+module.exports = {
+  resolveEnvironment,
+  parseFlags,
+  confirmProduction,
+  loadConfig,
+  writeUserEnvironment,
+}

package/package.json

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