Skip to content

Commit fe60f99

Browse files
hotlonghotlong
authored
Merge pull request #773 from objectstack-ai/copilot/add-package-artifact-format-spec
2 parents a3036bf + 4d46b39 commit fe60f99

21 files changed

Lines changed: 1639 additions & 3 deletions

‎ROADMAP.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -691,7 +691,12 @@ Final polish and advanced features.
691691

692692
### 8.5 Marketplace & Cloud
693693

694-
- [ ] Plugin marketplace — publish, discover, install community plugins
694+
- [x] Plugin marketplace protocol — package artifact format, artifact storage & distribution
695+
- [x] Platform version compatibility — engine requirements in manifest
696+
- [x] Dependency resolution protocol — conflict detection, topological install ordering
697+
- [x] Namespace collision detection — registry entries, conflict errors
698+
- [x] Upgrade migration context — version context for onUpgrade hooks, upgrade history
699+
- [ ] Plugin marketplace runtime — publish, discover, install community plugins
695700
- [ ] App store — pre-built applications (CRM, HRM, Project Management)
696701
- [ ] Developer portal — API keys, usage metrics, billing
697702
- [ ] Managed cloud offering — ObjectStack-as-a-Service

‎content/docs/references/cloud/marketplace.mdx‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,7 @@ const result = ListingStatus.parse(data);
128128
| **licenseKey** | `string` | optional | License key for paid packages |
129129
| **settings** | `Record<string, any>` | optional | |
130130
| **enableOnInstall** | `boolean` | ✅ | |
131+
| **artifactRef** | `Object` | optional | Artifact reference for direct installation |
131132
| **tenantId** | `string` | optional | |
132133

133134

@@ -282,3 +283,37 @@ const result = ListingStatus.parse(data);
282283

283284
---
284285

286+
## ArtifactReference
287+
288+
Reference to a downloadable package artifact with integrity verification.
289+
290+
### Properties
291+
292+
| Property | Type | Required | Description |
293+
| :--- | :--- | :--- | :--- |
294+
| **url** | `string` | ✅ | Artifact download URL |
295+
| **sha256** | `string` | ✅ | SHA256 checksum |
296+
| **size** | `integer` | ✅ | Artifact size in bytes |
297+
| **format** | `Enum<'tgz' \| 'zip'>` | ✅ | Artifact format |
298+
| **uploadedAt** | `string` | ✅ | Upload timestamp |
299+
300+
301+
---
302+
303+
## ArtifactDownloadResponse
304+
305+
Response from the artifact download API endpoint.
306+
307+
### Properties
308+
309+
| Property | Type | Required | Description |
310+
| :--- | :--- | :--- | :--- |
311+
| **downloadUrl** | `string` | ✅ | Artifact download URL (may be pre-signed) |
312+
| **sha256** | `string` | ✅ | SHA256 checksum for verification |
313+
| **size** | `integer` | ✅ | Artifact size in bytes |
314+
| **format** | `Enum<'tgz' \| 'zip'>` | ✅ | Artifact format |
315+
| **expiresAt** | `string` | optional | URL expiration timestamp for pre-signed URLs |
316+
317+
318+
---
319+

‎content/docs/references/kernel/dependency-resolution.mdx‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: Dependency Resolution
3+
description: Dependency Resolution 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+
# Dependency Resolution Protocol
9+
10+
Defines schemas for runtime dependency resolution when installing,
11+
upgrading, or managing packages. Provides a standardized way to
12+
express dependency conflicts, resolution results, and installation order.
13+
14+
## Architecture Alignment
15+
16+
- **npm**: Dependency tree resolution with conflict detection
17+
- **Helm**: Dependency management with version constraints
18+
- **Salesforce**: Package dependency validation at install time
19+
20+
## Resolution Flow
21+
22+
```
23+
1. Parse manifest.dependencies (SemVer ranges)
24+
2. Check installed packages registry
25+
3. Resolve each dependency → satisfied | needs_install | needs_upgrade | conflict
26+
4. Detect circular dependencies
27+
5. Compute topological install order
28+
6. Return resolution result with required actions
29+
```
30+
31+
<Callout type="info">
32+
**Source:** `packages/spec/src/kernel/dependency-resolution.zod.ts`
33+
</Callout>
34+
35+
## TypeScript Usage
36+
37+
```typescript
38+
import { DependencyResolutionResultSchema, ResolvedDependencySchema } from '@objectstack/spec/kernel';
39+
import type { DependencyResolutionResult, ResolvedDependency } from '@objectstack/spec/kernel';
40+
41+
// Validate resolution result
42+
const result = DependencyResolutionResultSchema.parse(data);
43+
```
44+
45+
---
46+
47+
## DependencyStatus
48+
49+
### Allowed Values
50+
51+
* `satisfied` — Already installed and version compatible
52+
* `needs_install` — Not installed, needs to be installed
53+
* `needs_upgrade` — Installed but version incompatible, needs upgrade
54+
* `conflict` — Conflicts with another package's dependency
55+
56+
57+
---
58+
59+
## ResolvedDependency
60+
61+
### Properties
62+
63+
| Property | Type | Required | Description |
64+
| :--- | :--- | :--- | :--- |
65+
| **packageId** | `string` | ✅ | Dependency package identifier |
66+
| **requiredRange** | `string` | ✅ | SemVer range required (e.g. "^2.0.0") |
67+
| **resolvedVersion** | `string` | optional | Actual version resolved from registry |
68+
| **installedVersion** | `string` | optional | Currently installed version |
69+
| **status** | `Enum<'satisfied' \| 'needs_install' \| 'needs_upgrade' \| 'conflict'>` | ✅ | Resolution status |
70+
| **conflictReason** | `string` | optional | Explanation of the conflict |
71+
72+
73+
---
74+
75+
## RequiredAction
76+
77+
### Properties
78+
79+
| Property | Type | Required | Description |
80+
| :--- | :--- | :--- | :--- |
81+
| **type** | `Enum<'install' \| 'upgrade' \| 'confirm_conflict'>` | ✅ | Type of action required |
82+
| **packageId** | `string` | ✅ | Target package identifier |
83+
| **description** | `string` | ✅ | Human-readable action description |
84+
85+
86+
---
87+
88+
## DependencyResolutionResult
89+
90+
### Properties
91+
92+
| Property | Type | Required | Description |
93+
| :--- | :--- | :--- | :--- |
94+
| **dependencies** | `ResolvedDependency[]` | ✅ | Resolution result for each dependency |
95+
| **canProceed** | `boolean` | ✅ | Whether installation can proceed |
96+
| **requiredActions** | `RequiredAction[]` | ✅ | Actions required before proceeding |
97+
| **installOrder** | `string[]` | ✅ | Topologically sorted package IDs |
98+
| **circularDependencies** | `string[][]` | optional | Circular dependency chains detected |
99+
100+
101+
---

‎content/docs/references/kernel/manifest.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ const result = Manifest.parse(data);
7575
| **capabilities** | `Object` | optional | Plugin capability declarations for interoperability |
7676
| **extensions** | `Record<string, any>` | optional | Extension points and contributions |
7777
| **loading** | `Object` | optional | Plugin loading and runtime behavior configuration |
78+
| **engine** | `Object` | optional | Platform compatibility requirements |
7879

7980

8081
---

‎content/docs/references/kernel/meta.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
"pages": [
44
"cli-extension",
55
"context",
6+
"dependency-resolution",
67
"dev-plugin",
78
"execution-context",
89
"feature",
@@ -11,6 +12,7 @@
1112
"metadata-persistence",
1213
"metadata-plugin",
1314
"misc",
15+
"package-artifact",
1416
"package-registry",
1517
"package-upgrade",
1618
"permission",

‎content/docs/references/kernel/package-artifact.mdx‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: Package Artifact
3+
description: Package Artifact format 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+
# Package Artifact Format Protocol
9+
10+
Defines the standard structure of a package artifact (.tgz) produced by
11+
`os plugin build`. The marketplace uses these schemas to validate, store,
12+
and distribute package artifacts.
13+
14+
## Artifact Internal Structure
15+
16+
```
17+
├── manifest.json ← ManifestSchema serialized
18+
├── metadata/ ← 30+ metadata types (JSON)
19+
│ ├── objects/ ← *.object.json
20+
│ ├── views/ ← *.view.json
21+
│ ├── pages/ ← *.page.json
22+
│ ├── flows/ ← *.flow.json
23+
│ ├── dashboards/ ← *.dashboard.json
24+
│ ├── permissions/ ← *.permission.json
25+
│ ├── agents/ ← *.agent.json
26+
│ └── ... ← Other metadata types
27+
├── assets/ ← Static resources
28+
├── data/ ← Seed data (DatasetSchema serialized)
29+
├── locales/ ← i18n translation files
30+
├── checksums.json ← SHA256 checksum per file
31+
└── signature.sig ← RSA-SHA256 package signature
32+
```
33+
34+
## Architecture Alignment
35+
36+
- **Salesforce**: Managed Package .zip with metadata components
37+
- **npm**: .tgz with package.json + contents
38+
- **Helm**: Chart .tgz with Chart.yaml + templates
39+
- **VS Code**: .vsix (zip) with extension manifest + assets
40+
41+
<Callout type="info">
42+
**Source:** `packages/spec/src/kernel/package-artifact.zod.ts`
43+
</Callout>
44+
45+
## TypeScript Usage
46+
47+
```typescript
48+
import { PackageArtifactSchema, ArtifactChecksumSchema, ArtifactSignatureSchema } from '@objectstack/spec/kernel';
49+
import type { PackageArtifact, ArtifactChecksum, ArtifactSignature } from '@objectstack/spec/kernel';
50+
51+
// Validate artifact metadata
52+
const result = PackageArtifactSchema.parse(data);
53+
```
54+
55+
---
56+
57+
## PackageArtifact
58+
59+
### Properties
60+
61+
| Property | Type | Required | Description |
62+
| :--- | :--- | :--- | :--- |
63+
| **formatVersion** | `string` | ✅ | Artifact format version (e.g. "1.0") |
64+
| **packageId** | `string` | ✅ | Package identifier from manifest |
65+
| **version** | `string` | ✅ | Package version from manifest |
66+
| **format** | `Enum<'tgz' \| 'zip'>` | ✅ | Archive format of the artifact |
67+
| **size** | `integer` | optional | Total artifact file size in bytes |
68+
| **builtAt** | `string` | ✅ | ISO 8601 build timestamp |
69+
| **builtWith** | `string` | optional | Build tool identifier |
70+
| **files** | `Object[]` | optional | List of files in the artifact |
71+
| **metadataCategories** | `string[]` | optional | Metadata categories included |
72+
| **checksums** | `Object` | optional | SHA256 checksums for integrity |
73+
| **signature** | `Object` | optional | Digital signature for authenticity |
74+
75+
76+
---
77+
78+
## ArtifactChecksum
79+
80+
### Properties
81+
82+
| Property | Type | Required | Description |
83+
| :--- | :--- | :--- | :--- |
84+
| **algorithm** | `Enum<'sha256' \| 'sha384' \| 'sha512'>` | ✅ | Hash algorithm used |
85+
| **files** | `Record<string, string>` | ✅ | File path to hash value mapping |
86+
87+
88+
---
89+
90+
## ArtifactSignature
91+
92+
### Properties
93+
94+
| Property | Type | Required | Description |
95+
| :--- | :--- | :--- | :--- |
96+
| **algorithm** | `Enum<'RSA-SHA256' \| 'RSA-SHA384' \| 'RSA-SHA512' \| 'ECDSA-SHA256'>` | ✅ | Signing algorithm |
97+
| **publicKeyRef** | `string` | ✅ | Public key reference for verification |
98+
| **signature** | `string` | ✅ | Base64-encoded signature |
99+
| **signedAt** | `string` | optional | Signing timestamp |
100+
| **signedBy** | `string` | optional | Signer identity |
101+
102+
103+
---
104+
105+
## MetadataCategory
106+
107+
### Allowed Values
108+
109+
* `objects`
110+
* `views`
111+
* `pages`
112+
* `flows`
113+
* `dashboards`
114+
* `permissions`
115+
* `agents`
116+
* `reports`
117+
* `actions`
118+
* `translations`
119+
* `themes`
120+
* `datasets`
121+
* `apis`
122+
* `triggers`
123+
* `workflows`
124+
125+
126+
---

‎content/docs/references/kernel/package-registry.mdx‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,6 +128,7 @@ const result = DisablePackageRequest.parse(data);
128128
| **manifest** | `Object` | ✅ | |
129129
| **settings** | `Record<string, any>` | optional | |
130130
| **enableOnInstall** | `boolean` | ✅ | |
131+
| **platformVersion** | `string` | optional | Current platform version for compatibility verification |
131132

132133

133134
---
@@ -140,6 +141,7 @@ const result = DisablePackageRequest.parse(data);
140141
| :--- | :--- | :--- | :--- |
141142
| **package** | `Object` | ✅ | |
142143
| **message** | `string` | optional | |
144+
| **dependencyResolution** | `Object` | optional | Dependency resolution result from install analysis |
143145

144146

145147
---
@@ -160,6 +162,8 @@ const result = DisablePackageRequest.parse(data);
160162
| **statusChangedAt** | `string` | optional | |
161163
| **errorMessage** | `string` | optional | |
162164
| **settings** | `Record<string, any>` | optional | |
165+
| **upgradeHistory** | `Object[]` | optional | Version upgrade history |
166+
| **registeredNamespaces** | `string[]` | optional | Namespace prefixes registered by this package |
163167

164168

165169
---
@@ -227,3 +231,36 @@ const result = DisablePackageRequest.parse(data);
227231

228232
---
229233

234+
## NamespaceRegistryEntry
235+
236+
Tracks namespace ownership within the platform instance.
237+
238+
### Properties
239+
240+
| Property | Type | Required | Description |
241+
| :--- | :--- | :--- | :--- |
242+
| **namespace** | `string` | ✅ | Namespace prefix |
243+
| **packageId** | `string` | ✅ | Owning package ID |
244+
| **registeredAt** | `string` | ✅ | Registration timestamp |
245+
| **status** | `Enum<'active' \| 'disabled' \| 'reserved'>` | ✅ | Namespace status |
246+
247+
248+
---
249+
250+
## NamespaceConflictError
251+
252+
Describes a namespace collision detected during package installation.
253+
254+
### Properties
255+
256+
| Property | Type | Required | Description |
257+
| :--- | :--- | :--- | :--- |
258+
| **type** | `literal<'namespace_conflict'>` | ✅ | Error type |
259+
| **requestedNamespace** | `string` | ✅ | Requested namespace |
260+
| **conflictingPackageId** | `string` | ✅ | Conflicting package ID |
261+
| **conflictingPackageName** | `string` | ✅ | Conflicting package display name |
262+
| **suggestion** | `string` | optional | Suggested alternative namespace |
263+
264+
265+
---
266+

‎docs/ENTERPRISE_ASSESSMENT.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -681,7 +681,15 @@ Create src/ai/governance.zod.ts:
681681

682682
**Enhancement 1: Plugin Marketplace Protocol**
683683

684-
The `cloud/marketplace.zod.ts` exists but needs tighter integration with the kernel for **security review, compatibility checking, and auto-update**.
684+
The `cloud/marketplace.zod.ts` now includes `ArtifactReferenceSchema` and `ArtifactDownloadResponseSchema` for artifact storage and distribution. The kernel has been extended with:
685+
- `package-artifact.zod.ts` — Standard artifact format (.tgz) with checksums and digital signatures
686+
- `dependency-resolution.zod.ts` — Runtime dependency resolution with conflict detection and topological ordering
687+
- `ManifestSchema.engine` — Platform version compatibility requirements
688+
- `UpgradeContextSchema` — Version migration context for onUpgrade hooks
689+
- `NamespaceRegistryEntrySchema` / `NamespaceConflictErrorSchema` — Namespace collision detection
690+
- `InstalledPackageSchema.upgradeHistory` — Version upgrade tracking
691+
692+
Further integration needed for **auto-update orchestration and telemetry reporting**.
685693

686694
**Enhancement 2: Plugin Telemetry Protocol**
687695

0 commit comments

Comments
 (0)