diff --git a/.changeset/skills-platform-os-deploy.md b/.changeset/skills-platform-os-deploy.md new file mode 100644 index 00000000000..b69738a25a9 --- /dev/null +++ b/.changeset/skills-platform-os-deploy.md @@ -0,0 +1,10 @@ +--- +'@objectstack/skills': patch +--- + +docs(skills): the platform skill teaches `os deploy`, the managed-package dev loop + +Clause-②: no +Metadata-protocol: none + +`objectstack-platform/references/operations.md` gains an `os deploy` row in "Environments & deploy": use it to see an edit on the organization's ObjectOS Cloud environment (also `npm run deploy` in a scaffolded project, or `d` in `os dev`); it builds, publishes `-dev.`, installs that version and waits until the environment serves it. The row names how the environment is picked (`--env`, else the one `os environments switch` recorded, kept across `os cloud login`, else the organization's only one) and the `--no-wait` and `--wait-timeout` flags. A short paragraph reads an `os deploy` exit 1: a refusal before any write (with no environment at all, create one in the ObjectOS Cloud console), the environment's own build failure, and the wait timeout, each with the next step. `SKILL.md`'s Part 3 pointer names `os deploy`. Eval 17 of `evals/config-plugins-ops.json` asks how to see a change on the environment and expects `os deploy`. Paid inside `operations.md` by deleting four restatements (the `os dev` row's platform-admin sentence, the `os validate` row's gate summary, the "Both run the same gates:" lead-in, the Docker row's list of the official image's three required variables); the remainder raises that file's token ceiling by the measurement. diff --git a/scripts/check-skills-token-ratchet.mjs b/scripts/check-skills-token-ratchet.mjs index f2ef227c7b9..0e7c4c1337c 100644 --- a/scripts/check-skills-token-ratchet.mjs +++ b/scripts/check-skills-token-ratchet.mjs @@ -1051,7 +1051,18 @@ export const CEILINGS = new Map([ // 花板,怎么付?」, tap A, verbatim and untranslated: 「A:先削重复,余额按实测提高」. ['skills/objectstack-data/references/seeds.md', 1566], ['skills/objectstack-platform/references/bootstrap.md', 1351], - ['skills/objectstack-platform/references/operations.md', 3108], + // 3108 -> 3287: `os deploy`, the managed-package dev loop — when to deploy + // rather than publish a release, its entry points, how it picks the + // environment, its flags, and how to read its exit 1 (refusal before any + // write, the environment's build failure, the wait timeout). Paid first by + // deleting restatement in the same file (the `os dev` row's platform-admin + // sentence, homed in the Setup / Studio pitfall; the `os validate` row's + // gate summary and the "Both run the same gates:" lead-in, homed in Verify + // your work; the Docker row's list of the image's three variables, homed in + // the image pitfall row); the remainder, +179 measured, raises the row, + // pinned at the measurement. Maintainer ruling 2026-10-27 on the decision card 「skills 修复卡的教学和 eval 都撞 token 天 + // 花板,怎么付?」, tap A, verbatim and untranslated: 「A:先削重复,余额按实测提高」. + ['skills/objectstack-platform/references/operations.md', 3287], ['skills/objectstack-platform/references/plugin-development.md', 3137], ['skills/objectstack-upgrade/references/examples-upgrade.md', 1197], diff --git a/skills/objectstack-platform/SKILL.md b/skills/objectstack-platform/SKILL.md index 367968ffdaa..fbd4312003f 100644 --- a/skills/objectstack-platform/SKILL.md +++ b/skills/objectstack-platform/SKILL.md @@ -401,7 +401,7 @@ existing account on the boot banner. --- -→ Part 3 — Operations: CLI, Testing, Deployment: [references/operations.md](./references/operations.md). +→ Part 3 — Operations: CLI, Testing, Deployment (`os deploy` to see an edit on your Cloud environment): [references/operations.md](./references/operations.md). --- diff --git a/skills/objectstack-platform/evals/config-plugins-ops.json b/skills/objectstack-platform/evals/config-plugins-ops.json index 67c317b917c..b2eb2cc00de 100644 --- a/skills/objectstack-platform/evals/config-plugins-ops.json +++ b/skills/objectstack-platform/evals/config-plugins-ops.json @@ -287,6 +287,20 @@ "OS_DEV_CRYPTO_KEY" ] } + }, + { + "id": 17, + "prompt": "I edited an object in my app locally. How do I see my change on my ObjectOS Cloud environment?", + "expected_output": "Run `os deploy` from the project (`npm run deploy` in a scaffolded project, or press `d` in `os dev`). It builds, publishes `-dev.`, installs it into your organization's only environment (or `--env `, or the one `os environments switch` recorded) and waits until the environment serves it; `--no-wait` returns once the install is recorded. `os package publish` is for publishing a release version, not for this loop. On exit 1, a refusal before any write published nothing (log in with `os cloud login`, or pass `--env`); `could not build` is the environment's build failing while it keeps serving the previous build; a timeout means the install is recorded, so deploy again with a longer `--wait-timeout` or check the build in the ObjectOS Cloud console.", + "files": [], + "assertions": { + "must_contain": [ + "os deploy" + ], + "must_not_contain": [ + "os push" + ] + } } ] } diff --git a/skills/objectstack-platform/references/operations.md b/skills/objectstack-platform/references/operations.md index 57944ff920b..dc6abbbbb75 100644 --- a/skills/objectstack-platform/references/operations.md +++ b/skills/objectstack-platform/references/operations.md @@ -5,9 +5,9 @@ | Command | What it does | |:--------|:-------------| | `os init` | Scaffold a new project (alternative to `npx create-objectstack`) | -| `os dev` | Start the dev server with hot metadata reload. `--seed-admin` (default **on** for plain `os dev`) seeds a loginable dev admin **in-process via the runtime** (env vars `OS_SEED_ADMIN*`) on an **empty** DB only — idempotent, never overwrites an existing account (default `admin@objectos.ai` / `admin123`; override with `--admin-email` / `--admin-password`; disable with `--no-seed-admin`). `--fresh` = ephemeral clean OS_HOME/DB, implies `--seed-admin`. The seeded admin is promoted to **platform admin**, so Setup/Studio work on first login. | +| `os dev` | Start the dev server with hot metadata reload. `--seed-admin` (default **on** for plain `os dev`) seeds a loginable dev admin **in-process via the runtime** (env vars `OS_SEED_ADMIN*`) on an **empty** DB only — idempotent, never overwrites an existing account (default `admin@objectos.ai` / `admin123`; override with `--admin-email` / `--admin-password`; disable with `--no-seed-admin`). `--fresh` = ephemeral clean OS_HOME/DB, implies `--seed-admin`. | | `os dev --ui` | Also mount the bundled Console portal at `/_console/` (there is no separate `os studio` command) | -| `os validate` | Validate `objectstack.config.ts`: the `os build` gates, no artifact emitted — see [Verify your work](#verify-your-work) | +| `os validate` | Validate `objectstack.config.ts` — see [Verify your work](#verify-your-work) | | `os lint` | Style/convention lint on metadata files | | `os info` | Print a metadata summary of the config (objects, apps, and other collections; `--json`) | | `os doctor` | Diagnose common setup issues | @@ -36,8 +36,6 @@ os validate # Zod schema + CEL predicates + widget bindings — no artifact os build # the same three gates, plus emits dist/objectstack.json ``` -Both run the same gates: - 1. **Zod protocol schema** — the stack conforms to `@objectstack/spec`. 2. **CEL / predicate validation (ADR-0032)** — every `visible` / `disabled` / `requiredWhen` / validation rule / flow condition / sharing rule is parsed @@ -97,9 +95,12 @@ Port resolution is the same for `os dev` and `os start` (both spawn `os serve`): | `os environments list` / `create` / `switch` | Manage cloud environments (prod/staging/dev) | | `os register` | Register the local stack as a deployable target | | `os cloud login` / `logout` / `whoami` | Cloud auth subcommands (these three only — there are no `os cloud logs/metrics/status`) | +| `os deploy` (or `npm run deploy`, or `d` in `os dev`) | See an edit on your org's ObjectOS Cloud environment: build, publish `-dev.`, install, wait until served. Environment: `--env `, else the one `os environments switch` recorded (kept across `os cloud login`), else your organization's only one. `--no-wait`; `--wait-timeout ` (600) | | `os package publish [dist/objectstack.json] [--env … --install --visibility org]` | Upload the compiled artifact as a versioned package to the cloud catalog (ADR-0008 P3). Listing file, README, review and every screen the customer's administrator meets: [Marketplace handbook](https://objectstack.ai/docs/deployment/marketplace-handbook) | | `os package install [--version │ -u/--url http://localhost:3000]` | Install a package into a **running** runtime. Catalog mode (by manifest id) or air-gapped local-artifact mode. Auths as a **target runtime** user (`-t/--token` or `--email/--password`; env `OS_RUNTIME_TOKEN` or `OS_RUNTIME_EMAIL`/`OS_RUNTIME_PASSWORD`), not the cloud login | +**`os deploy` exit 1:** a refusal before any write publishes nothing: log in (`os cloud login`), pick an environment (`--env`; none: create one in the ObjectOS Cloud console), or fix the local build or `manifest.version`. `could not build …: `: the environment's build failed, it keeps serving the previous one; fix and deploy again. `Timed out after …`: the install is recorded and a failing build reads as pending for minutes; deploy again with a longer `--wait-timeout`, or see the build in the ObjectOS Cloud console. + > **Cloud connection & marketplace (`@objectstack/cloud-connection`, ADR-0008/0009):** > the open runtime-side cloud client; its `MarketplaceInstallLocalPlugin` serves the > install-local endpoint `os package install` targets. @@ -154,7 +155,7 @@ the other imports: [Using Plugins](./plugin-development.md#using-plugins). | Edge (Cloudflare Workers, Vercel Edge) | `driver-turso` (**cloud / EE only**) | `@objectstack/hono` | Cold-start friendly; LiteKernel only | | Serverless (Lambda, Vercel functions) | `driver-sql` (`pg` with pooler) / `driver-mongodb` | `@objectstack/hono` | Mind cold-start: prefer LiteKernel | | Browser / WebContainer | `driver-sqlite-wasm` | none (in-process) | Playground, demos | -| Docker / Kubernetes | any | any | Use `os start` as the entrypoint; pin `PORT` and `EXPOSE` it (see [Ports & networking](#ports--networking)). The official image (`ghcr.io/objectstack-ai/objectstack`) refuses to start unless `OS_DATABASE_URL`, `OS_AUTH_SECRET` and `OS_SECRET_KEY` are set at runtime, never baked in; an explicit `OS_DATABASE_URL=file:/path/on/a/mounted/volume/app.db` passes, so SQLite on a volume still works | +| Docker / Kubernetes | any | any | Use `os start` as the entrypoint; pin `PORT` and `EXPOSE` it (see [Ports & networking](#ports--networking)). The official image (`ghcr.io/objectstack-ai/objectstack`): its required variables (pitfalls below) set at runtime, never baked in; an explicit `OS_DATABASE_URL=file:/path/on/a/mounted/volume/app.db` passes, so SQLite on a volume still works | ## Health & observability