@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/agents/agent-validator.js

@@ -0,0 +1,271 @@
+/**
+ * Agent Validator
+ *
+ * Validates agent metadata, content, and dependencies.
+ */
+import { validateCanonicalModelPolicy } from '../models/provider-policy.js';
+const VALID_TOOLS = [
+    'Read',
+    'Write',
+    'Bash',
+    'Grep',
+    'Glob',
+    'WebFetch',
+    'MultiEdit',
+    'Task',
+];
+const REQUIRED_FIELDS = [
+    'name',
+    'description',
+];
+export class AgentValidator {
+    /**
+     * Validate an agent
+     */
+    async validate(agent) {
+        const issues = [];
+        // Validate metadata
+        issues.push(...this.validateMetadata(agent.metadata));
+        // Validate tools
+        if (agent.metadata.tools) {
+            issues.push(...this.validateTools(agent.metadata.tools));
+        }
+        // Validate content
+        issues.push(...this.validatePrompt(agent.content));
+        // Check for errors
+        const hasErrors = issues.some((issue) => issue.type === 'error');
+        return {
+            valid: !hasErrors,
+            issues,
+            agent,
+        };
+    }
+    /**
+     * Validate metadata fields
+     */
+    validateMetadata(metadata) {
+        const issues = [];
+        // Check required fields
+        for (const field of REQUIRED_FIELDS) {
+            const value = metadata[field];
+            if (!value || (typeof value === 'string' && value.trim() === '')) {
+                issues.push({
+                    type: 'error',
+                    field,
+                    message: `Required field '${field}' is missing or empty`,
+                    suggestion: `Add ${field} to agent frontmatter`,
+                });
+            }
+        }
+        // Validate name format
+        if (metadata.name) {
+            if (!/^[a-z0-9-]+$/.test(metadata.name)) {
+                issues.push({
+                    type: 'error',
+                    field: 'name',
+                    message: 'Agent name must be lowercase alphanumeric with hyphens',
+                    suggestion: `Use format: ${metadata.name.toLowerCase().replace(/[^a-z0-9-]/g, '-')}`,
+                });
+            }
+        }
+        // Validate description length
+        if (metadata.description) {
+            if (metadata.description.length < 20) {
+                issues.push({
+                    type: 'warning',
+                    field: 'description',
+                    message: 'Description is too short (minimum 20 characters)',
+                    suggestion: 'Provide a more detailed description of agent capabilities',
+                });
+            }
+            if (metadata.description.length > 500) {
+                issues.push({
+                    type: 'warning',
+                    field: 'description',
+                    message: 'Description is very long (maximum 500 characters recommended)',
+                    suggestion: 'Keep description concise',
+                });
+            }
+        }
+        if (metadata.modelRole || metadata.modelTier) {
+            const policy = validateCanonicalModelPolicy({
+                role: metadata.modelRole ?? 'coding',
+                tier: metadata.modelTier ?? 'standard',
+            });
+            if (!policy.valid) {
+                issues.push(...policy.diagnostics.map(diagnostic => ({
+                    type: diagnostic.severity === 'error' ? 'error' : 'warning',
+                    field: 'model-policy',
+                    message: diagnostic.message,
+                    suggestion: 'Use canonical model-role/model-tier values from the shared model policy schema',
+                })));
+            }
+        }
+        // Legacy exact model aliases remain readable, but new scaffolds should use
+        // canonical model-role/model-tier intent so providers compile the final ID.
+        if (metadata.model) {
+            const compatibilityAliases = new Set(['sonnet', 'opus', 'haiku', 'gpt-4', 'gpt-3.5-turbo']);
+            if (!compatibilityAliases.has(metadata.model)) {
+                issues.push({
+                    type: 'warning',
+                    field: 'model',
+                    message: `Legacy exact model field is provider-specific: ${metadata.model}`,
+                    suggestion: 'Prefer model-role and model-tier; exact IDs should be compiled from the effective provider catalog',
+                });
+            }
+        }
+        // Validate version format
+        if (metadata.version) {
+            if (!/^\d+\.\d+\.\d+$/.test(metadata.version)) {
+                issues.push({
+                    type: 'warning',
+                    field: 'version',
+                    message: 'Version should follow semantic versioning (e.g., 1.0.0)',
+                    suggestion: 'Use format: MAJOR.MINOR.PATCH',
+                });
+            }
+        }
+        // Validate triggers completeness (#1623). When `triggers` is declared it
+        // must be a non-empty array of non-empty phrases. An explicit empty
+        // `triggers: []` (or whitespace-only entries) is the discoverability
+        // anti-pattern: a declared-but-empty NL routing surface that silently
+        // fails `aiwg discover`. Omitting the field is allowed; declaring it
+        // empty is an error so the persona-metadata regression cannot recur.
+        if (metadata.triggers !== undefined) {
+            if (!Array.isArray(metadata.triggers) || metadata.triggers.length === 0) {
+                issues.push({
+                    type: 'error',
+                    field: 'triggers',
+                    message: 'triggers is declared but empty — the discoverability anti-pattern',
+                    suggestion: 'Add at least one natural-language trigger phrase, or remove the empty field',
+                });
+            }
+            else if (metadata.triggers.some((t) => typeof t !== 'string' || t.trim() === '')) {
+                issues.push({
+                    type: 'error',
+                    field: 'triggers',
+                    message: 'triggers contains an empty or non-string phrase',
+                    suggestion: 'Remove empty trigger entries; each phrase must be a non-empty string',
+                });
+            }
+        }
+        return issues;
+    }
+    /**
+     * Validate tool names
+     */
+    validateTools(tools) {
+        const issues = [];
+        if (!Array.isArray(tools)) {
+            issues.push({
+                type: 'error',
+                field: 'tools',
+                message: 'Tools must be an array',
+                suggestion: 'Provide tools as comma-separated list or array',
+            });
+            return issues;
+        }
+        if (tools.length === 0) {
+            issues.push({
+                type: 'warning',
+                field: 'tools',
+                message: 'No tools specified',
+                suggestion: 'Agents typically need at least Read and Write tools',
+            });
+        }
+        // Check each tool
+        for (const tool of tools) {
+            const trimmedTool = tool.trim();
+            if (!VALID_TOOLS.includes(trimmedTool)) {
+                issues.push({
+                    type: 'warning',
+                    field: 'tools',
+                    message: `Unknown tool: ${trimmedTool}`,
+                    suggestion: `Valid tools: ${VALID_TOOLS.join(', ')}`,
+                });
+            }
+        }
+        return issues;
+    }
+    /**
+     * Validate prompt content
+     */
+    validatePrompt(prompt) {
+        const issues = [];
+        if (!prompt || prompt.trim() === '') {
+            issues.push({
+                type: 'error',
+                field: 'content',
+                message: 'Agent content/prompt is empty',
+                suggestion: 'Provide agent instructions and behavior',
+            });
+            return issues;
+        }
+        // Check minimum length
+        if (prompt.length < 100) {
+            issues.push({
+                type: 'warning',
+                field: 'content',
+                message: 'Agent content is very short (< 100 characters)',
+                suggestion: 'Provide more detailed instructions for the agent',
+            });
+        }
+        // Check for common issues
+        if (!prompt.includes('#')) {
+            issues.push({
+                type: 'info',
+                field: 'content',
+                message: 'Content has no headings - consider adding structure',
+                suggestion: 'Use markdown headings to organize agent instructions',
+            });
+        }
+        return issues;
+    }
+    /**
+     * Check dependencies
+     */
+    checkDependencies(agent, availableAgents) {
+        const issues = [];
+        if (!agent.metadata.dependencies || agent.metadata.dependencies.length === 0) {
+            return issues;
+        }
+        const availableNames = new Set(availableAgents.map((a) => a.metadata.name));
+        for (const dep of agent.metadata.dependencies) {
+            if (!availableNames.has(dep)) {
+                issues.push({
+                    type: 'error',
+                    field: 'dependencies',
+                    message: `Dependency not found: ${dep}`,
+                    suggestion: 'Ensure all dependencies are available for deployment',
+                });
+            }
+        }
+        // Check for circular dependencies (simple check)
+        if (agent.metadata.dependencies.includes(agent.metadata.name)) {
+            issues.push({
+                type: 'error',
+                field: 'dependencies',
+                message: 'Agent cannot depend on itself',
+                suggestion: 'Remove self-reference from dependencies',
+            });
+        }
+        return issues;
+    }
+    /**
+     * Validate batch of agents
+     */
+    async validateBatch(agents) {
+        const results = [];
+        for (const agent of agents) {
+            const result = await this.validate(agent);
+            // Also check dependencies
+            const depIssues = this.checkDependencies(agent, agents);
+            result.issues.push(...depIssues);
+            // Re-evaluate validity
+            result.valid = !result.issues.some((issue) => issue.type === 'error');
+            results.push(result);
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=agent-validator.js.map

package/dist/src/agents/grounding/knowledge-base.js

@@ -0,0 +1,161 @@
+/**
+ * Knowledge Base — load and search domain knowledge for grounding agents
+ *
+ * @module agents/grounding/knowledge-base
+ * @issue #184
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
+// ============================================================================
+// KnowledgeStore
+// ============================================================================
+export class KnowledgeStore {
+    bases;
+    projectPath;
+    constructor(projectPath) {
+        this.projectPath = projectPath;
+        this.bases = new Map();
+    }
+    /**
+     * Load knowledge bases from .aiwg/knowledge/
+     */
+    async load() {
+        const knowledgeDir = projectAiwgPath(this.projectPath, 'knowledge');
+        try {
+            const domains = await fs.readdir(knowledgeDir);
+            for (const domain of domains) {
+                const domainPath = path.join(knowledgeDir, domain);
+                const stat = await fs.stat(domainPath);
+                if (!stat.isDirectory())
+                    continue;
+                const files = await fs.readdir(domainPath);
+                const entries = [];
+                for (const file of files) {
+                    if (!file.endsWith('.json'))
+                        continue;
+                    try {
+                        const content = await fs.readFile(path.join(domainPath, file), 'utf-8');
+                        const parsed = JSON.parse(content);
+                        if (Array.isArray(parsed.entries)) {
+                            entries.push(...parsed.entries);
+                        }
+                        else if (parsed.id) {
+                            entries.push(parsed);
+                        }
+                    }
+                    catch {
+                        // Skip malformed files
+                    }
+                }
+                if (entries.length > 0) {
+                    this.bases.set(domain, {
+                        domain,
+                        version: '1.0.0',
+                        entries,
+                    });
+                }
+            }
+        }
+        catch {
+            // Knowledge directory doesn't exist yet
+        }
+    }
+    /**
+     * Add a knowledge base from a JSON file
+     */
+    async addFromFile(domain, filePath) {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(content);
+        const entries = Array.isArray(parsed.entries)
+            ? parsed.entries
+            : Array.isArray(parsed) ? parsed : [parsed];
+        const existing = this.bases.get(domain) || { domain, version: '1.0.0', entries: [] };
+        existing.entries.push(...entries);
+        this.bases.set(domain, existing);
+        // Persist
+        const domainDir = projectAiwgPath(this.projectPath, 'knowledge', domain);
+        await fs.mkdir(domainDir, { recursive: true });
+        const outFile = path.join(domainDir, path.basename(filePath));
+        await fs.copyFile(filePath, outFile);
+        return entries.length;
+    }
+    /**
+     * Search knowledge across all domains or a specific domain
+     */
+    search(query, options) {
+        const limit = options?.limit ?? 5;
+        const queryTerms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
+        const results = [];
+        const domains = options?.domain
+            ? [this.bases.get(options.domain)].filter(Boolean)
+            : Array.from(this.bases.values());
+        for (const base of domains) {
+            for (const entry of base.entries) {
+                const score = calculateRelevance(entry, queryTerms);
+                if (score > 0) {
+                    results.push({
+                        content: entry.content,
+                        source: `${base.domain}/${entry.source || entry.id}`,
+                        relevance_score: score,
+                        metadata: { topic: entry.topic, id: entry.id },
+                    });
+                }
+            }
+        }
+        return results
+            .sort((a, b) => b.relevance_score - a.relevance_score)
+            .slice(0, limit);
+    }
+    /**
+     * Verify a claim against domain knowledge
+     */
+    verifyClaim(claim, domain) {
+        const fragments = this.search(claim, { domain, limit: 3 });
+        if (fragments.length === 0) {
+            return {
+                claim,
+                verified: false,
+                confidence: 0,
+                sources: [],
+                correction: 'No relevant knowledge found in knowledge base',
+            };
+        }
+        // Simple verification: check if top fragments support or contradict
+        const topFragment = fragments[0];
+        const confidence = Math.min(topFragment.relevance_score, 1.0);
+        return {
+            claim,
+            verified: confidence > 0.3,
+            confidence,
+            sources: fragments.map((f) => f.source),
+        };
+    }
+    listDomains() {
+        return Array.from(this.bases.keys());
+    }
+    getDomainStats() {
+        return Array.from(this.bases.entries()).map(([domain, base]) => ({
+            domain,
+            entries: base.entries.length,
+        }));
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function calculateRelevance(entry, queryTerms) {
+    const searchable = [
+        entry.topic,
+        entry.content,
+        ...(entry.keywords || []),
+    ].join(' ').toLowerCase();
+    let matches = 0;
+    for (const term of queryTerms) {
+        if (searchable.includes(term)) {
+            matches++;
+        }
+    }
+    return queryTerms.length > 0 ? matches / queryTerms.length : 0;
+}
+//# sourceMappingURL=knowledge-base.js.map

package/dist/src/agents/grounding/types.js

@@ -0,0 +1,12 @@
+/**
+ * Grounding Agent Types
+ *
+ * Interfaces for domain knowledge injection agents that verify claims,
+ * retrieve knowledge, and ground conversations with factual context.
+ *
+ * @module agents/grounding/types
+ * @issue #184
+ * @research REF-022 AutoGen (ALFChat case study — 40% domain accuracy improvement)
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/agents/index.js

@@ -0,0 +1,10 @@
+/**
+ * Agent Deployment System
+ *
+ * Multi-platform agent deployment with validation and packaging.
+ */
+export * from './types.js';
+export { AgentDeployer } from './agent-deployer.js';
+export { AgentValidator } from './agent-validator.js';
+export { AgentPackager } from './agent-packager.js';
+//# sourceMappingURL=index.js.map

package/dist/src/agents/packaged-agent-inventory.js

@@ -0,0 +1,75 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+const MANAGED_MARKER_RE = /(?:^|\n)(?:#|<!--)\s*aiwg:managed\s+v?([^\s]+)\s+([^\s>]+)(?:\s*-->)?/;
+/** Normalize provider-specific deployed filenames to the source agent id. */
+export function normalizeAgentArtifactName(filename) {
+    return path.basename(filename)
+        .replace(/\.agent\.md$/i, '')
+        .replace(/\.soul\.md$/i, '')
+        .replace(/\.(?:md|mdc|toml)$/i, '');
+}
+export function parseManagedArtifactMarker(content) {
+    const match = MANAGED_MARKER_RE.exec(content);
+    return match ? { version: match[1], source: match[2] } : null;
+}
+async function collectAgentSources(frameworkRoot, rootDir, inventory, allMarkdownFiles) {
+    let entries;
+    try {
+        entries = await fs.readdir(rootDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    await Promise.all(entries.map(async (entry) => {
+        const absolute = path.join(rootDir, entry.name);
+        if (entry.isDirectory()) {
+            await collectAgentSources(frameworkRoot, absolute, inventory, allMarkdownFiles);
+            return;
+        }
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            return;
+        if (!allMarkdownFiles && path.basename(rootDir) !== 'agents')
+            return;
+        let stat;
+        try {
+            stat = await fs.stat(absolute);
+        }
+        catch {
+            return;
+        }
+        const name = normalizeAgentArtifactName(entry.name);
+        const sources = inventory.get(name) ?? [];
+        sources.push({
+            path: path.relative(frameworkRoot, absolute),
+            size: stat.size,
+        });
+        inventory.set(name, sources);
+    }));
+}
+/**
+ * Inventory every packaged agent source that can contribute to provider output.
+ * Framework, addon, and plugin agents live in named `agents/` directories;
+ * root personas live recursively below `agentic/code/agents/`.
+ */
+export async function collectPackagedAgentInventory(frameworkRoot) {
+    const inventory = new Map();
+    const codeRoot = path.join(frameworkRoot, 'agentic', 'code');
+    await Promise.all([
+        collectAgentSources(frameworkRoot, path.join(codeRoot, 'frameworks'), inventory, false),
+        collectAgentSources(frameworkRoot, path.join(codeRoot, 'addons'), inventory, false),
+        collectAgentSources(frameworkRoot, path.join(codeRoot, 'plugins'), inventory, false),
+        collectAgentSources(frameworkRoot, path.join(codeRoot, 'agents'), inventory, true),
+    ]);
+    return inventory;
+}
+/** Classify a deployed oversized file without assuming it came from the package. */
+export function diagnoseOversizedAgent(filename, content, inventory, ceilingBytes) {
+    const packaged = inventory.get(normalizeAgentArtifactName(filename)) ?? [];
+    if (packaged.some((source) => source.size > ceilingBytes))
+        return 'current-package';
+    const marker = parseManagedArtifactMarker(content);
+    if (marker?.source === 'bundled')
+        return 'stale-deployment';
+    return 'unmanaged-local';
+}
+//# sourceMappingURL=packaged-agent-inventory.js.map

package/dist/src/agents/types.js

@@ -0,0 +1,7 @@
+/**
+ * Agent Deployment System - Type Definitions
+ *
+ * Defines interfaces and types for multi-platform agent deployment.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/api/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Supported programmatic entry points for the installed AIWG package.
+ *
+ * `run()` dispatches through the same router used by `bin/aiwg.mjs`. Resource
+ * helpers expose the signed web-release contract without requiring callers to
+ * import private `dist/` paths.
+ */
+export { run } from '../cli/router.js';
+export * from '../resources/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/api/index.js

@@ -0,0 +1,10 @@
+/**
+ * Supported programmatic entry points for the installed AIWG package.
+ *
+ * `run()` dispatches through the same router used by `bin/aiwg.mjs`. Resource
+ * helpers expose the signed web-release contract without requiring callers to
+ * import private `dist/` paths.
+ */
+export { run } from '../cli/router.js';
+export * from '../resources/index.js';
+//# sourceMappingURL=index.js.map

package/dist/src/artifacts/address-parser.js

@@ -0,0 +1,73 @@
+/**
+ * Address Parser — parse hybrid addressing syntax into queries
+ *
+ * Syntaxes:
+ *   @.aiwg/requirements/UC-001.md     → location
+ *   @?"user authentication"            → semantic
+ *   @.aiwg/requirements/?"auth"        → hybrid
+ *   @#security,authentication           → tags
+ *   @phase:requirements                 → phase
+ *
+ * @module artifacts/address-parser
+ * @issue #187
+ */
+// ============================================================================
+// Parser
+// ============================================================================
+/**
+ * Parse an address string into a HybridQuery.
+ */
+export function parseAddress(input) {
+    const raw = input.trim();
+    // Remove leading @ if present
+    const addr = raw.startsWith('@') ? raw.slice(1) : raw;
+    // @#tag1,tag2 → tags
+    if (addr.startsWith('#')) {
+        const tags = addr.slice(1).split(',').map((t) => t.trim()).filter(Boolean);
+        return { type: 'tags', query: { tags }, raw };
+    }
+    // @phase:requirements → phase
+    if (addr.startsWith('phase:')) {
+        const phase = addr.slice(6).trim();
+        return { type: 'phase', query: { phase }, raw };
+    }
+    // @?"query" → semantic
+    if (addr.startsWith('?"') || addr.startsWith('?\'')) {
+        const semanticQuery = addr.slice(2, -1);
+        return { type: 'semantic', query: { semanticQuery }, raw };
+    }
+    // @path/?"query" → hybrid
+    const hybridMatch = addr.match(/^(.+?)\/\?"([^"]+)"$/);
+    if (hybridMatch) {
+        return {
+            type: 'hybrid',
+            query: { path: hybridMatch[1], semanticQuery: hybridMatch[2] },
+            raw,
+        };
+    }
+    const hybridMatchSingle = addr.match(/^(.+?)\/\?'([^']+)'$/);
+    if (hybridMatchSingle) {
+        return {
+            type: 'hybrid',
+            query: { path: hybridMatchSingle[1], semanticQuery: hybridMatchSingle[2] },
+            raw,
+        };
+    }
+    // Default: location (file path or glob)
+    return { type: 'location', query: { path: addr }, raw };
+}
+/**
+ * Build a HybridQuery from multiple criteria (CLI-style).
+ */
+export function buildQuery(options) {
+    return {
+        path: options.path,
+        semanticQuery: options.query,
+        tags: options.tags?.split(',').map((t) => t.trim()).filter(Boolean),
+        phase: options.phase,
+        type: options.type,
+        updatedAfter: options.since,
+        limit: options.limit,
+    };
+}
+//# sourceMappingURL=address-parser.js.map