@spader/dotllm 1.0.0

package/README.md

@@ -0,0 +1,25 @@
+# motivation
+LLMs work best with references. If you're like me, every project has loose repositories lying around half a dozen places because some LLM needed it.
+
+Instead, keep a cache of such repositories and use `dotllm` to link them to `.llm`. Check in `.llm/dotllm.json`, and a simple `dotllm sync` will restore all of your references.
+
+# installation
+```bash
+bun install -g @spader/dotllm
+```
+
+# usage
+Register a repository (by HTTPS, SSH, or path)
+```bash
+dotllm add https://github.com/tspader/dotllm.git
+```
+
+In any directory, use the interactive CLI to edit which repositories are linked to `.llm/reference`
+```bash
+dotllm link
+```
+
+Check in `.llm/dotllm.json`. Then, on a fresh clone, link the repositories to your local copy
+```bash
+dotllm sync
+```

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@spader/dotllm",
+  "version": "1.0.0",
+  "description": "A simple CLI to clone, manage, and link repositories for LLM reference",
+  "type": "module",
+  "bin": {
+    "dotllm": "src/cli/index.ts"
+  },
+  "scripts": {
+    "check": "bunx tsc --noEmit",
+    "prepublishOnly": "bun run check"
+  },
+  "files": [
+    "src/**/*.ts",
+    "README.md"
+  ],
+  "exports": {
+    "./cli": "./src/cli/index.ts",
+    "./cli/*": "./src/cli/*.ts",
+    "./core": "./src/core/index.ts",
+    "./core/*": "./src/core/*.ts"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cli",
+    "bun",
+    "dotfiles",
+    "symlink",
+    "llm"
+  ],
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "picocolors": "^1.1.1",
+    "yargs": "^17.7.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/yargs": "^17.0.33"
+  }
+}

package/src/cli/commands/add.ts

@@ -0,0 +1,177 @@
+import fs from "fs";
+import path from "path";
+import * as prompts from "@clack/prompts";
+import { z } from "zod";
+import { add } from "@spader/dotllm/core";
+import { defaultTheme as t } from "@spader/dotllm/cli/theme";
+import type { CommandDef } from "@spader/dotllm/cli/yargs";
+
+const RepoShape = z.object({
+  description: z.string().nullable().optional(),
+});
+
+function isUrl(value: string): boolean {
+  return value.startsWith("http://") ||
+    value.startsWith("https://") ||
+    value.startsWith("git@") ||
+    value.startsWith("ssh://");
+}
+
+function stem(value: string): string {
+  const clean = value.trim().replace(/\/+$/, "");
+  if (clean.length === 0) return "";
+
+  if (clean.startsWith("git@")) {
+    const raw = clean.split(":").slice(1).join(":");
+    const seg = raw.split("/").filter(Boolean).pop() ?? raw;
+    return seg.replace(/\.git$/, "");
+  }
+
+  if (isUrl(clean)) {
+    const seg = clean.split("/").filter(Boolean).pop() ?? clean;
+    const raw = seg.split("?")[0] ?? seg;
+    const full = raw.split("#")[0] ?? raw;
+    return full.replace(/\.git$/, "");
+  }
+
+  const base = path.basename(clean);
+  const parsed = path.parse(base);
+  if (parsed.name.length > 0) return parsed.name;
+  return base;
+}
+
+function github(uri: string): { owner: string; repo: string } | null {
+  const https = uri.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  if (https) {
+    return { owner: https[1]!, repo: https[2]! };
+  }
+
+  const ssh = uri.match(/^ssh:\/\/git@github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  if (ssh) {
+    return { owner: ssh[1]!, repo: ssh[2]! };
+  }
+
+  const scp = uri.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/);
+  if (scp) {
+    return { owner: scp[1]!, repo: scp[2]! };
+  }
+
+  return null;
+}
+
+function gitName(uri: string): string {
+  const dir = path.resolve(uri);
+  if (!fs.existsSync(dir)) return "";
+  if (!fs.statSync(dir).isDirectory()) return "";
+
+  const proc = Bun.spawnSync(["git", "remote", "get-url", "origin"], {
+    cwd: dir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (proc.exitCode !== 0) return "";
+
+  const out = proc.stdout.toString().trim();
+  if (out.length === 0) return "";
+  return stem(out);
+}
+
+async function remoteDescription(uri: string): Promise<string> {
+  const repo = github(uri);
+  if (!repo) return "";
+
+  const url = `https://api.github.com/repos/${repo.owner}/${repo.repo}`;
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/vnd.github+json",
+      "user-agent": "dotllm",
+    },
+  });
+  if (!response.ok) return "";
+
+  const raw = await response.json();
+  const result = RepoShape.safeParse(raw);
+  if (!result.success) return "";
+  return result.data.description ?? "";
+}
+
+async function prefill(uri: string): Promise<{ name: string; description: string }> {
+  const remote = isUrl(uri);
+  const git = remote ? "" : gitName(uri);
+  const name = git.length > 0 ? git : stem(uri);
+  const description = remote ? await remoteDescription(uri) : "";
+  return { name, description };
+}
+
+async function interactive(): Promise<void> {
+  const uri = await prompts.text({
+    message: "URL or local path to a git repo",
+  });
+  if (prompts.isCancel(uri)) return;
+
+  const input = uri.trim();
+  const seed = await prefill(input);
+
+  const name = await prompts.text({
+    message: "Name (leave empty to auto-detect)",
+    defaultValue: seed.name,
+  });
+  if (prompts.isCancel(name)) return;
+
+  const description = await prompts.text({
+    message: "Description",
+    defaultValue: seed.description,
+  });
+  if (prompts.isCancel(description)) return;
+
+  await run(input, name || undefined, description || undefined);
+}
+
+async function run(uri: string, name?: string, description?: string): Promise<void> {
+  const spinner = prompts.spinner();
+  spinner.start(`Adding ${uri}`);
+
+  const result = await add(uri, name, description);
+  if (!result.ok) {
+    spinner.stop(t.error(result.error), 1);
+    process.exit(1);
+    return;
+  }
+
+  spinner.stop(`${t.success("added")} ${t.primary(result.entry.name)} ${t.link(result.storePath)}`);
+}
+
+export const command: CommandDef = {
+  description: "Register a git repo as a reference",
+  summary: "Add a repo to the registry",
+  positionals: {
+    uri: {
+      type: "string",
+      description: "URL or local path to a git repo",
+    },
+  },
+  options: {
+    name: {
+      alias: "n",
+      type: "string",
+      description: "Name override (defaults to repo name from git)",
+    },
+    description: {
+      alias: "d",
+      type: "string",
+      description: "Description of the reference",
+    },
+  },
+  handler: async (argv) => {
+    const uri = typeof argv.uri === "string" && argv.uri.length > 0 ? argv.uri : undefined;
+
+    if (!uri) {
+      await interactive();
+      return;
+    }
+
+    const name = typeof argv.name === "string" && argv.name.length > 0 ? argv.name : undefined;
+    const description = typeof argv.description === "string" ? argv.description : undefined;
+    await run(uri, name, description);
+  },
+};

package/src/cli/commands/index.ts

@@ -0,0 +1,5 @@
+export { command as add } from "@spader/dotllm/cli/commands/add";
+export { command as remove } from "@spader/dotllm/cli/commands/remove";
+export { command as list } from "@spader/dotllm/cli/commands/list";
+export { command as link } from "@spader/dotllm/cli/commands/link";
+export { command as sync } from "@spader/dotllm/cli/commands/sync";

package/src/cli/commands/link.ts

@@ -0,0 +1,54 @@
+import * as prompts from "@clack/prompts";
+import { Config, link, type SyncResult } from "@spader/dotllm/core";
+import { defaultTheme as t } from "@spader/dotllm/cli/theme";
+import type { CommandDef } from "@spader/dotllm/cli/yargs";
+
+function printResult(result: SyncResult): void {
+  for (const name of result.removed) {
+    prompts.log.step(`unlinked ${t.primary(name)} -> ${t.link(`.llm/reference/${name}`)}`);
+  }
+  for (const name of result.linked) {
+    prompts.log.step(`linked ${t.primary(name)} -> ${t.link(`.llm/reference/${name}`)}`);
+  }
+}
+
+export const command: CommandDef = {
+  description: "Interactively select repos to symlink into .llm/reference/",
+  summary: "Select and link references",
+  handler: async () => {
+    const global = Config.Global.read();
+
+    if (global.repos.length === 0) {
+      console.log(t.dim("(no repos registered)"));
+      console.log(t.dim("use `dotllm add <path>` to register one"));
+      return;
+    }
+
+    const local = Config.Local.read();
+    const current = new Set(Object.keys(local.refs));
+
+    const selected = await prompts.multiselect({
+      message: "Select repos to link into .llm/reference/",
+      options: global.repos.map((r) => ({
+        value: r.name,
+        label: r.name,
+        hint: r.uri,
+      })),
+      initialValues: global.repos
+        .filter((r) => current.has(r.name))
+        .map((r) => r.name),
+      required: false,
+    });
+
+    if (prompts.isCancel(selected)) {
+      prompts.cancel("cancelled");
+      return;
+    }
+
+    const names = Array.isArray(selected)
+      ? selected.filter((value): value is string => typeof value === "string")
+      : [];
+
+    printResult(link(names));
+  },
+};

package/src/cli/commands/list.ts

@@ -0,0 +1,44 @@
+import { Config } from "@spader/dotllm/core";
+import { table } from "@spader/dotllm/cli/layout";
+import { defaultTheme as t } from "@spader/dotllm/cli/theme";
+import type { CommandDef } from "@spader/dotllm/cli/yargs";
+
+export const command: CommandDef = {
+  description: "List all registered repos",
+  summary: "Show the registry",
+  handler: () => {
+    const global = Config.Global.read();
+
+    if (global.repos.length === 0) {
+      console.log(t.dim("(no repos registered)"));
+      console.log(t.dim("use `dotllm add <path>` to register one"));
+      return;
+    }
+
+    const local = Config.Local.read();
+    const linked = new Set(Object.keys(local.refs));
+
+    table(
+      ["name", "kind", "uri", "description", "linked"],
+      [
+        global.repos.map((r) => r.name),
+        global.repos.map((r) => r.kind),
+        global.repos.map((r) => r.uri),
+        global.repos.map((r) => r.description),
+        global.repos.map((r) => linked.has(r.name) ? "yes" : "no"),
+      ],
+      {
+        flex: [0, 0, 1, 1, 0],
+        noTruncate: [true, true, false, false, true],
+        truncate: ["end", "end", "start", "end", "end"],
+        format: [
+          (s) => t.primary(s),
+          (s) => s,
+          (s) => t.link(s),
+          (s) => s,
+          (s) => s.trim() === "yes" ? t.success(s) : s,
+        ],
+      },
+    );
+  },
+};

package/src/cli/commands/remove.ts

@@ -0,0 +1,28 @@
+import { log } from "@clack/prompts";
+import { remove } from "@spader/dotllm/core";
+import { defaultTheme as t } from "@spader/dotllm/cli/theme";
+import type { CommandDef } from "@spader/dotllm/cli/yargs";
+
+export const command: CommandDef = {
+  description: "Remove a repo from the registry",
+  summary: "Remove a registered repo",
+  positionals: {
+    name: {
+      type: "string",
+      description: "Name of the reference to remove",
+      required: true,
+    },
+  },
+  handler: (argv) => {
+    const name = String(argv.name);
+
+    const result = remove(name);
+    if (!result.ok) {
+      log.error(t.error(result.error));
+      process.exit(1);
+      return;
+    }
+
+    log.step(`removed ${t.primary(name)}`);
+  },
+};

package/src/cli/commands/sync.ts

@@ -0,0 +1,45 @@
+import * as prompts from "@clack/prompts";
+import { pull, sync } from "@spader/dotllm/core";
+import { defaultTheme as t } from "@spader/dotllm/cli/theme";
+import type { CommandDef } from "@spader/dotllm/cli/yargs";
+
+export const command: CommandDef = {
+  description: "Re-create symlinks from .llm/dotllm.json",
+  summary: "Sync symlinks from local config",
+  handler: async () => {
+    const result = sync();
+
+    if (result.linked.length === 0 && result.removed.length === 0 && result.missing.length === 0 && result.unchanged.length === 0) {
+      console.log(t.dim("(no refs in local config)"));
+      console.log(t.dim("use `dotllm link` to select repos"));
+      return;
+    }
+
+    for (const name of result.removed) {
+      prompts.log.step(`removed stale ${t.primary(name)}`);
+    }
+    for (const name of result.missing) {
+      prompts.log.warn(`${t.primary(name)} missing cache entry`);
+    }
+    for (const name of result.linked) {
+      prompts.log.step(`linked ${t.primary(name)} -> ${t.link(`.llm/reference/${name}`)}`);
+    }
+
+    const refs = [...new Set([...result.unchanged, ...result.linked])];
+    if (refs.length === 0) {
+      return;
+    }
+
+    const spinner = prompts.spinner();
+    spinner.start(`Pulling ${refs.length} linked repo${refs.length === 1 ? "" : "s"}`);
+
+    const pulled = await pull(refs);
+    if (pulled.failed.length > 0) {
+      spinner.stop(t.error(`pull failed for ${pulled.failed.length} repo${pulled.failed.length === 1 ? "" : "s"}`), 1);
+      process.exit(1);
+      return;
+    }
+
+    spinner.stop(`${t.success("pulled")} ${pulled.count} repo${pulled.count === 1 ? "" : "s"}`);
+  },
+};

package/src/cli/index.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env bun
+
+import { build, type CliDef } from "@spader/dotllm/cli/yargs";
+import { add, remove, list, link, sync } from "@spader/dotllm/cli/commands/index";
+
+export namespace DotLlmCli {
+  export const def: CliDef = {
+    name: "dotllm",
+    description: "Manage git repo references symlinked into .llm/reference/",
+    commands: {
+      add,
+      remove,
+      list,
+      link,
+      sync,
+    },
+  };
+
+  export function run(): void {
+    build(def).parse();
+  }
+}
+
+DotLlmCli.run();

package/src/cli/layout.ts

@@ -0,0 +1,200 @@
+import { defaultTheme as theme } from "@spader/dotllm/cli/theme";
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+type TruncateMode = "start" | "middle" | "end";
+
+export type TableOptions = {
+  maxWidth?: number;
+  flex?: number[];
+  noTruncate?: boolean[];
+  truncate?: TruncateMode[];
+  format?: Array<(value: string, row: number, col: number) => string>;
+  maxRows?: number;
+};
+
+function clean(value: string): string {
+  return value.replace(/[\t\n]/g, " ").replace(ANSI_RE, "");
+}
+
+function truncateMiddle(value: string, width: number): string {
+  if (width <= 0) return "";
+  if (value.length <= width) return value;
+  if (width <= 3) return value.slice(0, width);
+
+  const tail = Math.floor((width - 3) / 2);
+  const head = width - 3 - tail;
+  return `${value.slice(0, head)}...${value.slice(value.length - tail)}`;
+}
+
+function truncateStart(value: string, width: number): string {
+  if (width <= 0) return "";
+  if (value.length <= width) return value;
+  if (width <= 3) return "...".slice(0, width);
+
+  return `...${value.slice(value.length - (width - 3))}`;
+}
+
+function truncateEnd(value: string, width: number): string {
+  if (width <= 0) return "";
+  if (value.length <= width) return value;
+  if (width <= 3) return "...".slice(0, width);
+
+  return `${value.slice(0, width - 3)}...`;
+}
+
+function truncate(value: string, width: number, mode: TruncateMode): string {
+  if (mode === "start") return truncateStart(value, width);
+  if (mode === "end") return truncateEnd(value, width);
+  return truncateMiddle(value, width);
+}
+
+function fitWidths(
+  natural: number[],
+  available: number,
+  flex: number[],
+  noTruncate: boolean[],
+): number[] {
+  const widths = [...natural];
+  const totalNatural = natural.reduce((sum, width) => sum + width, 0);
+
+  if (totalNatural <= available) {
+    return widths;
+  }
+
+  let fixedWidth = 0;
+  const dynamic: Array<{ index: number; weight: number }> = [];
+
+  for (let index = 0; index < widths.length; index++) {
+    if (noTruncate[index] || flex[index] === 0) {
+      fixedWidth += widths[index] ?? 0;
+      continue;
+    }
+
+    dynamic.push({ index, weight: flex[index] ?? 1 });
+  }
+
+  const remaining = Math.max(0, available - fixedWidth);
+
+  if (dynamic.length === 0) {
+    return widths;
+  }
+
+  const totalWeight = dynamic.reduce((sum, item) => sum + item.weight, 0);
+  let used = 0;
+
+  for (const item of dynamic) {
+    const share = Math.floor((remaining * item.weight) / totalWeight);
+    const width = Math.max(1, share);
+    widths[item.index] = width;
+    used += width;
+  }
+
+  let extra = remaining - used;
+  let cursor = 0;
+  while (extra > 0) {
+    const item = dynamic[cursor % dynamic.length]!;
+    widths[item.index] = (widths[item.index] ?? 0) + 1;
+    extra--;
+    cursor++;
+  }
+
+  return widths;
+}
+
+export function table(
+  headers: string[],
+  columns: string[][],
+  options: TableOptions = {},
+): void {
+  if (headers.length === 0) return;
+
+  const count = headers.length;
+  const gap = 2;
+  const rows = columns.reduce((max, column) => Math.max(max, column.length), 0);
+  const visibleRows = Math.min(rows, options.maxRows ?? rows);
+
+  const natural: number[] = [];
+
+  for (let col = 0; col < count; col++) {
+    const headerWidth = clean(headers[col] ?? "").length;
+    let width = headerWidth;
+
+    for (let row = 0; row < visibleRows; row++) {
+      const value = clean(columns[col]?.[row] ?? "");
+      width = Math.max(width, value.length);
+    }
+
+    natural[col] = width;
+  }
+
+  const maxWidth =
+    options.maxWidth ??
+    (process.stdout.columns == null ? 120 : process.stdout.columns);
+  const available = Math.max(0, maxWidth - gap * (count - 1) - 1);
+  const widths = fitWidths(
+    natural,
+    available,
+    options.flex ?? [],
+    options.noTruncate ?? [],
+  );
+
+  const header = headers
+    .map((title, col) =>
+      truncateMiddle(clean(title), widths[col] ?? 0).padEnd(widths[col] ?? 0),
+    )
+    .join("  ");
+
+  process.stdout.write(`${theme.dim(header)}\n`);
+
+  for (let row = 0; row < visibleRows; row++) {
+    const cells: string[] = [];
+
+    for (let col = 0; col < count; col++) {
+      const width = widths[col] ?? 0;
+      const source = clean(columns[col]?.[row] ?? "");
+      const mode = options.truncate?.[col] ?? "middle";
+      const value = options.noTruncate?.[col]
+        ? source
+        : truncate(source, width, mode);
+      const padded = width > 0 ? value.padEnd(width) : value;
+      const formatted = options.format?.[col]?.(padded, row, col) ?? padded;
+
+      cells.push(formatted);
+    }
+
+    process.stdout.write(`${cells.join("  ")}\n`);
+  }
+
+  if (rows > visibleRows) {
+    process.stdout.write(`${theme.dim("(...truncated)")}\n`);
+  }
+}
+
+export function cols(
+  rows: string[][],
+  colorFns?: Array<(value: string) => string>,
+): void {
+  if (rows.length === 0) return;
+
+  const widths = rows[0]!.map((_, col) => {
+    let width = 0;
+
+    for (const row of rows) {
+      width = Math.max(width, clean(row[col] ?? "").length);
+    }
+
+    return width;
+  });
+
+  for (const row of rows) {
+    const line = row
+      .map((value, col) => {
+        const padded = clean(value).padEnd(widths[col] ?? 0);
+        return colorFns?.[col]?.(padded) ?? padded;
+      })
+      .join(" ");
+
+    process.stdout.write(`${line}\n`);
+  }
+}

package/src/cli/theme.ts

@@ -0,0 +1,35 @@
+type Formatter = (value: string) => string;
+
+export type Theme = {
+  primary: Formatter;
+  link: Formatter;
+  header: Formatter;
+  command: Formatter;
+  arg: Formatter;
+  option: Formatter;
+  type: Formatter;
+  description: Formatter;
+  dim: Formatter;
+  error: Formatter;
+  success: Formatter;
+};
+
+function rgb(r: number, g: number, b: number): Formatter {
+  return (value: string) => `\x1b[38;2;${r};${g};${b}m${value}\x1b[39m`;
+}
+
+const gray = (value: number) => rgb(value, value, value);
+
+export const defaultTheme: Theme = {
+  primary: rgb(114, 161, 136),
+  link: rgb(114, 140, 212),
+  header: gray(128),
+  command: rgb(114, 161, 136),
+  arg: rgb(161, 212, 212),
+  option: rgb(212, 212, 161),
+  type: gray(128),
+  description: (value) => value,
+  dim: gray(128),
+  error: rgb(212, 114, 114),
+  success: rgb(114, 212, 136),
+};