@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/lint/runner.js

@@ -0,0 +1,364 @@
+/**
+ * Lint Runner
+ *
+ * Core lint execution engine. Matches rules to files,
+ * runs checks, and collects diagnostics.
+ *
+ * @issue #810
+ */
+import fs from 'fs';
+import fsp from 'fs/promises';
+import path from 'path';
+import { glob } from 'glob';
+import { minimatch } from 'minimatch';
+/**
+ * Parse YAML-style frontmatter from a markdown file
+ * Returns key-value pairs from the --- delimited block
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return {};
+    const result = {};
+    for (const line of match[1].split('\n')) {
+        const kv = line.match(/^(\w[\w-]*)\s*:\s*(.+)$/);
+        if (kv) {
+            result[kv[1]] = kv[2].trim().replace(/^["']|["']$/g, '');
+        }
+    }
+    return result;
+}
+const DEFAULT_REFERENCE_PATTERN = '\\bREF-\\d{3,}\\b';
+/**
+ * Build a target-wide artifact ID index once per lint run.
+ *
+ * Reference documents may use either an exact filename (`REF-001.md`) or the
+ * canonical slugged form (`REF-001-some-title.md`). Indexing the ID prefix also
+ * makes resolution independent of a particular corpus directory layout.
+ */
+function buildReferenceIndex(allFiles) {
+    const references = new Set();
+    for (const file of allFiles) {
+        if (path.extname(file).toLowerCase() !== '.md')
+            continue;
+        const basename = path.basename(file, '.md');
+        if (/^REF-\d+-(?:citations|radar)$/.test(basename))
+            continue;
+        references.add(basename);
+        const artifactId = basename.match(/^(.+?-\d+)(?:-|$)/);
+        if (artifactId)
+            references.add(artifactId[1]);
+    }
+    return references;
+}
+/**
+ * Preserve support for references stored outside the lint target when a rule
+ * explicitly supplies basePath. Accept both exact and slugged filenames.
+ */
+function resolvesFromBasePath(refId, targetDir, basePath) {
+    const candidateDirs = new Set([
+        path.resolve(targetDir, basePath),
+        path.resolve(process.cwd(), basePath),
+    ]);
+    for (const dir of candidateDirs) {
+        try {
+            if (fs.existsSync(path.join(dir, `${refId}.md`)))
+                return true;
+            if (fs.readdirSync(dir).some(file => file.startsWith(`${refId}-`) && file.endsWith('.md'))) {
+                return true;
+            }
+        }
+        catch {
+            // Missing or unreadable candidate directories do not resolve the ID.
+        }
+    }
+    return false;
+}
+/**
+ * Run a single check against a file's content and frontmatter
+ */
+function runCheck(check, content, frontmatter, filePath, targetDir, allFiles, referenceIndex) {
+    const diagnostics = [];
+    switch (check.type) {
+        case 'frontmatter-required': {
+            if (!check.fields)
+                break;
+            for (const field of check.fields) {
+                if (!frontmatter[field] || frontmatter[field].trim() === '') {
+                    diagnostics.push({
+                        ruleId: '',
+                        ruleName: '',
+                        severity: 'error',
+                        file: filePath,
+                        message: `Missing required frontmatter field: ${field}`,
+                        fix: `Add '${field}:' to the YAML frontmatter block`,
+                    });
+                }
+            }
+            break;
+        }
+        case 'frontmatter-format': {
+            if (!check.field || !check.pattern)
+                break;
+            const value = frontmatter[check.field];
+            if (value && !new RegExp(check.pattern).test(value)) {
+                diagnostics.push({
+                    ruleId: '',
+                    ruleName: '',
+                    severity: 'warn',
+                    file: filePath,
+                    message: `Frontmatter field '${check.field}' value '${value}' does not match pattern: ${check.pattern}`,
+                    fix: `Update '${check.field}' to match the expected format`,
+                });
+            }
+            break;
+        }
+        case 'reference-resolves': {
+            const refPattern = check.referencePattern || DEFAULT_REFERENCE_PATTERN;
+            const regex = new RegExp(refPattern, 'g');
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                let match;
+                while ((match = regex.exec(lines[i])) !== null) {
+                    const refId = match[0];
+                    const basePath = check.basePath || '.aiwg/research/findings';
+                    if (!referenceIndex.has(refId) && !resolvesFromBasePath(refId, targetDir, basePath)) {
+                        diagnostics.push({
+                            ruleId: '',
+                            ruleName: '',
+                            severity: 'error',
+                            file: filePath,
+                            message: `Reference '${refId}' does not resolve to an existing file`,
+                            line: i + 1,
+                        });
+                    }
+                }
+            }
+            break;
+        }
+        case 'pattern-match': {
+            if (!check.pattern)
+                break;
+            const regex = new RegExp(check.pattern);
+            if (!regex.test(content)) {
+                diagnostics.push({
+                    ruleId: '',
+                    ruleName: '',
+                    severity: 'warn',
+                    file: filePath,
+                    message: `File content does not match expected pattern: ${check.pattern}`,
+                });
+            }
+            break;
+        }
+        case 'file-exists': {
+            if (!check.field)
+                break;
+            const refPath = frontmatter[check.field];
+            if (refPath) {
+                const resolved = path.resolve(targetDir, refPath);
+                if (!fs.existsSync(resolved)) {
+                    diagnostics.push({
+                        ruleId: '',
+                        ruleName: '',
+                        severity: 'error',
+                        file: filePath,
+                        message: `Referenced file '${refPath}' (from field '${check.field}') does not exist`,
+                    });
+                }
+            }
+            break;
+        }
+        case 'id-unique': {
+            // Handled at ruleset level in runRule
+            break;
+        }
+        case 'id-format': {
+            if (!check.pattern)
+                break;
+            const basename = path.basename(filePath, '.md');
+            if (!new RegExp(check.pattern).test(basename)) {
+                diagnostics.push({
+                    ruleId: '',
+                    ruleName: '',
+                    severity: 'warn',
+                    file: filePath,
+                    message: `File name '${basename}' does not match expected format: ${check.pattern}`,
+                    fix: `Rename to match the pattern ${check.pattern}`,
+                });
+            }
+            break;
+        }
+        case 'cross-ref-bidirectional': {
+            const refPattern = check.referencePattern || DEFAULT_REFERENCE_PATTERN;
+            const regex = new RegExp(refPattern, 'g');
+            const currentBasename = path.basename(filePath, '.md');
+            const matches = content.match(regex) || [];
+            for (const ref of matches) {
+                if (ref === currentBasename)
+                    continue;
+                // Find the referenced file
+                const refFile = allFiles.find(f => path.basename(f, '.md') === ref);
+                if (refFile) {
+                    try {
+                        const refContent = fs.readFileSync(path.resolve(targetDir, refFile), 'utf8');
+                        if (!refContent.includes(currentBasename)) {
+                            diagnostics.push({
+                                ruleId: '',
+                                ruleName: '',
+                                severity: 'info',
+                                file: filePath,
+                                message: `References '${ref}' but '${ref}' does not reference back to '${currentBasename}'`,
+                                fix: `Add a cross-reference to '${currentBasename}' in ${ref}.md`,
+                            });
+                        }
+                    }
+                    catch {
+                        // Skip if can't read
+                    }
+                }
+            }
+            break;
+        }
+    }
+    return diagnostics;
+}
+/**
+ * Run a single rule against all matching files in the target
+ */
+async function runRule(rule, targetDir, allFiles, referenceIndex) {
+    const diagnostics = [];
+    // Filter files matching the rule's glob
+    const ruleGlob = rule.appliesTo.glob;
+    const matchingFiles = allFiles.filter(f => minimatch(f, ruleGlob));
+    if (matchingFiles.length === 0)
+        return diagnostics;
+    // Handle id-unique check at the ruleset level
+    const uniqueCheck = rule.checks.find(c => c.type === 'id-unique');
+    if (uniqueCheck) {
+        const ids = new Map();
+        for (const file of matchingFiles) {
+            const basename = path.basename(file, '.md');
+            if (ids.has(basename)) {
+                diagnostics.push({
+                    ruleId: rule.id,
+                    ruleName: rule.name,
+                    severity: rule.severity,
+                    file,
+                    message: `Duplicate identifier '${basename}' — also found in ${ids.get(basename)}`,
+                });
+            }
+            else {
+                ids.set(basename, file);
+            }
+        }
+    }
+    // Run per-file checks
+    for (const file of matchingFiles) {
+        const absPath = path.resolve(targetDir, file);
+        let content;
+        try {
+            content = await fsp.readFile(absPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const frontmatter = parseFrontmatter(content);
+        for (const check of rule.checks) {
+            if (check.type === 'id-unique')
+                continue; // Already handled
+            const checkDiagnostics = runCheck(check, content, frontmatter, file, targetDir, allFiles, referenceIndex);
+            for (const d of checkDiagnostics) {
+                d.ruleId = rule.id;
+                d.ruleName = rule.name;
+                d.severity = d.severity || rule.severity;
+                diagnostics.push(d);
+            }
+        }
+    }
+    return diagnostics;
+}
+/**
+ * Collect all files under a target directory
+ */
+async function collectFiles(targetDir, recursive) {
+    const pattern = recursive ? '**/*' : '*';
+    try {
+        const files = await glob(pattern, {
+            cwd: targetDir,
+            nodir: true,
+            dot: false,
+        });
+        return files.filter(f => f.endsWith('.md') || f.endsWith('.yaml') || f.endsWith('.yml') || f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Auto-detect which rulesets apply to a target path
+ *
+ * Maps known directory patterns to rulesets:
+ * - .aiwg/research/ → research-complete
+ * - .aiwg/requirements/, .aiwg/architecture/ → sdlc-complete
+ */
+function autoDetectRulesets(target, available) {
+    const normalized = target.replace(/\\/g, '/');
+    const matches = [];
+    for (const rs of available) {
+        // Match by framework ID patterns
+        if (normalized.includes('research') && rs.framework.includes('research')) {
+            matches.push(rs);
+        }
+        else if ((normalized.includes('requirements') ||
+            normalized.includes('architecture') ||
+            normalized.includes('testing') ||
+            normalized.includes('deployment')) &&
+            rs.framework.includes('sdlc')) {
+            matches.push(rs);
+        }
+    }
+    // If no auto-detection, return all available
+    return matches.length > 0 ? matches : available;
+}
+/**
+ * Run lint on a target path with specified or auto-detected rulesets
+ */
+export async function runLint(targetDir, rulesets, options = {}) {
+    const recursive = options.recursive ?? true;
+    const allFiles = await collectFiles(targetDir, recursive);
+    const referenceIndex = buildReferenceIndex(allFiles);
+    const allDiagnostics = [];
+    for (const ruleset of rulesets) {
+        for (const rule of ruleset.rules) {
+            const diagnostics = await runRule(rule, targetDir, allFiles, referenceIndex);
+            allDiagnostics.push(...diagnostics);
+        }
+    }
+    const errors = allDiagnostics.filter(d => d.severity === 'error').length;
+    const warnings = allDiagnostics.filter(d => d.severity === 'warn').length;
+    const infos = allDiagnostics.filter(d => d.severity === 'info').length;
+    const failOn = options.failOn || 'error';
+    let passed = true;
+    if (failOn === 'error' && errors > 0)
+        passed = false;
+    if (failOn === 'warn' && (errors > 0 || warnings > 0))
+        passed = false;
+    if (failOn === 'info' && allDiagnostics.length > 0)
+        passed = false;
+    return {
+        target: targetDir,
+        rulesets: rulesets.map(r => r.id),
+        diagnostics: allDiagnostics,
+        summary: {
+            filesChecked: allFiles.length,
+            errors,
+            warnings,
+            infos,
+            passed,
+        },
+        timestamp: new Date().toISOString(),
+    };
+}
+export { autoDetectRulesets };
+//# sourceMappingURL=runner.js.map

package/dist/src/lint/types.js

@@ -0,0 +1,10 @@
+/**
+ * Lint System Types
+ *
+ * Defines interfaces for lint rules, rulesets, results, and configuration.
+ * Rules are declarative YAML; the runner evaluates them against target files.
+ *
+ * @issue #810
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/marketplace/cache.js

@@ -0,0 +1,110 @@
+/**
+ * Marketplace Local Cache
+ *
+ * Manages the ~/.aiwg/marketplace-cache/ directory that stores fetched plugins.
+ *
+ * Layout: ~/.aiwg/marketplace-cache/<source>/<packageId>/<version>/
+ *
+ * @implements #787
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+/**
+ * Resolve the cache root. Supports AIWG_CACHE_DIR override for testing.
+ */
+export function getCacheRoot() {
+    if (process.env.AIWG_CACHE_DIR) {
+        return process.env.AIWG_CACHE_DIR;
+    }
+    return path.join(os.homedir(), '.aiwg', 'marketplace-cache');
+}
+/**
+ * Resolve the path for a specific package version
+ */
+export function getPackagePath(source, packageId, version) {
+    // Sanitize package ID for filesystem safety (replace / and : with -)
+    const safePackageId = packageId.replace(/[/:]/g, '__');
+    return path.join(getCacheRoot(), source, safePackageId, version);
+}
+/**
+ * Check whether a package version is cached
+ */
+export function isCached(source, packageId, version) {
+    const packagePath = getPackagePath(source, packageId, version);
+    const manifestPath = path.join(packagePath, 'manifest.json');
+    return fs.existsSync(manifestPath);
+}
+/**
+ * Write a package bundle to the cache
+ */
+export function cachePackage(bundle) {
+    const packagePath = getPackagePath(bundle.metadata.source, bundle.metadata.name, bundle.metadata.version);
+    fs.mkdirSync(packagePath, { recursive: true });
+    // Write normalized manifest
+    fs.writeFileSync(path.join(packagePath, 'manifest.json'), JSON.stringify(bundle.metadata, null, 2) + '\n', 'utf-8');
+    // Write raw source manifest for update detection
+    fs.writeFileSync(path.join(packagePath, 'raw-manifest.json'), JSON.stringify(bundle.rawManifest, null, 2) + '\n', 'utf-8');
+    // Note: actual artifact files are expected to be in bundle.localPath already;
+    // in a complete implementation we'd copy them into packagePath here.
+    return packagePath;
+}
+export function listCachedPackages() {
+    const root = getCacheRoot();
+    if (!fs.existsSync(root))
+        return [];
+    const entries = [];
+    // Walk <source>/<packageId>/<version>/manifest.json
+    const sources = fs.readdirSync(root);
+    for (const source of sources) {
+        const sourcePath = path.join(root, source);
+        if (!fs.statSync(sourcePath).isDirectory())
+            continue;
+        const packages = fs.readdirSync(sourcePath);
+        for (const pkg of packages) {
+            const pkgPath = path.join(sourcePath, pkg);
+            if (!fs.statSync(pkgPath).isDirectory())
+                continue;
+            const versions = fs.readdirSync(pkgPath);
+            for (const version of versions) {
+                const manifestPath = path.join(pkgPath, version, 'manifest.json');
+                if (!fs.existsSync(manifestPath))
+                    continue;
+                try {
+                    const metadata = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                    const stat = fs.statSync(manifestPath);
+                    entries.push({
+                        source: source,
+                        packageId: pkg.replace(/__/g, '/'),
+                        version,
+                        cachedAt: stat.mtime,
+                        metadata,
+                    });
+                }
+                catch {
+                    // Skip malformed entries
+                }
+            }
+        }
+    }
+    return entries;
+}
+/**
+ * Remove a specific cached package (all versions or a specific one)
+ */
+export function uncachePackage(source, packageId, version) {
+    const safePackageId = packageId.replace(/[/:]/g, '__');
+    const pkgPath = path.join(getCacheRoot(), source, safePackageId);
+    if (version) {
+        const versionPath = path.join(pkgPath, version);
+        if (!fs.existsSync(versionPath))
+            return false;
+        fs.rmSync(versionPath, { recursive: true, force: true });
+        return true;
+    }
+    if (!fs.existsSync(pkgPath))
+        return false;
+    fs.rmSync(pkgPath, { recursive: true, force: true });
+    return true;
+}
+//# sourceMappingURL=cache.js.map

package/dist/src/marketplace/identifier.js

@@ -0,0 +1,63 @@
+/**
+ * Source Identifier Parser
+ *
+ * Parses marketplace source identifiers of the form `<source>:<package>[@<version>]`.
+ *
+ * @implements #787
+ */
+const VALID_SOURCES = [
+    'clawhub',
+    'cursor',
+    'codex',
+    'claude',
+    'git',
+];
+/**
+ * Parse a marketplace source identifier.
+ *
+ * Examples:
+ *   "clawhub:aiwg/sdlc"              → { source: 'clawhub', packageId: 'aiwg/sdlc' }
+ *   "cursor:publisher.package"       → { source: 'cursor', packageId: 'publisher.package' }
+ *   "codex:some-plugin@1.2.0"        → { source: 'codex', packageId: 'some-plugin', version: '1.2.0' }
+ *   "claude:user/repo#plugin"        → { source: 'claude', packageId: 'user/repo#plugin' }
+ *   "git:https://github.com/foo/bar" → { source: 'git', packageId: 'https://github.com/foo/bar' }
+ *
+ * @throws Error if the identifier is malformed or the source is unknown
+ */
+export function parseIdentifier(identifier) {
+    // Split on first colon; the rest is the package id (may contain colons for git URLs)
+    const colonIdx = identifier.indexOf(':');
+    if (colonIdx === -1) {
+        throw new Error(`Invalid marketplace identifier '${identifier}'. Expected format: <source>:<package>[@<version>]`);
+    }
+    const source = identifier.slice(0, colonIdx).trim().toLowerCase();
+    let packageId = identifier.slice(colonIdx + 1).trim();
+    if (!VALID_SOURCES.includes(source)) {
+        throw new Error(`Unknown marketplace source '${source}'. Valid sources: ${VALID_SOURCES.join(', ')}`);
+    }
+    // Extract optional @version suffix (but not for git URLs which can contain @)
+    let version;
+    if (source !== 'git') {
+        const atIdx = packageId.lastIndexOf('@');
+        if (atIdx > 0) {
+            version = packageId.slice(atIdx + 1).trim();
+            packageId = packageId.slice(0, atIdx).trim();
+        }
+    }
+    if (!packageId) {
+        throw new Error(`Empty package id in identifier '${identifier}'`);
+    }
+    return {
+        source: source,
+        packageId,
+        version,
+    };
+}
+/**
+ * Format a parsed identifier back to string form
+ */
+export function formatIdentifier(parsed) {
+    const base = `${parsed.source}:${parsed.packageId}`;
+    return parsed.version ? `${base}@${parsed.version}` : base;
+}
+//# sourceMappingURL=identifier.js.map

package/dist/src/marketplace/registry.js

@@ -0,0 +1,36 @@
+/**
+ * Marketplace Source Registry
+ *
+ * Registers marketplace source adapters and resolves a parsed identifier
+ * to its adapter.
+ *
+ * @implements #787
+ */
+import { ClawHubSource } from './sources/clawhub.js';
+import { GitSource } from './sources/git.js';
+/**
+ * Registered source adapters keyed by source id.
+ * Additional adapters (cursor, codex, claude) will be registered here as
+ * their implementations land.
+ */
+const adapters = new Map();
+adapters.set('clawhub', new ClawHubSource());
+adapters.set('git', new GitSource());
+/**
+ * Get the adapter for a given source.
+ */
+export function getSource(source) {
+    const adapter = adapters.get(source);
+    if (!adapter) {
+        throw new Error(`No adapter registered for marketplace source '${source}'. ` +
+            `Registered sources: ${Array.from(adapters.keys()).join(', ')}`);
+    }
+    return adapter;
+}
+/**
+ * List all registered source ids
+ */
+export function listRegisteredSources() {
+    return Array.from(adapters.keys());
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/marketplace/sources/clawhub.js

@@ -0,0 +1,53 @@
+/**
+ * ClawHub Source Adapter
+ *
+ * Fetches plugins from the ClawHub registry. ClawHub is OpenClaw's central
+ * package registry.
+ *
+ * Status: scaffold. Full implementation requires ClawHub API spec or CLI
+ * integration.
+ *
+ * @implements #787
+ */
+export class ClawHubSource {
+    source = 'clawhub';
+    async fetch(packageId, _version) {
+        // TODO: invoke ClawHub CLI or HTTP API to fetch the package tarball,
+        // extract to a temp directory, parse clawhub.json, and return a
+        // normalized PackageBundle. For now, throw with a clear message.
+        throw new Error(`ClawHub source adapter is a scaffold. Full implementation pending. ` +
+            `Tried to fetch: clawhub:${packageId}`);
+    }
+    async search(_query, _options) {
+        throw new Error('ClawHub search not yet implemented');
+    }
+    validate(manifest) {
+        const errors = [];
+        const warnings = [];
+        if (typeof manifest !== 'object' || manifest === null) {
+            return { valid: false, errors: ['Manifest is not an object'], warnings };
+        }
+        const m = manifest;
+        // Required fields per ClawHub spec
+        if (typeof m.name !== 'string')
+            errors.push('Missing required field: name');
+        if (typeof m.version !== 'string')
+            errors.push('Missing required field: version');
+        if (typeof m.description !== 'string')
+            errors.push('Missing required field: description');
+        // Namespace collision check
+        if (typeof m.name === 'string' && m.name.startsWith('aiwg-') && m.author !== 'AIWG Contributors') {
+            warnings.push(`Package name '${m.name}' uses the aiwg- prefix but is not authored by AIWG. ` +
+                `This may cause namespace collisions.`);
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    async getVersions(_packageId) {
+        throw new Error('ClawHub getVersions not yet implemented');
+    }
+}
+//# sourceMappingURL=clawhub.js.map

package/dist/src/marketplace/sources/git.js

@@ -0,0 +1,45 @@
+/**
+ * Git (generic) Source Adapter
+ *
+ * Fetches plugins from any Git URL. Detects the manifest format automatically
+ * (looks for .claude-plugin/, .codex-plugin/, .cursor-plugin/, .factory-plugin/,
+ * clawhub.json in that order).
+ *
+ * Status: scaffold. Full implementation requires git-clone integration.
+ *
+ * @implements #787
+ */
+export class GitSource {
+    source = 'git';
+    async fetch(packageId, _version) {
+        // TODO: git clone into a temp dir, detect manifest format, normalize
+        throw new Error(`Git source adapter is a scaffold. Full implementation pending. ` +
+            `Tried to fetch: git:${packageId}`);
+    }
+    async search(_query, _options) {
+        // Git doesn't have a searchable registry — this is a no-op
+        return [];
+    }
+    validate(manifest) {
+        // Generic git manifest validation — accepts any of the known formats
+        if (typeof manifest !== 'object' || manifest === null) {
+            return { valid: false, errors: ['Manifest is not an object'], warnings: [] };
+        }
+        const m = manifest;
+        const errors = [];
+        if (typeof m.name !== 'string')
+            errors.push('Missing required field: name');
+        if (typeof m.version !== 'string')
+            errors.push('Missing required field: version');
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings: [],
+        };
+    }
+    async getVersions(_packageId) {
+        // Git "versions" would be tags or SHA references — requires git ls-remote
+        throw new Error('Git getVersions not yet implemented');
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/src/marketplace/types.js

@@ -0,0 +1,9 @@
+/**
+ * Marketplace Consumer Types
+ *
+ * Interfaces for third-party marketplace plugin ingestion.
+ *
+ * @implements #787
+ */
+export {};
+//# sourceMappingURL=types.js.map