cli4ai 0.8.0

package/src/core/link.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Tests for link.ts
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { tmpdir, homedir } from 'os';
+import {
+  ensureBinDir,
+  linkPackage,
+  linkPackageDirect,
+  unlinkPackage,
+  isPackageLinked,
+  getPathInstructions,
+  isBinInPath,
+  C4AI_BIN
+} from './link.js';
+import type { Manifest } from './manifest.js';
+
+describe('link', () => {
+  let tempDir: string;
+  let testBinDir: string;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'cli4ai-link-test-'));
+    testBinDir = join(tempDir, 'bin');
+    mkdirSync(testBinDir);
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  const createMockManifest = (name: string, version = '1.0.0'): Manifest => ({
+    name,
+    version,
+    entry: 'run.ts',
+    runtime: 'bun'
+  });
+
+  describe('C4AI_BIN constant', () => {
+    test('is in home directory', () => {
+      expect(C4AI_BIN).toBe(resolve(homedir(), '.cli4ai', 'bin'));
+    });
+  });
+
+  describe('ensureBinDir', () => {
+    test('creates bin directory if not exists', () => {
+      // This test affects real filesystem, so we just verify function doesn't throw
+      expect(() => ensureBinDir()).not.toThrow();
+      expect(existsSync(C4AI_BIN)).toBe(true);
+    });
+  });
+
+  describe('linkPackage', () => {
+    test('creates wrapper script', () => {
+      const manifest = createMockManifest('test-tool');
+      const packagePath = join(tempDir, 'test-tool');
+
+      const binPath = linkPackage(manifest, packagePath);
+
+      expect(existsSync(binPath)).toBe(true);
+      const content = readFileSync(binPath, 'utf-8');
+      expect(content).toContain('#!/bin/sh');
+      // SECURITY: Package names are shell-escaped with single quotes
+      expect(content).toContain("cli4ai run 'test-tool'");
+    });
+
+    test('makes script executable', () => {
+      const manifest = createMockManifest('test-tool');
+      const packagePath = join(tempDir, 'test-tool');
+
+      const binPath = linkPackage(manifest, packagePath);
+
+      const stat = statSync(binPath);
+      // Check executable bit (0o755 = rwxr-xr-x)
+      const isExecutable = (stat.mode & 0o111) !== 0;
+      expect(isExecutable).toBe(true);
+    });
+
+    test('includes version in comment', () => {
+      const manifest = createMockManifest('my-tool', '2.5.0');
+      const packagePath = join(tempDir, 'my-tool');
+
+      const binPath = linkPackage(manifest, packagePath);
+
+      const content = readFileSync(binPath, 'utf-8');
+      // SECURITY: Version is shell-escaped in comment
+      expect(content).toContain("'my-tool'@'2.5.0'");
+    });
+  });
+
+  describe('linkPackageDirect', () => {
+    test('creates direct wrapper script', () => {
+      const manifest = createMockManifest('direct-tool');
+      const packagePath = join(tempDir, 'direct-tool');
+
+      const binPath = linkPackageDirect(manifest, packagePath);
+
+      expect(existsSync(binPath)).toBe(true);
+      const content = readFileSync(binPath, 'utf-8');
+      expect(content).toContain('#!/bin/sh');
+      expect(content).toContain('bun run');
+      expect(content).toContain('run.ts');
+    });
+
+    test('uses correct runtime from manifest (node)', () => {
+      const manifest: Manifest = {
+        name: 'node-tool',
+        version: '1.0.0',
+        entry: 'index.js',
+        runtime: 'node'
+      };
+      const packagePath = join(tempDir, 'node-tool');
+
+      const binPath = linkPackageDirect(manifest, packagePath);
+
+      const content = readFileSync(binPath, 'utf-8');
+      // Node.js doesn't use 'run' subcommand - it's just 'node <file>'
+      // SECURITY: Paths are now shell-escaped with single quotes
+      expect(content).toContain("exec node '");
+      expect(content).not.toContain('node run');
+    });
+
+    test('defaults to bun runtime', () => {
+      const manifest: Manifest = {
+        name: 'no-runtime',
+        version: '1.0.0',
+        entry: 'run.ts'
+        // no runtime specified
+      };
+      const packagePath = join(tempDir, 'no-runtime');
+
+      const binPath = linkPackageDirect(manifest, packagePath);
+
+      const content = readFileSync(binPath, 'utf-8');
+      expect(content).toContain('bun run');
+    });
+
+    test('includes full path to entry', () => {
+      const manifest = createMockManifest('path-tool');
+      const packagePath = join(tempDir, 'path-tool');
+
+      const binPath = linkPackageDirect(manifest, packagePath);
+
+      const content = readFileSync(binPath, 'utf-8');
+      expect(content).toContain(resolve(packagePath, 'run.ts'));
+    });
+  });
+
+  describe('unlinkPackage', () => {
+    test('removes linked package', () => {
+      const manifest = createMockManifest('unlink-test');
+      const packagePath = join(tempDir, 'unlink-test');
+
+      const binPath = linkPackage(manifest, packagePath);
+      expect(existsSync(binPath)).toBe(true);
+
+      const result = unlinkPackage('unlink-test');
+
+      expect(result).toBe(true);
+      expect(existsSync(binPath)).toBe(false);
+    });
+
+    test('returns false for non-existent package', () => {
+      const result = unlinkPackage('nonexistent-package-name');
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('isPackageLinked', () => {
+    test('returns true for linked package', () => {
+      const manifest = createMockManifest('linked-tool');
+      const packagePath = join(tempDir, 'linked-tool');
+
+      linkPackage(manifest, packagePath);
+
+      expect(isPackageLinked('linked-tool')).toBe(true);
+    });
+
+    test('returns false for unlinked package', () => {
+      expect(isPackageLinked('not-linked-tool')).toBe(false);
+    });
+  });
+
+  describe('getPathInstructions', () => {
+    test('returns instructions string', () => {
+      const instructions = getPathInstructions();
+
+      expect(instructions).toContain('export PATH=');
+      expect(instructions).toContain(C4AI_BIN);
+      expect(instructions).toContain('source');
+    });
+
+    test('detects zsh shell', () => {
+      const originalShell = process.env.SHELL;
+      process.env.SHELL = '/bin/zsh';
+
+      const instructions = getPathInstructions();
+
+      expect(instructions).toContain('.zshrc');
+
+      process.env.SHELL = originalShell;
+    });
+
+    test('defaults to bash', () => {
+      const originalShell = process.env.SHELL;
+      process.env.SHELL = '/bin/bash';
+
+      const instructions = getPathInstructions();
+
+      expect(instructions).toContain('.bashrc');
+
+      process.env.SHELL = originalShell;
+    });
+  });
+
+  describe('isBinInPath', () => {
+    test('returns true when bin in PATH', () => {
+      const originalPath = process.env.PATH;
+      process.env.PATH = `${C4AI_BIN}:${originalPath}`;
+
+      expect(isBinInPath()).toBe(true);
+
+      process.env.PATH = originalPath;
+    });
+
+    test('returns false when bin not in PATH', () => {
+      const originalPath = process.env.PATH;
+      process.env.PATH = '/usr/bin:/usr/local/bin';
+
+      expect(isBinInPath()).toBe(false);
+
+      process.env.PATH = originalPath;
+    });
+  });
+});

package/src/core/link.ts

@@ -0,0 +1,190 @@
+/**
+ * PATH linking for global packages
+ *
+ * Creates executable symlinks in ~/.cli4ai/bin/ that can be added to PATH
+ */
+
+import { existsSync, mkdirSync, symlinkSync, unlinkSync, writeFileSync, chmodSync } from 'fs';
+import { resolve, join } from 'path';
+import { homedir } from 'os';
+import { type Manifest } from './manifest.js';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 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: string): boolean {
+  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: string): string {
+  // 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(): void {
+  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: Manifest, packagePath: string): string {
+  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);
+  chmodSync(binPath, 0o755);
+
+  return binPath;
+}
+
+/**
+ * Create direct executable wrapper that runs the tool directly
+ *
+ * This is faster than going through cli4ai run
+ */
+export function linkPackageDirect(manifest: Manifest, packagePath: string): string {
+  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);
+  const runtime = manifest.runtime || 'bun';
+
+  // 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 based on runtime type
+  // - bun: bun run <file>
+  // - node: node <file>
+  let execCommand: string;
+  switch (runtime) {
+    case 'node':
+      execCommand = `node ${safeEntryPath}`;
+      break;
+    case 'bun':
+    default:
+      execCommand = `bun run ${safeEntryPath}`;
+      break;
+  }
+
+  // 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);
+  chmodSync(binPath, 0o755);
+
+  return binPath;
+}
+
+/**
+ * Remove executable link for a package
+ */
+export function unlinkPackage(packageName: string): boolean {
+  const binPath = join(C4AI_BIN, packageName);
+
+  if (existsSync(binPath)) {
+    unlinkSync(binPath);
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Check if a package is linked
+ */
+export function isPackageLinked(packageName: string): boolean {
+  return existsSync(join(C4AI_BIN, packageName));
+}
+
+/**
+ * Get PATH setup instructions
+ */
+export function getPathInstructions(): string {
+  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(): boolean {
+  const pathEnv = process.env.PATH || '';
+  return pathEnv.split(':').some(p => resolve(p) === C4AI_BIN);
+}