@otomus/nerva-cli 0.1.1

package/dist/commands/test.js

@@ -0,0 +1,110 @@
+/**
+ * `nerva test` command.
+ *
+ * Detects the project language from nerva.yaml and runs the appropriate
+ * test runner (pytest for Python, vitest for TypeScript).
+ */
+import { spawn } from 'node:child_process';
+import { readNervaConfig } from '../config/nerva-yaml.js';
+/** Test runner command and arguments for each supported language. */
+const RUNNER_CONFIG = {
+    python: { cmd: 'python', args: ['-m', 'pytest'] },
+    typescript: { cmd: 'npx', args: ['vitest', 'run'] },
+};
+/**
+ * Builds the full argument list for the test runner, including optional coverage flag.
+ *
+ * @param lang - Project language
+ * @param coverage - Whether to enable coverage reporting
+ * @returns Tuple of [command, args]
+ */
+export function buildTestCommand(lang, coverage) {
+    const config = RUNNER_CONFIG[lang];
+    if (!config) {
+        throw new Error(`Unsupported language for testing: "${lang}"`);
+    }
+    const args = [...config.args];
+    if (coverage) {
+        args.push('--coverage');
+    }
+    return { cmd: config.cmd, args };
+}
+/**
+ * Detects the project language from nerva.yaml in the given directory.
+ *
+ * @param projectDir - Absolute path to project root
+ * @returns Detected project language
+ * @throws {Error} If nerva.yaml is missing or invalid
+ */
+export async function detectLanguage(projectDir) {
+    const config = await readNervaConfig(projectDir);
+    return config.lang;
+}
+/**
+ * Runs the test command as a child process and returns its exit code.
+ *
+ * @param projectDir - Working directory for the test runner
+ * @param cmd - Command to execute
+ * @param args - Arguments to pass
+ * @returns Exit code from the test runner (0 = success)
+ */
+export function runTestProcess(projectDir, cmd, args) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, {
+            cwd: projectDir,
+            stdio: 'inherit',
+            shell: true,
+        });
+        child.on('close', (code) => {
+            resolve(code ?? 1);
+        });
+        child.on('error', (err) => {
+            console.error(`[nerva test] Failed to start test runner: ${err.message}`);
+            resolve(1);
+        });
+    });
+}
+/**
+ * Executes the test command: detects language, runs the appropriate test runner,
+ * and prints a trace summary.
+ *
+ * @param projectDir - Absolute path to project root
+ * @param coverage - Whether to enable coverage
+ * @returns Exit code from the test runner
+ */
+export async function executeTest(projectDir, coverage) {
+    const lang = await detectLanguage(projectDir);
+    const { cmd, args } = buildTestCommand(lang, coverage);
+    console.log(`[nerva test] Detected language: ${lang}`);
+    console.log(`[nerva test] Running: ${cmd} ${args.join(' ')}`);
+    console.log('');
+    const startTime = Date.now();
+    const exitCode = await runTestProcess(projectDir, cmd, args);
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
+    console.log('');
+    console.log('  Nerva Test Summary');
+    console.log('  ==================');
+    console.log(`  Language: ${lang}`);
+    console.log(`  Runner:   ${cmd} ${args.join(' ')}`);
+    console.log(`  Duration: ${elapsed}s`);
+    console.log(`  Exit:     ${exitCode === 0 ? 'PASS' : 'FAIL'} (code ${exitCode})`);
+    console.log('');
+    return exitCode;
+}
+/**
+ * Registers the `nerva test` command with the CLI program.
+ *
+ * @param program - The root commander program
+ */
+export function registerTestCommand(program) {
+    program
+        .command('test')
+        .description('Run tests using the language-appropriate test runner')
+        .option('--coverage', 'Enable coverage reporting', false)
+        .action(async (options) => {
+        const projectDir = process.cwd();
+        const exitCode = await executeTest(projectDir, options.coverage);
+        process.exitCode = exitCode;
+    });
+}
+//# sourceMappingURL=test.js.map

package/dist/commands/test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.js","sourceRoot":"","sources":["../../src/commands/test.ts"],"names":[],"mappings":"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"}

package/dist/commands/trace-ui.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Trace UI HTML page served by the dev server.
+ *
+ * Returns a self-contained HTML page that displays trace events as a tree,
+ * auto-refreshing every 2 seconds from the `/traces` endpoint.
+ */
+/**
+ * Builds the trace UI HTML page as a string.
+ *
+ * The page fetches `/traces` every 2 seconds and renders spans
+ * as an indented, color-coded tree in a monospace font.
+ *
+ * @returns Complete HTML document string
+ */
+export declare function buildTraceHtml(): string;
+//# sourceMappingURL=trace-ui.d.ts.map

package/dist/commands/trace-ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-ui.d.ts","sourceRoot":"","sources":["../../src/commands/trace-ui.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAqGvC"}

package/dist/commands/trace-ui.js

@@ -0,0 +1,117 @@
+/**
+ * Trace UI HTML page served by the dev server.
+ *
+ * Returns a self-contained HTML page that displays trace events as a tree,
+ * auto-refreshing every 2 seconds from the `/traces` endpoint.
+ */
+/**
+ * Builds the trace UI HTML page as a string.
+ *
+ * The page fetches `/traces` every 2 seconds and renders spans
+ * as an indented, color-coded tree in a monospace font.
+ *
+ * @returns Complete HTML document string
+ */
+export function buildTraceHtml() {
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Nerva Trace UI</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: "SF Mono", "Menlo", "Consolas", monospace;
+      font-size: 13px;
+      background: #1a1a2e;
+      color: #e0e0e0;
+      padding: 24px;
+    }
+    h1 { color: #7fdbca; margin-bottom: 16px; font-size: 18px; }
+    .status { color: #888; margin-bottom: 16px; font-size: 11px; }
+    .trace-list { list-style: none; }
+    .trace-item { margin-bottom: 2px; white-space: pre; }
+    .channel-agent { color: #c792ea; }
+    .channel-tool { color: #82aaff; }
+    .channel-middleware { color: #ffcb6b; }
+    .channel-router { color: #f78c6c; }
+    .channel-system { color: #89ddff; }
+    .channel-unknown { color: #a0a0a0; }
+    .timestamp { color: #666; }
+    .empty { color: #555; font-style: italic; margin-top: 12px; }
+  </style>
+</head>
+<body>
+  <h1>Nerva Trace UI</h1>
+  <div class="status" id="status">Connecting...</div>
+  <ul class="trace-list" id="traces"></ul>
+
+  <script>
+    const CHANNEL_COLORS = {
+      agent: 'channel-agent',
+      tool: 'channel-tool',
+      middleware: 'channel-middleware',
+      router: 'channel-router',
+      system: 'channel-system',
+    };
+
+    function channelClass(channel) {
+      return CHANNEL_COLORS[channel] || 'channel-unknown';
+    }
+
+    function escapeHtml(text) {
+      const div = document.createElement('div');
+      div.textContent = text;
+      return div.innerHTML;
+    }
+
+    function renderTrace(trace, depth) {
+      const indent = '  '.repeat(depth);
+      const ch = trace.channel || 'unknown';
+      const ts = trace.timestamp ? new Date(trace.timestamp).toISOString().slice(11, 23) : '';
+      const msg = escapeHtml(trace.message || trace.event || JSON.stringify(trace));
+
+      let html = '<li class="trace-item">';
+      html += '<span class="timestamp">' + escapeHtml(ts) + '</span> ';
+      html += indent;
+      html += '<span class="' + channelClass(ch) + '">[' + escapeHtml(ch) + ']</span> ';
+      html += msg;
+      html += '</li>';
+
+      if (Array.isArray(trace.children)) {
+        for (const child of trace.children) {
+          html += renderTrace(child, depth + 1);
+        }
+      }
+
+      return html;
+    }
+
+    async function refresh() {
+      try {
+        const res = await fetch('/traces');
+        const data = await res.json();
+        const list = document.getElementById('traces');
+        const status = document.getElementById('status');
+
+        if (!Array.isArray(data) || data.length === 0) {
+          list.innerHTML = '<li class="empty">No traces yet.</li>';
+        } else {
+          list.innerHTML = data.map(function(t) { return renderTrace(t, 0); }).join('');
+        }
+
+        status.textContent = 'Last updated: ' + new Date().toLocaleTimeString() +
+          ' (' + (data.length || 0) + ' traces)';
+      } catch (err) {
+        document.getElementById('status').textContent = 'Error: ' + err.message;
+      }
+    }
+
+    refresh();
+    setInterval(refresh, 2000);
+  </script>
+</body>
+</html>`;
+}
+//# sourceMappingURL=trace-ui.js.map

package/dist/commands/trace-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-ui.js","sourceRoot":"","sources":["../../src/commands/trace-ui.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAmGD,CAAC;AACT,CAAC"}

package/dist/config/nerva-yaml.d.ts

@@ -0,0 +1,70 @@
+/**
+ * nerva.yaml configuration parser and validator.
+ *
+ * Handles reading, writing, and validating the project-level nerva.yaml
+ * that declares agents, tools, middleware, and routers.
+ */
+/** A single registered component (agent, tool, middleware, or router). */
+export interface ComponentEntry {
+    name: string;
+    path: string;
+    description?: string;
+}
+/** Supported project languages. */
+export type ProjectLang = 'python' | 'typescript';
+/** Top-level nerva.yaml schema. */
+export interface NervaConfig {
+    name: string;
+    version: string;
+    lang: ProjectLang;
+    agents: ComponentEntry[];
+    tools: ComponentEntry[];
+    middleware: ComponentEntry[];
+    routers: ComponentEntry[];
+    policy?: Record<string, unknown>;
+}
+/** Component types that can be registered in nerva.yaml. */
+export type ComponentType = 'agent' | 'tool' | 'middleware' | 'router';
+/** Keys used in nerva.yaml for each component type's list section. */
+export type ConfigListKey = 'agents' | 'tools' | 'middleware' | 'routers';
+/**
+ * Returns the config key used in nerva.yaml for a given component type.
+ *
+ * @param type - The singular component type
+ * @returns The yaml section key (e.g. 'agent' -> 'agents', 'middleware' -> 'middleware')
+ */
+export declare function pluralizeType(type: ComponentType): ConfigListKey;
+/**
+ * Parses raw YAML-like text into a NervaConfig object.
+ *
+ * Uses a simple line-based parser for the flat nerva.yaml format.
+ * This avoids pulling in a full YAML library for a predictable schema.
+ *
+ * @param content - Raw file content
+ * @returns Parsed configuration
+ * @throws {Error} If required fields are missing or lang is invalid
+ */
+export declare function parseNervaConfig(content: string): NervaConfig;
+/**
+ * Reads and parses nerva.yaml from the given project directory.
+ *
+ * @param projectDir - Absolute path to project root
+ * @returns Parsed NervaConfig
+ * @throws {Error} If the file cannot be read or parsed
+ */
+export declare function readNervaConfig(projectDir: string): Promise<NervaConfig>;
+/**
+ * Serializes a NervaConfig to YAML-formatted text.
+ *
+ * @param config - The configuration to serialize
+ * @returns YAML string
+ */
+export declare function serializeNervaConfig(config: NervaConfig): string;
+/**
+ * Writes a NervaConfig back to nerva.yaml in the given directory.
+ *
+ * @param projectDir - Absolute path to project root
+ * @param config - Configuration to write
+ */
+export declare function writeNervaConfig(projectDir: string, config: NervaConfig): Promise<void>;
+//# sourceMappingURL=nerva-yaml.d.ts.map

package/dist/config/nerva-yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nerva-yaml.d.ts","sourceRoot":"","sources":["../../src/config/nerva-yaml.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,mCAAmC;AACnC,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;AAElD,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEvE,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,YAAY,GAAG,SAAS,CAAC;AAc1E;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAEhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CA+D7D;AAmDD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAI9E;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAuBhE;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7F"}

package/dist/config/nerva-yaml.js

@@ -0,0 +1,185 @@
+/**
+ * nerva.yaml configuration parser and validator.
+ *
+ * Handles reading, writing, and validating the project-level nerva.yaml
+ * that declares agents, tools, middleware, and routers.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const VALID_LANGS = new Set(['python', 'typescript']);
+const REQUIRED_FIELDS = ['name', 'version', 'lang'];
+const COMPONENT_LISTS = ['agent', 'tool', 'middleware', 'router'];
+/** Maps singular component type to the nerva.yaml section key. */
+const TYPE_TO_KEY = {
+    agent: 'agents',
+    tool: 'tools',
+    middleware: 'middleware',
+    router: 'routers',
+};
+/**
+ * Returns the config key used in nerva.yaml for a given component type.
+ *
+ * @param type - The singular component type
+ * @returns The yaml section key (e.g. 'agent' -> 'agents', 'middleware' -> 'middleware')
+ */
+export function pluralizeType(type) {
+    return TYPE_TO_KEY[type];
+}
+/**
+ * Parses raw YAML-like text into a NervaConfig object.
+ *
+ * Uses a simple line-based parser for the flat nerva.yaml format.
+ * This avoids pulling in a full YAML library for a predictable schema.
+ *
+ * @param content - Raw file content
+ * @returns Parsed configuration
+ * @throws {Error} If required fields are missing or lang is invalid
+ */
+export function parseNervaConfig(content) {
+    const lines = content.split('\n');
+    const config = {};
+    const listSections = {
+        agents: [],
+        tools: [],
+        middleware: [],
+        routers: [],
+    };
+    let currentSection = null;
+    let currentEntry = null;
+    for (const rawLine of lines) {
+        const line = rawLine.trimEnd();
+        if (line.trim() === '' || line.trim().startsWith('#')) {
+            continue;
+        }
+        // Top-level section header (e.g. "agents:")
+        const sectionMatch = line.match(/^(\w+):$/);
+        if (sectionMatch) {
+            flushEntry(currentSection, currentEntry, listSections);
+            currentEntry = null;
+            const key = sectionMatch[1];
+            if (key in listSections) {
+                currentSection = key;
+            }
+            else {
+                currentSection = null;
+            }
+            continue;
+        }
+        // Top-level key: value pair (e.g. "name: my-project")
+        const kvMatch = line.match(/^(\w+):\s+(.+)$/);
+        if (kvMatch && !currentSection) {
+            config[kvMatch[1]] = kvMatch[2].trim();
+            continue;
+        }
+        // List item start (e.g. "  - name: my-agent")
+        const listItemMatch = line.match(/^\s+-\s+(\w+):\s+(.+)$/);
+        if (listItemMatch && currentSection) {
+            flushEntry(currentSection, currentEntry, listSections);
+            currentEntry = { [listItemMatch[1]]: listItemMatch[2].trim() };
+            continue;
+        }
+        // Continuation of list item (e.g. "    path: agents/my-agent.py")
+        const continuationMatch = line.match(/^\s+(\w+):\s+(.+)$/);
+        if (continuationMatch && currentSection && currentEntry) {
+            currentEntry[continuationMatch[1]] = continuationMatch[2].trim();
+            continue;
+        }
+    }
+    flushEntry(currentSection, currentEntry, listSections);
+    return validateConfig({
+        ...config,
+        ...listSections,
+    });
+}
+/**
+ * Flushes a partially-built component entry into the appropriate list.
+ *
+ * @param section - Current yaml section name
+ * @param entry - Partial entry to flush
+ * @param lists - Map of section name to component entries
+ */
+function flushEntry(section, entry, lists) {
+    if (!section || !entry || !entry.name || !entry.path) {
+        return;
+    }
+    lists[section].push({ name: entry.name, path: entry.path, description: entry.description });
+}
+/**
+ * Validates a raw parsed object against the NervaConfig schema.
+ *
+ * @param raw - Unvalidated config object
+ * @returns Validated NervaConfig
+ * @throws {Error} If validation fails
+ */
+function validateConfig(raw) {
+    for (const field of REQUIRED_FIELDS) {
+        if (!raw[field] || typeof raw[field] !== 'string') {
+            throw new Error(`nerva.yaml: missing or invalid required field "${field}"`);
+        }
+    }
+    const lang = raw['lang'];
+    if (!VALID_LANGS.has(lang)) {
+        throw new Error(`nerva.yaml: lang must be "python" or "typescript", got "${lang}"`);
+    }
+    return {
+        name: raw['name'],
+        version: raw['version'],
+        lang: lang,
+        agents: raw['agents'] ?? [],
+        tools: raw['tools'] ?? [],
+        middleware: raw['middleware'] ?? [],
+        routers: raw['routers'] ?? [],
+        policy: raw['policy'] ?? undefined,
+    };
+}
+/**
+ * Reads and parses nerva.yaml from the given project directory.
+ *
+ * @param projectDir - Absolute path to project root
+ * @returns Parsed NervaConfig
+ * @throws {Error} If the file cannot be read or parsed
+ */
+export async function readNervaConfig(projectDir) {
+    const filePath = join(projectDir, 'nerva.yaml');
+    const content = await readFile(filePath, 'utf-8');
+    return parseNervaConfig(content);
+}
+/**
+ * Serializes a NervaConfig to YAML-formatted text.
+ *
+ * @param config - The configuration to serialize
+ * @returns YAML string
+ */
+export function serializeNervaConfig(config) {
+    const lines = [];
+    lines.push(`name: ${config.name}`);
+    lines.push(`version: ${config.version}`);
+    lines.push(`lang: ${config.lang}`);
+    for (const type of COMPONENT_LISTS) {
+        const plural = pluralizeType(type);
+        const entries = config[plural];
+        lines.push('');
+        lines.push(`${plural}:`);
+        for (const entry of entries) {
+            lines.push(`  - name: ${entry.name}`);
+            lines.push(`    path: ${entry.path}`);
+            if (entry.description) {
+                lines.push(`    description: ${entry.description}`);
+            }
+        }
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Writes a NervaConfig back to nerva.yaml in the given directory.
+ *
+ * @param projectDir - Absolute path to project root
+ * @param config - Configuration to write
+ */
+export async function writeNervaConfig(projectDir, config) {
+    const filePath = join(projectDir, 'nerva.yaml');
+    const content = serializeNervaConfig(config);
+    await writeFile(filePath, content, 'utf-8');
+}
+//# sourceMappingURL=nerva-yaml.js.map

package/dist/config/nerva-yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nerva-yaml.js","sourceRoot":"","sources":["../../src/config/nerva-yaml.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Nerva CLI entry point.
+ *
+ * Registers all sub-commands and runs the CLI program.
+ */
+import { Command } from 'commander';
+/**
+ * Creates and configures the root CLI program with all commands.
+ *
+ * @returns Configured Commander program
+ */
+export declare function createProgram(): Command;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAgBvC"}

package/dist/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Nerva CLI entry point.
+ *
+ * Registers all sub-commands and runs the CLI program.
+ */
+import { Command } from 'commander';
+import { registerNewCommand } from './commands/new.js';
+import { registerGenerateCommand } from './commands/generate.js';
+import { registerListCommand } from './commands/list.js';
+import { registerDevCommand } from './commands/dev.js';
+import { registerTestCommand } from './commands/test.js';
+import { registerPluginCommand } from './commands/plugin.js';
+const VERSION = '0.1.0';
+/**
+ * Creates and configures the root CLI program with all commands.
+ *
+ * @returns Configured Commander program
+ */
+export function createProgram() {
+    const program = new Command();
+    program
+        .name('nerva')
+        .description('CLI for the Nerva agent runtime')
+        .version(VERSION);
+    registerNewCommand(program);
+    registerGenerateCommand(program);
+    registerListCommand(program);
+    registerDevCommand(program);
+    registerTestCommand(program);
+    registerPluginCommand(program);
+    return program;
+}
+const program = createProgram();
+program.parse(process.argv);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAE7D,MAAM,OAAO,GAAG,OAAO,CAAC;AAExB;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,OAAO,CAAC;SACb,WAAW,CAAC,iCAAiC,CAAC;SAC9C,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpB,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5B,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5B,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7B,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;AAChC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}

package/dist/registry/plugin-registry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Community plugin registry client.
+ *
+ * Searches the npm registry for packages with the `nerva-plugin` keyword
+ * and fetches package metadata. Uses `https.get` with no external dependencies.
+ */
+/** Summary of a plugin found in the npm registry. */
+export interface RegistryPluginInfo {
+    name: string;
+    description: string;
+    version: string;
+    downloads: number;
+}
+/**
+ * Searches the npm registry for packages matching a query and the `nerva-plugin` keyword.
+ *
+ * @param query - Free-text search query
+ * @returns Array of matching plugin summaries, sorted by relevance
+ * @throws {Error} If the npm registry is unreachable or returns invalid data
+ */
+export declare function searchPlugins(query: string): Promise<RegistryPluginInfo[]>;
+/**
+ * Fetches detailed package info from the npm registry for a specific package.
+ *
+ * @param name - Exact npm package name
+ * @returns Plugin info with name, description, latest version, and monthly downloads
+ * @throws {Error} If the package is not found or the registry is unreachable
+ */
+export declare function fetchPluginInfo(name: string): Promise<RegistryPluginInfo>;
+//# sourceMappingURL=plugin-registry.d.ts.map

package/dist/registry/plugin-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../../src/registry/plugin-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AA4ED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAiBhF;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsB/E"}