@helmlabs/docbot 0.0.1

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@helmlabs/docbot",
+  "version": "0.0.1",
+  "description": "AI-powered CLI for analyzing, planning, and executing documentation improvements",
+  "author": "Helm",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "docbot": "dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "exports": {
+    ".": "./dist/cli.js",
+    "./config": "./src/config/index.ts"
+  },
+  "files": [
+    "dist",
+    "src/config",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/helmlabs/docbot.git"
+  },
+  "homepage": "https://github.com/helmlabs/docbot/tree/main#readme",
+  "bugs": "https://github.com/helmlabs/docbot/issues",
+  "keywords": [
+    "documentation",
+    "ai",
+    "cli",
+    "docs",
+    "mdx",
+    "mintlify",
+    "bun"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "build": "bun build ./src/cli.ts --production --target=bun --format=esm --external react --external ink --outfile=dist/cli.js",
+    "dev": "bun run src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build",
+    "knip": "knip",
+    "format-and-lint": "biome check .",
+    "format-and-lint:fix": "biome check . --fix"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.0.6",
+    "@types/bun": "latest",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.0.0",
+    "@types/yargs": "^17.0.33",
+    "@ai-sdk/provider-utils": "^4.0.2",
+    "knip": "^5.79.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.2",
+    "@ai-sdk/cohere": "^3.0.1",
+    "@ai-sdk/devtools": "^0.0.2",
+    "@ai-sdk/google": "^3.0.2",
+    "@ai-sdk/mcp": "1.0.1",
+    "@ai-sdk/openai": "^3.0.2",
+    "@ai-sdk/react": "^3.0.3",
+    "@elysiajs/cors": "^1.0.0",
+    "@qdrant/qdrant-js": "^1.16.2",
+    "ai": "^6.0.3",
+    "elysia": "^1.4.19",
+    "ink": "^6.6.0",
+    "ink-scroll-view": "^0.3.3",
+    "ink-spinner": "^5.0.0",
+    "mdast": "^3.0.0",
+    "nanoid": "^5.1.6",
+    "react": "^19.2.3",
+    "remark-frontmatter": "^5.0.0",
+    "remark-mdx": "^3.1.1",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "yaml": "^2.8.2",
+    "yargs": "^18.0.0",
+    "zod": "^4.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,218 @@
+![docbot header](https://ltwtljxsstgqk8ay.public.blob.vercel-storage.com/docbot.jpg)
+
+# Docbot
+
+[![npm version](https://img.shields.io/npm/v/@helmlabs/docbot)](https://www.npmjs.com/package/@helmlabs/docbot)
+
+Docbot is a CLI agent that helps you keep documentation up to date.
+
+It reads your docs + codebase, proposes a concrete plan (file-level operations), and only writes changes after you approve.
+
+## Notes on speed (and why it's still worth it)
+
+- Indexing can feel a bit slow right now; running a full cycle across a bunch of pages may take 5–10 minutes, but that's still way faster than the hours you'd spend doing it by hand
+- Overall flow is under-optimized today; expect it to improve soon (again, the time and token costs are still much lower than manual work, at least for us)
+
+## Install
+
+```bash
+bunx @helmlabs/docbot --help
+```
+
+(Optional) global:
+
+```bash
+bun add -g @helmlabs/docbot
+docbot --help
+```
+
+## Quick Start
+
+```bash
+# qdrant (required)
+docker run --rm -p 6333:6333 -v "$(pwd)/qdrant_storage:/qdrant/storage" qdrant/qdrant
+
+# config + local state (.docbot/, docbot.config.jsonc)
+bunx @helmlabs/docbot init
+
+# index docs/code (uses config; CLI flags override)
+bunx @helmlabs/docbot index
+
+# run the agent
+bunx @helmlabs/docbot run "document the settings page"
+```
+
+## What It Does
+
+- **Codebase-aware doc work**: finds gaps/stale pages by reading your code, not vibes
+- **Search that's actually useful**: semantic + exact match, reranked
+- **Interactive planning**: you approve the plan before anything touches your files
+- **MDX-first output**: structured edits instead of “giant blob rewrite”
+- **TUI + API**: run with a terminal UI, or start the HTTP server only
+
+## Requirements
+
+Required:
+
+- [Bun](https://bun.sh)
+- [Qdrant](https://qdrant.tech) (local via Docker or remote - `docbot init` will set you up with a local instance via Docker)
+- `rg` (ripgrep) for fast exact-match search
+- `AI_GATEWAY_API_KEY` (Vercel AI Gateway)
+
+## How It Works
+
+1. **Analysis**: scan docs + codebase, find gaps/duplicates/stale content
+2. **Planning**: propose a structured set of operations (create/update/move/delete/consolidate)
+3. **Execution**: apply changes (MDX edits, component-aware when relevant)
+4. **Review**: verify and re-scan for obvious misses
+
+## Dependencies & Design Choices
+
+Docbot is opinionated so we were able to build it fast, but it's not meant to stay tied to a single docs framework or provider forever.
+
+- **Docs frameworks**: Today Docbot targets MDX-based doc sites and detects Mintlify project structure automatically (as long as you use `docs.json`). Mintlify was the first target because that's what we use at Helm; support will expand (custom MDX, Fumadocs, Nextra, Docusaurus, etc.). It's just a matter of tweaking the tools and prompts.
+- **Vector store**: Currently Qdrant (required). It's easy to run locally and does the job well. This may evolve as CI/multi-user needs grow.
+- **Models/provider**: Currently Vercel AI Gateway via `AI_GATEWAY_API_KEY`. Adding other providers is planned - you can use configure the models in the config file though.
+- **Bun**: Required. Will not change.
+
+## Commands
+
+### `docbot init`
+
+Scaffolds project config in the repo root:
+
+- `.docbot/`
+- `docbot.config.jsonc`
+
+```bash
+docbot init
+```
+
+Options:
+
+- `--force`: overwrite existing config
+- `--skip-docker`: skip docker setup (you'll need to set up Qdrant manually)
+
+### `docbot index`
+
+Indexes docs/code for search. If you don't pass flags, it uses your config.
+
+```bash
+docbot index
+# or
+docbot index --docs ./docs --codebase ./src
+```
+
+Options:
+
+- `--docs`: docs path (optional if configured)
+- `--codebase`: one or more codebase paths
+- `--config`: config file path (default: `docbot.config.jsonc`)
+- `--qdrant-url`: qdrant url (default: [http://127.0.0.1:6333](http://127.0.0.1:6333))
+- `--force`: force full re-index, ignoring manifest
+
+### `docbot run "<task>"`
+
+Runs the interactive workflow (plan → approval → execution → review).
+
+```bash
+docbot run "document the new api endpoints"
+```
+
+Options:
+
+- `--docs`: docs path (optional if configured)
+- `--codebase`: one or more codebase paths
+- `--config`: config file path (default: `docbot.config.jsonc`)
+- `--interactive`: plan approval (default: true)
+- `--port`: server port (default: 3070)
+- `--qdrant-url`: qdrant url (default: [http://127.0.0.1:6333](http://127.0.0.1:6333))
+- `--index-only`: only index, don't run
+- `--verbose` / `--no-verbose`: detailed logging + log panel
+- `--no-server`: reuse an already running server
+- `--force`: rebuild embeddings from scratch
+
+### `docbot search "<query>"`
+
+```bash
+docbot search "authentication" --type hybrid --limit 10
+```
+
+Options:
+
+- `--type`: `semantic`, `exact`, `hybrid` (default: `hybrid`)
+- `--limit`: max results (default: 5)
+
+### `docbot serve`
+
+Starts the HTTP server (Elysia) without the TUI.
+
+```bash
+docbot serve --port 3070
+```
+
+## Configuration
+
+`docbot init` creates `docbot.config.jsonc`. CLI flags override config.
+
+Example:
+
+```jsonc
+{
+  "projectSlug": "my-project",
+  "paths": {
+    "docs": "./docs",
+    "codebase": ["./apps/web", "./packages/shared"]
+  },
+  "qdrant": {
+    "url": "http://127.0.0.1:6333",
+    "manifestPath": ".docbot/manifest.json",
+    "collections": {
+      "docs": "docbot_my-project_docs",
+      "code": "docbot_my-project_code"
+    }
+  },
+  "server": { "port": 3070 },
+  "models": {
+    "planning": "openai/gpt-5.2",
+    "prose": "anthropic/claude-sonnet-4.5",
+    "fast": "anthropic/claude-haiku-4.5",
+    "embedding": "openai/text-embedding-3-small",
+    "reranker": "cohere/rerank-v3.5"
+  }
+}
+```
+
+CLI flags take precedence over the config file.
+
+## Logs & UI
+
+- **Run (default)**: TUI + server in one process (verbose by default; log panel available)
+- **Serve**: server only; logs to stdout
+- **Index-only**: `--index-only`
+- **No-server**: `--no-server`
+
+Log panel (TUI, verbose only):
+
+- Toggle: `Ctrl+L`
+- Tabs: `←/→`
+- Scroll: `Shift+↑/↓` or `Shift+PgUp/PgDn`
+- Clear: `C`
+
+## Contributing
+
+PRs welcome. Issues welcome.
+
+## Support
+
+- This is a very new project—if you hit issues, please open an issue here
+- You can also reach celia on X: [@pariscestchiant](https://x.com/pariscestchiant)
+- Our own docs live at [docs.helmkit.com](https://docs.helmkit.com)
+
+## License
+
+MIT
+
+## Todo
+
+Tasks and progress are tracked in [todo.md](todo.md). Next big focus is changebot's integration inside of docbot (it's a changelog generator between two commits; we use it at [helmkit.com/changelog](https://helmkit.com/changelog))

package/src/config/defaults.ts

@@ -0,0 +1,41 @@
+// default configuration values for docbot
+
+export const DEFAULT_QDRANT_URL = "http://127.0.0.1:6333"
+export const DEFAULT_SERVER_PORT = 3070
+
+export const DEFAULT_MODELS = {
+  context: "google/gemini-3-pro-preview",
+  embedding: "openai/text-embedding-3-small",
+  embeddingLarge: "openai/text-embedding-3-large",
+  fast: "openai/gpt-5.2",
+  nano: "google/gemini-3-flash",
+  planning: "openai/gpt-5.2",
+  planningHeavy: "anthropic/claude-opus-4.5",
+  prose: "anthropic/claude-sonnet-4.5",
+} as const
+
+export const DEFAULT_AGENTS = {
+  discoveryBudget: 6,
+} as const
+
+/**
+ * generate collection names from project slug
+ */
+export function makeCollectionNames(slug: string) {
+  return {
+    code: `docbot_${slug}_code`,
+    docs: `docbot_${slug}_docs`,
+  }
+}
+
+/**
+ * sanitize a string for use as a project slug
+ * lowercase, alphanumeric and hyphens only
+ */
+export function sanitizeSlug(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+}

package/src/config/index.ts

@@ -0,0 +1,57 @@
+// public exports for user configuration files
+// users can import from "docbot/config" in their docbot.config.ts
+
+import { gateway as aiGateway } from "ai"
+import type { DocbotUserConfig } from "./schema"
+
+export {
+  DEFAULT_AGENTS,
+  DEFAULT_MODELS,
+  DEFAULT_QDRANT_URL,
+  DEFAULT_SERVER_PORT,
+  makeCollectionNames,
+  sanitizeSlug,
+} from "./defaults"
+export {
+  findProjectRoot,
+  type LoadConfigOptions,
+  loadConfig,
+} from "./loader"
+export type { DocbotUserConfig, ResolvedConfig } from "./schema"
+export { docbotConfigSchema } from "./schema"
+
+/**
+ * helper for defining a typed config file
+ *
+ * @example
+ * ```ts
+ * // docbot.config.ts
+ * import { defineConfig } from "docbot/config"
+ *
+ * export default defineConfig({
+ *   projectSlug: "my-docs",
+ *   models: {
+ *     planning: "openai/gpt-4o",
+ *   },
+ * })
+ * ```
+ */
+export function defineConfig(config: DocbotUserConfig): DocbotUserConfig {
+  return config
+}
+
+/**
+ * re-export ai gateway for model configuration
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, gateway } from "docbot/config"
+ *
+ * export default defineConfig({
+ *   models: {
+ *     planning: gateway("openai/gpt-4o"),
+ *   },
+ * })
+ * ```
+ */
+export const gateway: typeof aiGateway = aiGateway

package/src/config/loader.ts

@@ -0,0 +1,284 @@
+import { existsSync } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { dirname, join, resolve } from "node:path"
+import {
+  DEFAULT_AGENTS,
+  DEFAULT_MODELS,
+  DEFAULT_QDRANT_URL,
+  DEFAULT_SERVER_PORT,
+  makeCollectionNames,
+  sanitizeSlug,
+} from "./defaults"
+import {
+  type DocbotUserConfig,
+  docbotConfigSchema,
+  type ResolvedConfig,
+} from "./schema"
+
+const CONFIG_FILENAMES = [
+  "docbot.config.ts",
+  "docbot.config.js",
+  "docbot.config.json",
+  "docbot.config.jsonc",
+]
+
+/**
+ * find the config file by searching up from the given directory
+ */
+function findConfigFile(startDir: string): string | null {
+  let current = resolve(startDir)
+  const root = dirname(current)
+
+  while (current !== root) {
+    for (const filename of CONFIG_FILENAMES) {
+      const candidate = join(current, filename)
+      if (existsSync(candidate)) {
+        return candidate
+      }
+    }
+    current = dirname(current)
+  }
+
+  return null
+}
+
+/**
+ * find package.json and extract project name
+ */
+async function findProjectName(startDir: string): Promise<string | null> {
+  let current = resolve(startDir)
+  const root = dirname(current)
+
+  while (current !== root) {
+    const pkgPath = join(current, "package.json")
+    if (existsSync(pkgPath)) {
+      try {
+        const content = await readFile(pkgPath, "utf-8")
+        const pkg = JSON.parse(content)
+        return pkg.name ?? null
+      } catch {
+        return null
+      }
+    }
+    current = dirname(current)
+  }
+
+  return null
+}
+
+/**
+ * find the project root (directory containing package.json)
+ */
+export function findProjectRoot(startDir: string): string | null {
+  let current = resolve(startDir)
+  const root = dirname(current)
+
+  while (current !== root) {
+    const pkgPath = join(current, "package.json")
+    if (existsSync(pkgPath)) {
+      return current
+    }
+    current = dirname(current)
+  }
+
+  return null
+}
+
+/**
+ * load and parse a config file
+ */
+async function loadConfigFile(path: string): Promise<DocbotUserConfig | null> {
+  try {
+    if (path.endsWith(".ts") || path.endsWith(".js")) {
+      // use bun's import for ts/js files
+      const mod = await import(path)
+      return mod.default ?? mod
+    }
+
+    if (path.endsWith(".jsonc")) {
+      // use bun's native jsonc loader which handles comments and trailing commas
+      const mod = await import(path, { with: { type: "jsonc" } })
+      return mod.default
+    }
+
+    // plain json
+    const content = await readFile(path, "utf-8")
+    return JSON.parse(content)
+  } catch (error) {
+    console.warn(`failed to load config from ${path}:`, error)
+    return null
+  }
+}
+
+export interface LoadConfigOptions {
+  // starting directory for config search
+  startDir: string
+  // explicit config file path (overrides search)
+  configPath?: string
+  // cli overrides
+  overrides?: Partial<{
+    qdrantUrl: string
+    port: number
+    docs: string
+    codebase: string | string[]
+  }>
+}
+
+function normalizeCodebase(value?: string | string[]): string[] | undefined {
+  if (!value) return undefined
+  if (Array.isArray(value)) return value.filter(Boolean)
+  return value
+    .split(",")
+    .map((v) => v.trim())
+    .filter(Boolean)
+}
+
+function readEnv() {
+  return {
+    codebase: process.env.DOCBOT_CODEBASE,
+    docs: process.env.DOCBOT_DOCS,
+    manifest: process.env.DOCBOT_MANIFEST_PATH,
+    port: process.env.DOCBOT_PORT,
+    qdrantUrl: process.env.QDRANT_URL,
+  }
+}
+
+async function loadUserConfigFromFile(
+  configPath: string | undefined,
+  startDir: string,
+): Promise<DocbotUserConfig> {
+  const configFile = configPath ?? findConfigFile(startDir)
+  if (!configFile) return {}
+
+  const loaded = await loadConfigFile(configFile)
+  if (!loaded) return {}
+
+  const parsed = docbotConfigSchema.safeParse(loaded)
+  if (parsed.success) {
+    return parsed.data
+  }
+
+  console.warn("invalid config file:", parsed.error.format())
+  return {}
+}
+
+async function resolveProjectInfo(startDir: string) {
+  const projectRoot = findProjectRoot(startDir)
+  const projectName = await findProjectName(startDir)
+  return {
+    defaultSlug: projectName ? sanitizeSlug(projectName) : "docbot",
+    projectRoot,
+  }
+}
+
+function resolvePaths(
+  baseDir: string,
+  userConfig: DocbotUserConfig,
+  env: ReturnType<typeof readEnv>,
+  overrides?: LoadConfigOptions["overrides"],
+) {
+  const cacheDir = join(baseDir, ".docbot")
+  const manifestPath =
+    env.manifest ??
+    userConfig.qdrant?.manifestPath ??
+    join(cacheDir, "manifest.json")
+  const docsPath =
+    overrides?.docs ?? env.docs ?? userConfig.paths?.docs ?? undefined
+  const codebasePaths = normalizeCodebase(
+    overrides?.codebase ?? env.codebase ?? userConfig.paths?.codebase,
+  )
+
+  return {
+    cacheDir,
+    codebase: codebasePaths?.map((p) => resolve(baseDir, p)),
+    docs: docsPath ? resolve(baseDir, docsPath) : undefined,
+    manifest: manifestPath,
+  }
+}
+
+function resolveAgentsConfig(userConfig: DocbotUserConfig) {
+  return {
+    discoveryBudget:
+      userConfig.agents?.discoveryBudget ?? DEFAULT_AGENTS.discoveryBudget,
+  }
+}
+
+function resolveModelConfig(userConfig: DocbotUserConfig) {
+  return {
+    context: userConfig.models?.context ?? DEFAULT_MODELS.context,
+    embedding: userConfig.models?.embedding ?? DEFAULT_MODELS.embedding,
+    embeddingLarge:
+      userConfig.models?.embeddingLarge ?? DEFAULT_MODELS.embeddingLarge,
+    fast: userConfig.models?.fast ?? DEFAULT_MODELS.fast,
+    nano: userConfig.models?.nano ?? DEFAULT_MODELS.nano,
+    planning: userConfig.models?.planning ?? DEFAULT_MODELS.planning,
+    planningHeavy:
+      userConfig.models?.planningHeavy ?? DEFAULT_MODELS.planningHeavy,
+    prose: userConfig.models?.prose ?? DEFAULT_MODELS.prose,
+  }
+}
+
+function resolveQdrantConfig(
+  userConfig: DocbotUserConfig,
+  slug: string,
+  env: ReturnType<typeof readEnv>,
+  overrides: LoadConfigOptions["overrides"],
+  manifestPath: string,
+) {
+  return {
+    collections: userConfig.qdrant?.collections ?? makeCollectionNames(slug),
+    manifestPath,
+    url:
+      overrides?.qdrantUrl ??
+      userConfig.qdrant?.url ??
+      env.qdrantUrl ??
+      DEFAULT_QDRANT_URL,
+  }
+}
+
+function resolveServerConfig(
+  userConfig: DocbotUserConfig,
+  env: ReturnType<typeof readEnv>,
+  overrides: LoadConfigOptions["overrides"],
+) {
+  return {
+    port:
+      overrides?.port ??
+      userConfig.server?.port ??
+      (env.port ? Number(env.port) : undefined) ??
+      DEFAULT_SERVER_PORT,
+  }
+}
+
+/**
+ * load and resolve the full configuration
+ *
+ * priority: cli args > config file > defaults
+ */
+export async function loadConfig(
+  options: LoadConfigOptions,
+): Promise<ResolvedConfig> {
+  const { startDir, configPath, overrides } = options
+
+  const env = readEnv()
+  const { defaultSlug, projectRoot } = await resolveProjectInfo(startDir)
+  const userConfig = await loadUserConfigFromFile(configPath, startDir)
+  const slug = userConfig.projectSlug ?? defaultSlug
+  const baseDir = projectRoot ?? startDir
+  const paths = resolvePaths(baseDir, userConfig, env, overrides)
+
+  return {
+    agents: resolveAgentsConfig(userConfig),
+    models: resolveModelConfig(userConfig),
+    paths,
+    projectSlug: slug,
+    qdrant: resolveQdrantConfig(
+      userConfig,
+      slug,
+      env,
+      overrides,
+      paths.manifest,
+    ),
+    server: resolveServerConfig(userConfig, env, overrides),
+  }
+}