@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/contributors/heuristic.js

@@ -0,0 +1,186 @@
+/**
+ * Heuristic Project-Type Inference
+ *
+ * Fallback used by `project-status` (and any other `kind: status` aggregator)
+ * when contributor discovery returns zero in-use contributors. Detects what
+ * kind of project this is from cheap local signals — manifest files, file
+ * extensions, basic git presence — so the report still says something useful
+ * for projects that have not opted into AIWG contributors.
+ *
+ * Local-only by design: no network calls, no `npm outdated`, no GitHub API.
+ * The whole inference returns in O(few hundred ms) on a typical repo because
+ * it only checks a small number of well-known paths and runs a handful of
+ * bounded globs.
+ *
+ * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
+ * @issue #941
+ */
+import { existsSync, statSync } from 'fs';
+import { glob } from 'glob';
+import path from 'path';
+/**
+ * Manifest files that strongly indicate a code project, mapped to a label.
+ * Order matters only for the summary string when multiple match.
+ */
+const CODE_MANIFESTS = [
+    { file: 'package.json', label: 'JS/TS' },
+    { file: 'pyproject.toml', label: 'Python' },
+    { file: 'requirements.txt', label: 'Python (pip)' },
+    { file: 'Cargo.toml', label: 'Rust' },
+    { file: 'go.mod', label: 'Go' },
+    { file: 'pom.xml', label: 'Java (Maven)' },
+    { file: 'build.gradle', label: 'JVM (Gradle)' },
+    { file: 'build.gradle.kts', label: 'JVM (Gradle Kotlin)' },
+    { file: 'Gemfile', label: 'Ruby' },
+    { file: 'composer.json', label: 'PHP' },
+    { file: 'mix.exs', label: 'Elixir' },
+];
+/** Common test directory names — presence indicates a code project takes testing seriously. */
+const TEST_DIRS = ['test', 'tests', '__tests__', 'spec'];
+/** Asset file extensions, grouped by kind. Kept tight to avoid false positives on icons in docs. */
+const ASSET_EXTENSIONS = {
+    audio: ['mp3', 'flac', 'opus', 'm4a', 'wav', 'aac', 'ogg'],
+    video: ['mp4', 'mkv', 'webm', 'mov', 'avi'],
+    image: ['jpg', 'jpeg', 'png', 'webp', 'heic', 'tiff'],
+};
+/** Soft thresholds to call something "asset-dominant" rather than "has a few images". */
+const ASSET_DOMINANCE_MIN = 25;
+function existsCheap(p) {
+    try {
+        return existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Format a Unix-epoch ms as a relative-age string. Cheap, no extra deps.
+ */
+function relativeAge(mtimeMs) {
+    const ageMs = Date.now() - mtimeMs;
+    const day = 86_400_000;
+    if (ageMs < day)
+        return 'today';
+    const days = Math.floor(ageMs / day);
+    if (days < 30)
+        return `${days} day${days === 1 ? '' : 's'} ago`;
+    const months = Math.floor(days / 30);
+    if (months < 12)
+        return `${months} month${months === 1 ? '' : 's'} ago`;
+    const years = Math.floor(days / 365);
+    return `${years} year${years === 1 ? '' : 's'} ago`;
+}
+async function detectCodeDimension(projectRoot) {
+    const matchedManifests = CODE_MANIFESTS.filter(m => existsCheap(path.join(projectRoot, m.file)));
+    if (matchedManifests.length === 0)
+        return null;
+    const details = [
+        { label: 'Manifests', value: matchedManifests.map(m => `${m.file} (${m.label})`).join(', ') },
+    ];
+    const testDirs = TEST_DIRS.filter(d => existsCheap(path.join(projectRoot, d)));
+    details.push({
+        label: 'Test directories',
+        value: testDirs.length > 0 ? testDirs.join(', ') : 'none',
+    });
+    const readmePath = path.join(projectRoot, 'README.md');
+    if (existsCheap(readmePath)) {
+        try {
+            const stat = statSync(readmePath);
+            details.push({ label: 'README', value: `last edited ${relativeAge(stat.mtimeMs)}` });
+        }
+        catch {
+            details.push({ label: 'README', value: 'present (mtime unavailable)' });
+        }
+    }
+    else {
+        details.push({ label: 'README', value: 'missing' });
+    }
+    const gitDir = path.join(projectRoot, '.git');
+    details.push({ label: 'Git', value: existsCheap(gitDir) ? 'tracked' : 'not a git repo' });
+    // Confidence is high when manifest + test dir + git all agree.
+    const signals = (matchedManifests.length > 0 ? 1 : 0) + (testDirs.length > 0 ? 1 : 0) + (existsCheap(gitDir) ? 1 : 0);
+    const confidence = signals >= 3 ? 'high' : signals === 2 ? 'medium' : 'low';
+    const summary = matchedManifests.length === 1
+        ? `${matchedManifests[0].label} code project`
+        : `code project (${matchedManifests.map(m => m.label).join(' + ')})`;
+    return { kind: 'code', confidence, summary, details };
+}
+async function detectDocsDimension(projectRoot) {
+    // Cap the scan so this stays cheap on huge repos. We only need the order
+    // of magnitude.
+    const mdFiles = await glob('**/*.md', {
+        cwd: projectRoot,
+        nodir: true,
+        ignore: ['node_modules/**', '.git/**', 'dist/**', 'build/**', 'target/**'],
+    });
+    if (mdFiles.length < 5)
+        return null;
+    const hasCodeManifest = CODE_MANIFESTS.some(m => existsCheap(path.join(projectRoot, m.file)));
+    // Docs project = lots of markdown AND no source manifests. With a manifest
+    // it's just a code project that has docs — surface both, but mark this
+    // dimension's confidence as low so the summary doesn't lie.
+    const confidence = hasCodeManifest ? 'low' : mdFiles.length > 50 ? 'high' : 'medium';
+    const details = [
+        { label: 'Markdown files', value: String(mdFiles.length) },
+    ];
+    // Top-level docs dirs hint at organization.
+    const docsDirs = ['docs', 'doc', 'documentation', 'wiki'].filter(d => existsCheap(path.join(projectRoot, d)));
+    details.push({
+        label: 'Docs directories',
+        value: docsDirs.length > 0 ? docsDirs.join(', ') : 'none at root',
+    });
+    return {
+        kind: 'docs',
+        confidence,
+        summary: hasCodeManifest
+            ? `${mdFiles.length} markdown files (code project with docs)`
+            : `${mdFiles.length} markdown files (docs / knowledge project)`,
+        details,
+    };
+}
+async function detectAssetsDimension(projectRoot) {
+    const counts = {};
+    let total = 0;
+    for (const [kind, exts] of Object.entries(ASSET_EXTENSIONS)) {
+        const pattern = `**/*.{${exts.join(',')}}`;
+        const matches = await glob(pattern, {
+            cwd: projectRoot,
+            nodir: true,
+            ignore: ['node_modules/**', '.git/**', 'dist/**', 'build/**'],
+        });
+        counts[kind] = matches.length;
+        total += matches.length;
+    }
+    if (total < ASSET_DOMINANCE_MIN)
+        return null;
+    const dominant = Object.entries(counts).sort((a, b) => b[1] - a[1])[0];
+    return {
+        kind: 'assets',
+        confidence: total > 200 ? 'high' : total > 50 ? 'medium' : 'low',
+        summary: `${total} media file${total === 1 ? '' : 's'} (${dominant[0]} dominant)`,
+        details: [
+            { label: 'Audio', value: String(counts.audio) },
+            { label: 'Video', value: String(counts.video) },
+            { label: 'Image', value: String(counts.image) },
+        ],
+    };
+}
+/**
+ * Run all heuristic detectors and return a unified report. The caller
+ * decides whether to surface this to the user — typically only when
+ * `discoverContributors()` returns zero in-use contributors.
+ */
+export async function inferProjectType(projectRoot) {
+    const [code, docs, assets] = await Promise.all([
+        detectCodeDimension(projectRoot),
+        detectDocsDimension(projectRoot),
+        detectAssetsDimension(projectRoot),
+    ]);
+    const dimensions = [code, docs, assets].filter((d) => d !== null);
+    return {
+        origin: 'heuristic',
+        dimensions,
+        empty: dimensions.length === 0,
+    };
+}
+//# sourceMappingURL=heuristic.js.map

package/dist/src/contributors/index.js

@@ -0,0 +1,11 @@
+/**
+ * Contributor Discovery — Public API
+ *
+ * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
+ * @issue #938
+ */
+export { discoverContributors } from './discover.js';
+export { runDetection, isInUse } from './detect.js';
+export { inferProjectType } from './heuristic.js';
+export { StatusContributorSchema, ResearchContributorSchema, getSchemaForKind, getRegisteredKinds, validateContributor, } from './validation.js';
+//# sourceMappingURL=index.js.map

package/dist/src/contributors/types.js

@@ -0,0 +1,13 @@
+/**
+ * Contributor Discovery Type Definitions
+ *
+ * Cross-framework contributor convention per ADR-023. Frameworks, addons,
+ * and extensions opt into cross-framework commands (project-status,
+ * best-practices-audit, ...) by shipping `<framework>/<kind>/contributor.md`
+ * files. The aggregator discovers, validates, and runs detection against them.
+ *
+ * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
+ * @issue #938
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/contributors/validation.js

@@ -0,0 +1,116 @@
+/**
+ * Contributor Frontmatter Validation
+ *
+ * Zod schemas for known contributor kinds (`status`, `research`). Schemas are
+ * keyed by kind so future consumers register their schema without forking the
+ * discovery module.
+ *
+ * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
+ * @issue #938
+ */
+import { z } from 'zod';
+/**
+ * Detection spec — declarative globs + counts. Common to every kind.
+ */
+const DetectionSpecSchema = z.object({
+    glob: z.array(z.string()).min(1, 'detect.glob must have at least one pattern'),
+    minCount: z.number().int().positive().optional(),
+    conditions: z.record(z.string()).optional(),
+});
+/**
+ * Base frontmatter shared by every kind. Per-kind schemas extend this.
+ */
+const ContributorBaseSchema = z.object({
+    kind: z.string().min(1),
+    domain: z.string().min(1, 'domain is required'),
+    description: z.string().min(1, 'description is required'),
+    detect: DetectionSpecSchema,
+});
+/**
+ * `kind: status` frontmatter. Reports observed state of a framework/domain
+ * (phase, counts, dates). Fields beyond the base schema are descriptive only —
+ * no prescriptive `next:` arrays per ADR-023 §Output voice.
+ */
+export const StatusContributorSchema = ContributorBaseSchema.extend({
+    kind: z.literal('status'),
+    /**
+     * Optional declarative field extractors. Each entry pulls a value out of a
+     * file using regex or count. Keeps contributors data-driven rather than
+     * code-driven; the aggregator reads these to populate the report block.
+     */
+    fields: z
+        .record(z.object({
+        type: z.enum(['string', 'number', 'date']),
+        source: z.string(),
+        regex: z.string().optional(),
+        count: z.string().optional(),
+    }))
+        .optional(),
+});
+/**
+ * `kind: research` frontmatter. Configures research fan-out for a framework's
+ * domain — focus areas, source preferences, recency window.
+ */
+export const ResearchContributorSchema = ContributorBaseSchema.extend({
+    kind: z.literal('research'),
+    sources: z
+        .object({
+        preferred: z.array(z.string()).optional(),
+        exclude: z.array(z.string()).optional(),
+    })
+        .optional(),
+    focus_areas: z.array(z.string()).min(1, 'research contributors must declare at least one focus area'),
+    recency_default_months: z.number().int().positive().optional(),
+});
+/**
+ * Schema registry. Adding a new kind means adding its schema here — no other
+ * code changes are required for the discovery module to validate it.
+ */
+const SCHEMA_REGISTRY = {
+    status: StatusContributorSchema,
+    research: ResearchContributorSchema,
+};
+/**
+ * Look up the zod schema for a kind. Throws if no schema is registered —
+ * unknown kinds must be deliberately added rather than silently accepted.
+ */
+export function getSchemaForKind(kind) {
+    const schema = SCHEMA_REGISTRY[kind];
+    if (!schema) {
+        throw new Error(`Unknown contributor kind '${kind}'. Register a zod schema in src/contributors/validation.ts before using it.`);
+    }
+    return schema;
+}
+/**
+ * List all registered kinds. Used by validate-metadata to scan for
+ * orphaned contributor files (kind in frontmatter but no schema registered).
+ */
+export function getRegisteredKinds() {
+    return Object.keys(SCHEMA_REGISTRY);
+}
+/**
+ * Validate a parsed frontmatter object against its kind's schema. Returns
+ * either the typed data or an error with formatted issue messages.
+ */
+export function validateContributor(data) {
+    const kind = data.kind;
+    if (typeof kind !== 'string' || kind.length === 0) {
+        return { ok: false, errors: ['frontmatter is missing required field `kind`'] };
+    }
+    let schema;
+    try {
+        schema = getSchemaForKind(kind);
+    }
+    catch (err) {
+        return { ok: false, errors: [err.message] };
+    }
+    const result = schema.safeParse(data);
+    if (!result.success) {
+        return {
+            ok: false,
+            errors: result.error.errors.map(e => `${e.path.join('.') || '<root>'}: ${e.message}`),
+        };
+    }
+    return { ok: true, data: result.data };
+}
+//# sourceMappingURL=validation.js.map

package/dist/src/data/community.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aiwg.io/schemas/community.schema.json",
+  "title": "AIWG Community Links",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["website", "repository", "channels", "star_cta"],
+  "properties": {
+    "website": { "type": "string", "format": "uri" },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["github"],
+      "properties": {
+        "github": { "type": "string", "format": "uri" },
+        "gitea": { "type": "string", "format": "uri" }
+      }
+    },
+    "channels": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "name", "url", "cta"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "name": { "type": "string", "minLength": 1 },
+          "url": { "type": "string", "format": "uri" },
+          "cta": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "star_cta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["short", "long"],
+      "properties": {
+        "short": { "type": "string", "minLength": 1 },
+        "long": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/dist/src/data/community.yaml

@@ -0,0 +1,16 @@
+website: https://aiwg.io
+repository:
+  github: https://github.com/jmagly/aiwg
+  gitea: https://git.integrolabs.net/roctinam/aiwg
+channels:
+  - id: discord
+    name: Discord
+    url: https://discord.gg/BuAusFMxdA
+    cta: Join the Discord
+  - id: telegram
+    name: Telegram
+    url: https://t.me/+oJg9w2lE6A5lOGFh
+    cta: Join the Telegram
+star_cta:
+  short: Star AIWG on GitHub
+  long: If AIWG saved you time, a star at github.com/jmagly/aiwg helps others find it.

package/dist/src/extensions/capability-index.js

@@ -0,0 +1,270 @@
+/**
+ * CapabilityIndex - Capability-based extension discovery system
+ *
+ * @implements @.aiwg/requirements/use-cases/UC-004-extension-system.md
+ * @architecture @.aiwg/architecture/software-architecture-doc.md
+ * @tests @test/unit/extensions/capability-index.test.ts
+ */
+/**
+ * CapabilityIndex enables finding extensions by what they can do.
+ *
+ * Maintains bidirectional mappings:
+ * - capability → extension IDs (for queries)
+ * - extension ID → capabilities (for updates)
+ *
+ * @example
+ * ```typescript
+ * const index = new CapabilityIndex();
+ * index.index(myExtension);
+ *
+ * // Find extensions that can format markdown
+ * const formatters = index.getByCapability('format:markdown');
+ *
+ * // Find extensions that can format OR lint
+ * const tools = index.query({ any: ['format:markdown', 'lint:markdown'] });
+ *
+ * // Find formatters that are NOT linters
+ * const pureFormatters = index.query({
+ *   all: ['format:markdown'],
+ *   not: ['lint:markdown']
+ * });
+ * ```
+ */
+export class CapabilityIndex {
+    /** Map of capability → extension IDs */
+    byCapability = new Map();
+    /** Map of extension ID → capabilities */
+    byExtension = new Map();
+    /** Map of extension ID → extension type */
+    extensionTypes = new Map();
+    /**
+     * Index an extension's capabilities for fast lookup.
+     *
+     * @param extension - Extension to index
+     *
+     * @example
+     * ```typescript
+     * index.index({
+     *   id: 'markdown-formatter',
+     *   type: 'tool',
+     *   capabilities: ['format:markdown', 'format:commonmark']
+     * });
+     * ```
+     */
+    index(extension) {
+        const extensionId = extension.id;
+        const capabilities = extension.capabilities || [];
+        // Store extension type
+        this.extensionTypes.set(extensionId, extension.type);
+        // Remove old mappings if re-indexing
+        this.remove(extensionId);
+        // Store extension → capabilities mapping
+        this.byExtension.set(extensionId, new Set(capabilities));
+        // Add to capability → extensions mappings
+        for (const capability of capabilities) {
+            if (!this.byCapability.has(capability)) {
+                this.byCapability.set(capability, new Set());
+            }
+            this.byCapability.get(capability).add(extensionId);
+        }
+    }
+    /**
+     * Remove an extension from the index.
+     *
+     * @param extensionId - ID of extension to remove
+     *
+     * @example
+     * ```typescript
+     * index.remove('markdown-formatter');
+     * ```
+     */
+    remove(extensionId) {
+        // Get capabilities for this extension
+        const capabilities = this.byExtension.get(extensionId);
+        if (!capabilities) {
+            return; // Not indexed
+        }
+        // Remove from capability → extensions mappings
+        const capabilityArray = Array.from(capabilities);
+        for (const capability of capabilityArray) {
+            const extensions = this.byCapability.get(capability);
+            if (extensions) {
+                extensions.delete(extensionId);
+                // Clean up empty sets
+                if (extensions.size === 0) {
+                    this.byCapability.delete(capability);
+                }
+            }
+        }
+        // Remove extension → capabilities mapping
+        this.byExtension.delete(extensionId);
+        // Remove extension type
+        this.extensionTypes.delete(extensionId);
+    }
+    /**
+     * Query extensions by capabilities.
+     *
+     * Query logic:
+     * 1. Start with all extensions if no `all` or `any` specified
+     * 2. Filter to extensions with ALL capabilities in `all` array
+     * 3. Filter to extensions with ANY capability in `any` array
+     * 4. Exclude extensions with capabilities in `not` array
+     * 5. Optionally filter by extension type
+     *
+     * @param query - Capability query
+     * @returns Array of matching extension IDs
+     *
+     * @example
+     * ```typescript
+     * // Extensions that can do BOTH formatting and validation
+     * index.query({ all: ['format:markdown', 'validate:markdown'] });
+     *
+     * // Extensions that can do EITHER formatting or linting
+     * index.query({ any: ['format:markdown', 'lint:markdown'] });
+     *
+     * // Formatters that are NOT linters
+     * index.query({
+     *   all: ['format:markdown'],
+     *   not: ['lint:markdown']
+     * });
+     *
+     * // Only tool-type extensions with formatting capability
+     * index.query({
+     *   all: ['format:markdown'],
+     *   type: 'tool'
+     * });
+     * ```
+     */
+    query(query) {
+        let candidates;
+        // Phase 1: Build initial candidate set
+        if (query.all && query.all.length > 0) {
+            // Start with extensions that have the first required capability
+            const firstCapability = this.byCapability.get(query.all[0]);
+            candidates = firstCapability ? new Set(firstCapability) : new Set();
+            // Intersect with extensions that have ALL other required capabilities
+            for (let i = 1; i < query.all.length; i++) {
+                const withCapability = this.byCapability.get(query.all[i]);
+                if (!withCapability || withCapability.size === 0) {
+                    // If any required capability has no extensions, result is empty
+                    return [];
+                }
+                // Keep only extensions that have this capability too
+                const candidateArray = Array.from(candidates);
+                candidates = new Set(candidateArray.filter(id => withCapability.has(id)));
+                if (candidates.size === 0) {
+                    // Early exit if intersection is empty
+                    return [];
+                }
+            }
+        }
+        else if (query.any && query.any.length > 0) {
+            // Union of extensions with ANY of the specified capabilities
+            candidates = new Set();
+            for (const capability of query.any) {
+                const withCapability = this.byCapability.get(capability);
+                if (withCapability) {
+                    const capabilityArray = Array.from(withCapability);
+                    for (const id of capabilityArray) {
+                        candidates.add(id);
+                    }
+                }
+            }
+        }
+        else {
+            // No constraints - start with all extensions
+            candidates = new Set(this.byExtension.keys());
+        }
+        // Phase 2: Apply exclusions
+        if (query.not && query.not.length > 0) {
+            for (const capability of query.not) {
+                const toExclude = this.byCapability.get(capability);
+                if (toExclude) {
+                    const excludeArray = Array.from(toExclude);
+                    for (const id of excludeArray) {
+                        candidates.delete(id);
+                    }
+                }
+            }
+        }
+        // Phase 3: Filter by type
+        if (query.type) {
+            const candidateArray = Array.from(candidates);
+            candidates = new Set(candidateArray.filter(id => this.extensionTypes.get(id) === query.type));
+        }
+        return Array.from(candidates).sort();
+    }
+    /**
+     * Get all capabilities in the index.
+     *
+     * @returns Sorted array of capability strings
+     *
+     * @example
+     * ```typescript
+     * const capabilities = index.getAllCapabilities();
+     * // ['format:markdown', 'lint:markdown', 'validate:markdown']
+     * ```
+     */
+    getAllCapabilities() {
+        return Array.from(this.byCapability.keys()).sort();
+    }
+    /**
+     * Get all extensions with a specific capability.
+     *
+     * @param capability - Capability to search for
+     * @returns Sorted array of extension IDs
+     *
+     * @example
+     * ```typescript
+     * const formatters = index.getByCapability('format:markdown');
+     * // ['markdown-formatter', 'prettier-markdown']
+     * ```
+     */
+    getByCapability(capability) {
+        const extensions = this.byCapability.get(capability);
+        return extensions ? Array.from(extensions).sort() : [];
+    }
+    /**
+     * Check if a capability exists in the index.
+     *
+     * @param capability - Capability to check
+     * @returns True if at least one extension has this capability
+     *
+     * @example
+     * ```typescript
+     * if (index.hasCapability('format:markdown')) {
+     *   console.log('Markdown formatting available');
+     * }
+     * ```
+     */
+    hasCapability(capability) {
+        const extensions = this.byCapability.get(capability);
+        return extensions !== undefined && extensions.size > 0;
+    }
+    /**
+     * Get the number of unique capabilities in the index.
+     *
+     * @example
+     * ```typescript
+     * console.log(`Indexed ${index.capabilityCount} capabilities`);
+     * ```
+     */
+    get capabilityCount() {
+        return this.byCapability.size;
+    }
+    /**
+     * Clear all indexed data.
+     *
+     * @example
+     * ```typescript
+     * index.clear();
+     * // All mappings reset
+     * ```
+     */
+    clear() {
+        this.byCapability.clear();
+        this.byExtension.clear();
+        this.extensionTypes.clear();
+    }
+}
+//# sourceMappingURL=capability-index.js.map