Add refdocs init command, auto-init on add, and fix add test buffer slice

Adds `refdocs init` to create .refdocs.json with full defaults, and
auto-initializes config when `refdocs add` is called without one.
Fixes downloadTarball mock buffer slice in add tests.
Bumps version to 0.3.0.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Chris Arter

CLAUDE.md

@@ -57,6 +57,10 @@ refdocs/
 
 ## CLI Commands
 
+### `refdocs init`
+
+Create a `.refdocs.json` config file with full defaults. Errors if the file already exists. Also auto-runs when `refdocs add` is called without an existing config.
+
 ### `refdocs index`
 
 Walk all configured paths, chunk every `.md` file, build and persist the MiniSearch index.

docs/cli-reference.md

@@ -9,6 +9,36 @@ refdocs --version  Show version number
 
 ---
 
+## `refdocs init`
+
+Create a `.refdocs.json` config file with default settings.
+
+```bash
+refdocs init
+```
+
+Writes `.refdocs.json` in the current directory with the full default configuration (paths, index location, chunk sizes, boost fields).
+
+**Output:**
+
+```
+Created .refdocs.json with default configuration.
+```
+
+**Behavior:**
+
+- Creates `.refdocs.json` in the current working directory
+- Includes all default values: `paths`, `index`, `chunkMaxTokens`, `chunkMinTokens`, `boostFields`
+- If `.refdocs.json` already exists, exits with an error
+
+**Errors:**
+
+- Config already exists: `.refdocs.json already exists in /path/to/dir`
+
+**Note:** Running `refdocs add` will automatically initialize `.refdocs.json` if it doesn't exist.
+
+---
+
 ## `refdocs index`
 
 Build the search index from all markdown files in configured paths.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamik-dev/refdocs",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Local CLI tool that indexes markdown documentation and exposes fast fuzzy search with intelligent chunking",
   "main": "dist/src/index.js",

src/config.ts

@@ -107,6 +107,18 @@ export function validateConfig(raw: unknown): string[] {
   return errors;
 }
 
+export function configExists(configDir: string): boolean {
+  return existsSync(join(configDir, CONFIG_FILENAME));
+}
+
+export function initConfig(configDir: string): void {
+  const configPath = join(configDir, CONFIG_FILENAME);
+  if (existsSync(configPath)) {
+    throw new Error(`${CONFIG_FILENAME} already exists in ${configDir}`);
+  }
+  writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n", "utf-8");
+}
+
 export function saveConfig(config: Partial<RefdocsConfig>, configDir: string): void {
   const configPath = join(configDir, CONFIG_FILENAME);
   let existing: Record<string, unknown> = {};

src/index.ts

@@ -2,7 +2,7 @@
 
 import { Command } from "commander";
 import { join } from "node:path";
-import { loadConfig } from "./config.js";
+import { loadConfig, configExists, initConfig } from "./config.js";
 import { buildIndex, loadPersistedIndex } from "./indexer.js";
 import { search } from "./search.js";
 import { addFromUrl, addLocalPath, removePath, updateSources } from "./add.js";
@@ -13,7 +13,20 @@ const program = new Command();
 program
   .name("refdocs")
   .description("Local CLI tool for indexing and searching markdown documentation")
-  .version("0.1.0");
+  .version("0.3.0");
+
+program
+  .command("init")
+  .description("Create a .refdocs.json config file with defaults")
+  .action(() => {
+    try {
+      initConfig(process.cwd());
+      console.log("Created .refdocs.json with default configuration.");
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
 
 program
   .command("index")
@@ -128,6 +141,11 @@ program
   .option("--no-index", "skip auto re-indexing after download")
   .action(async (source: string, opts: { path?: string; branch?: string; index: boolean }) => {
     try {
+      const cwd = process.cwd();
+      if (!configExists(cwd)) {
+        initConfig(cwd);
+        console.log("Initialized .refdocs.json with default configuration.");
+      }
       const { config, configDir } = loadConfig();
       const isUrl = source.startsWith("http://") || source.startsWith("https://");
 

tests/add.test.ts

@@ -77,7 +77,8 @@ vi.mock("../src/github.js", async (importOriginal) => {
   return {
     ...actual,
     downloadTarball: vi.fn(async () => {
-      return readFileSync(FIXTURE_PATH).buffer;
+      const buf = readFileSync(FIXTURE_PATH);
+      return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
     }),
   };
 });

tests/config.test.ts

@@ -2,7 +2,8 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { loadConfig, validateConfig } from "../src/config.js";
+import { readFileSync, existsSync } from "node:fs";
+import { loadConfig, validateConfig, configExists, initConfig, CONFIG_FILENAME } from "../src/config.js";
 
 describe("validateConfig", () => {
   it("returns no errors for valid config", () => {
@@ -131,3 +132,54 @@ describe("loadConfig", () => {
     expect(() => loadConfig(tmpDir)).toThrow("Invalid .refdocs.json");
   });
 });
+
+describe("configExists", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "refdocs-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns false when no config file exists", () => {
+    expect(configExists(tmpDir)).toBe(false);
+  });
+
+  it("returns true when config file exists", () => {
+    writeFileSync(join(tmpDir, CONFIG_FILENAME), "{}");
+    expect(configExists(tmpDir)).toBe(true);
+  });
+});
+
+describe("initConfig", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "refdocs-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("creates .refdocs.json with full defaults", () => {
+    initConfig(tmpDir);
+    const configPath = join(tmpDir, CONFIG_FILENAME);
+    expect(existsSync(configPath)).toBe(true);
+
+    const written = JSON.parse(readFileSync(configPath, "utf-8"));
+    expect(written.paths).toEqual(["ref-docs"]);
+    expect(written.index).toBe(".refdocs-index.json");
+    expect(written.chunkMaxTokens).toBe(800);
+    expect(written.chunkMinTokens).toBe(100);
+    expect(written.boostFields).toEqual({ title: 2, headings: 1.5, body: 1 });
+  });
+
+  it("throws if config already exists", () => {
+    writeFileSync(join(tmpDir, CONFIG_FILENAME), "{}");
+    expect(() => initConfig(tmpDir)).toThrow(".refdocs.json already exists");
+  });
+});