cognitive-modules 0.6.0

package/dist/commands/add.js

@@ -0,0 +1,229 @@
+/**
+ * Add command - Install modules from GitHub
+ *
+ * cog add ziel-io/cognitive-modules -m code-simplifier
+ * cog add https://github.com/org/repo --module name --tag v1.0.0
+ */
+import { createWriteStream, existsSync, mkdirSync, rmSync, readdirSync, statSync, copyFileSync } from 'node:fs';
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
+import { join, basename } from 'node:path';
+import { homedir, tmpdir } from 'node:os';
+// Module storage paths
+const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
+const INSTALLED_MANIFEST = join(homedir(), '.cognitive', 'installed.json');
+/**
+ * Parse GitHub URL or shorthand
+ */
+function parseGitHubUrl(url) {
+    // Handle shorthand: org/repo
+    if (!url.startsWith('http')) {
+        url = `https://github.com/${url}`;
+    }
+    const match = url.match(/https:\/\/github\.com\/([^\/]+)\/([^\/]+)\/?/);
+    if (!match) {
+        throw new Error(`Invalid GitHub URL: ${url}`);
+    }
+    const org = match[1];
+    const repo = match[2].replace(/\.git$/, '');
+    return {
+        org,
+        repo,
+        fullUrl: `https://github.com/${org}/${repo}`,
+    };
+}
+/**
+ * Download and extract ZIP from GitHub
+ */
+async function downloadAndExtract(org, repo, ref, isTag) {
+    const zipUrl = isTag
+        ? `https://github.com/${org}/${repo}/archive/refs/tags/${ref}.zip`
+        : `https://github.com/${org}/${repo}/archive/refs/heads/${ref}.zip`;
+    // Create temp directory
+    const tempDir = join(tmpdir(), `cog-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+    const zipPath = join(tempDir, 'repo.zip');
+    // Download ZIP
+    const response = await fetch(zipUrl, {
+        headers: { 'User-Agent': 'cognitive-runtime/1.0' },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
+    }
+    // Save to file
+    const fileStream = createWriteStream(zipPath);
+    await pipeline(Readable.fromWeb(response.body), fileStream);
+    // Extract using built-in unzip (available on most systems)
+    const { execSync } = await import('node:child_process');
+    execSync(`unzip -q "${zipPath}" -d "${tempDir}"`, { stdio: 'pipe' });
+    // Find extracted directory
+    const entries = readdirSync(tempDir).filter(e => e !== 'repo.zip' && statSync(join(tempDir, e)).isDirectory());
+    if (entries.length === 0) {
+        throw new Error('ZIP file was empty');
+    }
+    return join(tempDir, entries[0]);
+}
+/**
+ * Check if a directory is a valid module
+ */
+function isValidModule(path) {
+    return (existsSync(join(path, 'module.yaml')) ||
+        existsSync(join(path, 'MODULE.md')) ||
+        existsSync(join(path, 'module.md')));
+}
+/**
+ * Find module within repository
+ */
+function findModuleInRepo(repoRoot, modulePath) {
+    const possiblePaths = [
+        join(repoRoot, modulePath),
+        join(repoRoot, 'cognitive', 'modules', modulePath),
+        join(repoRoot, 'modules', modulePath),
+    ];
+    for (const p of possiblePaths) {
+        if (existsSync(p) && isValidModule(p)) {
+            return p;
+        }
+    }
+    throw new Error(`Module not found at: ${modulePath}\n` +
+        `Searched in: ${possiblePaths.map(p => p.replace(repoRoot, '.')).join(', ')}`);
+}
+/**
+ * Copy directory recursively
+ */
+function copyDir(src, dest) {
+    mkdirSync(dest, { recursive: true });
+    for (const entry of readdirSync(src)) {
+        const srcPath = join(src, entry);
+        const destPath = join(dest, entry);
+        if (statSync(srcPath).isDirectory()) {
+            copyDir(srcPath, destPath);
+        }
+        else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+/**
+ * Get module version from module.yaml or MODULE.md
+ */
+async function getModuleVersion(modulePath) {
+    const yaml = await import('js-yaml');
+    // Try v2 format
+    const yamlPath = join(modulePath, 'module.yaml');
+    if (existsSync(yamlPath)) {
+        const content = await readFile(yamlPath, 'utf-8');
+        const data = yaml.load(content);
+        return data?.version;
+    }
+    // Try v1 format
+    const mdPath = existsSync(join(modulePath, 'MODULE.md'))
+        ? join(modulePath, 'MODULE.md')
+        : join(modulePath, 'module.md');
+    if (existsSync(mdPath)) {
+        const content = await readFile(mdPath, 'utf-8');
+        if (content.startsWith('---')) {
+            const parts = content.split('---');
+            if (parts.length >= 3) {
+                const meta = yaml.load(parts[1]);
+                return meta?.version;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Record installation info
+ */
+async function recordInstall(moduleName, info) {
+    let manifest = {};
+    if (existsSync(INSTALLED_MANIFEST)) {
+        const content = await readFile(INSTALLED_MANIFEST, 'utf-8');
+        manifest = JSON.parse(content);
+    }
+    manifest[moduleName] = info;
+    await mkdir(join(homedir(), '.cognitive'), { recursive: true });
+    await writeFile(INSTALLED_MANIFEST, JSON.stringify(manifest, null, 2));
+}
+/**
+ * Get installation info for a module
+ */
+export async function getInstallInfo(moduleName) {
+    if (!existsSync(INSTALLED_MANIFEST)) {
+        return null;
+    }
+    const content = await readFile(INSTALLED_MANIFEST, 'utf-8');
+    const manifest = JSON.parse(content);
+    return manifest[moduleName] || null;
+}
+/**
+ * Add a module from GitHub
+ */
+export async function add(url, ctx, options = {}) {
+    const { org, repo, fullUrl } = parseGitHubUrl(url);
+    const { module: modulePath, name, branch = 'main', tag } = options;
+    // Determine ref (tag takes priority)
+    const ref = tag || branch;
+    const isTag = !!tag;
+    let repoRoot;
+    let sourcePath;
+    let moduleName;
+    try {
+        // Download repository
+        repoRoot = await downloadAndExtract(org, repo, ref, isTag);
+        // Find module
+        if (modulePath) {
+            sourcePath = findModuleInRepo(repoRoot, modulePath);
+        }
+        else {
+            // Use repo root as module
+            if (!isValidModule(repoRoot)) {
+                throw new Error('Repository root is not a valid module. Use --module to specify the module path.');
+            }
+            sourcePath = repoRoot;
+        }
+        // Determine module name
+        moduleName = name || basename(sourcePath);
+        // Get version
+        const version = await getModuleVersion(sourcePath);
+        // Install to user modules dir
+        const targetPath = join(USER_MODULES_DIR, moduleName);
+        // Remove existing
+        if (existsSync(targetPath)) {
+            rmSync(targetPath, { recursive: true, force: true });
+        }
+        // Copy module
+        await mkdir(USER_MODULES_DIR, { recursive: true });
+        copyDir(sourcePath, targetPath);
+        // Record installation info
+        await recordInstall(moduleName, {
+            source: sourcePath,
+            githubUrl: fullUrl,
+            modulePath,
+            tag,
+            branch,
+            version,
+            installedAt: targetPath,
+            installedTime: new Date().toISOString(),
+        });
+        // Cleanup temp directory
+        const tempDir = repoRoot.split('/').slice(0, -1).join('/');
+        rmSync(tempDir, { recursive: true, force: true });
+        return {
+            success: true,
+            data: {
+                message: `Added: ${moduleName}${version ? ` v${version}` : ''}`,
+                name: moduleName,
+                version,
+                location: targetPath,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/commands/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Commands - Re-export all commands
+ */
+export * from './run.js';
+export * from './list.js';
+export * from './pipe.js';
+export * from './init.js';
+export * from './add.js';
+export * from './update.js';
+export * from './remove.js';
+export * from './versions.js';

package/dist/commands/index.js

@@ -0,0 +1,11 @@
+/**
+ * Commands - Re-export all commands
+ */
+export * from './run.js';
+export * from './list.js';
+export * from './pipe.js';
+export * from './init.js';
+export * from './add.js';
+export * from './update.js';
+export * from './remove.js';
+export * from './versions.js';

package/dist/commands/init.d.ts

@@ -0,0 +1,5 @@
+/**
+ * cog init - Initialize a new Cognitive project
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export declare function init(ctx: CommandContext, moduleName?: string): Promise<CommandResult>;

package/dist/commands/init.js

@@ -0,0 +1,78 @@
+/**
+ * cog init - Initialize a new Cognitive project
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+const EXAMPLE_MODULE_MD = `---
+name: my-module
+version: 1.0.0
+responsibility: Describe what this module does
+excludes:
+  - Do not do X
+  - Do not do Y
+---
+
+Analyze the following input and provide a structured response:
+
+$ARGUMENTS
+
+Return a JSON object with your analysis.
+`;
+const EXAMPLE_SCHEMA_JSON = `{
+  "type": "object",
+  "properties": {
+    "result": {
+      "type": "string",
+      "description": "The main result of the analysis"
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Confidence score"
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Explanation of the reasoning"
+    }
+  },
+  "required": ["result", "confidence", "rationale"]
+}
+`;
+export async function init(ctx, moduleName) {
+    const cognitiveDir = path.join(ctx.cwd, 'cognitive', 'modules');
+    try {
+        // Create directory structure
+        await fs.mkdir(cognitiveDir, { recursive: true });
+        // If module name provided, create a new module
+        if (moduleName) {
+            const moduleDir = path.join(cognitiveDir, moduleName);
+            await fs.mkdir(moduleDir, { recursive: true });
+            await fs.writeFile(path.join(moduleDir, 'MODULE.md'), EXAMPLE_MODULE_MD.replace('my-module', moduleName));
+            await fs.writeFile(path.join(moduleDir, 'schema.json'), EXAMPLE_SCHEMA_JSON);
+            return {
+                success: true,
+                data: {
+                    message: `Created module: ${moduleName}`,
+                    location: moduleDir,
+                    files: ['MODULE.md', 'schema.json'],
+                },
+            };
+        }
+        // Just initialize the directory
+        return {
+            success: true,
+            data: {
+                message: 'Cognitive project initialized',
+                location: cognitiveDir,
+                hint: 'Run "cog init <module-name>" to create a new module',
+            },
+        };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}

package/dist/commands/list.d.ts

@@ -0,0 +1,5 @@
+/**
+ * cog list - List available Cognitive Modules
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export declare function list(ctx: CommandContext): Promise<CommandResult>;

package/dist/commands/list.js

@@ -0,0 +1,28 @@
+/**
+ * cog list - List available Cognitive Modules
+ */
+import { listModules, getDefaultSearchPaths } from '../modules/index.js';
+export async function list(ctx) {
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    const modules = await listModules(searchPaths);
+    if (modules.length === 0) {
+        return {
+            success: true,
+            data: {
+                modules: [],
+                message: `No modules found in: ${searchPaths.join(', ')}`,
+            },
+        };
+    }
+    return {
+        success: true,
+        data: {
+            modules: modules.map(m => ({
+                name: m.name,
+                version: m.version,
+                responsibility: m.responsibility,
+                location: m.location,
+            })),
+        },
+    };
+}

package/dist/commands/pipe.d.ts

@@ -0,0 +1,9 @@
+/**
+ * cog pipe - Pipe mode for stdin/stdout integration
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export interface PipeOptions {
+    module: string;
+    noValidate?: boolean;
+}
+export declare function pipe(ctx: CommandContext, options: PipeOptions): Promise<CommandResult>;

package/dist/commands/pipe.js

@@ -0,0 +1,59 @@
+/**
+ * cog pipe - Pipe mode for stdin/stdout integration
+ */
+import * as readline from 'node:readline';
+import { findModule, getDefaultSearchPaths, runModule } from '../modules/index.js';
+export async function pipe(ctx, options) {
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    // Find module
+    const module = await findModule(options.module, searchPaths);
+    if (!module) {
+        return {
+            success: false,
+            error: `Module not found: ${options.module}`,
+        };
+    }
+    // Read from stdin
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false,
+    });
+    const lines = [];
+    for await (const line of rl) {
+        lines.push(line);
+    }
+    const input = lines.join('\n');
+    try {
+        // Check if input is JSON
+        let inputData;
+        try {
+            inputData = JSON.parse(input);
+        }
+        catch {
+            // Not JSON, use as args
+        }
+        const result = await runModule(module, ctx.provider, {
+            args: inputData ? undefined : input,
+            input: inputData,
+        });
+        // Output envelope format to stdout
+        console.log(JSON.stringify(result));
+        return {
+            success: result.ok,
+            data: result,
+        };
+    }
+    catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        // Output error in envelope format
+        console.log(JSON.stringify({
+            ok: false,
+            error: { code: 'RUNTIME_ERROR', message: error }
+        }));
+        return {
+            success: false,
+            error,
+        };
+    }
+}

package/dist/commands/remove.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Remove command - Remove installed modules
+ *
+ * cog remove code-simplifier
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+/**
+ * Remove an installed module
+ */
+export declare function remove(moduleName: string, ctx: CommandContext): Promise<CommandResult>;

package/dist/commands/remove.js

@@ -0,0 +1,47 @@
+/**
+ * Remove command - Remove installed modules
+ *
+ * cog remove code-simplifier
+ */
+import { existsSync, rmSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
+const INSTALLED_MANIFEST = join(homedir(), '.cognitive', 'installed.json');
+/**
+ * Remove an installed module
+ */
+export async function remove(moduleName, ctx) {
+    const modulePath = join(USER_MODULES_DIR, moduleName);
+    if (!existsSync(modulePath)) {
+        return {
+            success: false,
+            error: `Module not found in global location: ${moduleName}. Only modules in ~/.cognitive/modules can be removed.`,
+        };
+    }
+    try {
+        // Remove module directory
+        rmSync(modulePath, { recursive: true, force: true });
+        // Remove from manifest
+        if (existsSync(INSTALLED_MANIFEST)) {
+            const content = await readFile(INSTALLED_MANIFEST, 'utf-8');
+            const manifest = JSON.parse(content);
+            delete manifest[moduleName];
+            await writeFile(INSTALLED_MANIFEST, JSON.stringify(manifest, null, 2));
+        }
+        return {
+            success: true,
+            data: {
+                message: `Removed: ${moduleName}`,
+                name: moduleName,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/commands/run.d.ts

@@ -0,0 +1,12 @@
+/**
+ * cog run - Run a Cognitive Module
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export interface RunOptions {
+    args?: string;
+    input?: string;
+    noValidate?: boolean;
+    pretty?: boolean;
+    verbose?: boolean;
+}
+export declare function run(moduleName: string, ctx: CommandContext, options?: RunOptions): Promise<CommandResult>;

package/dist/commands/run.js

@@ -0,0 +1,65 @@
+/**
+ * cog run - Run a Cognitive Module
+ */
+import { findModule, getDefaultSearchPaths, runModule } from '../modules/index.js';
+export async function run(moduleName, ctx, options = {}) {
+    const searchPaths = getDefaultSearchPaths(ctx.cwd);
+    // Find module
+    const module = await findModule(moduleName, searchPaths);
+    if (!module) {
+        return {
+            success: false,
+            error: `Module not found: ${moduleName}\nSearch paths: ${searchPaths.join(', ')}`,
+        };
+    }
+    try {
+        // Parse input if provided as JSON
+        let inputData;
+        if (options.input) {
+            try {
+                inputData = JSON.parse(options.input);
+            }
+            catch {
+                return {
+                    success: false,
+                    error: `Invalid JSON input: ${options.input}`,
+                };
+            }
+        }
+        // Run module
+        const result = await runModule(module, ctx.provider, {
+            args: options.args,
+            input: inputData,
+            verbose: options.verbose || ctx.verbose,
+        });
+        // Return envelope format or extracted data
+        if (options.pretty) {
+            return {
+                success: result.ok,
+                data: result,
+            };
+        }
+        else {
+            // For non-pretty mode, return data (success) or error (failure)
+            if (result.ok) {
+                return {
+                    success: true,
+                    data: result.data,
+                };
+            }
+            else {
+                return {
+                    success: false,
+                    error: `${result.error?.code}: ${result.error?.message}`,
+                    data: result.partial_data,
+                };
+            }
+        }
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Update command - Update installed modules to latest version
+ *
+ * cog update code-simplifier
+ * cog update code-simplifier --tag v2.0.0
+ */
+import type { CommandContext, CommandResult } from '../types.js';
+export interface UpdateOptions {
+    tag?: string;
+}
+/**
+ * Update an installed module
+ */
+export declare function update(moduleName: string, ctx: CommandContext, options?: UpdateOptions): Promise<CommandResult>;