@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/artifacts/views/cli.js

@@ -0,0 +1,293 @@
+/**
+ * `aiwg index views` subcommand router.
+ *
+ * Subcommands:
+ *   add <name>          — scaffold a definition YAML interactively or via flags
+ *   list                — list all views with freshness
+ *   show <name>         — print stored results
+ *   build [<name>]      — emit dispatch plan(s) for stale or named views
+ *   remove <name>       — delete definition + results
+ *
+ * `build` does NOT directly invoke RLM. RLM dispatch is an agent skill
+ * (/rlm-batch). This CLI prints a dispatch plan that the agent reads
+ * and acts on, then writes the result back via putResult().
+ *
+ * @implements #1207
+ */
+import { join } from 'node:path';
+import { computeHash } from '../../rlm/cache/hash.js';
+import { parseViewYaml, validate, ViewValidationError } from './definition.js';
+import { getDefinition, getResult, listViews, putDefinition, removeView, resolveViewsRoot, } from './store.js';
+import { readFileSync } from 'node:fs';
+export async function main(args) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case 'add':
+            handleAdd(rest);
+            break;
+        case 'list':
+            handleList(rest);
+            break;
+        case 'show':
+            handleShow(rest);
+            break;
+        case 'build':
+            handleBuild(rest);
+            break;
+        case 'remove':
+            handleRemove(rest);
+            break;
+        default:
+            printUsage();
+            if (sub)
+                throw new Error(`Unknown views subcommand: ${sub}`);
+    }
+}
+function asJson(args) {
+    return args.includes('--json');
+}
+function flagValue(args, flag) {
+    const i = args.indexOf(flag);
+    return i !== -1 && args[i + 1] ? args[i + 1] : undefined;
+}
+function handleAdd(args) {
+    const fileFlag = flagValue(args, '--from');
+    if (fileFlag) {
+        const yaml = readFileSync(fileFlag, 'utf-8');
+        let def;
+        try {
+            def = parseViewYaml(yaml);
+        }
+        catch (err) {
+            console.error(err instanceof ViewValidationError ? err.message : String(err));
+            process.exitCode = 1;
+            return;
+        }
+        const root = resolveViewsRoot();
+        const path = putDefinition(root, def);
+        console.log(`Added view '${def.name}' from ${fileFlag}`);
+        console.log(`  Definition: ${path}`);
+        return;
+    }
+    // Non-interactive add via flags: --name --producer --glob/--query/--neighbors-of --prompt --aggregate
+    const name = flagValue(args, '--name');
+    const producer = (flagValue(args, '--producer') ?? 'rlm-batch');
+    const prompt = flagValue(args, '--prompt');
+    const aggregate = (flagValue(args, '--aggregate') ?? 'concat');
+    const glob = flagValue(args, '--glob');
+    const query = flagValue(args, '--query');
+    const neighborsId = flagValue(args, '--neighbors-of');
+    if (!name || !prompt) {
+        console.error('Usage: aiwg index views add --name <name> --prompt <prompt> [--producer rlm-batch] [--glob <p>|--query <q>|--neighbors-of <id>] [--aggregate <strategy>]');
+        console.error('   or: aiwg index views add --from <path/to/view.yaml>');
+        process.exitCode = 1;
+        return;
+    }
+    const inputs = {};
+    if (glob)
+        inputs.glob = glob;
+    else if (query)
+        inputs.query = query;
+    else if (neighborsId) {
+        inputs.neighborsOf = {
+            id: neighborsId,
+            depth: parseInt(flagValue(args, '--depth') ?? '1', 10),
+            direction: flagValue(args, '--direction') ?? 'both',
+            ...(flagValue(args, '--graph') ? { graph: flagValue(args, '--graph') } : {}),
+        };
+    }
+    else {
+        console.error('Specify exactly one input source: --glob | --query | --neighbors-of');
+        process.exitCode = 1;
+        return;
+    }
+    let def;
+    try {
+        def = validate({
+            name,
+            producer,
+            inputs: renderInputsForValidate(inputs),
+            prompt,
+            aggregate,
+            refresh: { on_artifact_change: true, schedule: 'never', manual_only: false },
+            output_format: 'json',
+        });
+    }
+    catch (err) {
+        console.error(err instanceof ViewValidationError ? err.message : String(err));
+        process.exitCode = 1;
+        return;
+    }
+    const root = resolveViewsRoot();
+    const path = putDefinition(root, def);
+    console.log(`Added view '${def.name}'`);
+    console.log(`  Definition: ${path}`);
+    console.log('');
+    console.log('Build with: aiwg index views build ' + def.name);
+}
+function renderInputsForValidate(inputs) {
+    if (inputs.glob)
+        return { glob: inputs.glob };
+    if (inputs.query)
+        return { query: inputs.query };
+    if (inputs.neighborsOf) {
+        return {
+            'neighbors-of': {
+                id: inputs.neighborsOf.id,
+                depth: inputs.neighborsOf.depth,
+                direction: inputs.neighborsOf.direction,
+                ...(inputs.neighborsOf.graph ? { graph: inputs.neighborsOf.graph } : {}),
+            },
+        };
+    }
+    return {};
+}
+function handleList(args) {
+    const root = resolveViewsRoot();
+    const views = listViews(root);
+    if (asJson(args)) {
+        console.log(JSON.stringify(views, null, 2));
+        return;
+    }
+    if (views.length === 0) {
+        console.log('No views defined.');
+        console.log(`Views root: ${root}`);
+        return;
+    }
+    console.log(`name                          producer    aggregate     status            built`);
+    console.log(`────────────────────────────  ──────────  ────────────  ────────────────  ─────`);
+    for (const v of views) {
+        const status = v.staleReason ?? 'unknown';
+        const built = v.builtAt ? `${v.ageDays}d ago` : '—';
+        console.log(`${v.name.padEnd(28).slice(0, 28)}  ${v.producer.padEnd(10)}  ${v.aggregate.padEnd(12)}  ${status.padEnd(16)}  ${built}`);
+    }
+    console.log(`\n${views.length} views at ${root}`);
+}
+function handleShow(args) {
+    const name = args.find((a) => !a.startsWith('--'));
+    if (!name) {
+        console.error('Usage: aiwg index views show <name> [--json]');
+        process.exitCode = 1;
+        return;
+    }
+    const root = resolveViewsRoot();
+    try {
+        const r = getResult(root, name);
+        if (asJson(args)) {
+            console.log(JSON.stringify(r, null, 2));
+        }
+        else {
+            console.log(`View:     ${r.name}`);
+            console.log(`Built:    ${r.meta.builtAt}`);
+            console.log(`Inputs:   ${r.meta.inputCount} (cache hits: ${r.meta.cacheHits}, misses: ${r.meta.cacheMisses})`);
+            console.log(`Duration: ${r.meta.durationMs}ms`);
+            console.log('');
+            console.log(typeof r.result === 'string' ? r.result : JSON.stringify(r.result, null, 2));
+        }
+    }
+    catch (err) {
+        console.error(err.message);
+        process.exitCode = 1;
+    }
+}
+function handleBuild(args) {
+    const root = resolveViewsRoot();
+    const named = args.find((a) => !a.startsWith('--'));
+    const force = args.includes('--force');
+    const json = asJson(args);
+    const targets = named
+        ? [named]
+        : listViews(root)
+            .filter((v) => force || v.staleReason !== 'fresh')
+            .map((v) => v.name);
+    if (targets.length === 0) {
+        console.log('No views need building. Use --force to rebuild all, or pass a name.');
+        return;
+    }
+    const plans = [];
+    for (const name of targets) {
+        let def;
+        try {
+            def = getDefinition(root, name);
+        }
+        catch (err) {
+            console.error(err.message);
+            process.exitCode = 1;
+            continue;
+        }
+        const cacheKey = computeHash({
+            inputs: [
+                { artifactId: `view:${def.name}`, contentHash: 'pending' },
+            ],
+            query: def.prompt,
+            subPrompt: def.prompt,
+            model: 'claude-sonnet-4-6',
+            aggregateStrategy: def.aggregate,
+        });
+        plans.push({
+            name: def.name,
+            producer: def.producer,
+            inputs: def.inputs,
+            prompt: def.prompt,
+            aggregate: def.aggregate,
+            cacheKey,
+            outputPath: join(root, 'results', `${def.name}.json`),
+            metaPath: join(root, 'results', `${def.name}.meta.json`),
+        });
+    }
+    if (json) {
+        console.log(JSON.stringify({ plans }, null, 2));
+        return;
+    }
+    console.log('NOTE: This command emits dispatch plans. The RLM agent (/rlm-batch or /rlm-query)');
+    console.log('reads the plan, runs the prompt against the input set, and writes results to outputPath.');
+    console.log('');
+    for (const p of plans) {
+        console.log(`╭─ View: ${p.name}`);
+        console.log(`│  Producer:   ${p.producer}`);
+        console.log(`│  Inputs:     ${describeInputs(p.inputs)}`);
+        console.log(`│  Aggregate:  ${p.aggregate}`);
+        console.log(`│  Cache key:  ${p.cacheKey.slice(0, 16)}...`);
+        console.log(`│  Output:     ${p.outputPath}`);
+        console.log('╰─');
+    }
+    console.log('');
+    console.log(`${plans.length} plan(s) emitted. Re-run with --json to consume programmatically.`);
+}
+function describeInputs(i) {
+    if (i.glob)
+        return `glob: ${i.glob}`;
+    if (i.query)
+        return `query: ${i.query}`;
+    if (i.neighborsOf)
+        return `neighbors-of: ${i.neighborsOf.id} (depth ${i.neighborsOf.depth}, ${i.neighborsOf.direction})`;
+    return '<none>';
+}
+function handleRemove(args) {
+    const name = args.find((a) => !a.startsWith('--'));
+    if (!name) {
+        console.error('Usage: aiwg index views remove <name>');
+        process.exitCode = 1;
+        return;
+    }
+    const root = resolveViewsRoot();
+    const r = removeView(root, name);
+    if (!r.defRemoved) {
+        console.log(`No view named '${name}'.`);
+        return;
+    }
+    console.log(`Removed view '${name}' (definition${r.resultRemoved ? ' + results' : ''})`);
+}
+function printUsage() {
+    console.log('aiwg index views <subcommand>');
+    console.log('');
+    console.log('Subcommands:');
+    console.log('  add --name <n> --prompt <p> [--glob <g>|--query <q>|--neighbors-of <id>] [--aggregate <s>] [--producer <rlm-batch|rlm-query>]');
+    console.log('  add --from <path/to/view.yaml>');
+    console.log('  list [--json]');
+    console.log('  show <name> [--json]');
+    console.log('  build [<name>] [--force] [--json]');
+    console.log('  remove <name>');
+}
+//# sourceMappingURL=cli.js.map

package/dist/src/artifacts/views/definition.js

@@ -0,0 +1,170 @@
+/**
+ * View definition parser and validator.
+ *
+ * @implements #1207
+ * @see .aiwg/architecture/adr-rlm-index-features-impl-plan.md
+ */
+import { load as loadYaml, dump as dumpYaml } from 'js-yaml';
+const VALID_AGGREGATES = [
+    'concat',
+    'summarize',
+    'filter-true',
+    'filter-false',
+    'json-merge',
+];
+const VALID_PRODUCERS = ['rlm-batch', 'rlm-query'];
+const VALID_SCHEDULES = ['never', 'daily', 'weekly', 'monthly'];
+const NAME_RE = /^[a-z0-9][a-z0-9-_]*$/;
+export class ViewValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid view definition:\n  - ${issues.join('\n  - ')}`);
+        this.issues = issues;
+        this.name = 'ViewValidationError';
+    }
+}
+/** Parse a YAML string and validate as a ViewDefinition. Throws on failure. */
+export function parseViewYaml(yaml) {
+    const raw = loadYaml(yaml);
+    return validate(raw);
+}
+/** Validate an arbitrary value as a ViewDefinition. Throws ViewValidationError. */
+export function validate(value) {
+    const issues = [];
+    const v = (value ?? {});
+    if (typeof v['name'] !== 'string' || !NAME_RE.test(v['name'])) {
+        issues.push("'name' must be a kebab-case string [a-z0-9-_]");
+    }
+    if (typeof v['prompt'] !== 'string' || v['prompt'].trim().length === 0) {
+        issues.push("'prompt' must be a non-empty string");
+    }
+    const producer = v['producer'];
+    if (typeof producer !== 'string' || !VALID_PRODUCERS.includes(producer)) {
+        issues.push(`'producer' must be one of: ${VALID_PRODUCERS.join(', ')}`);
+    }
+    const aggregate = v['aggregate'];
+    if (typeof aggregate !== 'string' || !VALID_AGGREGATES.includes(aggregate)) {
+        issues.push(`'aggregate' must be one of: ${VALID_AGGREGATES.join(', ')}`);
+    }
+    const inputs = (v['inputs'] ?? {});
+    const inputModes = ['glob', 'query', 'neighbors-of', 'neighborsOf'].filter((k) => k in inputs);
+    if (inputModes.length === 0) {
+        issues.push("'inputs' must specify exactly one of: glob, query, neighbors-of");
+    }
+    else if (inputModes.length > 1) {
+        issues.push(`'inputs' must specify exactly one mode (got: ${inputModes.join(', ')})`);
+    }
+    if (inputs['glob'] !== undefined && typeof inputs['glob'] !== 'string') {
+        issues.push("'inputs.glob' must be a string");
+    }
+    if (inputs['query'] !== undefined && typeof inputs['query'] !== 'string') {
+        issues.push("'inputs.query' must be a string");
+    }
+    const neighbors = (inputs['neighbors-of'] ?? inputs['neighborsOf']);
+    if (neighbors !== undefined) {
+        if (typeof neighbors !== 'object' || neighbors === null) {
+            issues.push("'inputs.neighbors-of' must be an object with {id, depth, direction}");
+        }
+        else {
+            if (typeof neighbors['id'] !== 'string')
+                issues.push("'inputs.neighbors-of.id' is required");
+            const depth = neighbors['depth'];
+            if (typeof depth !== 'number' || depth < 1) {
+                issues.push("'inputs.neighbors-of.depth' must be a positive integer (default 1)");
+            }
+            const direction = neighbors['direction'];
+            if (direction !== undefined &&
+                direction !== 'in' &&
+                direction !== 'out' &&
+                direction !== 'both') {
+                issues.push("'inputs.neighbors-of.direction' must be one of: in, out, both");
+            }
+        }
+    }
+    const refresh = (v['refresh'] ?? {});
+    const onArtifactChange = refresh['on_artifact_change'] ?? refresh['onArtifactChange'];
+    if (onArtifactChange !== undefined && typeof onArtifactChange !== 'boolean') {
+        issues.push("'refresh.on_artifact_change' must be boolean");
+    }
+    const schedule = refresh['schedule'];
+    if (schedule !== undefined && !VALID_SCHEDULES.includes(schedule)) {
+        issues.push(`'refresh.schedule' must be one of: ${VALID_SCHEDULES.join(', ')}`);
+    }
+    const manualOnly = refresh['manual_only'] ?? refresh['manualOnly'];
+    if (manualOnly !== undefined && typeof manualOnly !== 'boolean') {
+        issues.push("'refresh.manual_only' must be boolean");
+    }
+    const outputFormat = v['output_format'] ?? v['outputFormat'] ?? 'json';
+    if (outputFormat !== 'json' &&
+        outputFormat !== 'markdown' &&
+        outputFormat !== 'text') {
+        issues.push("'output_format' must be one of: json, markdown, text");
+    }
+    if (issues.length > 0) {
+        throw new ViewValidationError(issues);
+    }
+    // Normalize the inputs into the canonical TS shape
+    const canonicalInputs = {};
+    if (typeof inputs['glob'] === 'string')
+        canonicalInputs.glob = inputs['glob'];
+    if (typeof inputs['query'] === 'string')
+        canonicalInputs.query = inputs['query'];
+    if (neighbors) {
+        canonicalInputs.neighborsOf = {
+            id: neighbors['id'],
+            depth: neighbors['depth'] ?? 1,
+            direction: (neighbors['direction'] ?? 'both'),
+            ...(typeof neighbors['graph'] === 'string' ? { graph: neighbors['graph'] } : {}),
+        };
+    }
+    return {
+        name: v['name'],
+        description: typeof v['description'] === 'string' ? v['description'] : undefined,
+        producer: producer,
+        inputs: canonicalInputs,
+        prompt: v['prompt'],
+        aggregate: aggregate,
+        refresh: {
+            onArtifactChange: typeof onArtifactChange === 'boolean' ? onArtifactChange : true,
+            schedule: schedule ?? 'never',
+            manualOnly: typeof manualOnly === 'boolean' ? manualOnly : false,
+        },
+        outputFormat: outputFormat ?? 'json',
+    };
+}
+/** Render a ViewDefinition back to canonical YAML. */
+export function dumpViewYaml(def) {
+    const out = {
+        name: def.name,
+        ...(def.description ? { description: def.description } : {}),
+        producer: def.producer,
+        inputs: renderInputs(def.inputs),
+        prompt: def.prompt,
+        aggregate: def.aggregate,
+        refresh: {
+            on_artifact_change: def.refresh.onArtifactChange,
+            schedule: def.refresh.schedule,
+            manual_only: def.refresh.manualOnly,
+        },
+        output_format: def.outputFormat,
+    };
+    return dumpYaml(out, { lineWidth: 100, noRefs: true });
+}
+function renderInputs(inputs) {
+    if (inputs.glob)
+        return { glob: inputs.glob };
+    if (inputs.query)
+        return { query: inputs.query };
+    if (inputs.neighborsOf) {
+        return {
+            'neighbors-of': {
+                id: inputs.neighborsOf.id,
+                depth: inputs.neighborsOf.depth,
+                direction: inputs.neighborsOf.direction,
+                ...(inputs.neighborsOf.graph ? { graph: inputs.neighborsOf.graph } : {}),
+            },
+        };
+    }
+    return {};
+}
+//# sourceMappingURL=definition.js.map

package/dist/src/artifacts/views/store.js

@@ -0,0 +1,149 @@
+/**
+ * View definition + result filesystem store.
+ *
+ * Layout:
+ *   .aiwg/index/views/
+ *     ├── <name>.yaml                  # definition
+ *     └── results/
+ *         ├── <name>.json              # last computed result
+ *         └── <name>.meta.json         # freshness metadata
+ *
+ * @implements #1207
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { join } from 'node:path';
+import { dumpViewYaml, parseViewYaml } from './definition.js';
+const VIEWS_ROOT_DEFAULT = '.aiwg/index/views';
+const NAME_RE = /^[a-z0-9][a-z0-9-_]*$/;
+export function resolveViewsRoot(cwd = process.cwd()) {
+    return join(cwd, VIEWS_ROOT_DEFAULT);
+}
+function defPath(root, name) {
+    if (!NAME_RE.test(name))
+        throw new Error(`Invalid view name: ${name}`);
+    return join(root, `${name}.yaml`);
+}
+function resultPath(root, name) {
+    return join(root, 'results', `${name}.json`);
+}
+function metaPath(root, name) {
+    return join(root, 'results', `${name}.meta.json`);
+}
+/** Persist a definition; creates the views directory if needed. */
+export function putDefinition(root, def) {
+    mkdirSync(root, { recursive: true });
+    const file = defPath(root, def.name);
+    writeFileSync(file, dumpViewYaml(def), 'utf-8');
+    return file;
+}
+/** Read a definition by name. Throws on missing or invalid. */
+export function getDefinition(root, name) {
+    const file = defPath(root, name);
+    if (!existsSync(file))
+        throw new Error(`No view: ${name}`);
+    return parseViewYaml(readFileSync(file, 'utf-8'));
+}
+/** Remove a definition and its results. */
+export function removeView(root, name) {
+    let defRemoved = false;
+    let resultRemoved = false;
+    const dp = defPath(root, name);
+    if (existsSync(dp)) {
+        rmSync(dp);
+        defRemoved = true;
+    }
+    const rp = resultPath(root, name);
+    const mp = metaPath(root, name);
+    if (existsSync(rp)) {
+        rmSync(rp);
+        resultRemoved = true;
+    }
+    if (existsSync(mp))
+        rmSync(mp);
+    return { defRemoved, resultRemoved };
+}
+/** List all views with freshness summary. */
+export function listViews(root, now = new Date()) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    for (const file of readdirSync(root)) {
+        if (!file.endsWith('.yaml'))
+            continue;
+        const name = file.replace(/\.yaml$/, '');
+        if (!NAME_RE.test(name))
+            continue;
+        let def;
+        try {
+            def = parseViewYaml(readFileSync(join(root, file), 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        const meta = readMeta(root, name);
+        const summary = {
+            name: def.name,
+            producer: def.producer,
+            aggregate: def.aggregate,
+            hasResults: meta !== null,
+            builtAt: meta?.builtAt ?? null,
+            ageDays: meta ? ageDays(meta.builtAt, now) : null,
+            staleReason: classifyStaleness(def, meta, now),
+        };
+        out.push(summary);
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Read a view's stored result. Throws on missing. */
+export function getResult(root, name) {
+    const rp = resultPath(root, name);
+    if (!existsSync(rp))
+        throw new Error(`No results for view: ${name}`);
+    const meta = readMeta(root, name);
+    if (!meta)
+        throw new Error(`No metadata for view: ${name}`);
+    const result = JSON.parse(readFileSync(rp, 'utf-8'));
+    return { name, result, meta };
+}
+/** Persist a view result + metadata atomically. */
+export function putResult(root, name, result, meta) {
+    mkdirSync(join(root, 'results'), { recursive: true });
+    writeFileSync(resultPath(root, name), JSON.stringify(result, null, 2), 'utf-8');
+    writeFileSync(metaPath(root, name), JSON.stringify(meta, null, 2), 'utf-8');
+}
+function readMeta(root, name) {
+    const mp = metaPath(root, name);
+    if (!existsSync(mp))
+        return null;
+    try {
+        return JSON.parse(readFileSync(mp, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function ageDays(iso, now) {
+    return Math.max(0, Math.floor((now.getTime() - new Date(iso).getTime()) / 86_400_000));
+}
+function classifyStaleness(def, meta, now) {
+    if (!meta)
+        return 'never-built';
+    const days = ageDays(meta.builtAt, now);
+    switch (def.refresh.schedule) {
+        case 'daily':
+            if (days >= 1)
+                return 'stale-schedule';
+            break;
+        case 'weekly':
+            if (days >= 7)
+                return 'stale-schedule';
+            break;
+        case 'monthly':
+            if (days >= 30)
+                return 'stale-schedule';
+            break;
+        case 'never': break;
+    }
+    return 'fresh';
+}
+//# sourceMappingURL=store.js.map

package/dist/src/artifacts/views/types.js

@@ -0,0 +1,8 @@
+/**
+ * Materialized index views — type definitions.
+ *
+ * @implements #1207
+ * @see .aiwg/architecture/adr-rlm-index-features-impl-plan.md
+ */
+export {};
+//# sourceMappingURL=types.js.map