@cleocode/cant 2026.3.76

package/dist/migrate/markdown-parser.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Heuristic markdown section parser for CANT migration.
+ *
+ * Splits markdown content into sections by headings and classifies
+ * each section by matching against known agent/hook/skill/permission patterns.
+ * This is intentionally conservative -- unknown patterns are left as-is.
+ */
+import type { ExtractedPermission, ExtractedProperty, MarkdownSection, SectionClassification } from './types';
+/**
+ * Parse markdown content into classified sections.
+ *
+ * Splits on `##` and `###` headings, classifies each section by
+ * heuristic pattern matching, and returns structured section data
+ * with line numbers for source mapping.
+ *
+ * @param content - Raw markdown content
+ * @returns Array of parsed and classified sections
+ */
+export declare function parseMarkdownSections(content: string): MarkdownSection[];
+/**
+ * Classify a markdown section based on its heading and content.
+ *
+ * Uses heuristic matching against known patterns. Returns 'unknown'
+ * for sections that cannot be confidently classified.
+ *
+ * @param section - The section to classify
+ * @returns The classification type
+ */
+export declare function classifySection(section: MarkdownSection): SectionClassification;
+/**
+ * Extract key-value properties from markdown bullet lists.
+ *
+ * Matches patterns like:
+ * - `- **Key**: value`
+ * - `- **Key**: value`
+ * - `- Key: value`
+ *
+ * @param lines - Body lines of a section
+ * @returns Array of extracted properties
+ */
+export declare function extractProperties(lines: string[]): ExtractedProperty[];
+/**
+ * Extract permission entries from markdown content.
+ *
+ * Handles two formats:
+ * 1. Structured: `- Tasks: read, write`
+ * 2. Prose: `- Read and write tasks`
+ *
+ * @param lines - Body lines of a permissions section
+ * @returns Array of extracted permissions
+ */
+export declare function extractPermissions(lines: string[]): ExtractedPermission[];
+/**
+ * Normalize a heading into a valid CANT identifier.
+ *
+ * Converts "Code Review Agent" to "code-review-agent", strips
+ * common suffixes like " Agent", lowercases, and replaces
+ * non-alphanumeric chars with hyphens.
+ *
+ * @param heading - The raw heading text
+ * @returns A valid CANT identifier
+ */
+export declare function headingToIdentifier(heading: string): string;
+/**
+ * Map a hook heading to a CAAMP event name.
+ *
+ * Converts headings like "On Session Start" to "SessionStart".
+ * Returns null if the heading does not match a known event.
+ *
+ * @param heading - The raw heading text
+ * @returns The CAAMP PascalCase event name, or null
+ */
+export declare function headingToEventName(heading: string): string | null;
+/**
+ * Get the full set of CAAMP event names.
+ *
+ * @returns A read-only set of the 16 canonical CAAMP events
+ */
+export declare function getCaampEvents(): ReadonlySet<string>;

package/dist/migrate/markdown-parser.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * Heuristic markdown section parser for CANT migration.
+ *
+ * Splits markdown content into sections by headings and classifies
+ * each section by matching against known agent/hook/skill/permission patterns.
+ * This is intentionally conservative -- unknown patterns are left as-is.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseMarkdownSections = parseMarkdownSections;
+exports.classifySection = classifySection;
+exports.extractProperties = extractProperties;
+exports.extractPermissions = extractPermissions;
+exports.headingToIdentifier = headingToIdentifier;
+exports.headingToEventName = headingToEventName;
+exports.getCaampEvents = getCaampEvents;
+/**
+ * Known CAAMP hook event names (PascalCase).
+ * Used to identify hook sections from headings like "On Session Start".
+ */
+const CAAMP_EVENTS = new Set([
+    'SessionStart',
+    'SessionEnd',
+    'PromptSubmit',
+    'ResponseComplete',
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'PermissionRequest',
+    'SubagentStart',
+    'SubagentStop',
+    'PreModel',
+    'PostModel',
+    'PreCompact',
+    'PostCompact',
+    'Notification',
+    'ConfigChange',
+]);
+/**
+ * Heading patterns that suggest a hook definition section.
+ * Case-insensitive matching against heading text.
+ */
+const HOOK_HEADING_PATTERNS = [
+    /^on\s+session\s*start/i,
+    /^on\s+session\s*end/i,
+    /^on\s+prompt\s*submit/i,
+    /^on\s+response\s*complete/i,
+    /^on\s+pre\s*tool\s*use/i,
+    /^on\s+post\s*tool\s*use/i,
+    /^on\s+post\s*tool\s*use\s*failure/i,
+    /^on\s+permission\s*request/i,
+    /^on\s+subagent\s*start/i,
+    /^on\s+subagent\s*stop/i,
+    /^on\s+pre\s*model/i,
+    /^on\s+post\s*model/i,
+    /^on\s+pre\s*compact/i,
+    /^on\s+post\s*compact/i,
+    /^on\s+notification/i,
+    /^on\s+config\s*change/i,
+    /^when\s+.*\s+start/i,
+    /^when\s+.*\s+end/i,
+    /^hooks?\b/i,
+];
+/**
+ * Parse markdown content into classified sections.
+ *
+ * Splits on `##` and `###` headings, classifies each section by
+ * heuristic pattern matching, and returns structured section data
+ * with line numbers for source mapping.
+ *
+ * @param content - Raw markdown content
+ * @returns Array of parsed and classified sections
+ */
+function parseMarkdownSections(content) {
+    const lines = content.split('\n');
+    const sections = [];
+    let currentSection = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const headingMatch = line.match(/^(#{2,3})\s+(.+)$/);
+        if (headingMatch) {
+            // Finalize previous section
+            if (currentSection?.heading) {
+                finalizeSection(currentSection, i, sections);
+            }
+            const level = (headingMatch[1] ?? '').length;
+            const heading = (headingMatch[2] ?? '').trim();
+            currentSection = {
+                heading,
+                level,
+                lineStart: i + 1, // 1-based
+                bodyLines: [],
+                classification: 'unknown',
+            };
+        }
+        else if (currentSection) {
+            currentSection.bodyLines = currentSection.bodyLines ?? [];
+            currentSection.bodyLines.push(line);
+        }
+    }
+    // Finalize last section
+    if (currentSection?.heading) {
+        finalizeSection(currentSection, lines.length, sections);
+    }
+    return sections;
+}
+/**
+ * Finalize a section: set lineEnd, trim trailing blank lines, classify.
+ */
+function finalizeSection(section, nextLineIndex, sections) {
+    section.lineEnd = nextLineIndex; // 1-based exclusive becomes the end
+    // Trim trailing blank lines from body
+    while (section.bodyLines.length > 0 &&
+        (section.bodyLines[section.bodyLines.length - 1] ?? '').trim() === '') {
+        section.bodyLines.pop();
+    }
+    section.classification = classifySection(section);
+    sections.push(section);
+}
+/**
+ * Classify a markdown section based on its heading and content.
+ *
+ * Uses heuristic matching against known patterns. Returns 'unknown'
+ * for sections that cannot be confidently classified.
+ *
+ * @param section - The section to classify
+ * @returns The classification type
+ */
+function classifySection(section) {
+    const heading = section.heading;
+    // Agent patterns: "## Agent: X", "## X Agent", "## Code Review Agent"
+    if (/\bagent\b/i.test(heading)) {
+        return 'agent';
+    }
+    // Permission patterns: "## Permissions", "### Permissions"
+    if (/^permissions?\b/i.test(heading)) {
+        return 'permissions';
+    }
+    // Hook patterns
+    for (const pattern of HOOK_HEADING_PATTERNS) {
+        if (pattern.test(heading)) {
+            return 'hook';
+        }
+    }
+    // Skill patterns: "## Skills", "## Skill: X"
+    if (/\bskills?\b/i.test(heading)) {
+        return 'skill';
+    }
+    // Workflow/procedure patterns
+    if (/\b(workflow|procedure|deploy|pipeline)\b/i.test(heading)) {
+        return 'workflow';
+    }
+    // Try content-based classification for agent-like sections
+    if (hasAgentProperties(section.bodyLines)) {
+        return 'agent';
+    }
+    return 'unknown';
+}
+/**
+ * Check if body lines contain agent-like property patterns.
+ *
+ * Looks for key-value bullet lists with keys like "Model", "Prompt",
+ * "Persistence", "Skills", etc.
+ */
+function hasAgentProperties(bodyLines) {
+    const agentKeys = /\b(model|prompt|persist(ence)?|skills?)\b/i;
+    let matchCount = 0;
+    for (const line of bodyLines) {
+        if (/^[-*]\s+\*?\*?/.test(line) && agentKeys.test(line)) {
+            matchCount++;
+        }
+    }
+    // Need at least 2 agent-like properties to classify
+    return matchCount >= 2;
+}
+/**
+ * Extract key-value properties from markdown bullet lists.
+ *
+ * Matches patterns like:
+ * - `- **Key**: value`
+ * - `- **Key**: value`
+ * - `- Key: value`
+ *
+ * @param lines - Body lines of a section
+ * @returns Array of extracted properties
+ */
+function extractProperties(lines) {
+    const properties = [];
+    for (const line of lines) {
+        // Match: - **Key**: value  or  - Key: value
+        const match = line.match(/^[-*]\s+\*{0,2}([A-Za-z][A-Za-z0-9 _-]*?)\*{0,2}\s*:\s*(.+)$/);
+        if (match) {
+            const key = (match[1] ?? '').trim().toLowerCase();
+            const value = (match[2] ?? '').trim();
+            properties.push({ key, value });
+        }
+    }
+    return properties;
+}
+/**
+ * Extract permission entries from markdown content.
+ *
+ * Handles two formats:
+ * 1. Structured: `- Tasks: read, write`
+ * 2. Prose: `- Read and write tasks`
+ *
+ * @param lines - Body lines of a permissions section
+ * @returns Array of extracted permissions
+ */
+function extractPermissions(lines) {
+    const permissions = [];
+    for (const line of lines) {
+        // Format 1: "- Tasks: read, write"
+        const structuredMatch = line.match(/^[-*]\s+([A-Za-z]+)\s*:\s*(.+)$/);
+        if (structuredMatch) {
+            const domain = (structuredMatch[1] ?? '').trim().toLowerCase();
+            const rawValues = (structuredMatch[2] ?? '').trim();
+            const values = rawValues
+                .split(/[,\s]+/)
+                .map((v) => v.trim().toLowerCase())
+                .filter((v) => ['read', 'write', 'execute'].includes(v));
+            if (values.length > 0) {
+                permissions.push({ domain, values });
+                continue;
+            }
+        }
+        // Format 2: "- Read and write tasks"
+        const proseMatch = line.match(/^[-*]\s+(read|write|execute)(?:\s+and\s+(read|write|execute))?\s+(\w+)/i);
+        if (proseMatch) {
+            const values = [(proseMatch[1] ?? '').toLowerCase()];
+            if (proseMatch[2]) {
+                values.push(proseMatch[2].toLowerCase());
+            }
+            const domain = (proseMatch[3] ?? '').toLowerCase();
+            permissions.push({ domain, values });
+        }
+    }
+    return permissions;
+}
+/**
+ * Normalize a heading into a valid CANT identifier.
+ *
+ * Converts "Code Review Agent" to "code-review-agent", strips
+ * common suffixes like " Agent", lowercases, and replaces
+ * non-alphanumeric chars with hyphens.
+ *
+ * @param heading - The raw heading text
+ * @returns A valid CANT identifier
+ */
+function headingToIdentifier(heading) {
+    return heading
+        .replace(/\bagent\b/gi, '')
+        .replace(/^[:]\s*/, '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/**
+ * Map a hook heading to a CAAMP event name.
+ *
+ * Converts headings like "On Session Start" to "SessionStart".
+ * Returns null if the heading does not match a known event.
+ *
+ * @param heading - The raw heading text
+ * @returns The CAAMP PascalCase event name, or null
+ */
+function headingToEventName(heading) {
+    // Direct "On EventName" pattern
+    const onMatch = heading.match(/^on\s+(.+)$/i);
+    if (onMatch) {
+        const eventCandidate = (onMatch[1] ?? '')
+            .trim()
+            .replace(/\s+/g, '')
+            .replace(/^(\w)/, (_, c) => c.toUpperCase());
+        if (CAAMP_EVENTS.has(eventCandidate)) {
+            return eventCandidate;
+        }
+    }
+    // "When session starts" -> "SessionStart" (common prose variant)
+    const whenMatch = heading.match(/^when\s+(?:a\s+)?(\w+)\s+starts?$/i);
+    if (whenMatch) {
+        const noun = (whenMatch[1] ?? '').trim();
+        const candidate = `${noun.charAt(0).toUpperCase()}${noun.slice(1).toLowerCase()}Start`;
+        if (CAAMP_EVENTS.has(candidate)) {
+            return candidate;
+        }
+    }
+    const whenEndMatch = heading.match(/^when\s+(?:a\s+)?(\w+)\s+ends?$/i);
+    if (whenEndMatch) {
+        const noun = (whenEndMatch[1] ?? '').trim();
+        const candidate = `${noun.charAt(0).toUpperCase()}${noun.slice(1).toLowerCase()}End`;
+        if (CAAMP_EVENTS.has(candidate)) {
+            return candidate;
+        }
+    }
+    // Generic "Hooks" heading -> null (contains multiple hooks, not a single event)
+    return null;
+}
+/**
+ * Get the full set of CAAMP event names.
+ *
+ * @returns A read-only set of the 16 canonical CAAMP events
+ */
+function getCaampEvents() {
+    return CAAMP_EVENTS;
+}

package/dist/migrate/serializer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * CANT AST serializer -- generates .cant file text from structured data.
+ *
+ * Produces well-formatted .cant files with:
+ * - YAML frontmatter (kind, version)
+ * - 2-space indentation
+ * - Blank lines between top-level blocks
+ * - Proper quoting of string values
+ */
+import type { ExtractedPermission, ExtractedProperty } from './types';
+/**
+ * Intermediate representation of a CANT document for serialization.
+ *
+ * This is the bridge between the converter's output and the
+ * final .cant file text. Each field maps to a CANT construct.
+ */
+export interface CantDocumentIR {
+    /** Document kind (agent, skill, hook, workflow). */
+    kind: string;
+    /** Document version (default: 1). */
+    version: number;
+    /** The primary block (agent definition, hook, workflow, etc.). */
+    block: CantBlockIR;
+}
+/** A CANT block (agent, skill, hook, or workflow). */
+export interface CantBlockIR {
+    /** Block type keyword (agent, skill, on, workflow, pipeline). */
+    type: string;
+    /** Block name/identifier (agent name, event name, workflow name). */
+    name: string;
+    /** Key-value properties. */
+    properties: CantPropertyIR[];
+    /** Permission entries (only for agent blocks). */
+    permissions: ExtractedPermission[];
+    /** Nested sub-blocks (hooks inside agents, steps in pipelines, etc.). */
+    children: CantBlockIR[];
+    /** Raw body lines for hook/workflow bodies that are directive sequences. */
+    bodyLines?: string[];
+}
+/** A single property key-value pair. */
+export interface CantPropertyIR {
+    /** Property key. */
+    key: string;
+    /** Property value (string, array, number, boolean). */
+    value: string | string[] | number | boolean;
+}
+/**
+ * Serialize a CANT document IR into .cant file text.
+ *
+ * Produces a complete .cant file including frontmatter and body.
+ * All string values are quoted, arrays use bracket notation,
+ * and indentation uses 2 spaces per level.
+ *
+ * @param doc - The document IR to serialize
+ * @returns The complete .cant file content as a string
+ */
+export declare function serializeCantDocument(doc: CantDocumentIR): string;
+/**
+ * Format a property value for .cant output.
+ *
+ * - Strings are double-quoted
+ * - Arrays use bracket notation with quoted elements
+ * - Numbers and booleans are bare
+ *
+ * @param value - The value to format
+ * @returns Formatted string
+ */
+export declare function formatValue(value: string | string[] | number | boolean): string;
+/**
+ * Convert extracted properties to CANT property IR format.
+ *
+ * Maps known markdown property keys to their CANT equivalents:
+ * - "model" -> model
+ * - "persistence" / "persist" -> persist
+ * - "prompt" -> prompt
+ * - "skills" -> skills (as array)
+ *
+ * @param properties - Extracted markdown properties
+ * @returns CANT property IR array
+ */
+export declare function propertiesToIR(properties: ExtractedProperty[]): CantPropertyIR[];

package/dist/migrate/serializer.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * CANT AST serializer -- generates .cant file text from structured data.
+ *
+ * Produces well-formatted .cant files with:
+ * - YAML frontmatter (kind, version)
+ * - 2-space indentation
+ * - Blank lines between top-level blocks
+ * - Proper quoting of string values
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeCantDocument = serializeCantDocument;
+exports.formatValue = formatValue;
+exports.propertiesToIR = propertiesToIR;
+/**
+ * Serialize a CANT document IR into .cant file text.
+ *
+ * Produces a complete .cant file including frontmatter and body.
+ * All string values are quoted, arrays use bracket notation,
+ * and indentation uses 2 spaces per level.
+ *
+ * @param doc - The document IR to serialize
+ * @returns The complete .cant file content as a string
+ */
+function serializeCantDocument(doc) {
+    const lines = [];
+    // Frontmatter
+    lines.push('---');
+    lines.push(`kind: ${doc.kind}`);
+    lines.push(`version: ${doc.version}`);
+    lines.push('---');
+    lines.push('');
+    // Main block
+    serializeBlock(doc.block, 0, lines);
+    // Ensure trailing newline
+    return lines.join('\n') + '\n';
+}
+/**
+ * Serialize a single block at the given indentation level.
+ */
+function serializeBlock(block, indent, lines) {
+    const prefix = '  '.repeat(indent);
+    // Block header
+    lines.push(`${prefix}${block.type} ${block.name}:`);
+    const childIndent = indent + 1;
+    const childPrefix = '  '.repeat(childIndent);
+    // Properties
+    for (const prop of block.properties) {
+        lines.push(`${childPrefix}${prop.key}: ${formatValue(prop.value)}`);
+    }
+    // Permissions
+    if (block.permissions.length > 0) {
+        lines.push(`${childPrefix}permissions:`);
+        const permPrefix = '  '.repeat(childIndent + 1);
+        for (const perm of block.permissions) {
+            lines.push(`${permPrefix}${perm.domain}: ${perm.values.join(', ')}`);
+        }
+    }
+    // Body lines (directives in hooks, etc.)
+    if (block.bodyLines && block.bodyLines.length > 0) {
+        for (const bodyLine of block.bodyLines) {
+            if (bodyLine.trim() === '') {
+                lines.push('');
+            }
+            else {
+                lines.push(`${childPrefix}${bodyLine}`);
+            }
+        }
+    }
+    // Child blocks (nested hooks, pipeline steps, etc.)
+    if (block.children.length > 0) {
+        lines.push('');
+        for (const child of block.children) {
+            serializeBlock(child, childIndent, lines);
+            lines.push('');
+        }
+    }
+}
+/**
+ * Format a property value for .cant output.
+ *
+ * - Strings are double-quoted
+ * - Arrays use bracket notation with quoted elements
+ * - Numbers and booleans are bare
+ *
+ * @param value - The value to format
+ * @returns Formatted string
+ */
+function formatValue(value) {
+    if (typeof value === 'string') {
+        // Don't double-quote if already quoted or is a bare keyword
+        if (/^\d+$/.test(value) || value === 'true' || value === 'false') {
+            return value;
+        }
+        return `"${value.replace(/"/g, '\\"')}"`;
+    }
+    if (Array.isArray(value)) {
+        const elements = value.map((v) => `"${v.replace(/"/g, '\\"')}"`);
+        return `[${elements.join(', ')}]`;
+    }
+    // number or boolean
+    return String(value);
+}
+/**
+ * Convert extracted properties to CANT property IR format.
+ *
+ * Maps known markdown property keys to their CANT equivalents:
+ * - "model" -> model
+ * - "persistence" / "persist" -> persist
+ * - "prompt" -> prompt
+ * - "skills" -> skills (as array)
+ *
+ * @param properties - Extracted markdown properties
+ * @returns CANT property IR array
+ */
+function propertiesToIR(properties) {
+    const result = [];
+    for (const prop of properties) {
+        const key = normalizePropertyKey(prop.key);
+        const value = normalizePropertyValue(key, prop.value);
+        result.push({ key, value });
+    }
+    return result;
+}
+/**
+ * Normalize a markdown property key to CANT form.
+ */
+function normalizePropertyKey(key) {
+    const keyMap = {
+        model: 'model',
+        persistence: 'persist',
+        persist: 'persist',
+        prompt: 'prompt',
+        skills: 'skills',
+        skill: 'skills',
+        description: 'description',
+        tier: 'tier',
+    };
+    return keyMap[key] ?? key;
+}
+/**
+ * Normalize a property value based on the key type.
+ *
+ * Skills are converted to arrays, others remain strings.
+ */
+function normalizePropertyValue(key, value) {
+    if (key === 'skills') {
+        // "ct-cleo, ct-orchestrator" -> ["ct-cleo", "ct-orchestrator"]
+        return value
+            .split(/[,\s]+/)
+            .map((v) => v.trim())
+            .filter(Boolean);
+    }
+    return value;
+}