feat(cli): add version, --version, -V

- CODEMAP_VERSION from package.json (inlined at build)
- Export CODEMAP_VERSION from package entry
- Tests for version subcommand and flags

Author: SutuSebastian

README.md

@@ -33,6 +33,9 @@ The package exposes a **`codemap`** binary, a **library** entry (`import` / `exp
 # Index project root (optional codemap.config.ts / codemap.config.json)
 codemap
 
+# Version (also: codemap --version, codemap -V)
+codemap version
+
 # Full rebuild
 codemap --full
 

docs/architecture.md

@@ -10,13 +10,13 @@ A local SQLite database (`.codemap.db`) indexes the project tree and stores stru
 
 ## Layering
 
-| Layer                                        | Role                                                                                                                                                              |
-| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`cli.ts`**                                 | Parses argv (`--root`, `--config`, `query`, `agents init`, `--files`, `--full`), wires bootstrap → `runCodemapIndex` / `printQueryResult`.                        |
-| **`api.ts`**                                 | Public programmatic surface: `createCodemap()`, `Codemap` (`query`, `index`), re-exports `runCodemapIndex` for advanced use.                                      |
-| **`application/`**                           | Use cases: `run-index.ts` (incremental / full / targeted orchestration), `index-engine.ts` (collect files, git diff, `indexFiles`, workers via `worker-pool.ts`). |
-| **`adapters/`**                              | `LanguageAdapter` registry; built-ins call `parser.ts` / `css-parser.ts` / `markers.ts` from `parse-worker-core`.                                                 |
-| **`runtime.ts` / `config.ts` / `db.ts` / …** | Config, SQLite, resolver, workers.                                                                                                                                |
+| Layer                                        | Role                                                                                                                                                                          |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`cli.ts`**                                 | Parses argv (`--root`, `--config`, `query`, `agents init`, `--files`, `--full`, `--help`, `version` / `--version`), wires bootstrap → `runCodemapIndex` / `printQueryResult`. |
+| **`api.ts`**                                 | Public programmatic surface: `createCodemap()`, `Codemap` (`query`, `index`), re-exports `runCodemapIndex` for advanced use.                                                  |
+| **`application/`**                           | Use cases: `run-index.ts` (incremental / full / targeted orchestration), `index-engine.ts` (collect files, git diff, `indexFiles`, workers via `worker-pool.ts`).             |
+| **`adapters/`**                              | `LanguageAdapter` registry; built-ins call `parser.ts` / `css-parser.ts` / `markers.ts` from `parse-worker-core`.                                                             |
+| **`runtime.ts` / `config.ts` / `db.ts` / …** | Config, SQLite, resolver, workers.                                                                                                                                            |
 
 `index.ts` is the package entry: re-exports the public API and runs `cli.ts` only when executed as the main module (Node/Bun `codemap` binary).
 
@@ -89,7 +89,7 @@ A local SQLite database (`.codemap.db`) indexes the project tree and stores stru
 | File              | Purpose                                                                                          |
 | ----------------- | ------------------------------------------------------------------------------------------------ |
 | `index.ts`        | Package entry — re-exports `api` / `config`, runs CLI when main                                  |
-| `cli.ts`          | CLI — argv parsing, `query`, `agents init`, `--files`, index modes                               |
+| `cli.ts`          | CLI — argv parsing, `query`, `agents init`, `--files`, `version`, index modes                    |
 | `api.ts`          | Programmatic API — `createCodemap`, `Codemap`, `runCodemapIndex`                                 |
 | `application/`    | Indexing use cases and engine (`run-index`, `index-engine`, types)                               |
 | `worker-pool.ts`  | Parallel parse workers (Bun / Node)                                                              |

src/cli.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { join } from "node:path";
 
 import { parseBootstrapArgs } from "./cli";
+import { CODEMAP_VERSION } from "./version";
 
 describe("parseBootstrapArgs", () => {
   test("passes --help through in rest after --root", () => {
@@ -11,20 +12,39 @@ describe("parseBootstrapArgs", () => {
   });
 });
 
+async function runCli(
+  args: string[],
+): Promise<{ exitCode: number; out: string; err: string }> {
+  const indexTs = join(import.meta.dir, "index.ts");
+  const proc = Bun.spawn([Bun.which("bun")!, indexTs, ...args], {
+    cwd: join(import.meta.dir, ".."),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  const out = await new Response(proc.stdout).text();
+  const err = await new Response(proc.stderr).text();
+  return { exitCode, out, err };
+}
+
 describe("CLI --help", () => {
   test("exits 0 and prints usage without touching the database", async () => {
-    const indexTs = join(import.meta.dir, "index.ts");
-    const proc = Bun.spawn([Bun.which("bun")!, indexTs, "--help"], {
-      cwd: join(import.meta.dir, ".."),
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const exitCode = await proc.exited;
-    const out = await new Response(proc.stdout).text();
-    const err = await new Response(proc.stderr).text();
+    const { exitCode, out, err } = await runCli(["--help"]);
     expect(exitCode).toBe(0);
     expect(out).toContain("Usage:");
     expect(out).toContain("codemap query");
     expect(err).toBe("");
   });
 });
+
+describe("CLI version", () => {
+  test.each(["version", "--version", "-V"])(
+    "%s prints version and exits 0",
+    async (flag) => {
+      const { exitCode, out, err } = await runCli([flag]);
+      expect(exitCode).toBe(0);
+      expect(out.trim()).toBe(CODEMAP_VERSION);
+      expect(err).toBe("");
+    },
+  );
+});

src/cli.ts

@@ -7,6 +7,7 @@ import { loadUserConfig, resolveCodemapConfig } from "./config";
 import { closeDb, openDb } from "./db";
 import { configureResolver } from "./resolver";
 import { getProjectRoot, getTsconfigPath, initCodemap } from "./runtime";
+import { CODEMAP_VERSION } from "./version";
 
 /** Printed for `codemap --help` / `-h` (must run before config or DB access). */
 export function printCliUsage(): void {
@@ -22,6 +23,10 @@ Query:
 Agents:
   codemap agents init [--force]
 
+Other:
+  codemap version
+  codemap --version, -V
+
 Environment: CODEMAP_ROOT (same as --root)
 
 Options:
@@ -30,6 +35,10 @@ Options:
 `);
 }
 
+export function printVersion(): void {
+  console.log(CODEMAP_VERSION);
+}
+
 export function parseBootstrapArgs(argv: string[]) {
   const envRoot = process.env.CODEMAP_ROOT ?? process.env.CODEMAP_TEST_BENCH;
   let root = envRoot ? resolve(envRoot) : undefined;
@@ -60,6 +69,11 @@ export async function main() {
     return;
   }
 
+  if (rest[0] === "--version" || rest[0] === "-V" || rest[0] === "version") {
+    printVersion();
+    return;
+  }
+
   if (rest[0] === "agents" && rest[1] === "init") {
     if (rest.includes("--help") || rest.includes("-h")) {
       console.log(`Usage: codemap agents init [--force]

src/index.ts

@@ -16,6 +16,7 @@ export {
   type ResolvedCodemapConfig,
 } from "./config";
 export type { ParsedFile } from "./parsed-types";
+export { CODEMAP_VERSION } from "./version";
 
 function isMainModule(): boolean {
   if (

src/version.ts

@@ -0,0 +1,4 @@
+import packageJson from "../package.json" with { type: "json" };
+
+/** Package version from `package.json` (inlined at build time). */
+export const CODEMAP_VERSION = packageJson.version;

tsconfig.json

@@ -3,6 +3,7 @@
     "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "resolveJsonModule": true,
     "lib": ["ESNext"],
     "types": ["bun", "node"],
     "strict": true,