@objectstack/cli 3.0.5 → 3.0.7

package/.turbo/turbo-build.log

@@ -1,28 +1,4 @@
 
-> @objectstack/cli@3.0.5 build /home/runner/work/spec/spec/packages/cli
-> tsup
+> @objectstack/cli@3.0.7 build /home/runner/work/spec/spec/packages/cli
+> tsc -p tsconfig.build.json
 
-CLI Building entry: src/bin.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/spec/spec/packages/cli/tsup.config.ts
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/spec/spec/packages/cli/tsup.config.ts
-CLI Target: es2022
-CLI Target: es2022
-ESM Build start
-CLI Cleaning output folder
-ESM Build start
-ESM dist/index.js           94.66 KB
-ESM dist/config-UN34WBHT.js 151.00 B
-ESM dist/chunk-CSHQEILI.js  7.29 KB
-ESM ⚡️ Build success in 186ms
-ESM dist/bin.js             131.47 KB
-ESM dist/config-A7BN6UIT.js 171.00 B
-ESM dist/chunk-Q74JNWKD.js  7.31 KB
-ESM ⚡️ Build success in 186ms
-DTS Build start
-DTS ⚡️ Build success in 14521ms
-DTS dist/index.d.ts 3.42 KB

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @objectstack/cli
 
+## 3.0.7
+
+### Patch Changes
+
+- Updated dependencies [0119bd7]
+- Updated dependencies [5426bdf]
+  - @objectstack/spec@3.0.7
+  - @objectstack/core@3.0.7
+  - @objectstack/objectql@3.0.7
+  - @objectstack/driver-memory@3.0.7
+  - @objectstack/plugin-hono-server@3.0.7
+  - @objectstack/rest@3.0.7
+  - @objectstack/runtime@3.0.7
+
+## 3.0.6
+
+### Patch Changes
+
+- Updated dependencies [5df254c]
+  - @objectstack/spec@3.0.6
+  - @objectstack/core@3.0.6
+  - @objectstack/objectql@3.0.6
+  - @objectstack/driver-memory@3.0.6
+  - @objectstack/plugin-hono-server@3.0.6
+  - @objectstack/rest@3.0.6
+  - @objectstack/runtime@3.0.6
+
 ## 3.0.5
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,8 @@
 
 Command Line Interface for building metadata-driven applications with the ObjectStack Protocol.
 
+Built on [oclif](https://oclif.io/) — commands are auto-discovered, and plugins can extend the CLI without modifying the main package.
+
 ## Installation
 
 ```bash
@@ -40,6 +42,7 @@ os compile
 | `os init [name]` | Initialize a new ObjectStack project in the current directory |
 | `os dev [package]` | Start development mode with hot reload |
 | `os serve [config]` | Start the ObjectStack server with plugin auto-detection |
+| `os studio [config]` | Launch Studio UI with development server |
 
 ### Build & Validate
 
@@ -73,6 +76,20 @@ Available generate types: `object`, `view`, `action`, `flow`, `agent`, `dashboar
 |---------|-------------|
 | `os test [files]` | Run Quality Protocol test scenarios against a running server |
 | `os doctor` | Check development environment health |
+| `os lint [config]` | Check configuration for style and convention issues |
+| `os diff [before] [after]` | Compare two configurations and detect breaking changes |
+
+### Reference
+
+| Command | Description |
+|---------|-------------|
+| `os explain [schema]` | Display human-readable explanation of an ObjectStack schema |
+
+### Code Transforms
+
+| Command | Description |
+|---------|-------------|
+| `os codemod v2-to-v3` | Migrate ObjectStack v2 config to v3 format |
 
 ## Configuration
 
@@ -120,12 +137,12 @@ export default defineStack({
 
 - `-p, --port <port>` — Server port (default: `3000`)
 - `--dev` — Run in development mode (load devPlugins, pretty logging)
+- `--ui` — Enable Studio UI
 - `--no-server` — Skip starting HTTP server plugin
 
 ### `os generate`
 
 - `-d, --dir <directory>` — Override target directory
-- `--dry-run` — Preview without writing files
 
 ### `os plugin list`
 
@@ -140,75 +157,78 @@ export default defineStack({
 
 - `-c, --config <path>` — Configuration file path
 
-## Plugin CLI Extensions
+### `os info`
+
+- `--json` — Output as JSON
 
-Plugins can extend the CLI with custom commands via the `contributes.commands` manifest field. The CLI automatically discovers and loads these commands at startup.
+### `os doctor`
 
-### How to Create a CLI Plugin
+- `-v, --verbose` — Show fix suggestions for warnings
+- `--scan-deprecations` — Scan for deprecated patterns
 
-**1. Declare commands in the plugin manifest:**
+## oclif Plugin System
 
-```typescript
-export default defineStack({
-  manifest: {
-    id: 'com.acme.marketplace',
-    version: '1.0.0',
-    type: 'plugin',
-    name: 'Marketplace Plugin',
-    contributes: {
-      commands: [
-        {
-          name: 'marketplace',
-          description: 'Manage marketplace applications',
-          module: './dist/cli.js',
-        },
-      ],
-    },
-  },
-});
+The CLI uses oclif's built-in plugin system for extensibility. Third-party plugins (e.g., cloud commands, marketplace tools) can extend the CLI without modifying the main package.
+
+### How Plugin Extension Works
+
+1. **Create an oclif plugin package** with its own `oclif` config in `package.json`
+2. **Export oclif Command classes** from the plugin's `src/commands/` directory
+3. **Install the plugin** via `os plugins install <package>` or declare it in the main CLI's `oclif.plugins`
+
+### Creating a CLI Plugin
+
+**1. Configure the plugin's `package.json`:**
+
+```json
+{
+  "name": "@acme/plugin-marketplace",
+  "oclif": {
+    "commands": {
+      "strategy": "pattern",
+      "target": "./dist/commands",
+      "glob": "**/*.js"
+    }
+  }
+}
 ```
 
-**2. Export Commander.js commands from the module:**
+**2. Create oclif Command classes:**
 
 ```typescript
-// src/cli.ts
-import { Command } from 'commander';
-
-const marketplaceCommand = new Command('marketplace')
-  .description('Manage marketplace applications')
-  .addCommand(
-    new Command('search')
-      .argument('<query>')
-      .action(async (query) => { /* ... */ })
-  )
-  .addCommand(
-    new Command('install')
-      .argument('<app>')
-      .action(async (app) => { /* ... */ })
-  );
-
-// Named export (recommended)
-export const commands = [marketplaceCommand];
-// Also supports: export default Command | Command[]
+// src/commands/marketplace/search.ts
+import { Args, Command, Flags } from '@oclif/core';
+
+export default class MarketplaceSearch extends Command {
+  static override description = 'Search marketplace applications';
+
+  static override args = {
+    query: Args.string({ description: 'Search query', required: true }),
+  };
+
+  async run() {
+    const { args } = await this.parse(MarketplaceSearch);
+    // Implementation...
+  }
+}
 ```
 
-**3. Register the plugin in the host project and use:**
+**3. Install and use:**
 
 ```bash
-os plugin add @acme/plugin-marketplace
+os plugins install @acme/plugin-marketplace
 os marketplace search "crm"
-os marketplace install com.acme.crm
 ```
 
-For a complete guide, see the [Plugin CLI Extensions](/docs/guides/plugins#cli-command-extensions) section in the Plugins guide.
+### Key Differences from Previous Plugin Model
 
-### `os info`
-
-- `--json` — Output as JSON
-
-### `os doctor`
-
-- `-v, --verbose` — Show fix suggestions for warnings
+| Before (Commander.js) | After (oclif) |
+|---|---|
+| Plugins declared in `objectstack.config.ts` | Plugins installed via `os plugins install` or `oclif.plugins` |
+| Custom `loadPluginCommands` mechanism | oclif's built-in plugin discovery |
+| `contributes.commands` in manifest | `oclif.commands` in `package.json` |
+| Commander.js `new Command(...)` exports | oclif `class extends Command` exports |
+| Project config determines CLI commands | CLI commands available without project init |
 
 ## Typical Workflow
 
@@ -223,6 +243,30 @@ os dev                           # 7. Start dev server
 os compile                       # 8. Build for production
 ```
 
+## Architecture
+
+```
+@objectstack/cli (oclif)
+├── bin/run.js                  # Entry point (os / objectstack)
+├── src/commands/               # Auto-discovered command classes
+│   ├── init.ts                 # os init
+│   ├── dev.ts                  # os dev
+│   ├── serve.ts                # os serve
+│   ├── compile.ts              # os compile
+│   ├── validate.ts             # os validate
+│   ├── generate.ts             # os generate (alias: g)
+│   ├── plugin/                 # os plugin <subcommand>
+│   │   ├── list.ts
+│   │   ├── info.ts
+│   │   ├── add.ts
+│   │   └── remove.ts
+│   ├── codemod/                # os codemod <subcommand>
+│   │   └── v2-to-v3.ts
+│   └── ...
+├── src/utils/                  # Shared utilities
+└── package.json                # oclif config under "oclif" key
+```
+
 ## License
 
 Apache-2.0

package/bin/run-dev.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env tsx
+
+import { execute } from '@oclif/core';
+
+await execute({ type: 'esm', development: true, dir: import.meta.url });

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { execute } from '@oclif/core';
+
+await execute({ type: 'esm', dir: import.meta.url });

package/dist/bin.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ObjectStack CLI — oclif-based entry point.
+ *
+ * All commands are auto-discovered from `src/commands/` by oclif.
+ * Plugins extend the CLI via oclif's built-in plugin system
+ * (configured in package.json under "oclif.plugins").
+ *
+ * Run `os --help` for available commands.
+ */
+export { execute } from '@oclif/core';
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC"}