core: add --version

Author: tspader

AGENTS.md

@@ -13,4 +13,8 @@
 - Never use `/tmp`; prefer `.llm/scratch`. Out-of-tree directory access forces manual approval, `.llm/scratch` lets you work autonomously
 - Never write utilities as Bash scripts; always use TypeScript + Bun
 - Never wrap `await foo()` in parentheses in an if statement
-- NEVER use the Glob tool without a path parameter
+- NEVER use the Glob tool without a path parameter; if none is needed, use "*"
+- Always make tests declarative rather than imperative. Tests describe filesystem state (repos, store entries, config), the `fixture()` function materializes it. No imperative setup.
+- Never use mocks. Tests call actual functions against temporary filesystems.
+- Always run tests in isolation. Each test gets its own HOME and cwd via fixture. Cleanup via `await using`.
+- Always build paths and read environment variables lazily e.g. `src/core/config.ts` reads `process.env.HOME` at call time, not import time. This is what makes per-test isolation work without preloads.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spader/dotllm",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "A simple CLI to clone, manage, and link repositories for LLM reference",
   "type": "module",
   "repository": {
@@ -14,6 +14,8 @@
     "dotllm": "src/cli/index.ts"
   },
   "scripts": {
+    "clean": "bun tools/clean.ts",
+    "build": "bun tools/build.ts",
     "check": "bunx tsc --noEmit",
     "prepublishOnly": "bun run check"
   },
@@ -27,6 +29,9 @@
     "./core": "./src/core/index.ts",
     "./core/*": "./src/core/*.ts"
   },
+  "imports": {
+    "#tools/*": "./tools/*.ts"
+  },
   "engines": {
     "bun": ">=1.1.0"
   },

src/cli/index.ts

@@ -4,23 +4,27 @@ import { build, type Cli } from "@spader/dotllm/cli/yargs";
 import { add, remove, list, link, sync, which, cd } from "@spader/dotllm/cli/commands/index";
 
 export namespace DotLlmCli {
-  export const def: Cli = {
-    name: "dotllm",
-    description: "Manage git repo references symlinked into .llm/reference/",
-    commands: {
-      add,
-      remove,
-      list,
-      link,
-      sync,
-      which,
-      cd,
-    },
-  };
+  export async function run(): Promise<void> {
+    const raw = await Bun.file(new URL("../../package.json", import.meta.url)).json() as { version?: unknown };
+    const version = typeof raw.version === "string" ? raw.version : undefined;
+
+    const def: Cli = {
+      name: "dotllm",
+      description: "Manage git repo references symlinked into .llm/reference/",
+      version,
+      commands: {
+        add,
+        remove,
+        list,
+        link,
+        sync,
+        which,
+        cd,
+      },
+    };
 
-  export function run(): void {
     build(def).parse();
   }
 }
 
-DotLlmCli.run();
+await DotLlmCli.run();

src/cli/yargs.ts

@@ -36,6 +36,7 @@ export type Command = {
 export type Cli = {
   name: string;
   description: string;
+  version?: string;
   options?: Options;
   commands: Record<string, Command>;
 };
@@ -109,6 +110,9 @@ export function help(
     ...(def.options ?? {}),
     help: { alias: "h", type: "boolean", description: "Show help" },
   };
+  if ("version" in def && def.version) {
+    opts.version = { alias: "v", type: "boolean", description: "Show version" };
+  }
 
   if (Object.keys(opts).length > 0) {
     if (prev) console.log("");
@@ -214,6 +218,10 @@ function configure(
     .option("help", { alias: "h", type: "boolean", describe: "Show help" })
     .check(check(def, root, path))
     .fail(fail(def, root, path));
+
+  if (path.length === 0 && "version" in def && def.version) {
+    y.version(def.version).alias("version", "v");
+  }
 }
 
 function command(

test/SPEC.md

@@ -0,0 +1,38 @@
+import fs from "fs"
+import path from "path"
+import { test, expect } from "bun:test"
+import { Build } from "#tools/build"
+import { fixture } from "../fixture"
+
+test("dotllm --version matches installed package.json", async () => {
+  await using env = await fixture()
+
+  fs.writeFileSync(
+    path.join(env.path, "package.json"),
+    JSON.stringify({ name: "dotllm-version-test", private: true }, null, 2),
+  )
+
+  const built = await Build.build({ pack: env.path })
+  const tar = built.tar
+  expect(path.isAbsolute(tar)).toBe(true)
+  const installed = Bun.spawnSync(["npm", "install", "--no-package-lock", tar], {
+    cwd: env.path,
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  expect(installed.exitCode).toBe(0)
+
+  const raw = await Bun.file(path.join(env.path, "node_modules", "@spader", "dotllm", "package.json")).json() as { version?: unknown }
+  const version = typeof raw.version === "string" ? raw.version : ""
+  expect(version.length > 0).toBe(true)
+
+  const bin = path.join(env.path, "node_modules", ".bin", "dotllm")
+  const proc = Bun.spawnSync([bin, "--version"], {
+    cwd: env.path,
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+
+  expect(proc.exitCode).toBe(0)
+  expect(proc.stdout.toString().trim()).toBe(version)
+})

test/cli/version.test.ts

@@ -1,56 +1,89 @@
 import path from "path";
 import fs from "fs";
 
-async function main() {
-  const root = path.resolve(import.meta.dir, "..");
-  const out = path.join(root, ".build");
-
-  fs.rmSync(out, { recursive: true, force: true });
-
-  // Compile all source files in one shot. `packages: "external"` keeps npm
-  // deps and self-referencing @spader/dotllm/* imports as bare specifiers.
-  const sources = Array.from(new Bun.Glob("src/**/*.ts").scanSync(root));
-  const result = await Bun.build({
-    entrypoints: sources.map(f => path.join(root, f)),
-    outdir: out,
-    root,
-    target: "bun",
-    packages: "external",
-  });
-
-  if (!result.success) {
-    for (const log of result.logs) console.error(log);
-    process.exit(1);
-  }
+export namespace Build {
+  type Opt = {
+    root?: string;
+    out?: string;
+    pack?: string;
+  };
 
-  // Ensure CLI entry point is executable
-  fs.chmodSync(path.join(out, "src/cli/index.js"), 0o755);
-
-  // Generate a publish-ready package.json with JS paths
-  const pkg = await Bun.file(path.join(root, "package.json")).json();
-  pkg.bin = { dotllm: "src/cli/index.js" };
-  pkg.exports = {
-    "./cli": "./src/cli/index.js",
-    "./cli/*": "./src/cli/*.js",
-    "./core": "./src/core/index.js",
-    "./core/*": "./src/core/*.js",
+  type Result = {
+    files: number;
+    out: string;
+    tar: string;
   };
-  pkg.files = ["src/**/*.js", "README.md"];
-  delete pkg.scripts;
-  delete pkg.devDependencies;
-  await Bun.write(path.join(out, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
-
-  fs.copyFileSync(path.join(root, "README.md"), path.join(out, "README.md"));
-
-  // Create npm tarball
-  const pack = Bun.spawnSync(["npm", "pack"], { cwd: out, stdout: "pipe", stderr: "pipe" });
-  if (pack.exitCode !== 0) {
-    console.error(pack.stderr.toString());
-    process.exit(1);
+
+  export async function build(opt: Opt = {}): Promise<Result> {
+    const root = opt.root ?? path.resolve(import.meta.dir, "..");
+    const out = opt.out ?? path.join(root, ".build");
+    const packDir = opt.pack ?? out;
+
+    fs.rmSync(out, { recursive: true, force: true });
+    fs.mkdirSync(packDir, { recursive: true });
+
+    const src = Array.from(new Bun.Glob("src/**/*.ts").scanSync(root));
+    const res = await Bun.build({
+      entrypoints: src.map(f => path.join(root, f)),
+      outdir: out,
+      root,
+      target: "bun",
+      packages: "external",
+    });
+
+    if (!res.success) {
+      for (const log of res.logs) console.error(log);
+      return Promise.reject(new Error("build failed"));
+    }
+
+    fs.chmodSync(path.join(out, "src/cli/index.js"), 0o755);
+
+    const raw = await Bun.file(path.join(root, "package.json")).json() as Record<string, unknown>;
+    raw.bin = { dotllm: "src/cli/index.js" };
+    raw.exports = {
+      "./cli": "./src/cli/index.js",
+      "./cli/*": "./src/cli/*.js",
+      "./core": "./src/core/index.js",
+      "./core/*": "./src/core/*.js",
+    };
+    raw.files = ["src/**/*.js", "README.md"];
+    delete raw.scripts;
+    delete raw.devDependencies;
+    delete raw.imports;
+    await Bun.write(path.join(out, "package.json"), JSON.stringify(raw, null, 2) + "\n");
+
+    fs.copyFileSync(path.join(root, "README.md"), path.join(out, "README.md"));
+
+    const pack = Bun.spawnSync(["npm", "pack", "--json", "--pack-destination", packDir], {
+      cwd: out,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (pack.exitCode !== 0) {
+      return Promise.reject(new Error(pack.stderr.toString() || "npm pack failed"));
+    }
+
+    const json = JSON.parse(pack.stdout.toString()) as { filename?: string }[];
+    const file = json[0]?.filename ?? "";
+    if (file.length === 0) {
+      return Promise.reject(new Error("npm pack did not return filename"));
+    }
+
+    return {
+      files: src.length,
+      out,
+      tar: path.join(packDir, file),
+    };
   }
 
-  console.log(`${sources.length} files compiled`);
-  console.log(`.build/${pack.stdout.toString().trim()}`);
+  export async function main(): Promise<void> {
+  }
 }
 
-main();
+if (import.meta.main) {
+  const res = await Build.build();
+  const root = path.resolve(import.meta.dir, "..");
+  const rel = path.relative(root, res.tar);
+  console.log(`${res.files} files compiled`);
+  console.log(rel);
+}

tools/build.ts

@@ -0,0 +1,22 @@
+import path from "path";
+import fs from "fs";
+
+export namespace CleanTool {
+  export function clean(root?: string): string {
+    const base = root ?? path.resolve(import.meta.dir, "..");
+    const out = path.join(base, ".build");
+    fs.rmSync(out, { recursive: true, force: true });
+    return out;
+  }
+
+  export async function main(): Promise<void> {
+    const out = clean();
+    const root = path.resolve(import.meta.dir, "..");
+    const rel = path.relative(root, out);
+    console.log(rel);
+  }
+}
+
+if (import.meta.main) {
+  await CleanTool.main();
+}

tools/clean.ts

@@ -15,7 +15,8 @@
       "@spader/dotllm/cli": ["src/cli/index.ts"],
       "@spader/dotllm/cli/*": ["src/cli/*"],
       "@spader/dotllm/core": ["src/core/index.ts"],
-      "@spader/dotllm/core/*": ["src/core/*"]
+      "@spader/dotllm/core/*": ["src/core/*"],
+      "#tools/*": ["tools/*"]
     }
   },
   "include": ["src/**/*.ts", "test/**/*.ts"]