Add .describe() to all marketplace lifecycle protocol schemas and update ROADMAP

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

ROADMAP.md

@@ -697,6 +697,18 @@ Final polish and advanced features.
 - [x] Namespace collision detection — registry entries, conflict errors
 - [x] Upgrade migration context — version context for onUpgrade hooks, upgrade history
 - [ ] Plugin marketplace runtime — publish, discover, install community plugins
+  - [ ] CLI: `os plugin build` — generate `.tgz` per PackageArtifactSchema
+  - [ ] CLI: `os plugin validate` — verify artifact structure, checksums, signatures
+  - [ ] CLI: `os plugin publish` — upload artifact to marketplace REST API
+  - [ ] Runtime: package dependency resolution & platform compatibility enforcement
+  - [ ] Runtime: namespace conflict detection at install time
+  - [ ] Runtime: package upgrade lifecycle — plan, snapshot, execute, validate, rollback
+  - [ ] API: `/api/v1/packages/install` — install with dependency & namespace checks
+  - [ ] API: `/api/v1/packages/upgrade` — upgrade with plan, rollback support
+  - [ ] API: `/api/v1/packages/resolve-dependencies` — topological sort & conflict detection
+  - [ ] API: `/api/v1/packages/upload` — artifact upload & validation
+  - [ ] Studio: marketplace browse/search, install, upgrade, uninstall UI
+  - [ ] Cloud: artifact storage, distribution, SHA256 verification, security scanning
 - [ ] App store — pre-built applications (CRM, HRM, Project Management)
 - [ ] Developer portal — API keys, usage metrics, billing
 - [ ] Managed cloud offering — ObjectStack-as-a-Service

packages/spec/src/cloud/marketplace.zod.ts

@@ -51,7 +51,7 @@ export const PublisherVerificationSchema = z.enum([
   'verified',    // Identity verified by platform
   'trusted',     // Trusted publisher (track record of quality)
   'partner',     // Official platform partner
-]);
+]).describe('Publisher verification status');
 
 /**
  * Publisher Schema
@@ -68,7 +68,8 @@ export const PublisherSchema = z.object({
   type: z.enum(['individual', 'organization']).describe('Publisher type'),
 
   /** Verification status */
-  verification: PublisherVerificationSchema.default('unverified'),
+  verification: PublisherVerificationSchema.default('unverified')
+    .describe('Publisher verification status'),
 
   /** Contact email */
   email: z.string().email().optional().describe('Contact email'),
@@ -83,7 +84,8 @@ export const PublisherSchema = z.object({
   description: z.string().optional().describe('Publisher description'),
 
   /** Registration date */
-  registeredAt: z.string().datetime().optional(),
+  registeredAt: z.string().datetime().optional()
+    .describe('Publisher registration timestamp'),
 });
 
 // ==========================================
@@ -164,7 +166,7 @@ export const MarketplaceCategorySchema = z.enum([
   'ui-theme',        // UI Themes & Appearance
   'storage',         // Storage & Drivers
   'other',           // Other / Uncategorized
-]);
+]).describe('Marketplace package category');
 
 /**
  * Listing Status
@@ -179,7 +181,7 @@ export const ListingStatusSchema = z.enum([
   'suspended',       // Suspended by platform (policy violation)
   'deprecated',      // Deprecated by publisher
   'unlisted',        // Available by direct link only
-]);
+]).describe('Marketplace listing status');
 
 /**
  * Pricing Model
@@ -191,7 +193,7 @@ export const PricingModelSchema = z.enum([
   'subscription',    // Recurring subscription
   'usage-based',     // Pay per usage
   'contact-sales',   // Enterprise pricing, contact for quote
-]);
+]).describe('Package pricing model');
 
 /**
  * Marketplace Listing Schema
@@ -210,7 +212,8 @@ export const MarketplaceListingSchema = z.object({
   publisherId: z.string().describe('Publisher ID'),
 
   /** Current listing status */
-  status: ListingStatusSchema.default('draft'),
+  status: ListingStatusSchema.default('draft')
+    .describe('Current listing status'),
 
   /** Display name */
   name: z.string().describe('Display name'),
@@ -237,16 +240,20 @@ export const MarketplaceListingSchema = z.object({
   })).optional().describe('Screenshots'),
 
   /** Documentation URL */
-  documentationUrl: z.string().url().optional(),
+  documentationUrl: z.string().url().optional()
+    .describe('Documentation URL'),
 
   /** Support URL */
-  supportUrl: z.string().url().optional(),
+  supportUrl: z.string().url().optional()
+    .describe('Support URL'),
 
   /** Source repository URL (if open source) */
-  repositoryUrl: z.string().url().optional(),
+  repositoryUrl: z.string().url().optional()
+    .describe('Source repository URL'),
 
   /** Pricing model */
-  pricing: PricingModelSchema.default('free'),
+  pricing: PricingModelSchema.default('free')
+    .describe('Pricing model'),
 
   /** Price in cents (if paid) */
   priceInCents: z.number().int().min(0).optional()

packages/spec/src/kernel/package-registry.zod.ts

@@ -40,7 +40,7 @@ export const PackageStatusEnum = z.enum([
   'upgrading',     // Upgrade in progress
   'uninstalling',  // Removal in progress
   'error',         // Installation or runtime error
-]);
+]).describe('Package installation status');
 export type PackageStatus = z.infer<typeof PackageStatusEnum>;
 
 /**
@@ -53,28 +53,32 @@ export const InstalledPackageSchema = z.object({
   /** 
    * The full package manifest (source of truth for package definition).
    */
-  manifest: ManifestSchema,
+  manifest: ManifestSchema.describe('Full package manifest'),
 
   /**
    * Current lifecycle status.
    */
-  status: PackageStatusEnum.default('installed'),
+  status: PackageStatusEnum.default('installed')
+    .describe('Current lifecycle status'),
 
   /**
    * Whether the package is currently enabled (active).
    * When disabled, the package's metadata is not loaded into the registry.
    */
-  enabled: z.boolean().default(true),
+  enabled: z.boolean().default(true)
+    .describe('Whether the package is currently enabled'),
 
   /**
    * ISO 8601 timestamp of when the package was installed.
    */
-  installedAt: z.string().datetime().optional(),
+  installedAt: z.string().datetime().optional()
+    .describe('Installation timestamp'),
 
   /**
    * ISO 8601 timestamp of last update.
    */
-  updatedAt: z.string().datetime().optional(),
+  updatedAt: z.string().datetime().optional()
+    .describe('Last update timestamp'),
 
   /**
    * The currently installed version string.
@@ -93,18 +97,21 @@ export const InstalledPackageSchema = z.object({
   /**
    * ISO 8601 timestamp of when the package was last enabled/disabled.
    */
-  statusChangedAt: z.string().datetime().optional(),
+  statusChangedAt: z.string().datetime().optional()
+    .describe('Status change timestamp'),
 
   /**
    * Error message if status is 'error'.
    */
-  errorMessage: z.string().optional(),
+  errorMessage: z.string().optional()
+    .describe('Error message when status is error'),
 
   /**
    * Configuration values set by the user for this package.
    * Keys correspond to the package's `configuration.properties`.
    */
-  settings: z.record(z.string(), z.unknown()).optional(),
+  settings: z.record(z.string(), z.unknown()).optional()
+    .describe('User-provided configuration settings'),
 
   /**
    * Upgrade history for this package.
@@ -190,38 +197,38 @@ export type NamespaceConflictError = z.infer<typeof NamespaceConflictErrorSchema
  */
 export const ListPackagesRequestSchema = z.object({
   /** Filter by status */
-  status: PackageStatusEnum.optional(),
+  status: PackageStatusEnum.optional().describe('Filter by package status'),
   /** Filter by package type */
-  type: ManifestSchema.shape.type.optional(),
+  type: ManifestSchema.shape.type.optional().describe('Filter by package type'),
   /** Filter by enabled state */
-  enabled: z.boolean().optional(),
-});
+  enabled: z.boolean().optional().describe('Filter by enabled state'),
+}).describe('List packages request');
 export type ListPackagesRequest = z.infer<typeof ListPackagesRequestSchema>;
 
 /**
  * List Packages Response
  */
 export const ListPackagesResponseSchema = z.object({
-  packages: z.array(InstalledPackageSchema),
-  total: z.number(),
-});
+  packages: z.array(InstalledPackageSchema).describe('List of installed packages'),
+  total: z.number().describe('Total package count'),
+}).describe('List packages response');
 export type ListPackagesResponse = z.infer<typeof ListPackagesResponseSchema>;
 
 /**
  * Get Package Request
  */
 export const GetPackageRequestSchema = z.object({
   /** Package ID (reverse domain identifier from manifest) */
-  id: z.string(),
-});
+  id: z.string().describe('Package identifier'),
+}).describe('Get package request');
 export type GetPackageRequest = z.infer<typeof GetPackageRequestSchema>;
 
 /**
  * Get Package Response
  */
 export const GetPackageResponseSchema = z.object({
-  package: InstalledPackageSchema,
-});
+  package: InstalledPackageSchema.describe('Package details'),
+}).describe('Get package response');
 export type GetPackageResponse = z.infer<typeof GetPackageResponseSchema>;
 
 /**
@@ -232,11 +239,13 @@ export type GetPackageResponse = z.infer<typeof GetPackageResponseSchema>;
  */
 export const InstallPackageRequestSchema = z.object({
   /** The package manifest to install */
-  manifest: ManifestSchema,
+  manifest: ManifestSchema.describe('Package manifest to install'),
   /** Optional: user-provided settings at install time */
-  settings: z.record(z.string(), z.unknown()).optional(),
+  settings: z.record(z.string(), z.unknown()).optional()
+    .describe('User-provided settings at install time'),
   /** Whether to enable immediately after install (default: true) */
-  enableOnInstall: z.boolean().default(true),
+  enableOnInstall: z.boolean().default(true)
+    .describe('Whether to enable immediately after install'),
   /**
    * Current platform version for compatibility checking.
    * When provided, the system compares this against the package's
@@ -251,8 +260,8 @@ export type InstallPackageRequest = z.infer<typeof InstallPackageRequestSchema>;
  * Install Package Response
  */
 export const InstallPackageResponseSchema = z.object({
-  package: InstalledPackageSchema,
-  message: z.string().optional(),
+  package: InstalledPackageSchema.describe('Installed package details'),
+  message: z.string().optional().describe('Installation status message'),
   /** Dependency resolution result (when dependencies were analyzed) */
   dependencyResolution: DependencyResolutionResultSchema.optional()
     .describe('Dependency resolution result from install analysis'),
@@ -264,52 +273,52 @@ export type InstallPackageResponse = z.infer<typeof InstallPackageResponseSchema
  */
 export const UninstallPackageRequestSchema = z.object({
   /** Package ID to uninstall */
-  id: z.string(),
-});
+  id: z.string().describe('Package ID to uninstall'),
+}).describe('Uninstall package request');
 export type UninstallPackageRequest = z.infer<typeof UninstallPackageRequestSchema>;
 
 /**
  * Uninstall Package Response
  */
 export const UninstallPackageResponseSchema = z.object({
-  id: z.string(),
-  success: z.boolean(),
-  message: z.string().optional(),
-});
+  id: z.string().describe('Uninstalled package ID'),
+  success: z.boolean().describe('Whether uninstall succeeded'),
+  message: z.string().optional().describe('Uninstall status message'),
+}).describe('Uninstall package response');
 export type UninstallPackageResponse = z.infer<typeof UninstallPackageResponseSchema>;
 
 /**
  * Enable Package Request
  */
 export const EnablePackageRequestSchema = z.object({
   /** Package ID to enable */
-  id: z.string(),
-});
+  id: z.string().describe('Package ID to enable'),
+}).describe('Enable package request');
 export type EnablePackageRequest = z.infer<typeof EnablePackageRequestSchema>;
 
 /**
  * Enable Package Response
  */
 export const EnablePackageResponseSchema = z.object({
-  package: InstalledPackageSchema,
-  message: z.string().optional(),
-});
+  package: InstalledPackageSchema.describe('Enabled package details'),
+  message: z.string().optional().describe('Enable status message'),
+}).describe('Enable package response');
 export type EnablePackageResponse = z.infer<typeof EnablePackageResponseSchema>;
 
 /**
  * Disable Package Request
  */
 export const DisablePackageRequestSchema = z.object({
   /** Package ID to disable */
-  id: z.string(),
-});
+  id: z.string().describe('Package ID to disable'),
+}).describe('Disable package request');
 export type DisablePackageRequest = z.infer<typeof DisablePackageRequestSchema>;
 
 /**
  * Disable Package Response
  */
 export const DisablePackageResponseSchema = z.object({
-  package: InstalledPackageSchema,
-  message: z.string().optional(),
-});
+  package: InstalledPackageSchema.describe('Disabled package details'),
+  message: z.string().optional().describe('Disable status message'),
+}).describe('Disable package response');
 export type DisablePackageResponse = z.infer<typeof DisablePackageResponseSchema>;

packages/spec/src/kernel/package-upgrade.zod.ts

@@ -40,7 +40,7 @@ export const MetadataChangeTypeSchema = z.enum([
   'modified', // Existing metadata item modified
   'removed',  // Metadata item removed in new version
   'renamed',  // Metadata item renamed
-]);
+]).describe('Type of metadata change between package versions');
 
 /**
  * Metadata Diff Item
@@ -54,7 +54,7 @@ export const MetadataDiffItemSchema = z.object({
   name: z.string().describe('Metadata name'),
 
   /** Type of change */
-  changeType: MetadataChangeTypeSchema,
+  changeType: MetadataChangeTypeSchema.describe('Type of change'),
 
   /** Whether this change has potential conflicts with customizations */
   hasConflict: z.boolean().default(false)
@@ -77,7 +77,7 @@ export const UpgradeImpactLevelSchema = z.enum([
   'medium',   // Some changes that may affect workflows
   'high',     // Significant changes, user review recommended
   'critical', // Breaking changes, manual intervention required
-]);
+]).describe('Severity of upgrade impact');
 
 /**
  * Upgrade Plan Schema
@@ -95,7 +95,7 @@ export const UpgradePlanSchema = z.object({
   toVersion: z.string().describe('Target upgrade version'),
 
   /** Overall impact level */
-  impactLevel: UpgradeImpactLevelSchema,
+  impactLevel: UpgradeImpactLevelSchema.describe('Overall upgrade impact level'),
 
   /** List of all metadata changes between versions */
   changes: z.array(MetadataDiffItemSchema).describe('All metadata changes'),
@@ -229,7 +229,7 @@ export const UpgradePhaseSchema = z.enum([
   'failed',      // Upgrade failed
   'rolling-back', // Rollback in progress
   'rolled-back', // Rollback completed
-]);
+]).describe('Current phase of the upgrade process');
 
 /**
  * Upgrade Package Response