Skip to content

Commit abeeecf

Browse files
committed
feat(cloud): add new protocol schemas for Environment, Package, Package Version, and Plugin Security
- Added Environment and Package protocol schemas with detailed properties and TypeScript usage. - Introduced new Package Version protocol schema to manage immutable release snapshots. - Created Plugin Security schema for package dependency declarations. - Updated existing documentation for cloud references to include new schemas and properties. - Removed unnecessary patterns from SysObject, SysFlow, SysAgent, SysMetadata, and SysTool object definitions.
1 parent eaa46bb commit abeeecf

19 files changed

Lines changed: 766 additions & 19 deletions
Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
title: Environment Package
3+
description: Environment Package protocol schemas
4+
---
5+
6+
{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}
7+
8+
Environment Package Installation Protocol
9+
10+
Models `sys_package_installation` — the pairing between an environment and a
11+
12+
specific, immutable package version snapshot (`sys_package_version`).
13+
14+
Key invariants (per ADR-0003):
15+
16+
- One active version per package per environment at any time.
17+
18+
- **Upgrade** = atomic `UPDATE package_version_id` to a newer version UUID.
19+
20+
- **Rollback** = atomic `UPDATE package_version_id` to an older version UUID.
21+
22+
- The `upgradeHistory` field is removed; history is tracked via the
23+
24+
sequence of `package_version_id` changes on this row (and an optional
25+
26+
`sys_package_installation_history` audit table).
27+
28+
- Only `status = 'published'` versions may be installed in production
29+
30+
environments (draft/pre-release allowed in dev/sandbox with `allowDraft`).
31+
32+
Stored in the **Control Plane DB** (not in environment DBs).
33+
34+
See `docs/adr/0003-package-as-first-class-citizen.md` for the full rationale.
35+
36+
<Callout type="info">
37+
**Source:** `packages/spec/src/cloud/environment-package.zod.ts`
38+
</Callout>
39+
40+
## TypeScript Usage
41+
42+
```typescript
43+
import { EnvPackageStatus, EnvPackageStatusEnum, EnvironmentPackageInstallation, InstallPackageToEnvRequest, ListEnvPackagesResponse, RollbackEnvPackageRequest, UpgradeEnvPackageRequest } from '@objectstack/spec/cloud';
44+
import type { EnvPackageStatus, EnvPackageStatusEnum, EnvironmentPackageInstallation, InstallPackageToEnvRequest, ListEnvPackagesResponse, RollbackEnvPackageRequest, UpgradeEnvPackageRequest } from '@objectstack/spec/cloud';
45+
46+
// Validate data
47+
const result = EnvPackageStatus.parse(data);
48+
```
49+
50+
---
51+
52+
## EnvPackageStatus
53+
54+
Package installation status within an environment
55+
56+
### Allowed Values
57+
58+
* `installed`
59+
* `installing`
60+
* `upgrading`
61+
* `disabled`
62+
* `error`
63+
64+
65+
---
66+
67+
## EnvPackageStatusEnum
68+
69+
Package installation status within an environment
70+
71+
### Allowed Values
72+
73+
* `installed`
74+
* `installing`
75+
* `upgrading`
76+
* `disabled`
77+
* `error`
78+
79+
80+
---
81+
82+
## EnvironmentPackageInstallation
83+
84+
Package installation record in an environment (sys_package_installation)
85+
86+
### Properties
87+
88+
| Property | Type | Required | Description |
89+
| :--- | :--- | :--- | :--- |
90+
| **id** | `string` || Unique installation record ID |
91+
| **environmentId** | `string` || Environment this installation belongs to |
92+
| **packageVersionId** | `string` || UUID of the installed sys_package_version row |
93+
| **packageId** | `string` || UUID of the parent sys_package row (denormalized for constraint enforcement) |
94+
| **status** | `Enum<'installed' \| 'installing' \| 'upgrading' \| 'disabled' \| 'error'>` || Package installation status within an environment |
95+
| **enabled** | `boolean` || Whether the package metadata is loaded |
96+
| **settings** | `Record<string, any>` | optional | Per-installation configuration settings |
97+
| **installedAt** | `string` || Installation timestamp (ISO-8601) |
98+
| **installedBy** | `string` | optional | User ID of the installer |
99+
| **updatedAt** | `string` | optional | Last update timestamp (ISO-8601) |
100+
| **errorMessage** | `string` | optional | Error message when status is error |
101+
102+
103+
---
104+
105+
## InstallPackageToEnvRequest
106+
107+
Install a package version into a specific environment
108+
109+
### Properties
110+
111+
| Property | Type | Required | Description |
112+
| :--- | :--- | :--- | :--- |
113+
| **packageVersionId** | `string` | optional | Exact package version UUID to install (preferred) |
114+
| **packageManifestId** | `string` | optional | Package manifest ID (reverse-domain, e.g. com.acme.crm) — resolved to version UUID |
115+
| **version** | `string` | optional | Version string (defaults to latest published) |
116+
| **allowDraft** | `boolean` || Allow installing a draft version (dev/sandbox envs only) |
117+
| **settings** | `Record<string, any>` | optional | Installation-time configuration settings |
118+
| **enableOnInstall** | `boolean` || Activate the package immediately after install |
119+
| **installedBy** | `string` | optional | User ID of the installer |
120+
121+
122+
---
123+
124+
## ListEnvPackagesResponse
125+
126+
List of packages installed in an environment
127+
128+
### Properties
129+
130+
| Property | Type | Required | Description |
131+
| :--- | :--- | :--- | :--- |
132+
| **packages** | `Object[]` || Packages installed in this environment |
133+
| **total** | `number` || Total count |
134+
135+
136+
---
137+
138+
## RollbackEnvPackageRequest
139+
140+
Roll back a package installation to a specific older version
141+
142+
### Properties
143+
144+
| Property | Type | Required | Description |
145+
| :--- | :--- | :--- | :--- |
146+
| **targetPackageVersionId** | `string` || Package version UUID to roll back to |
147+
| **rolledBackBy** | `string` | optional | User ID performing the rollback |
148+
149+
150+
---
151+
152+
## UpgradeEnvPackageRequest
153+
154+
Upgrade a package installation to a newer version
155+
156+
### Properties
157+
158+
| Property | Type | Required | Description |
159+
| :--- | :--- | :--- | :--- |
160+
| **targetPackageVersionId** | `string` | optional | Target package version UUID (preferred) |
161+
| **targetVersion** | `string` | optional | Target version string (defaults to latest published) |
162+
| **allowDraft** | `boolean` || Allow upgrading to a draft version |
163+
| **upgradedBy** | `string` | optional | User ID performing the upgrade |
164+
165+
166+
---
167+

0 commit comments

Comments
 (0)