@objectstack/cli 3.0.6 → 3.0.8

package/dist/utils/studio.js

@@ -0,0 +1,288 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Studio UI Integration Utilities
+ *
+ * Handles resolving, spawning, and proxying the @objectstack/studio
+ * frontend when the CLI is started with --ui or via the `studio` command.
+ */
+import path from 'path';
+import fs from 'fs';
+import net from 'net';
+import { createRequire } from 'module';
+import { pathToFileURL } from 'url';
+import { spawn } from 'child_process';
+// ─── Constants ──────────────────────────────────────────────────────
+/** URL mount path for the Console UI inside the ObjectStack server */
+export const STUDIO_PATH = '/_studio';
+/** Internal port range start for the Vite dev server */
+const VITE_PORT_START = 24678;
+// ─── Path Resolution ────────────────────────────────────────────────
+/**
+ * Resolve the filesystem path to the @objectstack/studio package.
+ * Searches workspace locations first, then falls back to node_modules.
+ */
+export function resolveStudioPath() {
+    const cwd = process.cwd();
+    // Workspace candidates (monorepo layouts)
+    const candidates = [
+        path.resolve(cwd, 'apps/studio'),
+        path.resolve(cwd, '../../apps/studio'),
+        path.resolve(cwd, '../apps/studio'),
+    ];
+    for (const candidate of candidates) {
+        const pkgPath = path.join(candidate, 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                if (pkg.name === '@objectstack/studio')
+                    return candidate;
+            }
+            catch {
+                // Skip invalid package.json
+            }
+        }
+    }
+    // Fallback: resolve from node_modules via createRequire.
+    // Try the consumer's cwd first (pnpm strict isolation means the CLI's own
+    // import.meta.url cannot see the consumer's dependencies), then the CLI itself.
+    const resolutionBases = [
+        pathToFileURL(path.join(cwd, 'package.json')).href, // consumer workspace
+        import.meta.url, // CLI package itself
+    ];
+    for (const base of resolutionBases) {
+        try {
+            const req = createRequire(base);
+            const resolved = req.resolve('@objectstack/studio/package.json');
+            return path.dirname(resolved);
+        }
+        catch {
+            // Not resolvable from this base — try next
+        }
+    }
+    // Last resort: direct filesystem check in cwd/node_modules
+    const directPath = path.join(cwd, 'node_modules', '@objectstack', 'studio');
+    if (fs.existsSync(path.join(directPath, 'package.json'))) {
+        return directPath;
+    }
+    return null;
+}
+/**
+ * Check whether the Studio has a pre-built `dist/` directory.
+ */
+export function hasStudioDist(studioPath) {
+    return fs.existsSync(path.join(studioPath, 'dist', 'index.html'));
+}
+// ─── Port Utilities ─────────────────────────────────────────────────
+/**
+ * Find the next available TCP port starting from `start`.
+ */
+export function findAvailablePort(start = VITE_PORT_START) {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once('error', () => {
+            // Port in use — try next
+            findAvailablePort(start + 1).then(resolve, reject);
+        });
+        server.once('listening', () => {
+            server.close(() => resolve(start));
+        });
+        server.listen(start);
+    });
+}
+/**
+ * Spawn a Vite dev server for the Console application.
+ *
+ * Sets environment variables so the Console runs in server mode and
+ * connects to the ObjectStack API on the same origin.
+ *
+ * @param studioPath - Absolute path to the @objectstack/studio package
+ * @param options.serverPort - The main ObjectStack server port (for display only)
+ */
+export async function spawnViteDevServer(studioPath, options = {}) {
+    const vitePort = await findAvailablePort(VITE_PORT_START);
+    // Resolve the Vite binary from the Studio's own dependencies
+    const viteBinCandidates = [
+        path.join(studioPath, 'node_modules', '.bin', 'vite'),
+        path.join(studioPath, '..', '..', 'node_modules', '.bin', 'vite'),
+    ];
+    let viteBin = null;
+    for (const candidate of viteBinCandidates) {
+        if (fs.existsSync(candidate)) {
+            viteBin = candidate;
+            break;
+        }
+    }
+    const command = viteBin || 'npx';
+    const args = viteBin
+        ? ['--port', String(vitePort), '--strictPort']
+        : ['vite', '--port', String(vitePort), '--strictPort'];
+    const child = spawn(command, args, {
+        cwd: studioPath,
+        env: {
+            ...process.env,
+            VITE_BASE: `${STUDIO_PATH}/`,
+            VITE_PORT: String(vitePort),
+            VITE_HMR_PORT: String(vitePort),
+            VITE_RUNTIME_MODE: 'server',
+            VITE_SERVER_URL: '', // Same-origin API
+            NODE_ENV: 'development',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // Accumulate stderr for error reporting
+    let stderr = '';
+    child.stderr?.on('data', (data) => {
+        stderr += data.toString();
+    });
+    // Wait for Vite to signal readiness
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Vite dev server timed out after 30 s.\n${stderr}`));
+        }, 30_000);
+        child.stdout?.on('data', (data) => {
+            const output = data.toString();
+            // Vite prints "ready in Xms" or "Local: http://..." when ready
+            if (output.includes('Local:') || output.includes('ready in')) {
+                clearTimeout(timeout);
+                resolve();
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+        child.on('exit', (code) => {
+            if (code !== 0 && code !== null) {
+                clearTimeout(timeout);
+                reject(new Error(`Vite exited with code ${code}.\n${stderr}`));
+            }
+        });
+    });
+    return { port: vitePort, process: child };
+}
+// ─── Console Plugin Factories ───────────────────────────────────────
+/**
+ * Create a lightweight kernel plugin that proxies `/_studio/*` requests
+ * to the Vite dev server. Used in development mode.
+ */
+export function createStudioProxyPlugin(vitePort) {
+    return {
+        name: 'com.objectstack.studio-proxy',
+        init: async () => { },
+        start: async (ctx) => {
+            const httpServer = ctx.getService?.('http.server');
+            if (!httpServer?.getRawApp) {
+                ctx.logger?.warn?.('Studio proxy: http.server service not found — skipping');
+                return;
+            }
+            const app = httpServer.getRawApp();
+            // Redirect bare path to trailing-slash (SPA convention)
+            app.get(STUDIO_PATH, (c) => c.redirect(`${STUDIO_PATH}/`));
+            // Proxy all /_studio/* requests to the Vite dev server
+            app.all(`${STUDIO_PATH}/*`, async (c) => {
+                const targetUrl = `http://localhost:${vitePort}${c.req.path}`;
+                try {
+                    const headers = new Headers(c.req.raw.headers);
+                    headers.delete('host');
+                    const isBodyAllowed = !['GET', 'HEAD'].includes(c.req.method);
+                    const resp = await fetch(targetUrl, {
+                        method: c.req.method,
+                        headers,
+                        body: isBodyAllowed ? c.req.raw.body : undefined,
+                        duplex: isBodyAllowed ? 'half' : undefined,
+                    });
+                    // Forward the full response (status, headers, body)
+                    return new Response(resp.body, {
+                        status: resp.status,
+                        headers: resp.headers,
+                    });
+                }
+                catch {
+                    return c.text('Console dev server is starting…', 502);
+                }
+            });
+        },
+    };
+}
+/**
+ * Create a lightweight kernel plugin that serves the pre-built Studio
+ * static files at `/_studio/*`. Used in production mode.
+ *
+ * Uses Node.js built-in fs for static file serving to avoid external
+ * bundling dependencies.
+ */
+export function createStudioStaticPlugin(distPath, options) {
+    return {
+        name: 'com.objectstack.studio-static',
+        init: async () => { },
+        start: async (ctx) => {
+            const httpServer = ctx.getService?.('http.server');
+            if (!httpServer?.getRawApp) {
+                ctx.logger?.warn?.('Studio static: http.server service not found — skipping');
+                return;
+            }
+            const app = httpServer.getRawApp();
+            const absoluteDist = path.resolve(distPath);
+            const indexPath = path.join(absoluteDist, 'index.html');
+            if (!fs.existsSync(indexPath)) {
+                ctx.logger?.warn?.(`Studio static: dist not found at ${absoluteDist}`);
+                return;
+            }
+            // Read and rewrite index.html so asset paths respect the mount path.
+            // The dist may have been built with base '/' (absolute paths like
+            // /assets/...) which won't resolve when mounted under /_studio/.
+            const rawHtml = fs.readFileSync(indexPath, 'utf-8');
+            const rewrittenHtml = rawHtml.replace(/(\s(?:href|src))="\/(?!\/)/g, `$1="${STUDIO_PATH}/`);
+            // In dev mode, redirect root to Studio for convenience
+            if (options?.isDev) {
+                app.get('/', (c) => c.redirect(`${STUDIO_PATH}/`));
+            }
+            // Redirect bare path
+            app.get(STUDIO_PATH, (c) => c.redirect(`${STUDIO_PATH}/`));
+            // Serve static files with SPA fallback
+            app.get(`${STUDIO_PATH}/*`, async (c) => {
+                const reqPath = c.req.path.substring(STUDIO_PATH.length) || '/';
+                const filePath = path.join(absoluteDist, reqPath);
+                // Security: prevent path traversal
+                if (!filePath.startsWith(absoluteDist)) {
+                    return c.text('Forbidden', 403);
+                }
+                // Try serving the exact file
+                if (fs.existsSync(filePath) && fs.statSync(filePath).isFile()) {
+                    const content = fs.readFileSync(filePath);
+                    return new Response(content, {
+                        headers: { 'content-type': mimeType(filePath) },
+                    });
+                }
+                // SPA fallback: serve rewritten index.html for non-file routes
+                return new Response(rewrittenHtml, {
+                    headers: { 'content-type': 'text/html; charset=utf-8' },
+                });
+            });
+        },
+    };
+}
+// ─── Helpers ────────────────────────────────────────────────────────
+const MIME_TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.ico': 'image/x-icon',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.map': 'application/json',
+};
+function mimeType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return MIME_TYPES[ext] || 'application/octet-stream';
+}
+//# sourceMappingURL=studio.js.map

package/dist/utils/studio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"studio.js","sourceRoot":"","sources":["../../src/utils/studio.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,47 +1,65 @@
 {
   "name": "@objectstack/cli",
-  "version": "3.0.6",
+  "version": "3.0.8",
   "description": "Command Line Interface for ObjectStack Protocol",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "bin": {
-    "objectstack": "./bin/objectstack.js",
-    "os": "./bin/objectstack.js"
+    "objectstack": "./bin/run.js",
+    "os": "./bin/run.js"
   },
   "keywords": [
     "objectstack",
     "cli",
+    "oclif",
     "compiler",
     "scaffold"
   ],
   "type": "module",
   "author": "Steedos",
   "license": "Apache-2.0",
+  "oclif": {
+    "bin": "os",
+    "dirname": "objectstack",
+    "commands": {
+      "strategy": "pattern",
+      "target": "./dist/commands",
+      "glob": "**/*.js"
+    },
+    "plugins": [
+      "@oclif/plugin-help",
+      "@oclif/plugin-plugins"
+    ],
+    "topicSeparator": " "
+  },
   "dependencies": {
+    "@oclif/core": "^4.8.0",
     "bundle-require": "^5.1.0",
     "chalk": "^5.3.0",
-    "commander": "^14.0.3",
     "tsx": "^4.7.1",
     "zod": "^4.3.6",
-    "@objectstack/core": "3.0.6",
-    "@objectstack/driver-memory": "^3.0.6",
-    "@objectstack/objectql": "^3.0.6",
-    "@objectstack/plugin-hono-server": "3.0.6",
-    "@objectstack/rest": "3.0.6",
-    "@objectstack/runtime": "^3.0.6",
-    "@objectstack/spec": "3.0.6"
+    "@objectstack/core": "3.0.8",
+    "@objectstack/driver-memory": "^3.0.8",
+    "@objectstack/objectql": "^3.0.8",
+    "@objectstack/plugin-hono-server": "3.0.8",
+    "@objectstack/rest": "3.0.8",
+    "@objectstack/runtime": "^3.0.8",
+    "@objectstack/spec": "3.0.8"
   },
   "peerDependencies": {
-    "@objectstack/core": "3.0.6"
+    "@objectstack/core": "3.0.8"
   },
   "devDependencies": {
-    "@types/node": "^25.2.2",
+    "@oclif/plugin-help": "^6.2.37",
+    "@oclif/plugin-plugins": "^5.4.56",
+    "@types/node": "^25.2.3",
     "tsup": "^8.0.2",
     "typescript": "^5.3.3",
     "vitest": "^4.0.18"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
     "test": "vitest run",
     "lint": "eslint src"
   }

package/src/bin.ts

@@ -1,106 +1,13 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { createRequire } from 'module';
-import { Command } from 'commander';
-import chalk from 'chalk';
-
-// Commands
-import { compileCommand } from './commands/compile.js';
-import { devCommand } from './commands/dev.js';
-import { doctorCommand } from './commands/doctor.js';
-import { createCommand } from './commands/create.js';
-import { serveCommand } from './commands/serve.js';
-import { studioCommand } from './commands/studio.js';
-import { testCommand } from './commands/test.js';
-import { validateCommand } from './commands/validate.js';
-import { initCommand } from './commands/init.js';
-import { infoCommand } from './commands/info.js';
-import { generateCommand } from './commands/generate.js';
-import { pluginCommand } from './commands/plugin.js';
-import { diffCommand } from './commands/diff.js';
-import { lintCommand } from './commands/lint.js';
-import { explainCommand } from './commands/explain.js';
-import { codemodCommand } from './commands/codemod.js';
-import { loadPluginCommands } from './utils/plugin-commands.js';
-
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
-
-// ─── Global Error Handling ──────────────────────────────────────────
-process.on('unhandledRejection', (err: any) => {
-  console.error(chalk.red(`\n  ✗ Unhandled error: ${err?.message || err}`));
-  if (err?.stack && process.env.DEBUG) {
-    console.error(chalk.dim(err.stack));
-  }
-  process.exit(1);
-});
-
-// ─── Program Definition ─────────────────────────────────────────────
-const program = new Command();
-
-program
-  .name('objectstack')
-  .description('ObjectStack CLI — Build metadata-driven apps with the ObjectStack Protocol')
-  .version(pkg.version, '-v, --version')
-  .configureHelp({
-    sortSubcommands: false,
-  })
-  .addHelpText('before', `
-${chalk.bold.cyan('◆ ObjectStack CLI')} ${chalk.dim(`v${pkg.version}`)}
-`)
-  .addHelpText('after', `
-${chalk.bold('Workflow:')}
-  ${chalk.dim('$')} os init                      ${chalk.dim('# Create a new project')}
-  ${chalk.dim('$')} os generate object task       ${chalk.dim('# Add metadata')}
-  ${chalk.dim('$')} os plugin add <package>       ${chalk.dim('# Add a plugin')}
-  ${chalk.dim('$')} os validate                   ${chalk.dim('# Check configuration')}
-  ${chalk.dim('$')} os dev                        ${chalk.dim('# Start dev server')}
-  ${chalk.dim('$')} os studio                     ${chalk.dim('# Dev server + Studio UI')}
-  ${chalk.dim('$')} os compile                    ${chalk.dim('# Build for production')}
-
-${chalk.dim('Aliases: objectstack | os')}
-${chalk.dim('Docs: https://objectstack.dev')}
-`);
-
-// ── Development ──
-program.addCommand(initCommand);
-program.addCommand(devCommand);
-program.addCommand(serveCommand);
-program.addCommand(studioCommand);
-
-// ── Build & Validate ──
-program.addCommand(compileCommand);
-program.addCommand(validateCommand);
-program.addCommand(infoCommand);
-
-// ── Scaffolding ──
-program.addCommand(generateCommand);
-program.addCommand(createCommand);
-
-// ── Plugin Management ──
-program.addCommand(pluginCommand);
-
-// ── Quality ──
-program.addCommand(testCommand);
-program.addCommand(doctorCommand);
-program.addCommand(lintCommand);
-program.addCommand(diffCommand);
-
-// ── Reference ──
-program.addCommand(explainCommand);
-
-// ── Code Transforms ──
-program.addCommand(codemodCommand);
-
-// ── Plugin-Contributed Commands ──
-// Load commands from installed plugins that declare `contributes.commands` in their manifest.
-// This must complete before `program.parse()` so that plugin commands are available.
-loadPluginCommands(program).then(() => {
-  program.parse(process.argv);
-}).catch((err) => {
-  // If plugin command loading fails, still parse with built-in commands
-  if (process.env.DEBUG) {
-    console.error(chalk.yellow(`\n  ⚠ Plugin command loading failed: ${err?.message || err}`));
-  }
-  program.parse(process.argv);
-});
+/**
+ * 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';

package/src/commands/{codemod.ts → codemod/v2-to-v3.ts}

@@ -1,10 +1,10 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
-import { Command } from 'commander';
+import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import fs from 'fs';
 import path from 'path';
-import { printHeader, printSuccess, printError, printInfo, printStep, createTimer } from '../utils/format.js';
+import { printHeader, printSuccess, printError, printInfo, printStep, createTimer } from '../../utils/format.js';
 
 // ─── Transform Definitions ──────────────────────────────────────────
 
@@ -76,25 +76,31 @@ function walkDir(dir: string, ext: string): string[] {
   return results;
 }
 
-// ─── v2-to-v3 Sub-Command ──────────────────────────────────────────
+// ─── Command ────────────────────────────────────────────────────────
+
+export default class V2ToV3 extends Command {
+  static override description = 'Migrate ObjectStack v2 config to v3 format';
+
+  static override flags = {
+    dir: Flags.string({ description: 'Directory to scan', default: 'src/' }),
+    'dry-run': Flags.boolean({ description: 'Show changes without writing files' }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(V2ToV3);
 
-const v2ToV3Command = new Command('v2-to-v3')
-  .description('Migrate ObjectStack v2 code patterns to v3')
-  .option('--dir <directory>', 'Directory to scan', 'src/')
-  .option('--dry-run', 'Show changes without writing files')
-  .action(async (options) => {
     printHeader('Codemod: v2 → v3');
 
     const timer = createTimer();
-    const dir = path.resolve(process.cwd(), options.dir);
+    const dir = path.resolve(process.cwd(), flags.dir);
 
     if (!fs.existsSync(dir)) {
       printError(`Directory not found: ${dir}`);
       process.exit(1);
     }
 
-    console.log(`  ${chalk.dim('Directory:')} ${chalk.white(options.dir)}`);
-    console.log(`  ${chalk.dim('Dry run:')}   ${chalk.white(options.dryRun ? 'yes' : 'no')}`);
+    console.log(`  ${chalk.dim('Directory:')} ${chalk.white(flags.dir)}`);
+    console.log(`  ${chalk.dim('Dry run:')}   ${chalk.white(flags['dry-run'] ? 'yes' : 'no')}`);
     console.log('');
 
     printStep('Scanning TypeScript files...');
@@ -132,7 +138,7 @@ const v2ToV3Command = new Command('v2-to-v3')
         filesModified++;
         totalTransforms += fileTransforms;
 
-        if (options.dryRun) {
+        if (flags['dry-run']) {
           printInfo(`${relPath} — ${fileTransforms} change(s)`);
         } else {
           fs.writeFileSync(file, content);
@@ -152,7 +158,7 @@ const v2ToV3Command = new Command('v2-to-v3')
       }
       console.log('');
 
-      if (options.dryRun) {
+      if (flags['dry-run']) {
         printInfo(`Would modify ${filesModified} file(s) with ${totalTransforms} total change(s)`);
         console.log(chalk.dim('  Run without --dry-run to apply changes'));
       } else {
@@ -161,18 +167,5 @@ const v2ToV3Command = new Command('v2-to-v3')
     }
 
     console.log('');
-  });
-
-// ─── Main Codemod Command ───────────────────────────────────────────
-
-export const codemodCommand = new Command('codemod')
-  .description('Run automated code transformations')
-  .addCommand(v2ToV3Command)
-  .action(() => {
-    printHeader('Codemod');
-    console.log(chalk.bold('  Available codemods:'));
-    console.log(`    ${chalk.cyan('v2-to-v3'.padEnd(16))} Migrate ObjectStack v2 code patterns to v3`);
-    console.log('');
-    console.log(chalk.dim('  Usage: objectstack codemod v2-to-v3 [--dir src/] [--dry-run]'));
-    console.log('');
-  });
+  }
+}