cli4ai 1.2.0 → 1.2.2

package/dist/core/link.js

@@ -0,0 +1,214 @@
+/**
+ * PATH linking for global packages
+ *
+ * Creates executable symlinks in ~/.cli4ai/bin/ that can be added to PATH
+ */
+import { existsSync, mkdirSync, unlinkSync, writeFileSync, chmodSync } from 'fs';
+import { resolve, join } from 'path';
+import { homedir } from 'os';
+// ═══════════════════════════════════════════════════════════════════════════
+// SECURITY: Shell escaping for safe script generation
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Validate that a string is safe for shell script embedding.
+ * Only allows alphanumeric, hyphens, underscores, and dots.
+ * This is a strict allowlist approach for defense in depth.
+ */
+function isShellSafe(value) {
+    return /^[a-zA-Z0-9._-]+$/.test(value);
+}
+/**
+ * Escape a string for safe embedding in shell scripts.
+ * Uses single quotes which prevent all shell interpretation except for single quotes themselves.
+ */
+function shellEscape(value) {
+    // Single quotes prevent shell interpretation; escape any single quotes in the value
+    // by ending the single-quoted string, adding an escaped single quote, and starting a new single-quoted string
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// PATHS
+// ═══════════════════════════════════════════════════════════════════════════
+export const C4AI_BIN = resolve(homedir(), '.cli4ai', 'bin');
+// ═══════════════════════════════════════════════════════════════════════════
+// FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Ensure bin directory exists
+ */
+export function ensureBinDir() {
+    if (!existsSync(C4AI_BIN)) {
+        mkdirSync(C4AI_BIN, { recursive: true });
+    }
+}
+/**
+ * Create executable wrapper script for a package
+ *
+ * Creates a shell script that invokes `cli4ai run <package> [args]`
+ */
+export function linkPackage(manifest, packagePath) {
+    ensureBinDir();
+    // SECURITY: Validate manifest values before embedding in shell script
+    if (!isShellSafe(manifest.name)) {
+        throw new Error(`Invalid package name for shell script: ${manifest.name}`);
+    }
+    if (!isShellSafe(manifest.version)) {
+        throw new Error(`Invalid package version for shell script: ${manifest.version}`);
+    }
+    const binPath = join(C4AI_BIN, manifest.name);
+    // Create wrapper script with escaped values for defense in depth
+    const safeName = shellEscape(manifest.name);
+    const safeVersion = shellEscape(manifest.version);
+    const script = `#!/bin/sh
+# cli4ai wrapper for ${safeName}@${safeVersion}
+# Auto-generated - do not edit
+
+exec cli4ai run ${safeName} "$@"
+`;
+    writeFileSync(binPath, script);
+    if (process.platform !== 'win32') {
+        chmodSync(binPath, 0o755);
+    }
+    // Windows compatibility: generate .cmd and .ps1 launchers
+    if (process.platform === 'win32') {
+        const cmdContent = `@echo off\r\ncli4ai run ${manifest.name} %*\r\nexit /b %errorlevel%\r\n`;
+        writeFileSync(binPath + '.cmd', cmdContent);
+        const ps1Content = `& cli4ai run ${manifest.name} @args\nexit $LASTEXITCODE\n`;
+        writeFileSync(binPath + '.ps1', ps1Content);
+    }
+    return binPath;
+}
+/**
+ * Create direct executable wrapper that runs the tool directly
+ *
+ * This is faster than going through cli4ai run
+ */
+export function linkPackageDirect(manifest, packagePath) {
+    ensureBinDir();
+    // SECURITY: Validate manifest values before embedding in shell script
+    if (!isShellSafe(manifest.name)) {
+        throw new Error(`Invalid package name for shell script: ${manifest.name}`);
+    }
+    if (!isShellSafe(manifest.version)) {
+        throw new Error(`Invalid package version for shell script: ${manifest.version}`);
+    }
+    const binPath = join(C4AI_BIN, manifest.name);
+    const entryPath = resolve(packagePath, manifest.entry);
+    // SECURITY: Shell-escape the entry path to prevent injection
+    const safeEntryPath = shellEscape(entryPath);
+    const safeName = shellEscape(manifest.name);
+    const safeVersion = shellEscape(manifest.version);
+    // Build runtime command - use tsx for TypeScript, node for JavaScript
+    let execCommand;
+    if (entryPath.endsWith('.ts') || entryPath.endsWith('.tsx')) {
+        execCommand = `npx tsx ${safeEntryPath}`;
+    }
+    else {
+        execCommand = `node ${safeEntryPath}`;
+    }
+    // Create wrapper script that runs the tool directly
+    const script = `#!/bin/sh
+# cli4ai wrapper for ${safeName}@${safeVersion}
+# Auto-generated - do not edit
+
+exec ${execCommand} "$@"
+`;
+    writeFileSync(binPath, script);
+    if (process.platform !== 'win32') {
+        chmodSync(binPath, 0o755);
+    }
+    // Windows compatibility: generate .cmd and .ps1 launchers
+    if (process.platform === 'win32') {
+        const quotedEntry = `"${entryPath.replaceAll('"', '""')}"`;
+        let cmdContent;
+        let ps1Content;
+        if (entryPath.endsWith('.ts') || entryPath.endsWith('.tsx')) {
+            cmdContent = `@echo off\r\nnpx tsx ${quotedEntry} %*\r\nexit /b %errorlevel%\r\n`;
+            ps1Content = `& npx tsx ${quotedEntry} @args\nexit $LASTEXITCODE\n`;
+        }
+        else {
+            cmdContent = `@echo off\r\nnode ${quotedEntry} %*\r\nexit /b %errorlevel%\r\n`;
+            ps1Content = `& node ${quotedEntry} @args\nexit $LASTEXITCODE\n`;
+        }
+        writeFileSync(binPath + '.cmd', cmdContent);
+        writeFileSync(binPath + '.ps1', ps1Content);
+    }
+    return binPath;
+}
+/**
+ * Remove executable link for a package
+ */
+export function unlinkPackage(packageName) {
+    // SECURITY: Validate package name to prevent path traversal
+    if (!isShellSafe(packageName) || packageName.includes('..')) {
+        throw new Error(`Invalid package name: ${packageName}`);
+    }
+    const basePath = join(C4AI_BIN, packageName);
+    const candidates = process.platform === 'win32'
+        ? [basePath, basePath + '.cmd', basePath + '.ps1']
+        : [basePath];
+    let removed = false;
+    for (const path of candidates) {
+        if (existsSync(path)) {
+            unlinkSync(path);
+            removed = true;
+        }
+    }
+    return removed;
+}
+/**
+ * Check if a package is linked
+ */
+export function isPackageLinked(packageName) {
+    const basePath = join(C4AI_BIN, packageName);
+    if (existsSync(basePath))
+        return true;
+    if (process.platform === 'win32') {
+        if (existsSync(basePath + '.cmd'))
+            return true;
+        if (existsSync(basePath + '.ps1'))
+            return true;
+    }
+    return false;
+}
+/**
+ * Get PATH setup instructions
+ */
+export function getPathInstructions() {
+    if (process.platform === 'win32') {
+        return `
+To use globally installed cli4ai packages from anywhere, add the bin directory to your PATH:
+
+  ${C4AI_BIN}
+
+On Windows, you can:
+1. Use System Settings > Edit environment variables (GUI)
+2. Or run in PowerShell (current session): $env:PATH += ";${C4AI_BIN}"
+3. Or run in PowerShell (permanent): [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";${C4AI_BIN}", "User")
+
+Then restart your terminal.
+`.trim();
+    }
+    const shell = process.env.SHELL || '/bin/bash';
+    const isZsh = shell.includes('zsh');
+    const rcFile = isZsh ? '~/.zshrc' : '~/.bashrc';
+    return `
+To use globally installed cli4ai packages from anywhere, add this to your ${rcFile}:
+
+  export PATH="${C4AI_BIN}:$PATH"
+
+Then reload your shell:
+
+  source ${rcFile}
+
+Or start a new terminal session.
+`.trim();
+}
+/**
+ * Check if bin directory is in PATH
+ */
+export function isBinInPath() {
+    const pathEnv = process.env.PATH || '';
+    const separator = process.platform === 'win32' ? ';' : ':';
+    return pathEnv.split(separator).some(p => resolve(p) === C4AI_BIN);
+}

package/dist/core/lockfile.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Lock file management (cli4ai.lock)
+ *
+ * Tracks installed packages with exact versions and sources
+ * for reproducible installations.
+ */
+export interface LockedPackage {
+    name: string;
+    version: string;
+    resolved: string;
+    integrity?: string;
+    dependencies?: Record<string, string>;
+}
+export interface Lockfile {
+    lockfileVersion: number;
+    packages: Record<string, LockedPackage>;
+}
+export declare const LOCKFILE_NAME = "cli4ai.lock";
+export declare const LOCKFILE_VERSION = 1;
+/**
+ * Get lock file path for a project
+ */
+export declare function getLockfilePath(projectDir: string): string;
+/**
+ * Check if lock file exists
+ */
+export declare function lockfileExists(projectDir: string): boolean;
+/**
+ * Load lock file, returns empty lockfile if doesn't exist
+ */
+export declare function loadLockfile(projectDir: string): Lockfile;
+/**
+ * Save lock file
+ */
+export declare function saveLockfile(projectDir: string, lockfile: Lockfile): void;
+/**
+ * Add or update a package in the lock file
+ */
+export declare function lockPackage(projectDir: string, pkg: LockedPackage): void;
+/**
+ * Remove a package from the lock file
+ */
+export declare function unlockPackage(projectDir: string, packageName: string): void;
+/**
+ * Get a locked package by name
+ */
+export declare function getLockedPackage(projectDir: string, packageName: string): LockedPackage | null;
+/**
+ * Get all locked packages
+ */
+export declare function getLockedPackages(projectDir: string): LockedPackage[];
+/**
+ * Check if a package is locked
+ */
+export declare function isPackageLocked(projectDir: string, packageName: string): boolean;
+/**
+ * Clear all packages from lock file
+ */
+export declare function clearLockfile(projectDir: string): void;
+/**
+ * Format lock file as human-readable string
+ */
+export declare function formatLockfile(lockfile: Lockfile): string;

package/dist/core/lockfile.js

@@ -0,0 +1,140 @@
+/**
+ * Lock file management (cli4ai.lock)
+ *
+ * Tracks installed packages with exact versions and sources
+ * for reproducible installations.
+ */
+import { readFileSync, writeFileSync, renameSync, existsSync } from 'fs';
+import { resolve } from 'path';
+// ═══════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════
+export const LOCKFILE_NAME = 'cli4ai.lock';
+export const LOCKFILE_VERSION = 1;
+// ═══════════════════════════════════════════════════════════════════════════
+// FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Get lock file path for a project
+ */
+export function getLockfilePath(projectDir) {
+    return resolve(projectDir, LOCKFILE_NAME);
+}
+/**
+ * Check if lock file exists
+ */
+export function lockfileExists(projectDir) {
+    return existsSync(getLockfilePath(projectDir));
+}
+/**
+ * Load lock file, returns empty lockfile if doesn't exist
+ */
+export function loadLockfile(projectDir) {
+    const lockfilePath = getLockfilePath(projectDir);
+    if (!existsSync(lockfilePath)) {
+        return {
+            lockfileVersion: LOCKFILE_VERSION,
+            packages: {}
+        };
+    }
+    try {
+        const content = readFileSync(lockfilePath, 'utf-8');
+        const data = JSON.parse(content);
+        // Validate version
+        if (data.lockfileVersion !== LOCKFILE_VERSION) {
+            console.error(`Warning: Lock file version mismatch (${data.lockfileVersion} vs ${LOCKFILE_VERSION})`);
+        }
+        return data;
+    }
+    catch (err) {
+        console.error('Warning: Could not parse lock file, starting fresh');
+        return {
+            lockfileVersion: LOCKFILE_VERSION,
+            packages: {}
+        };
+    }
+}
+/**
+ * Save lock file
+ */
+export function saveLockfile(projectDir, lockfile) {
+    const lockfilePath = getLockfilePath(projectDir);
+    const content = JSON.stringify(lockfile, null, 2) + '\n';
+    const tmpPath = lockfilePath + '.tmp';
+    writeFileSync(tmpPath, content);
+    renameSync(tmpPath, lockfilePath);
+}
+/**
+ * Add or update a package in the lock file
+ */
+export function lockPackage(projectDir, pkg) {
+    const lockfile = loadLockfile(projectDir);
+    lockfile.packages[pkg.name] = pkg;
+    saveLockfile(projectDir, lockfile);
+}
+/**
+ * Remove a package from the lock file
+ */
+export function unlockPackage(projectDir, packageName) {
+    const lockfile = loadLockfile(projectDir);
+    if (lockfile.packages[packageName]) {
+        delete lockfile.packages[packageName];
+        saveLockfile(projectDir, lockfile);
+    }
+}
+/**
+ * Get a locked package by name
+ */
+export function getLockedPackage(projectDir, packageName) {
+    const lockfile = loadLockfile(projectDir);
+    return lockfile.packages[packageName] || null;
+}
+/**
+ * Get all locked packages
+ */
+export function getLockedPackages(projectDir) {
+    const lockfile = loadLockfile(projectDir);
+    return Object.values(lockfile.packages);
+}
+/**
+ * Check if a package is locked
+ */
+export function isPackageLocked(projectDir, packageName) {
+    const lockfile = loadLockfile(projectDir);
+    return packageName in lockfile.packages;
+}
+/**
+ * Clear all packages from lock file
+ */
+export function clearLockfile(projectDir) {
+    saveLockfile(projectDir, {
+        lockfileVersion: LOCKFILE_VERSION,
+        packages: {}
+    });
+}
+/**
+ * Format lock file as human-readable string
+ */
+export function formatLockfile(lockfile) {
+    const lines = [
+        `# cli4ai.lock - Auto-generated, do not edit`,
+        `# lockfileVersion: ${lockfile.lockfileVersion}`,
+        ``
+    ];
+    const sortedPackages = Object.values(lockfile.packages).sort((a, b) => a.name.localeCompare(b.name));
+    for (const pkg of sortedPackages) {
+        lines.push(`${pkg.name}@${pkg.version}:`);
+        lines.push(`  resolved: "${pkg.resolved}"`);
+        if (pkg.integrity) {
+            lines.push(`  integrity: ${pkg.integrity}`);
+        }
+        if (pkg.dependencies && Object.keys(pkg.dependencies).length > 0) {
+            lines.push(`  dependencies:`);
+            for (const [depName, depVersion] of Object.entries(pkg.dependencies)) {
+                lines.push(`    ${depName}: "${depVersion}"`);
+            }
+        }
+        lines.push(``);
+    }
+    return lines.join('\n');
+}

package/dist/core/manifest.d.ts

@@ -0,0 +1,96 @@
+/**
+ * cli4ai.json manifest validation and parsing
+ */
+export declare class ManifestValidationError extends Error {
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, details?: Record<string, unknown> | undefined);
+}
+export interface CommandArg {
+    name: string;
+    description?: string;
+    required?: boolean;
+    type?: 'string' | 'number' | 'boolean';
+    default?: string | number | boolean;
+}
+export interface CommandOption {
+    name: string;
+    short?: string;
+    description?: string;
+    type?: 'string' | 'number' | 'boolean';
+    default?: string | number | boolean;
+}
+export interface CommandDef {
+    description: string;
+    args?: CommandArg[];
+    options?: CommandOption[];
+}
+export interface EnvDef {
+    required?: boolean;
+    description?: string;
+    default?: string;
+    secret?: boolean;
+}
+export interface McpConfig {
+    enabled?: boolean;
+    transport?: 'stdio' | 'http';
+    port?: number;
+}
+export interface Manifest {
+    name: string;
+    version: string;
+    entry: string;
+    description?: string;
+    author?: string;
+    license?: string;
+    repository?: string;
+    homepage?: string;
+    keywords?: string[];
+    runtime?: 'node' | 'bun';
+    commands?: Record<string, CommandDef>;
+    env?: Record<string, EnvDef>;
+    dependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    mcp?: McpConfig;
+    scripts?: Record<string, string>;
+    files?: string[];
+}
+export declare function validateManifest(manifest: unknown, source?: string): Manifest;
+export declare const MANIFEST_FILENAME = "cli4ai.json";
+export declare class ManifestNotFoundError extends Error {
+    path: string;
+    constructor(path: string);
+}
+export declare class ManifestParseError extends Error {
+    path: string;
+    constructor(path: string, message: string);
+}
+/**
+ * Load and validate cli4ai.json from a directory (throws on error)
+ * Use this for programmatic/testable usage
+ */
+export declare function loadManifestOrThrow(dir: string): Manifest;
+/**
+ * Load manifest from package.json (fallback for npm packages)
+ */
+export declare function loadFromPackageJson(dir: string): Manifest | null;
+/**
+ * Load and validate cli4ai.json from a directory
+ * Falls back to package.json for npm packages
+ * Exits with error on failure (for CLI usage)
+ */
+export declare function loadManifest(dir: string): Manifest;
+/**
+ * Try to load manifest, return null if not found
+ */
+export declare function tryLoadManifest(dir: string): Manifest | null;
+/**
+ * Find manifest by walking up directory tree
+ */
+export declare function findManifest(startDir?: string): {
+    manifest: Manifest;
+    dir: string;
+} | null;
+/**
+ * Create a minimal manifest
+ */
+export declare function createManifest(name: string, options?: Partial<Manifest>): Manifest;