@spader/dotllm 1.0.0

package/src/cli/yargs.ts

@@ -0,0 +1,245 @@
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import pc from "picocolors";
+import { cols } from "@spader/dotllm/cli/layout";
+import { type Theme, defaultTheme } from "@spader/dotllm/cli/theme";
+
+export type OptionDef = {
+  alias?: string;
+  type: "string" | "number" | "boolean" | "array";
+  description: string;
+  required?: boolean;
+  default?: unknown;
+};
+
+export type Options = Record<string, OptionDef>;
+
+export type PositionalDef = {
+  type: "string" | "number";
+  description: string;
+  required?: boolean;
+  default?: unknown;
+};
+
+export type Positionals = Record<string, PositionalDef>;
+
+export type CommandDef = {
+  description: string;
+  summary?: string;
+  hidden?: boolean;
+  positionals?: Positionals;
+  options?: Options;
+  commands?: Record<string, CommandDef>;
+  handler?: (argv: Record<string, unknown>) => void | Promise<void>;
+};
+
+export type CliDef = {
+  name: string;
+  description: string;
+  options?: Options;
+  commands: Record<string, CommandDef>;
+};
+
+function usage(def: CommandDef | CliDef, path: string[], t: Theme): string {
+  const parts: string[] = [];
+  const last = path.length - 1;
+  for (let i = 0; i < path.length; i++) {
+    const fmt = t.command;
+    parts.push(i === last ? fmt(path[i]!) : path[i]!);
+  }
+
+  if ("positionals" in def && def.positionals) {
+    for (const [k, v] of Object.entries(def.positionals)) {
+      const name = t.arg(`$${k}`);
+      parts.push(v.required ? name : `[${name}]`);
+    }
+  }
+
+  if (def.options && Object.keys(def.options).length > 0) {
+    parts.push(t.dim("[options]"));
+  }
+
+  if (
+    "commands" in def &&
+    def.commands &&
+    Object.keys(def.commands).length > 0
+  ) {
+    parts.push(t.arg("$command"));
+  }
+
+  return parts.join(" ");
+}
+
+export function help(
+  def: CommandDef | CliDef,
+  name: string,
+  path: string[] = [],
+  t: Theme = defaultTheme,
+): void {
+  let prev = false;
+
+  if (def.description) {
+    console.log(t.description(def.description));
+    prev = true;
+  }
+
+  if (prev) console.log("");
+  console.log(t.header("usage:"));
+  console.log(`  ${usage(def, [name, ...path], t)}`);
+  prev = true;
+
+  const pos = "positionals" in def ? def.positionals : undefined;
+  if (pos && Object.keys(pos).length > 0) {
+    if (prev) console.log("");
+    console.log(t.header("arguments"));
+    prev = true;
+
+    const rows: string[][] = [];
+    for (const [k, v] of Object.entries(pos)) {
+      let desc = v.description;
+      if (v.default !== undefined)
+        desc += ` ${t.dim(`(default: ${v.default})`)}`;
+      if (v.required) desc += ` ${t.dim("(required)")}`;
+      rows.push([`  ${k}`, v.type, desc]);
+    }
+    cols(rows, [t.arg, t.type, t.description]);
+  }
+
+  const opts: Record<string, OptionDef> = {
+    ...(def.options ?? {}),
+    help: { alias: "h", type: "boolean", description: "Show help" },
+  };
+
+  if (Object.keys(opts).length > 0) {
+    if (prev) console.log("");
+    console.log(t.header("options"));
+    prev = true;
+
+    const rows: string[][] = [];
+    for (const [k, v] of Object.entries(opts)) {
+      const short = v.alias ? `-${v.alias}, ` : "    ";
+      let desc = v.description;
+      if (v.default !== undefined && v.type !== "boolean") {
+        desc += ` ${t.dim(`(default: ${v.default})`)}`;
+      }
+      rows.push([`  ${short}--${k}`, v.type, desc]);
+    }
+    cols(rows, [t.option, t.type, t.description]);
+  }
+
+  const cmds = "commands" in def ? def.commands : undefined;
+  if (cmds && Object.keys(cmds).length > 0) {
+    if (prev) console.log("");
+    console.log(t.header("commands"));
+
+    const rows: string[][] = [];
+    const rowCmdFmt: ((s: string) => string)[] = [];
+    for (const [k, v] of Object.entries(cmds)) {
+      if (v.hidden) continue;
+      const args = v.positionals ? Object.keys(v.positionals).join(" ") : "";
+      rows.push([`  ${k}`, args, v.summary ?? v.description]);
+      rowCmdFmt.push(t.command);
+    }
+    let ri = 0;
+    cols(rows, [(s) => rowCmdFmt[ri++]!(s), t.arg, t.description]);
+  }
+}
+
+function fail(def: CommandDef | CliDef, name: string, path: string[] = []) {
+  return (msg: string | null): void => {
+    if (process.argv.includes("--help") || process.argv.includes("-h")) {
+      help(def, name, path);
+      process.exit(0);
+    }
+    if (
+      msg?.includes("You must specify") ||
+      msg?.includes("Not enough non-option arguments")
+    ) {
+      help(def, name, path);
+      process.exit(1);
+    }
+    console.error(pc.red(msg ?? "Unknown error"));
+    process.exit(1);
+  };
+}
+
+function check(def: CommandDef | CliDef, name: string, path: string[] = []) {
+  return (argv: Record<string, unknown>): boolean => {
+    const args = argv as Record<string, unknown> & { _: unknown[]; help?: boolean };
+    if (args.help && args._.length === path.length) {
+      help(def, name, path);
+      process.exit(0);
+    }
+    return true;
+  };
+}
+
+function configure(
+  y: ReturnType<typeof yargs>,
+  def: CommandDef | CliDef,
+  root: string,
+  path: string[],
+): void {
+  if ("positionals" in def && def.positionals) {
+    for (const [k, v] of Object.entries(def.positionals)) {
+      y.positional(k, {
+        type: v.type,
+        describe: v.description,
+        demandOption: v.required,
+        default: v.default,
+      });
+    }
+  }
+
+  if (def.options) {
+    for (const [k, v] of Object.entries(def.options)) {
+      y.option(k, {
+        alias: v.alias,
+        type: v.type,
+        describe: v.description,
+        demandOption: v.required,
+        default: v.default,
+      });
+    }
+  }
+
+  if ("commands" in def && def.commands) {
+    for (const [k, v] of Object.entries(def.commands)) {
+      command(y, k, v, root, path);
+    }
+    y.demandCommand(1, "You must specify a command");
+  }
+
+  y.help(false)
+    .option("help", { alias: "h", type: "boolean", describe: "Show help" })
+    .check(check(def, root, path))
+    .fail(fail(def, root, path));
+}
+
+function command(
+  y: ReturnType<typeof yargs>,
+  name: string,
+  def: CommandDef,
+  root: string,
+  path: string[],
+): void {
+  let cmd = name;
+  if (def.positionals) {
+    for (const [k, v] of Object.entries(def.positionals)) {
+      cmd += v.required ? ` <${k}>` : ` [${k}]`;
+    }
+  }
+  y.command(
+    cmd,
+    def.description,
+    (inner: ReturnType<typeof yargs>) => configure(inner, def, root, [...path, name]),
+    def.handler as (argv: Record<string, unknown>) => void,
+  );
+}
+
+export function build(def: CliDef): ReturnType<typeof yargs> {
+  const y = yargs(hideBin(process.argv)).scriptName(def.name);
+  configure(y, def, def.name, []);
+  y.strict();
+  return y;
+}

package/src/core/add.ts

@@ -0,0 +1,100 @@
+import fs from "fs";
+import path from "path";
+import { Config, type RepoEntry } from "@spader/dotllm/core/config";
+
+function isUrl(value: string): boolean {
+  return value.startsWith("http://") ||
+    value.startsWith("https://") ||
+    value.startsWith("git@") ||
+    value.startsWith("ssh://");
+}
+
+function nameFromGitRemote(dir: string): string | null {
+  const result = Bun.spawnSync(["git", "remote", "get-url", "origin"], {
+    cwd: dir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.exitCode !== 0) return null;
+  const url = result.stdout.toString().trim();
+  return nameFromUrl(url);
+}
+
+function nameFromUrl(url: string): string {
+  const base = url.split("/").pop() ?? url;
+  return base.replace(/\.git$/, "");
+}
+
+export type AddResult = {
+  ok: true;
+  entry: RepoEntry;
+  storePath: string;
+} | {
+  ok: false;
+  error: string;
+};
+
+export async function add(uri: string, name?: string, description?: string): Promise<AddResult> {
+  const desc = description ?? "";
+
+  if (isUrl(uri)) {
+    return cloneUrl(uri, name, desc);
+  }
+
+  return linkLocal(uri, name, desc);
+}
+
+async function cloneUrl(url: string, name: string | undefined, description: string): Promise<AddResult> {
+  const resolved = name ?? nameFromUrl(url);
+  const store = Config.storeDir();
+  fs.mkdirSync(store, { recursive: true });
+
+  const target = path.join(store, resolved);
+
+  if (!fs.existsSync(target)) {
+    const proc = Bun.spawn(["git", "clone", url, target], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const code = await proc.exited;
+
+    if (code !== 0) {
+      const msg = await new Response(proc.stderr).text();
+      return { ok: false, error: `git clone failed: ${msg.trim()}` };
+    }
+  }
+
+  const entry: RepoEntry = { kind: "url", name: resolved, uri: url, description };
+  const global = Config.Global.read();
+  Config.Global.write(Config.Global.add(global, entry));
+
+  return { ok: true, entry, storePath: target };
+}
+
+function linkLocal(raw: string, name: string | undefined, description: string): AddResult {
+  const resolved = path.resolve(raw);
+
+  if (!fs.existsSync(resolved)) {
+    return { ok: false, error: `Path does not exist: ${resolved}` };
+  }
+
+  if (!fs.statSync(resolved).isDirectory()) {
+    return { ok: false, error: `Not a directory: ${resolved}` };
+  }
+
+  const store = Config.storeDir();
+  fs.mkdirSync(store, { recursive: true });
+
+  const finalName = name ?? nameFromGitRemote(resolved) ?? path.basename(resolved);
+  const target = path.join(store, finalName);
+
+  if (!fs.existsSync(target)) {
+    fs.symlinkSync(resolved, target, "dir");
+  }
+
+  const entry: RepoEntry = { kind: "file", name: finalName, uri: resolved, description };
+  const global = Config.Global.read();
+  Config.Global.write(Config.Global.add(global, entry));
+
+  return { ok: true, entry, storePath: target };
+}

package/src/core/config.ts

@@ -0,0 +1,126 @@
+import fs from "fs";
+import path from "path";
+import { z } from "zod";
+
+const GLOBAL_DIR = path.join(
+  process.env.HOME ?? "",
+  ".local",
+  "share",
+  "dotllm",
+);
+const STORE_DIR = path.join(GLOBAL_DIR, "store");
+const GLOBAL_FILE = path.join(GLOBAL_DIR, "dotllm.json");
+const LOCAL_DIR = ".llm";
+const LOCAL_FILE = path.join(LOCAL_DIR, "dotllm.json");
+const REF_DIR = path.join(LOCAL_DIR, "reference");
+
+const RepoEntry = z.object({
+  kind: z.enum(["url", "file"]),
+  name: z.string(),
+  uri: z.string(),
+  description: z.string(),
+});
+
+export type RepoEntry = z.infer<typeof RepoEntry>;
+
+const GlobalShape = z.object({
+  repos: z.array(RepoEntry),
+});
+
+const LocalShape = z.object({
+  refs: z.record(z.string(), RepoEntry),
+});
+
+const LocalLegacyShape = z.object({
+  refs: z.array(z.string()),
+});
+
+export namespace Config {
+  export function storeDir(): string {
+    return STORE_DIR;
+  }
+
+  export function refDir(): string {
+    return REF_DIR;
+  }
+
+  export namespace Global {
+    export type Shape = z.infer<typeof GlobalShape>;
+
+    export function read(): Shape {
+      const raw = readJson(GLOBAL_FILE);
+      if (!raw) return { repos: [] };
+      const result = GlobalShape.safeParse(raw);
+      if (!result.success) return { repos: [] };
+      return result.data;
+    }
+
+    export function write(config: Shape): void {
+      fs.mkdirSync(GLOBAL_DIR, { recursive: true });
+      fs.writeFileSync(GLOBAL_FILE, JSON.stringify(config, null, 2) + "\n");
+    }
+
+    export function find(config: Shape, name: string): RepoEntry | undefined {
+      return config.repos.find((r) => r.name === name);
+    }
+
+    export function add(config: Shape, entry: RepoEntry): Shape {
+      const filtered = config.repos.filter((r) => r.name !== entry.name);
+      return { repos: [...filtered, entry] };
+    }
+
+    export function remove(config: Shape, name: string): Shape {
+      return { repos: config.repos.filter((r) => r.name !== name) };
+    }
+  }
+
+  export namespace Local {
+    export type Shape = z.infer<typeof LocalShape>;
+
+    export function read(): Shape {
+      const raw = readJson(LOCAL_FILE);
+      if (!raw) return { refs: {} };
+      const result = LocalShape.safeParse(raw);
+      if (result.success) return result.data;
+      const legacy = LocalLegacyShape.safeParse(raw);
+      if (!legacy.success) return { refs: {} };
+
+      const global = Global.read();
+      const rows = legacy.data.refs
+        .map((name) => {
+          const repo = Global.find(global, name);
+          if (!repo) return null;
+          return [name, repo] as const;
+        })
+        .filter((row): row is readonly [string, RepoEntry] => row !== null);
+
+      return { refs: Object.fromEntries(rows) };
+    }
+
+    export function write(config: Shape): void {
+      fs.mkdirSync(LOCAL_DIR, { recursive: true });
+      fs.writeFileSync(LOCAL_FILE, JSON.stringify(config, null, 2) + "\n");
+    }
+
+    export function has(config: Shape, name: string): boolean {
+      return Object.prototype.hasOwnProperty.call(config.refs, name);
+    }
+
+    export function add(config: Shape, repo: RepoEntry): Shape {
+      return { refs: { ...config.refs, [repo.name]: repo } };
+    }
+
+    export function remove(config: Shape, name: string): Shape {
+      const refs = Object.fromEntries(
+        Object.entries(config.refs).filter(([key]) => key !== name),
+      );
+      return { refs };
+    }
+  }
+}
+
+function readJson(filepath: string): unknown {
+  if (!fs.existsSync(filepath)) return null;
+  const raw = fs.readFileSync(filepath, "utf-8");
+  return JSON.parse(raw);
+}

package/src/core/index.ts

@@ -0,0 +1,6 @@
+export { Config, type RepoEntry } from "@spader/dotllm/core/config";
+export { add, type AddResult } from "@spader/dotllm/core/add";
+export { remove, type RemoveResult } from "@spader/dotllm/core/remove";
+export { link } from "@spader/dotllm/core/link";
+export { unlink, type UnlinkResult } from "@spader/dotllm/core/unlink";
+export { pull, sync, type PullError, type PullResult, type SyncResult } from "@spader/dotllm/core/sync";

package/src/core/link.ts

@@ -0,0 +1,16 @@
+import { Config } from "@spader/dotllm/core/config";
+import { sync, type SyncResult } from "@spader/dotllm/core/sync";
+
+export function link(names: string[]): SyncResult {
+  const global = Config.Global.read();
+  const rows = names
+    .map((name) => {
+      const repo = Config.Global.find(global, name);
+      if (!repo) return null;
+      return [name, repo] as const;
+    })
+    .filter((row): row is readonly [string, (typeof global.repos)[number]] => row !== null);
+
+  Config.Local.write({ refs: Object.fromEntries(rows) });
+  return sync();
+}

package/src/core/remove.ts

@@ -0,0 +1,33 @@
+import fs from "fs";
+import path from "path";
+import { Config } from "@spader/dotllm/core/config";
+
+export type RemoveResult = {
+  ok: true;
+} | {
+  ok: false;
+  error: string;
+};
+
+export function remove(name: string): RemoveResult {
+  const global = Config.Global.read();
+  const found = Config.Global.find(global, name);
+
+  if (!found) {
+    return { ok: false, error: `No repo named "${name}" in registry` };
+  }
+
+  const target = path.join(Config.storeDir(), name);
+  if (fs.existsSync(target)) {
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink()) {
+      fs.unlinkSync(target);
+    }
+    if (stat.isDirectory()) {
+      fs.rmSync(target, { recursive: true, force: true });
+    }
+  }
+
+  Config.Global.write(Config.Global.remove(global, name));
+  return { ok: true };
+}

package/src/core/sync.ts

@@ -0,0 +1,136 @@
+import fs from "fs";
+import path from "path";
+import { Config } from "@spader/dotllm/core/config";
+
+export type SyncResult = {
+  linked: string[];
+  removed: string[];
+  missing: string[];
+  unchanged: string[];
+};
+
+type PullState = {
+  name: string;
+  error: string;
+} | null;
+
+export type PullError = {
+  name: string;
+  error: string;
+};
+
+export type PullResult = {
+  count: number;
+  failed: PullError[];
+};
+
+export async function pull(names: string[]): Promise<PullResult> {
+  const states = await Promise.all(
+    names.map(async (name): Promise<PullState> => {
+      const cwd = path.join(Config.refDir(), name);
+      if (!fs.existsSync(cwd)) {
+        return { name, error: "reference directory missing" };
+      }
+
+      const proc = Bun.spawn(["git", "pull", "--ff-only"], {
+        cwd,
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      const [code, out, err] = await Promise.all([
+        proc.exited,
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+      ]);
+      const msg = `${out}\n${err}`.trim();
+
+      if (code !== 0) {
+        return { name, error: msg || "git pull failed" };
+      }
+
+      return null;
+    }),
+  );
+
+  const failed = states.filter((state): state is PullError => state !== null);
+
+  return { count: names.length, failed };
+}
+
+export function sync(): SyncResult {
+  const local = Config.Local.read();
+  const global = Config.Global.read();
+  const merged = Object.values(local.refs).reduce(
+    (config, repo) => Config.Global.add(config, repo),
+    global,
+  );
+  if (Object.keys(local.refs).length > 0) {
+    Config.Global.write(merged);
+  }
+
+  const refDir = Config.refDir();
+  fs.mkdirSync(refDir, { recursive: true });
+  fs.mkdirSync(Config.storeDir(), { recursive: true });
+
+  const linked: string[] = [];
+  const removed: string[] = [];
+  const missing: string[] = [];
+  const unchanged: string[] = [];
+
+  const wanted = new Set(Object.keys(local.refs));
+  for (const entry of fs.readdirSync(refDir)) {
+    if (wanted.has(entry)) continue;
+    const target = path.join(refDir, entry);
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink()) {
+      fs.unlinkSync(target);
+      removed.push(entry);
+    }
+  }
+
+  for (const [name, repo] of Object.entries(local.refs)) {
+    const store = path.join(Config.storeDir(), name);
+    if (!fs.existsSync(store)) {
+      fs.rmSync(store, { recursive: true, force: true });
+    }
+
+    if (!fs.existsSync(store) && repo.kind === "url") {
+      const clone = Bun.spawnSync(["git", "clone", repo.uri, store], {
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+      if (clone.exitCode !== 0) {
+        missing.push(name);
+        continue;
+      }
+    }
+
+    if (!fs.existsSync(store) && repo.kind === "file") {
+      if (!fs.existsSync(repo.uri)) {
+        missing.push(name);
+        continue;
+      }
+      if (!fs.statSync(repo.uri).isDirectory()) {
+        missing.push(name);
+        continue;
+      }
+      fs.symlinkSync(repo.uri, store, "dir");
+    }
+
+    if (!fs.existsSync(store)) {
+      missing.push(name);
+      continue;
+    }
+
+    const target = path.join(refDir, name);
+    if (fs.existsSync(target)) {
+      unchanged.push(name);
+      continue;
+    }
+
+    fs.symlinkSync(store, target, "dir");
+    linked.push(name);
+  }
+
+  return { linked, removed, missing, unchanged };
+}

package/src/core/unlink.ts

@@ -0,0 +1,26 @@
+import fs from "fs";
+import path from "path";
+import { Config } from "@spader/dotllm/core/config";
+
+export type UnlinkResult = {
+  ok: true;
+} | {
+  ok: false;
+  error: string;
+};
+
+export function unlink(name: string): UnlinkResult {
+  const local = Config.Local.read();
+
+  if (!Config.Local.has(local, name)) {
+    return { ok: false, error: `"${name}" is not linked in local config` };
+  }
+
+  const target = path.join(Config.refDir(), name);
+  if (fs.existsSync(target)) {
+    fs.unlinkSync(target);
+  }
+
+  Config.Local.write(Config.Local.remove(local, name));
+  return { ok: true };
+}