@objectstack/cli 2.0.7 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/cli",
-  "version": "2.0.7",
+  "version": "3.0.1",
   "description": "Command Line Interface for ObjectStack Protocol",
   "main": "dist/index.js",
   "bin": {
@@ -22,16 +22,16 @@
     "commander": "^14.0.3",
     "tsx": "^4.7.1",
     "zod": "^4.3.6",
-    "@objectstack/core": "2.0.7",
-    "@objectstack/driver-memory": "^2.0.7",
-    "@objectstack/objectql": "^2.0.7",
-    "@objectstack/plugin-hono-server": "2.0.7",
-    "@objectstack/rest": "2.0.7",
-    "@objectstack/runtime": "^2.0.7",
-    "@objectstack/spec": "2.0.7"
+    "@objectstack/core": "3.0.1",
+    "@objectstack/driver-memory": "^3.0.1",
+    "@objectstack/objectql": "^3.0.1",
+    "@objectstack/plugin-hono-server": "3.0.1",
+    "@objectstack/rest": "3.0.1",
+    "@objectstack/runtime": "^3.0.1",
+    "@objectstack/spec": "3.0.1"
   },
   "peerDependencies": {
-    "@objectstack/core": "2.0.7"
+    "@objectstack/core": "3.0.1"
   },
   "devDependencies": {
     "@types/node": "^25.2.2",

package/src/bin.ts

@@ -17,6 +17,10 @@ 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);
@@ -79,6 +83,14 @@ 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.

package/src/commands/codemod.ts

@@ -0,0 +1,178 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { printHeader, printSuccess, printError, printInfo, printStep, createTimer } from '../utils/format.js';
+
+// ─── Transform Definitions ──────────────────────────────────────────
+
+interface Transform {
+  pattern: RegExp;
+  replacement: string;
+  description: string;
+}
+
+const V2_TO_V3_TRANSFORMS: Transform[] = [
+  {
+    pattern: /\bEnhancedObjectKernel\b/g,
+    replacement: 'ObjectKernel',
+    description: 'EnhancedObjectKernel → ObjectKernel',
+  },
+  {
+    pattern: /\bmax_length\b/g,
+    replacement: 'maxLength',
+    description: 'max_length → maxLength',
+  },
+  {
+    pattern: /\breference_filters\b/g,
+    replacement: 'referenceFilters',
+    description: 'reference_filters → referenceFilters',
+  },
+  {
+    pattern: /\bdefault_value\b/g,
+    replacement: 'defaultValue',
+    description: 'default_value → defaultValue',
+  },
+  {
+    pattern: /\bmin_length\b/g,
+    replacement: 'minLength',
+    description: 'min_length → minLength',
+  },
+  {
+    pattern: /\bunique_name\b/g,
+    replacement: 'uniqueName',
+    description: 'unique_name → uniqueName',
+  },
+  {
+    pattern: /from\s+['"]@objectstack\/core\/enhanced['"]/g,
+    replacement: "from '@objectstack/core'",
+    description: 'Update import from @objectstack/core/enhanced',
+  },
+  {
+    pattern: /from\s+['"]@objectstack\/spec\/dist\/[^'"]+['"]/g,
+    replacement: "from '@objectstack/spec'",
+    description: 'Update deep import from @objectstack/spec/dist/',
+  },
+];
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function walkDir(dir: string, ext: string): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === 'node_modules') continue;
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath, ext));
+    } else if (entry.name.endsWith(ext)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+// ─── v2-to-v3 Sub-Command ──────────────────────────────────────────
+
+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);
+
+    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('');
+
+    printStep('Scanning TypeScript files...');
+    const files = walkDir(dir, '.ts');
+
+    if (files.length === 0) {
+      printInfo('No .ts files found in directory');
+      return;
+    }
+
+    printInfo(`Found ${files.length} TypeScript file(s)`);
+    console.log('');
+
+    let totalTransforms = 0;
+    let filesModified = 0;
+    const transformCounts: Record<string, number> = {};
+
+    for (const file of files) {
+      const original = fs.readFileSync(file, 'utf-8');
+      let content = original;
+      let fileTransforms = 0;
+
+      for (const transform of V2_TO_V3_TRANSFORMS) {
+        const matches = content.match(transform.pattern);
+        if (matches) {
+          const count = matches.length;
+          content = content.replace(transform.pattern, transform.replacement);
+          fileTransforms += count;
+          transformCounts[transform.description] = (transformCounts[transform.description] || 0) + count;
+        }
+      }
+
+      if (fileTransforms > 0) {
+        const relPath = path.relative(process.cwd(), file);
+        filesModified++;
+        totalTransforms += fileTransforms;
+
+        if (options.dryRun) {
+          printInfo(`${relPath} — ${fileTransforms} change(s)`);
+        } else {
+          fs.writeFileSync(file, content);
+          printSuccess(`${relPath} — ${fileTransforms} change(s)`);
+        }
+      }
+    }
+
+    console.log('');
+
+    if (totalTransforms === 0) {
+      printSuccess('No v2 patterns found — code is already v3 compatible');
+    } else {
+      console.log(chalk.bold('  Summary:'));
+      for (const [desc, count] of Object.entries(transformCounts)) {
+        console.log(`    ${chalk.dim(desc)}: ${chalk.white(count)}`);
+      }
+      console.log('');
+
+      if (options.dryRun) {
+        printInfo(`Would modify ${filesModified} file(s) with ${totalTransforms} total change(s)`);
+        console.log(chalk.dim('  Run without --dry-run to apply changes'));
+      } else {
+        printSuccess(`Modified ${filesModified} file(s) with ${totalTransforms} total change(s) (${timer.display()})`);
+      }
+    }
+
+    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('');
+  });

package/src/commands/diff.ts

@@ -0,0 +1,285 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadConfig } from '../utils/config.js';
+import {
+  printHeader,
+  printSuccess,
+  printWarning,
+  printError,
+  printInfo,
+  printStep,
+  createTimer,
+} from '../utils/format.js';
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+interface DiffEntry {
+  type: 'added' | 'removed' | 'modified';
+  category: string;
+  name: string;
+  detail?: string;
+  breaking: boolean;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function getNames(items: any[] | undefined): Map<string, any> {
+  const map = new Map<string, any>();
+  if (!Array.isArray(items)) return map;
+  for (const item of items) {
+    if (item?.name) map.set(item.name, item);
+  }
+  return map;
+}
+
+function getFieldNames(obj: any): string[] {
+  if (!obj?.fields || typeof obj.fields !== 'object') return [];
+  return Object.keys(obj.fields);
+}
+
+function getFieldType(obj: any, fieldName: string): string | undefined {
+  return obj?.fields?.[fieldName]?.type;
+}
+
+function isFieldRequired(obj: any, fieldName: string): boolean {
+  return obj?.fields?.[fieldName]?.required === true;
+}
+
+function diffNamedArrays(
+  beforeItems: any[] | undefined,
+  afterItems: any[] | undefined,
+  category: string,
+  detectFieldChanges: boolean,
+): DiffEntry[] {
+  const entries: DiffEntry[] = [];
+  const beforeMap = getNames(beforeItems);
+  const afterMap = getNames(afterItems);
+
+  // Removed items
+  for (const [name] of beforeMap) {
+    if (!afterMap.has(name)) {
+      entries.push({
+        type: 'removed',
+        category,
+        name,
+        breaking: true,
+      });
+    }
+  }
+
+  // Added items
+  for (const [name] of afterMap) {
+    if (!beforeMap.has(name)) {
+      entries.push({
+        type: 'added',
+        category,
+        name,
+        breaking: false,
+      });
+    }
+  }
+
+  // Modified items — field-level diff for objects
+  if (detectFieldChanges) {
+    for (const [name, beforeObj] of beforeMap) {
+      const afterObj = afterMap.get(name);
+      if (!afterObj) continue;
+
+      const beforeFields = getFieldNames(beforeObj);
+      const afterFields = getFieldNames(afterObj);
+      const beforeSet = new Set(beforeFields);
+      const afterSet = new Set(afterFields);
+
+      // Removed fields
+      for (const f of beforeFields) {
+        if (!afterSet.has(f)) {
+          entries.push({
+            type: 'removed',
+            category: `${category}.${name}.fields`,
+            name: f,
+            breaking: true,
+            detail: 'field removed',
+          });
+        }
+      }
+
+      // Added fields
+      for (const f of afterFields) {
+        if (!beforeSet.has(f)) {
+          const breaking = isFieldRequired(afterObj, f);
+          entries.push({
+            type: 'added',
+            category: `${category}.${name}.fields`,
+            name: f,
+            breaking,
+            detail: breaking ? 'required field added' : 'optional field added',
+          });
+        }
+      }
+
+      // Type changes
+      for (const f of beforeFields) {
+        if (!afterSet.has(f)) continue;
+        const oldType = getFieldType(beforeObj, f);
+        const newType = getFieldType(afterObj, f);
+        if (oldType && newType && oldType !== newType) {
+          entries.push({
+            type: 'modified',
+            category: `${category}.${name}.fields`,
+            name: f,
+            breaking: true,
+            detail: `type changed: ${oldType} → ${newType}`,
+          });
+        }
+      }
+
+      // Label / ownership changes on the object itself
+      if (beforeObj.label !== afterObj.label) {
+        entries.push({
+          type: 'modified',
+          category,
+          name,
+          breaking: false,
+          detail: `label changed: "${beforeObj.label ?? '(none)'}" → "${afterObj.label ?? '(none)'}"`,
+        });
+      }
+    }
+  }
+
+  return entries;
+}
+
+// ─── Command ────────────────────────────────────────────────────────
+
+export const diffCommand = new Command('diff')
+  .description('Compare two ObjectStack configurations and detect breaking changes')
+  .argument('[before]', 'Path to the "before" config file')
+  .argument('[after]', 'Path to the "after" config file')
+  .option('--before <path>', 'Path to the "before" config (alternative)')
+  .option('--after <path>', 'Path to the "after" config (alternative)')
+  .option('--json', 'Output as JSON')
+  .option('--breaking-only', 'Show only breaking changes')
+  .action(async (beforeArg, afterArg, options) => {
+    const timer = createTimer();
+
+    const beforePath: string | undefined = beforeArg || options.before;
+    const afterPath: string | undefined = afterArg || options.after;
+
+    if (!beforePath || !afterPath) {
+      printError('Two config file paths are required.');
+      console.log('');
+      console.log(chalk.dim('  Usage: objectstack diff <before> <after>'));
+      console.log(chalk.dim('     or: objectstack diff --before path1 --after path2'));
+      process.exit(1);
+    }
+
+    if (!options.json) {
+      printHeader('Diff');
+      printStep('Loading configurations...');
+    }
+
+    try {
+      const { config: beforeConfig } = await loadConfig(beforePath);
+      const { config: afterConfig } = await loadConfig(afterPath);
+
+      if (!options.json) {
+        printInfo(`Before: ${chalk.white(beforePath)}`);
+        printInfo(`After:  ${chalk.white(afterPath)}`);
+      }
+
+      // ── Diff all categories ──
+      const allDiffs: DiffEntry[] = [];
+
+      // Objects (with field-level diff)
+      allDiffs.push(...diffNamedArrays(beforeConfig.objects, afterConfig.objects, 'objects', true));
+
+      // Views, Flows, Agents, Apps (name-level diff)
+      const simpleCats: Array<{ key: string; label: string }> = [
+        { key: 'views', label: 'views' },
+        { key: 'flows', label: 'flows' },
+        { key: 'agents', label: 'agents' },
+        { key: 'apps', label: 'apps' },
+        { key: 'dashboards', label: 'dashboards' },
+        { key: 'actions', label: 'actions' },
+        { key: 'workflows', label: 'workflows' },
+        { key: 'apis', label: 'apis' },
+        { key: 'roles', label: 'roles' },
+      ];
+
+      for (const cat of simpleCats) {
+        allDiffs.push(
+          ...diffNamedArrays(beforeConfig[cat.key], afterConfig[cat.key], cat.label, false),
+        );
+      }
+
+      // ── Filter ──
+      const diffs = options.breakingOnly
+        ? allDiffs.filter((d) => d.breaking)
+        : allDiffs;
+
+      const breakingCount = allDiffs.filter((d) => d.breaking).length;
+
+      // ── Output ──
+      if (options.json) {
+        console.log(JSON.stringify({
+          before: beforePath,
+          after: afterPath,
+          total: diffs.length,
+          breaking: breakingCount,
+          changes: diffs,
+          duration: timer.elapsed(),
+        }, null, 2));
+        return;
+      }
+
+      console.log('');
+
+      if (diffs.length === 0) {
+        printSuccess(options.breakingOnly
+          ? 'No breaking changes detected.'
+          : 'No changes detected.');
+        console.log('');
+        return;
+      }
+
+      // Group by category
+      const grouped = new Map<string, DiffEntry[]>();
+      for (const d of diffs) {
+        const key = d.category;
+        if (!grouped.has(key)) grouped.set(key, []);
+        grouped.get(key)!.push(d);
+      }
+
+      for (const [category, items] of grouped) {
+        console.log(`  ${chalk.bold(category)}`);
+        for (const item of items) {
+          const icon = item.type === 'added' ? '+' : item.type === 'removed' ? '-' : '~';
+          const color = item.type === 'added' ? chalk.green : item.type === 'removed' ? chalk.red : chalk.yellow;
+          const breakingTag = item.breaking ? chalk.bgRed.white(' BREAKING ') + ' ' : '';
+          const detail = item.detail ? chalk.dim(` (${item.detail})`) : '';
+          console.log(`    ${color(icon)} ${breakingTag}${color(item.name)}${detail}`);
+        }
+        console.log('');
+      }
+
+      // Summary
+      if (breakingCount > 0) {
+        printError(`${breakingCount} breaking change(s) detected`);
+      } else {
+        printSuccess('No breaking changes');
+      }
+      console.log(chalk.dim(`  ${diffs.length} total change(s) in ${timer.display()}`));
+      console.log('');
+
+    } catch (error: any) {
+      if (options.json) {
+        console.log(JSON.stringify({ error: error.message }));
+        process.exit(1);
+      }
+      console.log('');
+      printError(error.message || String(error));
+      process.exit(1);
+    }
+  });