Merge pull request #607 from objectstack-ai/copilot/add-cli-command-plugin

Author: hotlong

content/docs/guides/plugins.mdx

@@ -465,6 +465,243 @@ const slowPlugin: PluginMetadata = {
 };
 ```
 
+### CLI Command Extensions
+
+Plugins can extend the ObjectStack CLI (`os`) with custom commands. This enables third-party packages — such as marketplace tools, deployment utilities, or domain-specific workflows — to register new top-level subcommands.
+
+#### How It Works
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                     os (CLI)                             │
+│  ┌────────────┐ ┌────────────┐ ┌─────────────────────┐  │
+│  │ Built-in   │ │ Built-in   │ │  Plugin Commands    │  │
+│  │ init, dev  │ │ plugin,    │ │  marketplace,       │  │
+│  │ compile .. │ │ generate   │ │  deploy, ...        │  │
+│  └────────────┘ └────────────┘ └─────────────────────┘  │
+│                                       ▲                  │
+│                                       │                  │
+│                    loadPluginCommands()                   │
+│                    reads objectstack.config.ts            │
+│                    discovers contributes.commands         │
+│                    dynamically imports modules            │
+└──────────────────────────────────────────────────────────┘
+```
+
+1. The plugin declares `contributes.commands` in its manifest.
+2. The CLI scans installed plugins at startup via `loadPluginCommands()`.
+3. Each plugin module is dynamically imported and its exported Commander.js `Command` instances are registered.
+
+#### Step 1: Declare Commands in the Manifest
+
+Add a `contributes.commands` section to the plugin's manifest:
+
+```typescript
+// objectstack.config.ts (plugin package)
+import { defineStack } from '@objectstack/spec';
+
+export default defineStack({
+  manifest: {
+    id: 'com.acme.marketplace',
+    namespace: 'marketplace',
+    version: '1.0.0',
+    type: 'plugin',
+    name: 'Marketplace Plugin',
+    contributes: {
+      commands: [
+        {
+          name: 'marketplace',
+          description: 'Manage marketplace applications',
+          module: './dist/cli.js',  // optional, defaults to package main
+        },
+      ],
+    },
+  },
+});
+```
+
+Each command entry has:
+
+| Property | Type | Required | Description |
+|:---------|:-----|:---------|:------------|
+| `name` | `string` | ✅ | CLI command name (lowercase, hyphens allowed) |
+| `description` | `string` | optional | Help text shown in `os --help` |
+| `module` | `string` | optional | Module path exporting Commander.js commands |
+
+#### Step 2: Implement the CLI Module
+
+Create a module that exports Commander.js `Command` instances. The CLI supports three export forms:
+
+```typescript
+// src/cli.ts
+import { Command } from 'commander';
+
+// ── Subcommands ──────────────────────────────────────────
+
+const publishCommand = new Command('publish')
+  .description('Publish an app to the marketplace')
+  .argument('<package>', 'Package to publish')
+  .option('--public', 'Make publicly visible')
+  .action(async (pkg: string, options: { public?: boolean }) => {
+    console.log(`Publishing ${pkg}...`);
+    // ... publish logic
+  });
+
+const searchCommand = new Command('search')
+  .description('Search marketplace apps')
+  .argument('<query>', 'Search query')
+  .option('-l, --limit <n>', 'Max results', '10')
+  .action(async (query: string, options: { limit: string }) => {
+    console.log(`Searching for "${query}"...`);
+    // ... search logic
+  });
+
+const installCommand = new Command('install')
+  .description('Install an app from the marketplace')
+  .argument('<app>', 'App identifier')
+  .action(async (app: string) => {
+    console.log(`Installing ${app}...`);
+    // ... install logic
+  });
+
+// ── Main Command ─────────────────────────────────────────
+
+const marketplaceCommand = new Command('marketplace')
+  .description('Manage marketplace applications')
+  .addCommand(publishCommand)
+  .addCommand(searchCommand)
+  .addCommand(installCommand);
+
+// Export as named array (recommended)
+export const commands = [marketplaceCommand];
+
+// Alternative: export default (single command or array)
+// export default marketplaceCommand;
+// export default [marketplaceCommand, anotherCommand];
+```
+
+#### Step 3: Register the Plugin
+
+Add the plugin to the host project's `objectstack.config.ts`:
+
+```typescript
+// Host project objectstack.config.ts
+import { defineStack } from '@objectstack/spec';
+import marketplacePlugin from '@acme/plugin-marketplace';
+
+export default defineStack({
+  manifest: {
+    id: 'com.example.my-app',
+    version: '1.0.0',
+    type: 'app',
+    name: 'My App',
+  },
+  plugins: [
+    marketplacePlugin,
+  ],
+});
+```
+
+Or use the CLI to add it:
+
+```bash
+os plugin add @acme/plugin-marketplace
+pnpm add @acme/plugin-marketplace
+```
+
+#### Using the Extended CLI
+
+Once installed, the new commands appear in `os --help` and can be invoked directly:
+
+```bash
+# List available commands (includes plugin commands)
+os --help
+
+# Use marketplace commands
+os marketplace search "crm"
+os marketplace install com.acme.crm
+os marketplace publish ./dist --public
+```
+
+#### Complete Example: Deployment Plugin
+
+Here's a full example of a deployment CLI plugin:
+
+```typescript
+// @acme/plugin-deploy/src/cli.ts
+import { Command } from 'commander';
+
+const deployCommand = new Command('deploy')
+  .description('Deploy ObjectStack app to cloud')
+  .addCommand(
+    new Command('staging')
+      .description('Deploy to staging environment')
+      .option('--skip-tests', 'Skip pre-deploy tests')
+      .action(async (options) => {
+        console.log('Deploying to staging...');
+        if (!options.skipTests) {
+          console.log('Running tests first...');
+        }
+        // deploy logic
+      })
+  )
+  .addCommand(
+    new Command('production')
+      .description('Deploy to production')
+      .option('--confirm', 'Skip confirmation prompt')
+      .action(async (options) => {
+        if (!options.confirm) {
+          // prompt for confirmation
+        }
+        console.log('Deploying to production...');
+      })
+  )
+  .addCommand(
+    new Command('status')
+      .description('Check deployment status')
+      .action(async () => {
+        console.log('Checking deployment status...');
+      })
+  );
+
+export const commands = [deployCommand];
+```
+
+```typescript
+// @acme/plugin-deploy/objectstack.config.ts
+import { defineStack } from '@objectstack/spec';
+
+export default defineStack({
+  manifest: {
+    id: 'com.acme.deploy',
+    version: '1.0.0',
+    type: 'plugin',
+    name: 'Deploy Plugin',
+    contributes: {
+      commands: [
+        {
+          name: 'deploy',
+          description: 'Deploy ObjectStack app to cloud',
+          module: './dist/cli.js',
+        },
+      ],
+    },
+  },
+});
+```
+
+Usage:
+
+```bash
+os deploy staging --skip-tests
+os deploy production --confirm
+os deploy status
+```
+
+<Callout type="info">
+**Graceful Degradation**: If a plugin command fails to load (e.g., missing dependency), the CLI logs a warning in `DEBUG` mode and continues with built-in commands. Plugin commands never block the CLI.
+</Callout>
+
 ---
 
 ## Directory Structure Convention
@@ -480,6 +717,7 @@ plugin-my-feature/
 ├── CHANGELOG.md
 └── src/
     ├── index.ts               # Entry point (required)
+    ├── cli.ts                 # CLI commands (optional, for contributes.commands)
     ├── my_feature/             # Domain folder (snake_case)
     │   ├── feature.object.ts   # Business object
     │   ├── feature.view.ts     # View definition

content/docs/references/api/index.mdx

@@ -23,6 +23,7 @@ This section contains all protocol schemas for the api layer of ObjectStack.
   <Card href="/docs/references/api/plugin-rest-api" title="Plugin Rest Api" description="Source: packages/spec/src/api/plugin-rest-api.zod.ts" />
   <Card href="/docs/references/api/protocol" title="Protocol" description="Source: packages/spec/src/api/protocol.zod.ts" />
   <Card href="/docs/references/api/realtime" title="Realtime" description="Source: packages/spec/src/api/realtime.zod.ts" />
+  <Card href="/docs/references/api/realtime-shared" title="Realtime Shared" description="Source: packages/spec/src/api/realtime-shared.zod.ts" />
   <Card href="/docs/references/api/registry" title="Registry" description="Source: packages/spec/src/api/registry.zod.ts" />
   <Card href="/docs/references/api/rest-server" title="Rest Server" description="Source: packages/spec/src/api/rest-server.zod.ts" />
   <Card href="/docs/references/api/router" title="Router" description="Source: packages/spec/src/api/router.zod.ts" />

content/docs/references/api/meta.json

@@ -22,6 +22,7 @@
     "plugin-rest-api",
     "protocol",
     "realtime",
+    "realtime-shared",
     "registry",
     "rest-server",
     "router",

content/docs/references/api/realtime-shared.mdx

@@ -0,0 +1,78 @@
+---
+title: Realtime Shared
+description: Realtime Shared protocol schemas
+---
+
+Realtime Shared Protocol
+
+Shared schemas and types for real-time communication protocols.
+
+This module consolidates overlapping definitions between the transport-level
+
+realtime protocol (SSE/Polling/WebSocket) and the WebSocket collaboration protocol.
+
+**Architecture:**
+
+- `realtime-shared.zod.ts` — Shared base schemas (Presence, Event types)
+
+- `realtime.zod.ts` — Transport-layer protocol (Channel, Subscription, Transport selection)
+
+- `websocket.zod.ts` — Collaboration protocol (Cursor, OT editing, Advanced presence)
+
+@see realtime.zod.ts for transport-layer configuration
+
+@see websocket.zod.ts for collaborative editing protocol
+
+<Callout type="info">
+**Source:** `packages/spec/src/api/realtime-shared.zod.ts`
+</Callout>
+
+## TypeScript Usage
+
+```typescript
+import { BasePresence, PresenceStatus, RealtimeRecordAction } from '@objectstack/spec/api';
+import type { BasePresence, PresenceStatus, RealtimeRecordAction } from '@objectstack/spec/api';
+
+// Validate data
+const result = BasePresence.parse(data);
+```
+
+---
+
+## BasePresence
+
+### Properties
+
+| Property | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| **userId** | `string` | ✅ | User identifier |
+| **status** | `Enum<'online' \| 'away' \| 'busy' \| 'offline'>` | ✅ | Current presence status |
+| **lastSeen** | `string` | ✅ | ISO 8601 datetime of last activity |
+| **metadata** | `Record<string, any>` | optional | Custom presence data (e.g., current page, custom status) |
+
+
+---
+
+## PresenceStatus
+
+### Allowed Values
+
+* `online`
+* `away`
+* `busy`
+* `offline`
+
+
+---
+
+## RealtimeRecordAction
+
+### Allowed Values
+
+* `created`
+* `updated`
+* `deleted`
+
+
+---
+