|
| 1 | +--- |
| 2 | +"@objectstack/cli": major |
| 3 | +"@objectstack/runtime": major |
| 4 | +"@objectstack/rest": major |
| 5 | +"@objectstack/client": major |
| 6 | +"@objectstack/spec": major |
| 7 | +"@objectstack/metadata": major |
| 8 | +"@objectstack/platform-objects": major |
| 9 | +--- |
| 10 | + |
| 11 | +# v5.0 — `project` → `environment` hard rename |
| 12 | + |
| 13 | +The runtime concept previously called **"project"** (per-tenant business |
| 14 | +workspace; Org → **Project** → Branch hierarchy; per-project ObjectKernel, |
| 15 | +per-project DB, per-project artifact) is now uniformly called |
| 16 | +**"environment"**. |
| 17 | + |
| 18 | +This is a **hard rename with no aliases, deprecation shims, or compatibility |
| 19 | +layer**. Upgrade requires a coordinated update of CLI, runtime, server, and any |
| 20 | +clients calling the REST API. |
| 21 | + |
| 22 | +> Note: "project" in the npm / monorepo sense (the framework itself, `package.json`, |
| 23 | +> tsconfig project references, vitest `projects` config) is **unchanged**. |
| 24 | +
|
| 25 | +## Breaking changes |
| 26 | + |
| 27 | +### CLI |
| 28 | + |
| 29 | +- Flags renamed: |
| 30 | + - `--project` / `-p` → `--environment` / `-e` (`os publish`, `os rollback`) |
| 31 | + - `--project-id` → `--environment-id` (`os dev`) |
| 32 | +- Default local env id: `proj_local` → `env_local`. |
| 33 | +- Env var: `OS_PROJECT_ID` → `OS_ENVIRONMENT_ID`. |
| 34 | +- Command group renamed: `os projects ...` → `os environments ...` |
| 35 | + (`bind`, `create`, `list`, `show`, `switch`). |
| 36 | +- Persisted auth-config key: `activeProjectId` → `activeEnvironmentId`. |
| 37 | + |
| 38 | +### HTTP / REST |
| 39 | + |
| 40 | +- Scoped routes: `/api/v1/projects/:projectId/...` → `/api/v1/environments/:environmentId/...`. |
| 41 | +- Cloud control-plane routes: `/api/v1/cloud/projects/...` → `/api/v1/cloud/environments/...` |
| 42 | + (including `/cloud/environments/:id/artifact`, `/cloud/environments/:id/metadata`, |
| 43 | + `/cloud/environments/:id/credentials/rotate`, etc.). |
| 44 | +- Header: `X-Project-Id` (and lowercase `x-project-id`) → `X-Environment-Id` |
| 45 | + (`x-environment-id`). |
| 46 | +- Route param name in handlers: `req.params.projectId` → `req.params.environmentId`. |
| 47 | +- Hostname-routing and tenant-resolution code-paths use `environmentId` end-to-end. |
| 48 | + |
| 49 | +### Runtime / spec |
| 50 | + |
| 51 | +- Exported symbols (no aliases): |
| 52 | + - `createSystemProjectPlugin` → `createSystemEnvironmentPlugin` |
| 53 | + - `SYSTEM_PROJECT_ID` → `SYSTEM_ENVIRONMENT_ID` |
| 54 | + - `ProjectArtifactSchema` → `EnvironmentArtifactSchema` |
| 55 | + - `PROJECT_ARTIFACT_SCHEMA_VERSION` → `ENVIRONMENT_ARTIFACT_SCHEMA_VERSION` |
| 56 | + - `ObjectOSProjectPlugin` → `ObjectOSEnvironmentPlugin` |
| 57 | + - `createSingleProjectPlugin` → `createSingleEnvironmentPlugin` |
| 58 | +- Plugin identifier strings: |
| 59 | + - `com.objectstack.runtime.objectos-project` → `objectos-environment` |
| 60 | + - `com.objectstack.studio.single-project` → `single-environment` |
| 61 | + - `com.objectstack.multi-project` → `multi-environment` |
| 62 | + - `com.objectstack.runtime.system-project` → `system-environment` |
| 63 | +- Provisioning hook: `provisionSystemProject` → `provisionSystemEnvironment`. |
| 64 | + |
| 65 | +### Database / schemas |
| 66 | + |
| 67 | +- Column renames on `sys_metadata` and `sys_metadata_history`: |
| 68 | + `project_id` → `environment_id`. |
| 69 | +- Column renames on `sys_activity`: `project_id` → `environment_id` (plus index). |
| 70 | +- Object renames in platform-objects metadata: `sys_project` → `sys_environment` |
| 71 | + (lookup targets), `sys_project_member` → `sys_environment_member`, |
| 72 | + `sys_project_credential` → `sys_environment_credential`. |
| 73 | +- Auth-context field: `active_project_id` → `active_environment_id`. |
| 74 | +- JSON schemas under `packages/spec/json-schema/system/`: |
| 75 | + `ProjectArtifact*.json` → `EnvironmentArtifact*.json` (regenerated at build). |
| 76 | + |
| 77 | +### Automatic forward migration |
| 78 | + |
| 79 | +A new migration `migrateProjectIdToEnvironmentId` |
| 80 | +(`packages/metadata/src/migrations/migrate-project-id-to-environment-id.ts`) |
| 81 | +auto-runs from `DatabaseLoader.ensureSchema()` on bootstrap and rewrites any |
| 82 | +existing `project_id` column on `sys_metadata` / `sys_metadata_history` to |
| 83 | +`environment_id` (idempotent, best-effort). Existing rows are preserved. |
| 84 | + |
| 85 | +The legacy reverse migration `migrateEnvIdToProjectId` is retained verbatim |
| 86 | +for historical / disaster-recovery use; it is **not** auto-run. |
| 87 | + |
| 88 | +## Migration guide |
| 89 | + |
| 90 | +```diff |
| 91 | +-os publish --project proj_xyz |
| 92 | ++os publish --environment env_xyz |
| 93 | + |
| 94 | +-curl -H "X-Project-Id: env_xyz" https://api.example.com/api/v1/data/customer |
| 95 | ++curl -H "X-Environment-Id: env_xyz" https://api.example.com/api/v1/data/customer |
| 96 | + |
| 97 | +-OS_PROJECT_ID=env_xyz os dev |
| 98 | ++OS_ENVIRONMENT_ID=env_xyz os dev |
| 99 | + |
| 100 | +-import { createSystemProjectPlugin, SYSTEM_PROJECT_ID } from "@objectstack/runtime"; |
| 101 | ++import { createSystemEnvironmentPlugin, SYSTEM_ENVIRONMENT_ID } from "@objectstack/runtime"; |
| 102 | + |
| 103 | +-import { ProjectArtifactSchema } from "@objectstack/spec"; |
| 104 | ++import { EnvironmentArtifactSchema } from "@objectstack/spec"; |
| 105 | +``` |
| 106 | + |
| 107 | +If you maintain a Cloud control-plane deployment, the `cloud` repository must |
| 108 | +be updated in lockstep to pick up the new plugin identifier strings |
| 109 | +(`single-environment`, `multi-environment`, `objectos-environment`). |
0 commit comments