@cleocode/core 2026.3.66 → 2026.3.68

package/dist/issue/template-parser.js

@@ -0,0 +1,267 @@
+/**
+ * GitHub Issue Template Parser.
+ *
+ * Parses .github/ISSUE_TEMPLATE/*.yml files into JSON config.
+ * Supports three resolution strategies:
+ *   1. Live parse from YAML templates (if in a repo with templates)
+ *   2. Cached config from .cleo/issue-templates.json
+ *   3. Hardcoded fallback defaults
+ *
+ * @task T4454
+ * @epic T4454
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { BUILD_CONFIG } from '../config/build-config.js';
+import { getCleoDir, getProjectRoot } from '../paths.js';
+import { getPackageRoot } from '../scaffold.js';
+const TEMPLATE_DIR = '.github/ISSUE_TEMPLATE';
+const PACKAGED_TEMPLATE_DIR = BUILD_CONFIG.templates.issueTemplatesDir;
+const CACHE_FILE = 'issue-templates.json';
+/** Known filename-to-subcommand mappings. */
+const SUBCOMMAND_MAP = {
+    bug_report: 'bug',
+    feature_request: 'feature',
+    help_question: 'help',
+};
+/** Fallback default templates. */
+const FALLBACK_TEMPLATES = [
+    {
+        name: 'Bug Report',
+        description: 'Report a bug',
+        title: '[Bug] ',
+        labels: ['bug'],
+        subcommand: 'bug',
+        fileName: 'bug_report.yml',
+    },
+    {
+        name: 'Feature Request',
+        description: 'Suggest an enhancement',
+        title: '[Feature] ',
+        labels: ['enhancement'],
+        subcommand: 'feature',
+        fileName: 'feature_request.yml',
+    },
+    {
+        name: 'Help Question',
+        description: 'Ask a question or get help',
+        title: '[Help] ',
+        labels: ['help', 'question'],
+        subcommand: 'help',
+        fileName: 'help_question.yml',
+    },
+];
+/**
+ * Extract a YAML field value from template content.
+ * Handles simple top-level scalar fields only (not nested).
+ */
+function extractYamlField(content, field) {
+    const regex = new RegExp(`^${field}:\\s*["']?(.+?)["']?\\s*$`, 'm');
+    const match = content.match(regex);
+    return match?.[1]?.trim() ?? '';
+}
+/**
+ * Extract YAML array values (labels).
+ * Handles both inline `[a, b]` and multi-line `- a\n- b` formats.
+ */
+function extractYamlArray(content, field) {
+    // Try inline format: labels: [bug, enhancement]
+    const inlineRegex = new RegExp(`^${field}:\\s*\\[([^\\]]+)\\]`, 'm');
+    const inlineMatch = content.match(inlineRegex);
+    if (inlineMatch) {
+        return inlineMatch[1]
+            .split(',')
+            .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+            .filter(Boolean);
+    }
+    // Try multi-line format
+    const lines = content.split('\n');
+    const items = [];
+    let inArray = false;
+    for (const line of lines) {
+        if (line.match(new RegExp(`^${field}:`))) {
+            inArray = true;
+            continue;
+        }
+        if (inArray) {
+            const itemMatch = line.match(/^\s+-\s+["']?(.+?)["']?\s*$/);
+            if (itemMatch) {
+                items.push(itemMatch[1].trim());
+            }
+            else if (line.match(/^\S/)) {
+                break; // New top-level key, done
+            }
+        }
+    }
+    return items;
+}
+/**
+ * Parse a single YAML template file.
+ */
+function parseTemplateFile(filePath) {
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const content = readFileSync(filePath, 'utf-8');
+        const fileName = basename(filePath);
+        const stem = fileName.replace(/\.ya?ml$/, '');
+        const name = extractYamlField(content, 'name');
+        const description = extractYamlField(content, 'description');
+        const title = extractYamlField(content, 'title');
+        const labels = extractYamlArray(content, 'labels');
+        const subcommand = SUBCOMMAND_MAP[stem] ?? stem;
+        if (!name)
+            return null;
+        return { name, description, title, labels, subcommand, fileName };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse all issue templates from available sources.
+ * Priority:
+ *   1. Packaged templates in the CLEO installation (for npm-installed users)
+ *   2. Project's .github/ISSUE_TEMPLATE/ (for contributors working on CLEO)
+ */
+export function parseIssueTemplates(projectDir) {
+    // Strategy 1: Check packaged templates (for npm-installed users)
+    try {
+        const packageRoot = getPackageRoot();
+        const packagedTemplateDir = join(packageRoot, PACKAGED_TEMPLATE_DIR);
+        if (existsSync(packagedTemplateDir)) {
+            const templates = [];
+            for (const file of readdirSync(packagedTemplateDir)) {
+                if (!file.endsWith('.yml') && !file.endsWith('.yaml'))
+                    continue;
+                const template = parseTemplateFile(join(packagedTemplateDir, file));
+                if (template)
+                    templates.push(template);
+            }
+            if (templates.length > 0)
+                return templates;
+        }
+    }
+    catch {
+        // Fall through to next strategy
+    }
+    // Strategy 2: Check project's .github/ISSUE_TEMPLATE/ (for contributors)
+    const dir = projectDir ?? getProjectRoot();
+    const templateDir = join(dir, TEMPLATE_DIR);
+    if (!existsSync(templateDir))
+        return [];
+    const templates = [];
+    for (const file of readdirSync(templateDir)) {
+        if (!file.endsWith('.yml') && !file.endsWith('.yaml'))
+            continue;
+        const template = parseTemplateFile(join(templateDir, file));
+        if (template)
+            templates.push(template);
+    }
+    return templates;
+}
+/**
+ * Get template configuration - tries live parse, cache, then fallback.
+ */
+export function getTemplateConfig(cwd) {
+    // Strategy 1: Live parse
+    const projectDir = cwd ?? getProjectRoot();
+    const liveTemplates = parseIssueTemplates(projectDir);
+    if (liveTemplates.length > 0)
+        return liveTemplates;
+    // Strategy 2: Cached config
+    const cachePath = join(getCleoDir(cwd), CACHE_FILE);
+    if (existsSync(cachePath)) {
+        try {
+            const cached = JSON.parse(readFileSync(cachePath, 'utf-8'));
+            if (cached.templates?.length > 0)
+                return cached.templates;
+        }
+        catch {
+            // Fall through to defaults
+        }
+    }
+    // Strategy 3: Fallback defaults
+    return FALLBACK_TEMPLATES;
+}
+/**
+ * Get the template for a specific subcommand (bug, feature, etc.).
+ */
+export function getTemplateForSubcommand(subcommand, cwd) {
+    const templates = getTemplateConfig(cwd);
+    return templates.find((t) => t.subcommand === subcommand) ?? null;
+}
+/**
+ * Cache parsed templates to .cleo/issue-templates.json.
+ */
+export function cacheTemplates(templates, cwd) {
+    const cachePath = join(getCleoDir(cwd), CACHE_FILE);
+    const cache = {
+        version: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        templates,
+    };
+    writeFileSync(cachePath, JSON.stringify(cache, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Validate that labels referenced in issue templates are consistent.
+ *
+ * Collects all labels used across templates and checks that each label
+ * appears in at least one template definition. Reports any labels that
+ * are referenced by only one template but not defined as a known label
+ * across the template set. This catches typos and orphaned labels
+ * without requiring GitHub API access.
+ */
+export function validateLabelsExist(templates) {
+    if (templates.length === 0) {
+        return { valid: true, missingLabels: [] };
+    }
+    // Build a frequency map of all labels across templates
+    const labelFrequency = new Map();
+    for (const template of templates) {
+        for (const label of template.labels) {
+            labelFrequency.set(label, (labelFrequency.get(label) ?? 0) + 1);
+        }
+    }
+    // Cross-reference: each template's labels should be known across the template set.
+    // A label used by only one template AND not matching any known subcommand is suspicious.
+    const knownSubcommands = new Set(templates.map((t) => t.subcommand));
+    const knownNames = new Set(templates.map((t) => t.name.toLowerCase()));
+    const missingLabels = [];
+    for (const template of templates) {
+        for (const label of template.labels) {
+            // Check if the label is completely unknown: used once, and not matching
+            // any template subcommand or name (which would make it a valid unique label)
+            const freq = labelFrequency.get(label) ?? 0;
+            if (freq === 1 &&
+                !knownSubcommands.has(label) &&
+                !knownNames.has(label.toLowerCase()) &&
+                !WELL_KNOWN_LABELS.has(label)) {
+                missingLabels.push(label);
+            }
+        }
+    }
+    return {
+        valid: missingLabels.length === 0,
+        missingLabels,
+    };
+}
+/** Labels that are well-known in GitHub/issue trackers and always valid. */
+const WELL_KNOWN_LABELS = new Set([
+    'bug',
+    'enhancement',
+    'feature',
+    'help',
+    'question',
+    'documentation',
+    'good first issue',
+    'duplicate',
+    'invalid',
+    'wontfix',
+    'priority',
+    'critical',
+    'high',
+    'medium',
+    'low',
+]);
+//# sourceMappingURL=template-parser.js.map

package/dist/issue/template-parser.js.map

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

package/dist/json-schema-validator.js

@@ -0,0 +1,76 @@
+/**
+ * JSON Schema validation engine using ajv.
+ * @epic T4454
+ * @task T4458
+ */
+import { ExitCode } from '@cleocode/contracts';
+import { default as AjvImport } from 'ajv';
+import { default as addFormatsImport } from 'ajv-formats';
+import { CleoError } from './errors.js';
+import { readJson } from './store/json.js';
+// Handle ESM/CJS interop for Ajv and ajv-formats
+const ajvMod = AjvImport;
+const Ajv = (typeof ajvMod.default === 'function' ? ajvMod.default : AjvImport);
+const fmtMod = addFormatsImport;
+const addFormats = (typeof fmtMod.default === 'function' ? fmtMod.default : addFormatsImport);
+/** Singleton ajv instance. */
+let ajvInstance = null;
+function getAjv() {
+    if (!ajvInstance) {
+        ajvInstance = new Ajv({
+            allErrors: true,
+            strict: false,
+            allowUnionTypes: true,
+        });
+        addFormats(ajvInstance);
+    }
+    return ajvInstance;
+}
+/** Compiled schema cache. */
+const schemaCache = new Map();
+/**
+ * Validate data against a JSON Schema object.
+ * Throws CleoError on validation failure.
+ */
+export function validateAgainstSchema(data, schema, schemaId) {
+    const ajv = getAjv();
+    const cacheKey = schemaId ?? JSON.stringify(schema);
+    let validate = schemaCache.get(cacheKey);
+    if (!validate) {
+        validate = ajv.compile(schema);
+        schemaCache.set(cacheKey, validate);
+    }
+    if (!validate(data)) {
+        const errors = validate.errors
+            ?.map((e) => `${e.instancePath || '/'}: ${e.message}`)
+            .join('; ');
+        throw new CleoError(ExitCode.VALIDATION_ERROR, `Schema validation failed: ${errors ?? 'unknown error'}`);
+    }
+}
+/**
+ * Load a JSON Schema file and validate data against it.
+ */
+export async function validateAgainstSchemaFile(data, schemaPath) {
+    const schema = await readJson(schemaPath);
+    if (!schema) {
+        throw new CleoError(ExitCode.NOT_FOUND, `Schema file not found: ${schemaPath}`);
+    }
+    validateAgainstSchema(data, schema, schemaPath);
+}
+/**
+ * Check if data is valid against a schema without throwing.
+ * Returns an array of error messages (empty if valid).
+ */
+export function checkSchema(data, schema) {
+    try {
+        validateAgainstSchema(data, schema);
+        return [];
+    }
+    catch (err) {
+        if (err instanceof CleoError) {
+            return [err.message];
+        }
+        return [String(err)];
+    }
+}
+//# sourceMappingURL=json-schema-validator.js.map

package/dist/json-schema-validator.js.map

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

package/dist/lib/index.js

@@ -0,0 +1,10 @@
+/**
+ * Shared utility primitives for @cleocode/core.
+ *
+ * These modules are dependency-free and safe to import from any layer
+ * without risking circular dependencies or DB coupling.
+ *
+ * @module lib
+ */
+export { computeDelay, withRetry, } from './retry.js';
+//# sourceMappingURL=index.js.map

package/dist/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,YAAY,EAIZ,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/lib/retry.js

@@ -0,0 +1,152 @@
+/**
+ * General-purpose retry utility with exponential backoff.
+ *
+ * This module provides a shared, dependency-free retry primitive for use
+ * anywhere in the CLEO core. Unlike the agent-specific retry in
+ * `agents/retry.ts`, this utility has no database coupling and is safe to
+ * import from any layer.
+ *
+ * Default schedule (3 attempts, task T040 spec):
+ * - Attempt 1: immediate (0 ms delay before retry)
+ * - Attempt 2: 2 000 ms delay before retry
+ * - Attempt 3: 4 000 ms delay before retry
+ * - After attempt 3: throw last error
+ *
+ * @module lib/retry
+ */
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Execute an async function with automatic retry and exponential backoff.
+ *
+ * @remarks
+ * The function is called up to `maxAttempts` times. After the first failure,
+ * the utility waits `baseDelayMs` milliseconds, then retries. Each subsequent
+ * wait doubles: `baseDelayMs * 2^(attempt - 1)`, capped at `maxDelayMs`.
+ *
+ * If `retryableErrors` is supplied, only errors matching at least one entry
+ * are retried; other errors cause immediate re-throw.
+ *
+ * On final failure the original error is re-thrown. Use {@link RetryContext}
+ * fields (attached to the error) to inspect retry metadata.
+ *
+ * @example
+ * ```ts
+ * // Basic usage — 3 attempts with 0 ms / 2 000 ms / 4 000 ms delays
+ * const data = await withRetry(() => fetchFromApi());
+ *
+ * // Custom retry window — only on network errors
+ * const result = await withRetry(
+ *   () => db.query(sql),
+ *   {
+ *     maxAttempts: 5,
+ *     baseDelayMs: 500,
+ *     retryableErrors: [/SQLITE_BUSY/, /database is locked/i],
+ *   },
+ * );
+ * ```
+ *
+ * @typeParam T - The resolved type of the async function
+ * @param fn - Async factory that is called on each attempt.
+ * @param options - Optional retry configuration.
+ * @returns Resolved value of `fn` on success.
+ * @throws The last error thrown by `fn`, augmented with {@link RetryContext}
+ *   fields (`attempts`, `totalDelayMs`).
+ */
+export async function withRetry(fn, options) {
+    const maxAttempts = options?.maxAttempts ?? 3;
+    const baseDelayMs = options?.baseDelayMs ?? 2_000;
+    const maxDelayMs = options?.maxDelayMs ?? 30_000;
+    const retryableErrors = options?.retryableErrors;
+    let lastError;
+    let totalDelayMs = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            const isLastAttempt = attempt === maxAttempts;
+            if (isLastAttempt)
+                break;
+            // If a filter list is provided, only retry matching errors.
+            if (retryableErrors !== undefined && !isRetryable(err, retryableErrors))
+                break;
+            const delay = computeDelay(attempt, baseDelayMs, maxDelayMs);
+            totalDelayMs += delay;
+            await sleep(delay);
+        }
+    }
+    // Augment last error with retry context before re-throwing.
+    const context = { attempts: maxAttempts, totalDelayMs };
+    augmentError(lastError, context);
+    throw lastError;
+}
+// ============================================================================
+// Delay helpers (exported for unit testing)
+// ============================================================================
+/**
+ * Compute the wait time before the next attempt.
+ *
+ * @remarks
+ * Formula: `min(baseDelayMs * 2^(attempt - 1), maxDelayMs)`.
+ * On the first retry (`attempt === 1`) the delay is `baseDelayMs * 1 = baseDelayMs`.
+ *
+ * @example
+ * ```ts
+ * computeDelay(1, 2000, 30000); // 2000
+ * computeDelay(2, 2000, 30000); // 4000
+ * computeDelay(3, 2000, 30000); // 8000
+ * ```
+ *
+ * @param attempt - The 1-based attempt number that just failed.
+ * @param baseDelayMs - Base delay in milliseconds.
+ * @param maxDelayMs - Maximum allowed delay in milliseconds.
+ * @returns Delay in milliseconds before the next attempt.
+ */
+export function computeDelay(attempt, baseDelayMs, maxDelayMs) {
+    const exponential = baseDelayMs * 2 ** (attempt - 1);
+    return Math.min(exponential, maxDelayMs);
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/**
+ * Test whether an error matches at least one retryable predicate.
+ *
+ * @param err - The caught error.
+ * @param predicates - List of `RegExp` or predicate functions.
+ * @returns `true` if the error is retryable.
+ */
+function isRetryable(err, predicates) {
+    const message = err instanceof Error ? err.message : String(err);
+    return predicates.some((predicate) => {
+        if (predicate instanceof RegExp)
+            return predicate.test(message);
+        return predicate(err);
+    });
+}
+/**
+ * Attach `RetryContext` fields to an error value in-place when possible.
+ * Falls back gracefully for non-Error thrown values.
+ *
+ * @param err - The value to augment.
+ * @param context - Retry metadata to attach.
+ */
+function augmentError(err, context) {
+    if (err instanceof Error) {
+        const mutableErr = err;
+        mutableErr.attempts = context.attempts;
+        mutableErr.totalDelayMs = context.totalDelayMs;
+    }
+}
+/**
+ * Promisified `setTimeout` for testability.
+ *
+ * @param ms - Duration in milliseconds.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry.js.map

package/dist/lib/retry.js.map

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