radar-cli 0.1.0

package/dist/index.js

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/convex-client.ts
+import { ConvexHttpClient } from "convex/browser";
+
+// ../../convex/_generated/api.js
+import { anyApi, componentsGeneric } from "convex/server";
+var api = anyApi;
+var components = componentsGeneric();
+
+// src/convex-client.ts
+var DEFAULT_CONVEX_URL = "https://tough-bird-920.convex.cloud";
+var cachedClient = null;
+function getConvexClient() {
+  if (cachedClient) return cachedClient;
+  const url = process.env.CONVEX_URL ?? DEFAULT_CONVEX_URL;
+  cachedClient = new ConvexHttpClient(url);
+  return cachedClient;
+}
+
+// src/commands/context.ts
+function registerContext(program2) {
+  program2.command("context").description(
+    "Get an overview of a site's knowledge \u2014 metadata and file summaries without full body content"
+  ).argument("<domain>", "Website domain, e.g. github.com").action(async (domain) => {
+    const client = getConvexClient();
+    const site = await client.query(api.sites.getByDomain, { domain });
+    if (!site) {
+      console.error(
+        `No knowledge found for "${domain}". Try "radar search" or "radar explore" to discover or create knowledge for this site.`
+      );
+      process.exit(1);
+    }
+    const files = await client.query(api.files.listBySite, {
+      siteId: site._id
+    });
+    const fileList = files.map(
+      (f) => `- **${f.path}** \u2014 ${f.title} [${f.confidence}]
+  ${f.summary}`
+    ).join("\n");
+    const lines = [
+      `# ${site.name} (${site.domain})`,
+      "",
+      `> ${site.description}`,
+      "",
+      `Tags: ${site.tags.join(", ")}`,
+      `Files: ${site.fileCount}`,
+      site.complexity ? `Complexity: ${site.complexity}` : null,
+      site.authRequired ? `Auth required: yes` : null,
+      "",
+      "## Available Knowledge Files",
+      "",
+      fileList || "_No files yet._"
+    ].filter((line) => line !== null);
+    console.log(lines.join("\n"));
+  });
+}
+
+// src/commands/read.ts
+function reconstructMarkdown(file) {
+  const frontmatter = [
+    "---",
+    `title: "${file.title}"`,
+    `domain: "${file.domain}"`,
+    `path: "${file.path}"`,
+    `summary: "${file.summary}"`,
+    `tags: [${file.tags.map((t) => `"${t}"`).join(", ")}]`,
+    `entities:`,
+    `  primary: "${file.entities.primary}"`,
+    `  disambiguation: "${file.entities.disambiguation}"`,
+    `  related_concepts: [${file.entities.relatedConcepts.map((c) => `"${c}"`).join(", ")}]`,
+    `intent:`,
+    `  core_question: "${file.intent.coreQuestion}"`,
+    `  audience: "${file.intent.audience}"`,
+    `confidence: "${file.confidence}"`,
+    `requires_auth: ${file.requiresAuth}`,
+    file.selectorsCount !== void 0 ? `selectors_count: ${file.selectorsCount}` : null,
+    `related_files: [${file.relatedFiles.map((f) => `"${f}"`).join(", ")}]`,
+    `version: ${file.version}`,
+    `last_updated: "${new Date(file.lastUpdated).toISOString()}"`,
+    `last_contributor: "${file.lastContributor}"`,
+    `last_change_reason: "${file.lastChangeReason}"`,
+    "---"
+  ].filter((line) => line !== null).join("\n");
+  return `${frontmatter}
+
+${file.content}`;
+}
+function registerRead(program2) {
+  program2.command("read").description(
+    "Get the full content of a specific knowledge file, including YAML frontmatter and markdown body"
+  ).argument("<domain>", "Website domain, e.g. github.com").argument("<path>", 'File path within the site, e.g. "flows/checkout"').action(async (domain, path) => {
+    const client = getConvexClient();
+    const file = await client.query(api.files.getByDomainPath, {
+      domain,
+      path
+    });
+    if (!file) {
+      console.error(
+        `No file found at "${domain}/${path}". Use "radar list ${domain}" to see available files.`
+      );
+      process.exit(1);
+    }
+    console.log(reconstructMarkdown(file));
+  });
+}
+
+// src/commands/list.ts
+import { minimatch } from "minimatch";
+function registerList(program2) {
+  program2.command("list").description(
+    "List knowledge files for a domain with frontmatter summaries (no body content)"
+  ).argument("<domain>", "Website domain, e.g. github.com").option(
+    "--glob <pattern>",
+    'Glob pattern to filter files, e.g. "flows/*"'
+  ).action(async (domain, opts) => {
+    const client = getConvexClient();
+    const site = await client.query(api.sites.getByDomain, { domain });
+    if (!site) {
+      console.error(`No site found for "${domain}".`);
+      process.exit(1);
+    }
+    let files = await client.query(api.files.listBySite, {
+      siteId: site._id
+    });
+    if (opts.glob) {
+      files = files.filter((f) => minimatch(f.path, opts.glob));
+    }
+    if (files.length === 0) {
+      console.log(
+        `No files found for "${domain}"${opts.glob ? ` matching "${opts.glob}"` : ""}.`
+      );
+      return;
+    }
+    const formatted = files.map(
+      (f) => `- **${f.path}** \u2014 ${f.title} [${f.confidence}]
+  ${f.summary}
+  Tags: ${f.tags.join(", ")}`
+    ).join("\n");
+    console.log(
+      `${files.length} file(s) for ${domain}${opts.glob ? ` (matching "${opts.glob}")` : ""}:
+
+${formatted}`
+    );
+  });
+}
+
+// src/commands/search.ts
+function registerSearch(program2) {
+  program2.command("search").description(
+    "Full-text search across all knowledge file content. Returns matching files with frontmatter."
+  ).argument("<query>", "Search query text").option("--domain <domain>", "Filter results to a specific domain").action(async (query, opts) => {
+    const client = getConvexClient();
+    const results = await client.query(api.files.search, {
+      query,
+      domain: opts.domain
+    });
+    if (results.length === 0) {
+      console.log(
+        `No results found for "${query}"${opts.domain ? ` in ${opts.domain}` : ""}. Try broader search terms or check if the site has been explored.`
+      );
+      return;
+    }
+    const formatted = results.map(
+      (f) => `### ${f.domain}/${f.path}
+**${f.title}** [${f.confidence}]
+${f.summary}
+Tags: ${f.tags.join(", ")}`
+    ).join("\n\n");
+    console.log(`Found ${results.length} result(s):
+
+${formatted}`);
+  });
+}
+
+// src/commands/submit.ts
+import { readFileSync } from "fs";
+import { parse } from "zod-matter";
+
+// src/schemas/frontmatter.ts
+import { z } from "zod";
+var knowledgeFrontmatterSchema = z.object({
+  title: z.string(),
+  domain: z.string(),
+  path: z.string(),
+  summary: z.string().max(300),
+  tags: z.array(z.string()),
+  entities: z.object({
+    primary: z.string(),
+    disambiguation: z.string(),
+    related_concepts: z.array(z.string())
+  }),
+  intent: z.object({
+    core_question: z.string(),
+    audience: z.enum(["browser-agent", "coding-agent", "human", "any"])
+  }),
+  confidence: z.enum(["low", "medium", "high"]),
+  requires_auth: z.boolean(),
+  selectors_count: z.number().int().min(0).optional(),
+  related_files: z.array(z.string()).default([]),
+  version: z.number().int().positive(),
+  last_updated: z.string().datetime(),
+  last_contributor: z.string(),
+  last_change_reason: z.string()
+});
+
+// src/commands/submit.ts
+function registerSubmit(program2) {
+  program2.command("submit").description(
+    "Submit a knowledge file to Radar. The file must be markdown with valid YAML frontmatter. Auto-approved, versioned, and attributed."
+  ).argument("<file>", "Path to a local markdown file with YAML frontmatter").requiredOption(
+    "--contributor <name>",
+    'Your name/identifier, e.g. "my-agent"'
+  ).requiredOption(
+    "--reason <reason>",
+    'Why this change was made, e.g. "Added checkout flow tips"'
+  ).option(
+    "--agent-type <type>",
+    'Type of agent, e.g. "claude-code", "cursor"'
+  ).action(
+    async (filePath, opts) => {
+      let content;
+      try {
+        content = readFileSync(filePath, "utf-8");
+      } catch {
+        console.error(`Could not read file: ${filePath}`);
+        process.exit(1);
+      }
+      let parsed;
+      try {
+        parsed = parse(content, knowledgeFrontmatterSchema);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(
+          `Invalid knowledge file format:
+
+${message}
+
+Ensure the markdown has valid YAML frontmatter matching the knowledge file schema.`
+        );
+        process.exit(1);
+      }
+      const { data: fm, content: body } = parsed;
+      const client = getConvexClient();
+      const result = await client.mutation(api.files.submit, {
+        domain: fm.domain,
+        path: fm.path,
+        title: fm.title,
+        summary: fm.summary,
+        tags: fm.tags,
+        entities: {
+          primary: fm.entities.primary,
+          disambiguation: fm.entities.disambiguation,
+          relatedConcepts: fm.entities.related_concepts
+        },
+        intent: {
+          coreQuestion: fm.intent.core_question,
+          audience: fm.intent.audience
+        },
+        confidence: fm.confidence,
+        requiresAuth: fm.requires_auth,
+        selectorsCount: fm.selectors_count,
+        relatedFiles: fm.related_files,
+        content: body.trim(),
+        contributorName: opts.contributor,
+        changeReason: opts.reason,
+        agentType: opts.agentType
+      });
+      console.log(
+        `Submitted successfully!
+
+File: ${fm.domain}/${fm.path}
+Version: ${result.version}
+Points awarded: ${result.pointsAwarded}`
+      );
+    }
+  );
+}
+
+// src/urls.ts
+function normalizeUrl(rawUrl) {
+  if (!rawUrl.includes("://")) rawUrl = `https://${rawUrl}`;
+  const parsed = new URL(rawUrl);
+  let domain = parsed.hostname.toLowerCase();
+  if (domain.startsWith("www.")) domain = domain.slice(4);
+  let path = parsed.pathname.toLowerCase();
+  if (path.endsWith("/") && path.length > 1) path = path.slice(0, -1);
+  if (path === "") path = "/";
+  return { domain, path, url: `https://${domain}${path}` };
+}
+
+// src/commands/explore.ts
+function registerExplore(program2) {
+  program2.command("explore").description(
+    "Trigger a Browser Use exploration of a website. Queues an automated agent to navigate the site and generate knowledge files."
+  ).argument(
+    "<url>",
+    'URL of the site to explore, e.g. "https://amazon.com" or "github.com"'
+  ).action(async (url) => {
+    const { domain, url: normalizedUrl } = normalizeUrl(url);
+    const client = getConvexClient();
+    const explorationId = await client.mutation(api.explorations.create, {
+      domain,
+      url: normalizedUrl
+    });
+    console.log(
+      `Exploration queued for ${domain}.
+
+Exploration ID: ${explorationId}
+URL: ${normalizedUrl}
+
+The Browser Use agent will explore the site and generate knowledge files. Check the Radar web UI for real-time progress.`
+    );
+  });
+}
+
+// src/index.ts
+var program = new Command();
+program.name("radar").description(
+  "Radar CLI \u2014 query and contribute to the shared knowledge base for web agents"
+).version("0.1.0");
+registerContext(program);
+registerRead(program);
+registerList(program);
+registerSearch(program);
+registerSubmit(program);
+registerExplore(program);
+program.parse();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "radar-cli",
+  "version": "0.1.0",
+  "description": "CLI for Radar — the shared knowledge base for web agents",
+  "type": "module",
+  "bin": {
+    "radar": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsc -b --watch",
+    "start": "node dist/index.js",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build",
+    "publish:npm": "npm publish --access public"
+  },
+  "keywords": [
+    "radar",
+    "web-agents",
+    "knowledge-base",
+    "mcp",
+    "browser-automation"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "convex": "^1.21.0",
+    "gray-matter": "^4.0.3",
+    "minimatch": "^10.2.4",
+    "zod": "^3.25.76",
+    "zod-matter": "^0.1.3"
+  },
+  "devDependencies": {
+    "@radar/typescript-config": "workspace:*",
+    "@types/node": "^25.3.3",
+    "tsup": "^8.5.1",
+    "typescript": "5.9.2"
+  }
+}