@cleocode/core 2026.4.9 → 2026.4.12

package/dist/crypto/credentials.js

@@ -0,0 +1,191 @@
+/**
+ * Credential encryption — AES-256-GCM with machine-bound key derivation.
+ *
+ * API keys (`sk_live_*`) are encrypted at rest in SQLite using AES-256-GCM.
+ * The encryption key is derived per-project from a machine-specific secret:
+ *
+ *   machine-key (32 random bytes at ~/.local/share/cleo/machine-key)
+ *   + project path
+ *   = HMAC-SHA256(machine-key, project-path) → per-project AES key
+ *
+ * This means credentials are bound to BOTH the machine AND the project.
+ * Moving `.cleo/tasks.db` to another machine renders stored keys unreadable.
+ *
+ * @see docs/specs/SIGNALDOCK-UNIFIED-AGENT-REGISTRY.md Section 3.6
+ * @module crypto/credentials
+ */
+import { execFileSync } from 'node:child_process';
+import { createCipheriv, createDecipheriv, createHmac, randomBytes } from 'node:crypto';
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+/** AES-256-GCM constants. */
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+const KEY_LENGTH = 32;
+/** Version byte prefix for ciphertext format (F-006: enables future algorithm migration). */
+const CIPHERTEXT_VERSION = 0x01;
+/**
+ * Get the path to the machine key file.
+ * Uses XDG data dir: `~/.local/share/cleo/machine-key`
+ *
+ * @throws If HOME/USERPROFILE are unset (F-002: never fall back to /tmp).
+ */
+function getMachineKeyPath() {
+    // Use platform-aware data directory: XDG on Linux, Library on macOS, %LOCALAPPDATA% on Windows
+    if (process.platform === 'win32') {
+        const appData = process.env['LOCALAPPDATA'] ?? process.env['APPDATA'];
+        if (appData)
+            return join(appData, 'cleo', 'Data', 'machine-key');
+    }
+    else if (process.platform === 'darwin') {
+        const home = process.env['HOME'];
+        if (home)
+            return join(home, 'Library', 'Application Support', 'cleo', 'machine-key');
+    }
+    // Linux / fallback: XDG_DATA_HOME or ~/.local/share
+    const dataHome = process.env['XDG_DATA_HOME'] ?? join(process.env['HOME'] ?? '', '.local', 'share');
+    if (!dataHome) {
+        throw new Error('Cannot determine data directory. Set HOME or XDG_DATA_HOME environment variable. ' +
+            'Machine key cannot be stored securely without a persistent data directory.');
+    }
+    return join(dataHome, 'cleo', 'machine-key');
+}
+/**
+ * Read or auto-generate the machine key (32 random bytes).
+ * Sets file permissions to 0600 (owner read/write only).
+ *
+ * @throws If the machine key exists but has wrong permissions (not 0600).
+ */
+async function getMachineKey() {
+    const keyPath = getMachineKeyPath();
+    try {
+        // Verify key file permissions
+        const stats = await stat(keyPath);
+        if (process.platform === 'win32') {
+            // Windows: use icacls to verify the key is not world-readable.
+            try {
+                const output = execFileSync('icacls', [keyPath], { encoding: 'utf-8', timeout: 5000 });
+                const unsafePatterns = /\\(Users|Everyone|Authenticated Users):/i;
+                if (unsafePatterns.test(output)) {
+                    throw new Error(`Machine key has unsafe Windows ACLs (accessible to other users). ` +
+                        `Fix with: icacls "${keyPath}" /inheritance:r /grant:r "%USERNAME%":F`);
+                }
+            }
+            catch (aclErr) {
+                if (aclErr instanceof Error && aclErr.message.includes('unsafe'))
+                    throw aclErr;
+            }
+        }
+        else {
+            // Unix: verify 0600 permissions
+            const mode = stats.mode & 0o777;
+            if (mode !== 0o600) {
+                throw new Error(`Machine key has unsafe permissions (${mode.toString(8)}). Expected 0600. ` +
+                    `Fix with: chmod 600 ${keyPath}`);
+            }
+        }
+        const key = await readFile(keyPath);
+        // F-004: validate key length
+        if (key.length !== KEY_LENGTH) {
+            throw new Error(`Machine key has invalid length (${key.length} bytes, expected ${KEY_LENGTH}). ` +
+                `Delete ${keyPath} and re-register agents to generate a new key.`);
+        }
+        return key;
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            // Auto-generate on first use
+            const key = randomBytes(KEY_LENGTH);
+            await mkdir(dirname(keyPath), { recursive: true });
+            await writeFile(keyPath, key, { mode: 0o600 });
+            if (process.platform === 'win32') {
+                // Lock down Windows ACLs: remove inherited permissions, grant only current user
+                try {
+                    execFileSync('icacls', [
+                        keyPath,
+                        '/inheritance:r',
+                        '/grant:r',
+                        `${process.env['USERNAME'] ?? 'CURRENT_USER'}:F`,
+                    ], { timeout: 5000 });
+                }
+                catch {
+                    // Best-effort — icacls may not be available in all environments
+                }
+            }
+            else {
+                await chmod(keyPath, 0o600);
+            }
+            return key;
+        }
+        throw err;
+    }
+}
+/**
+ * Derive a per-project encryption key from the machine key.
+ * Uses HMAC-SHA256(machine-key, project-path) to produce a 32-byte AES key.
+ */
+async function deriveProjectKey(projectPath) {
+    const machineKey = await getMachineKey();
+    return createHmac('sha256', machineKey).update(projectPath).digest();
+}
+/**
+ * Encrypt a plaintext string using AES-256-GCM with a per-project key.
+ *
+ * Output format: base64(version + iv + ciphertext + authTag)
+ *   - version: 1 byte (0x01 = AES-256-GCM)
+ *   - iv: 12 bytes
+ *   - ciphertext: variable length
+ *   - authTag: 16 bytes
+ *
+ * @param plaintext - The string to encrypt (e.g. an API key).
+ * @param projectPath - Absolute path to the project directory (used for key derivation).
+ * @returns Base64-encoded ciphertext.
+ */
+export async function encrypt(plaintext, projectPath) {
+    const key = await deriveProjectKey(projectPath);
+    const iv = randomBytes(IV_LENGTH);
+    const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    // Pack: version + iv + ciphertext + authTag (F-006: version byte for future migration)
+    const version = Buffer.from([CIPHERTEXT_VERSION]);
+    const packed = Buffer.concat([version, iv, encrypted, authTag]);
+    return packed.toString('base64');
+}
+/**
+ * Decrypt a base64-encoded ciphertext using AES-256-GCM with a per-project key.
+ *
+ * @param ciphertext - Base64-encoded string from `encrypt()`.
+ * @param projectPath - Absolute path to the project directory (must match the one used for encryption).
+ * @returns The original plaintext string.
+ * @throws If decryption fails (wrong key, corrupted data, or machine key mismatch).
+ */
+export async function decrypt(ciphertext, projectPath) {
+    const key = await deriveProjectKey(projectPath);
+    const packed = Buffer.from(ciphertext, 'base64');
+    if (packed.length < 1 + IV_LENGTH + AUTH_TAG_LENGTH) {
+        throw new Error('Cannot decrypt credentials: ciphertext too short');
+    }
+    // F-006: check version byte
+    const version = packed[0];
+    if (version !== CIPHERTEXT_VERSION) {
+        throw new Error(`Unknown ciphertext version (${version}). Expected ${CIPHERTEXT_VERSION}. ` +
+            'Re-register agents to re-encrypt with the current format.');
+    }
+    const iv = packed.subarray(1, 1 + IV_LENGTH);
+    const authTag = packed.subarray(packed.length - AUTH_TAG_LENGTH);
+    const encrypted = packed.subarray(1 + IV_LENGTH, packed.length - AUTH_TAG_LENGTH);
+    const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    decipher.setAuthTag(authTag);
+    try {
+        const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+        return decrypted.toString('utf8');
+    }
+    catch {
+        throw new Error('Cannot decrypt credentials. Machine key mismatch or corrupted data. ' +
+            'If this database was moved from another machine, re-register agents: ' +
+            'cleo agent register --id <id> --api-key <key>');
+    }
+}
+//# sourceMappingURL=credentials.js.map

package/dist/crypto/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/crypto/credentials.ts"],"names":[],"mappings":"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"}

package/dist/discovery.js

@@ -0,0 +1,182 @@
+/**
+ * Greenfield/Brownfield project discovery & classification (Phase 5).
+ *
+ * Classifies a project directory as either:
+ *   - **greenfield**: empty or nearly-empty, no code, no git history
+ *   - **brownfield**: existing codebase with files, possibly git history
+ *
+ * Used by `cleo init` (Phase 5 bootstrap) to choose the correct seed
+ * pipeline:
+ *   - Greenfield → seed a Vision/PRD "research" epic so the agent starts
+ *     from a blank-slate planning posture
+ *   - Brownfield → invoke codebase mapping and anchor findings in BRAIN as
+ *     baseline context (per ULTRAPLAN §1 "Context Anchoring")
+ *
+ * Classification is intentionally simple and transparent — no heuristics,
+ * no ML, just file/directory presence checks. A project qualifies as
+ * brownfield if ANY of these are true:
+ *   - `.git/` directory exists (under a size threshold we still treat as
+ *     brownfield since history matters)
+ *   - source files exist under common source dirs (src, lib, app, packages)
+ *   - any manifest file exists (package.json, Cargo.toml, go.mod, pyproject.toml)
+ *   - markdown docs already exist (README.md, docs/)
+ *
+ * @task Phase 5 — Greenfield/brownfield bootstrap + context anchoring
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+// ============================================================================
+// Detection helpers
+// ============================================================================
+/** Common source directory names that indicate an existing codebase. */
+const SOURCE_DIRS = ['src', 'lib', 'app', 'packages', 'crates', 'cmd', 'internal'];
+/** Manifest files that indicate a managed project. */
+const MANIFESTS = [
+    { file: 'package.json', signal: 'package-manifest', description: 'Node.js manifest' },
+    { file: 'Cargo.toml', signal: 'rust-manifest', description: 'Rust manifest' },
+    { file: 'go.mod', signal: 'go-manifest', description: 'Go manifest' },
+    { file: 'pyproject.toml', signal: 'python-manifest', description: 'Python manifest (PEP 621)' },
+    { file: 'requirements.txt', signal: 'python-manifest', description: 'Python requirements.txt' },
+    { file: 'setup.py', signal: 'python-manifest', description: 'Python setup.py' },
+];
+/** Docs files/directories that indicate prior work. */
+const DOCS_MARKERS = [
+    { path: 'README.md', signal: 'readme' },
+    { path: 'README.rst', signal: 'readme' },
+    { path: 'docs', signal: 'docs' },
+];
+/**
+ * Check if a directory (at the top level only) contains any files that are
+ * NOT part of the CLEO scaffolding itself. Used to decide whether the caller
+ * is about to `cleo init` into an already-populated directory.
+ */
+function countMeaningfulTopLevelFiles(directory) {
+    if (!existsSync(directory))
+        return 0;
+    try {
+        const entries = readdirSync(directory);
+        let count = 0;
+        for (const entry of entries) {
+            // Ignore hidden files, the CLEO dir itself, and common CI/git debris
+            if (entry.startsWith('.') ||
+                entry === '.cleo' ||
+                entry === 'node_modules' ||
+                entry === 'target' ||
+                entry === 'dist' ||
+                entry === 'build') {
+                continue;
+            }
+            count += 1;
+        }
+        return count;
+    }
+    catch {
+        return 0;
+    }
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Classify a project directory as greenfield or brownfield.
+ *
+ * Read-only — never mutates the filesystem. Safe to call at any time.
+ *
+ * @param directory - Absolute or relative path; defaults to process.cwd()
+ * @returns Classification result with signals and metadata
+ *
+ * @example
+ * ```typescript
+ * const classification = classifyProject('/my/project');
+ * if (classification.kind === 'greenfield') {
+ *   // Seed initial Vision epic
+ * } else {
+ *   // Run codebase mapping
+ * }
+ * ```
+ */
+export function classifyProject(directory) {
+    const root = resolve(directory ?? process.cwd());
+    const signals = [];
+    // Signal 1: .git directory
+    const gitPath = join(root, '.git');
+    const hasGit = existsSync(gitPath);
+    if (hasGit) {
+        signals.push({
+            id: 'git-dir',
+            description: '.git/ directory present — project has version history',
+            path: gitPath,
+        });
+    }
+    // Signal 2: manifest files
+    for (const manifest of MANIFESTS) {
+        const manifestPath = join(root, manifest.file);
+        if (existsSync(manifestPath)) {
+            signals.push({
+                id: manifest.signal,
+                description: manifest.description,
+                path: manifestPath,
+            });
+        }
+    }
+    // Signal 3: common source directories
+    for (const dir of SOURCE_DIRS) {
+        const srcPath = join(root, dir);
+        if (existsSync(srcPath) && isNonEmptyDir(srcPath)) {
+            signals.push({
+                id: 'source-dir',
+                description: `Source directory ${dir}/ contains files`,
+                path: srcPath,
+            });
+            break; // One source-dir signal is enough
+        }
+    }
+    // Signal 4: docs / README
+    for (const marker of DOCS_MARKERS) {
+        const markerPath = join(root, marker.path);
+        if (existsSync(markerPath)) {
+            signals.push({
+                id: marker.signal,
+                description: `${marker.path} present`,
+                path: markerPath,
+            });
+            break;
+        }
+    }
+    const topLevelFileCount = countMeaningfulTopLevelFiles(root);
+    // Empty signal if we have nothing
+    if (signals.length === 0 && topLevelFileCount === 0) {
+        signals.push({
+            id: 'empty',
+            description: 'No source files, manifests, git history, or docs detected',
+            path: root,
+        });
+    }
+    // Classification rule: brownfield if ANY non-'empty' signal present
+    const kind = signals.some((s) => s.id !== 'empty')
+        ? 'brownfield'
+        : 'greenfield';
+    return {
+        kind,
+        directory: root,
+        signals,
+        topLevelFileCount,
+        hasGit,
+    };
+}
+/**
+ * True if a directory exists AND contains at least one non-hidden entry.
+ */
+function isNonEmptyDir(dirPath) {
+    try {
+        const stat = statSync(dirPath);
+        if (!stat.isDirectory())
+            return false;
+        const entries = readdirSync(dirPath).filter((e) => !e.startsWith('.'));
+        return entries.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"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"}

package/dist/engine-result.js

@@ -0,0 +1,12 @@
+/**
+ * Canonical EngineResult type used by dispatch engines and core modules.
+ *
+ * This type was originally defined in src/dispatch/engines/_error.ts.
+ * Moved to core so that core modules can reference it without
+ * importing from the dispatch layer.
+ *
+ * @task T5715
+ * @epic T5701
+ */
+export {};
+//# sourceMappingURL=engine-result.js.map

package/dist/engine-result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-result.js","sourceRoot":"","sources":["../src/engine-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}