@deimoscloud/coreai 0.1.0

package/src/commands/context.ts

@@ -0,0 +1,111 @@
+/**
+ * Command Context
+ *
+ * Runtime context for command execution with graceful degradation support.
+ */
+
+import type { ResolvedCoreAIConfig } from '../config/types.js';
+import type { AdapterType } from '../adapters/types.js';
+import type { AdapterFactory } from '../adapters/factory.js';
+import { createAdapterFactory } from '../adapters/factory.js';
+import { loadConfig, configExists } from '../config/loader.js';
+import type { CommandContext } from './types.js';
+
+/**
+ * Options for creating a command context
+ */
+export interface CreateContextOptions {
+  /**
+   * Project root directory
+   */
+  projectRoot?: string;
+
+  /**
+   * Pre-loaded configuration (if already loaded)
+   */
+  config?: ResolvedCoreAIConfig;
+
+  /**
+   * Pre-created adapter factory (if already created)
+   */
+  adapterFactory?: AdapterFactory;
+}
+
+/**
+ * Create a command execution context
+ *
+ * Handles configuration loading and adapter factory creation with graceful fallbacks.
+ */
+export function createCommandContext(options: CreateContextOptions = {}): CommandContext {
+  const projectRoot = options.projectRoot ?? process.cwd();
+
+  // Load config if not provided
+  let config: ResolvedCoreAIConfig | null = options.config ?? null;
+  if (!config && configExists(projectRoot)) {
+    try {
+      config = loadConfig(projectRoot);
+    } catch {
+      // Config loading failed, continue without config
+      config = null;
+    }
+  }
+
+  // Create adapter factory if config is available and factory not provided
+  let adapterFactory: AdapterFactory | null = options.adapterFactory ?? null;
+  if (!adapterFactory && config) {
+    try {
+      adapterFactory = createAdapterFactory(config);
+    } catch {
+      // Factory creation failed, continue without adapters
+      adapterFactory = null;
+    }
+  }
+
+  return {
+    config,
+    adapterFactory,
+    projectRoot,
+
+    hasIntegration(type: AdapterType): boolean {
+      if (!adapterFactory) return false;
+      return adapterFactory.hasIntegration(type);
+    },
+
+    async getAdapterSafe<T>(type: AdapterType): Promise<T | null> {
+      if (!adapterFactory) return null;
+      if (!adapterFactory.hasIntegration(type)) return null;
+
+      try {
+        const adapter = await adapterFactory.getAdapter(type);
+        return adapter as T;
+      } catch {
+        // Adapter creation failed, return null for graceful degradation
+        return null;
+      }
+    },
+  };
+}
+
+/**
+ * Cleanup resources in a command context
+ */
+export async function cleanupContext(context: CommandContext): Promise<void> {
+  if (context.adapterFactory) {
+    await context.adapterFactory.disconnectAll();
+  }
+}
+
+/**
+ * Execute a function with automatic context cleanup
+ */
+export async function withContext<T>(
+  options: CreateContextOptions,
+  fn: (context: CommandContext) => Promise<T>
+): Promise<T> {
+  const context = createCommandContext(options);
+  try {
+    return await fn(context);
+  } finally {
+    await cleanupContext(context);
+  }
+}

package/src/commands/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Command Framework
+ *
+ * Registration, discovery, and execution of CoreAI commands.
+ */
+
+// Types
+export type {
+  CommandCategory,
+  IntegrationDependency,
+  CommandMetadata,
+  CommandContext,
+  BaseCommandOptions,
+  CommandResult,
+  CommandHandler,
+  CommandDefinition,
+  CommandOptionDefinition,
+  CommandArgumentDefinition,
+  MarkdownCommand,
+  RegistryEntry,
+  CommandLoaderOptions,
+  CommandLoadResult,
+} from './types.js';
+
+// Context
+export {
+  createCommandContext,
+  cleanupContext,
+  withContext,
+  type CreateContextOptions,
+} from './context.js';
+
+// Registry
+export {
+  CommandRegistry,
+  createCommandRegistry,
+  getGlobalRegistry,
+  resetGlobalRegistry,
+} from './registry.js';
+
+// Loader
+export {
+  loadCommandFromFile,
+  loadCommandsFromDirectory,
+  loadCoreAICommands,
+  loadAllCommands,
+} from './loader.js';
+
+// Runner
+export {
+  runCommand,
+  executeWithDegradation,
+  createDegradingHandler,
+  StepTracker,
+  type RunCommandOptions,
+} from './runner.js';

package/src/commands/loader.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Command Loader Tests
+ */
+
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { loadCommandFromFile, loadCommandsFromDirectory, loadAllCommands } from './loader.js';
+
+describe('Command Loader', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(
+      tmpdir(),
+      `cmd-loader-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+    await fs.mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    try {
+      await fs.rm(testDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('loadCommandFromFile', () => {
+    it('should load command with frontmatter', async () => {
+      const cmdPath = join(testDir, 'test-command.md');
+      await fs.writeFile(
+        cmdPath,
+        `---
+description: A test command
+argument-hint: <task>
+---
+
+# Test Command
+
+Instructions for the command.
+`
+      );
+
+      const cmd = await loadCommandFromFile(cmdPath, testDir);
+
+      expect(cmd.metadata.name).toBe('test-command');
+      expect(cmd.metadata.description).toBe('A test command');
+      expect(cmd.metadata.argumentHint).toBe('<task>');
+      expect(cmd.sections.title).toBe('Test Command');
+    });
+
+    it('should load command without frontmatter', async () => {
+      const cmdPath = join(testDir, 'simple.md');
+      await fs.writeFile(cmdPath, '# Simple Command\n\nJust instructions.');
+
+      const cmd = await loadCommandFromFile(cmdPath, testDir);
+
+      expect(cmd.metadata.name).toBe('simple');
+      expect(cmd.metadata.description).toBe('Simple Command');
+      expect(cmd.content).toContain('Just instructions');
+    });
+
+    it('should parse dependencies from frontmatter', async () => {
+      const cmdPath = join(testDir, 'with-deps.md');
+      await fs.writeFile(
+        cmdPath,
+        `---
+description: Command with deps
+requires: [jira, github]
+optional: [confluence]
+---
+
+# With Dependencies
+`
+      );
+
+      const cmd = await loadCommandFromFile(cmdPath, testDir);
+
+      expect(cmd.metadata.dependencies).toHaveLength(3);
+
+      const jiraDep = cmd.metadata.dependencies.find((d) => d.type === 'issue_tracker');
+      expect(jiraDep?.required).toBe(true);
+
+      const gitDep = cmd.metadata.dependencies.find((d) => d.type === 'git');
+      expect(gitDep?.required).toBe(true);
+
+      const docsDep = cmd.metadata.dependencies.find((d) => d.type === 'documentation');
+      expect(docsDep?.required).toBe(false);
+    });
+
+    it('should extract sections from markdown', async () => {
+      const cmdPath = join(testDir, 'sectioned.md');
+      await fs.writeFile(
+        cmdPath,
+        `---
+description: Sectioned command
+---
+
+# Sectioned Command
+
+## Instructions
+
+Do this thing.
+
+## Fallbacks
+
+If integration missing, do this instead.
+
+## Output Format
+
+Return JSON.
+`
+      );
+
+      const cmd = await loadCommandFromFile(cmdPath, testDir);
+
+      expect(cmd.sections.title).toBe('Sectioned Command');
+      expect(cmd.sections.instructions).toContain('Do this thing');
+      expect(cmd.sections.fallbacks).toContain('integration missing');
+      expect(cmd.sections.outputFormat).toContain('JSON');
+    });
+
+    it('should derive category from path', async () => {
+      // Create core subdirectory
+      const coreDir = join(testDir, 'core');
+      await fs.mkdir(coreDir, { recursive: true });
+      const corePath = join(coreDir, 'core-cmd.md');
+      await fs.writeFile(corePath, '# Core Command');
+
+      // Create optional subdirectory
+      const optDir = join(testDir, 'optional');
+      await fs.mkdir(optDir, { recursive: true });
+      const optPath = join(optDir, 'opt-cmd.md');
+      await fs.writeFile(optPath, '# Optional Command');
+
+      const coreCmd = await loadCommandFromFile(corePath, testDir);
+      const optCmd = await loadCommandFromFile(optPath, testDir);
+
+      expect(coreCmd.metadata.category).toBe('core');
+      expect(optCmd.metadata.category).toBe('optional');
+    });
+
+    it('should use category override', async () => {
+      const cmdPath = join(testDir, 'cmd.md');
+      await fs.writeFile(cmdPath, '# Command');
+
+      const cmd = await loadCommandFromFile(cmdPath, testDir, 'custom');
+
+      expect(cmd.metadata.category).toBe('custom');
+    });
+  });
+
+  describe('loadCommandsFromDirectory', () => {
+    it('should load all markdown files', async () => {
+      await fs.writeFile(join(testDir, 'cmd1.md'), '# Command 1');
+      await fs.writeFile(join(testDir, 'cmd2.md'), '# Command 2');
+      await fs.writeFile(join(testDir, 'not-md.txt'), 'Not a command');
+
+      const result = await loadCommandsFromDirectory({
+        directory: testDir,
+        category: 'core',
+      });
+
+      expect(result.loaded).toHaveLength(2);
+      expect(result.errors).toHaveLength(0);
+      expect(result.loaded.map((c) => c.metadata.name)).toContain('cmd1');
+      expect(result.loaded.map((c) => c.metadata.name)).toContain('cmd2');
+    });
+
+    it('should load recursively by default', async () => {
+      await fs.writeFile(join(testDir, 'root.md'), '# Root');
+
+      const subDir = join(testDir, 'sub');
+      await fs.mkdir(subDir, { recursive: true });
+      await fs.writeFile(join(subDir, 'nested.md'), '# Nested');
+
+      const result = await loadCommandsFromDirectory({
+        directory: testDir,
+        category: 'core',
+        recursive: true,
+      });
+
+      expect(result.loaded).toHaveLength(2);
+    });
+
+    it('should not load recursively when disabled', async () => {
+      await fs.writeFile(join(testDir, 'root.md'), '# Root');
+
+      const subDir = join(testDir, 'sub');
+      await fs.mkdir(subDir, { recursive: true });
+      await fs.writeFile(join(subDir, 'nested.md'), '# Nested');
+
+      const result = await loadCommandsFromDirectory({
+        directory: testDir,
+        category: 'core',
+        recursive: false,
+      });
+
+      expect(result.loaded).toHaveLength(1);
+      expect(result.loaded[0].metadata.name).toBe('root');
+    });
+
+    it('should apply filter', async () => {
+      await fs.writeFile(join(testDir, 'include-me.md'), '# Include');
+      await fs.writeFile(join(testDir, 'exclude-me.md'), '# Exclude');
+
+      const result = await loadCommandsFromDirectory({
+        directory: testDir,
+        category: 'core',
+        filter: (metadata) => metadata.name.startsWith('include'),
+      });
+
+      expect(result.loaded).toHaveLength(1);
+      expect(result.loaded[0].metadata.name).toBe('include-me');
+    });
+
+    it('should handle non-existent directory', async () => {
+      const result = await loadCommandsFromDirectory({
+        directory: join(testDir, 'non-existent'),
+        category: 'core',
+      });
+
+      expect(result.loaded).toHaveLength(0);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should handle directories with .md extension gracefully', async () => {
+      // Create a valid file
+      await fs.writeFile(join(testDir, 'valid.md'), '# Valid');
+
+      // Create a directory with .md name (should be skipped, not errored)
+      await fs.mkdir(join(testDir, 'not-a-file.md'), { recursive: true });
+
+      const result = await loadCommandsFromDirectory({
+        directory: testDir,
+        category: 'core',
+        recursive: false,
+      });
+
+      // Only the valid file should be loaded, directory should be ignored
+      expect(result.loaded).toHaveLength(1);
+      expect(result.loaded[0].metadata.name).toBe('valid');
+      expect(result.errors).toHaveLength(0);
+    });
+  });
+
+  describe('loadAllCommands', () => {
+    it('should load from multiple directories', async () => {
+      const coreDir = join(testDir, 'core');
+      const customDir = join(testDir, 'custom');
+      await fs.mkdir(coreDir, { recursive: true });
+      await fs.mkdir(customDir, { recursive: true });
+
+      await fs.writeFile(join(coreDir, 'core-cmd.md'), '# Core');
+      await fs.writeFile(join(customDir, 'custom-cmd.md'), '# Custom');
+
+      const result = await loadAllCommands(coreDir, customDir);
+
+      expect(result.loaded).toHaveLength(2);
+    });
+
+    it('should work without custom directory', async () => {
+      const coreDir = join(testDir, 'core');
+      await fs.mkdir(coreDir, { recursive: true });
+      await fs.writeFile(join(coreDir, 'cmd.md'), '# Command');
+
+      const result = await loadAllCommands(coreDir);
+
+      expect(result.loaded).toHaveLength(1);
+    });
+  });
+});