codeguilds 0.2.0

package/src/lib/installers.ts

@@ -0,0 +1,165 @@
+import { writeFileSync, existsSync, readFileSync, mkdirSync } from "fs";
+import { resolve } from "path";
+import { homedir } from "os";
+import { addMcpServer, addHook, removeMcpServer, removeHook } from "./claude-settings.js";
+import type {
+  RegistryPackage,
+  InstallConfigMcp,
+  InstallConfigHook,
+  InstallConfigFile,
+  InstallConfigTemplate,
+} from "./types.js";
+
+export type Scope = "global" | "project";
+
+export interface InstallResult {
+  destination: string;
+  note?: string;
+}
+
+export async function installPackage(
+  pkg: RegistryPackage,
+  scope: Scope,
+  strategyOverride?: "append" | "prepend" | "replace",
+): Promise<InstallResult> {
+  switch (pkg.package_type) {
+    case "mcp_server": {
+      if (!pkg.install_config) throw new Error(`Package '${pkg.slug}' has no install_config.`);
+      return installMcp(pkg, pkg.install_config as InstallConfigMcp, scope);
+    }
+    case "hook": {
+      if (!pkg.install_config) throw new Error(`Package '${pkg.slug}' has no install_config.`);
+      return installHook(pkg, pkg.install_config as InstallConfigHook, scope);
+    }
+    case "skill":
+    case "prompt": {
+      const fileConfig = pkg.install_config as InstallConfigFile | undefined;
+      const filename = fileConfig?.filename ?? `${pkg.slug}.md`;
+      return installFile(pkg, { filename }, "commands");
+    }
+    case "agent": {
+      const fileConfig = pkg.install_config as InstallConfigFile | undefined;
+      const filename = fileConfig?.filename ?? `${pkg.slug}.md`;
+      return installFile(pkg, { filename }, "agents");
+    }
+    case "claude_md_template": {
+      const tmplConfig = pkg.install_config as InstallConfigTemplate | undefined;
+      const strategy = strategyOverride ?? tmplConfig?.merge_strategy ?? "append";
+      return installTemplate(pkg, { filename: tmplConfig?.filename ?? "CLAUDE.md", merge_strategy: strategy }, scope);
+    }
+    default:
+      throw new Error(`Unknown package type: ${pkg.package_type}`);
+  }
+}
+
+function installMcp(
+  pkg: RegistryPackage,
+  config: InstallConfigMcp,
+  scope: Scope
+): InstallResult {
+  addMcpServer(config.server_name, config.command, config.args ?? [], config.env ?? {}, scope);
+  const path = scope === "global" ? "~/.claude/settings.json" : ".claude/settings.json";
+  return {
+    destination: path,
+    note: `Added MCP server '${config.server_name}' — restart Claude Code to activate`,
+  };
+}
+
+function installHook(
+  pkg: RegistryPackage,
+  config: InstallConfigHook,
+  scope: Scope
+): InstallResult {
+  addHook(config.event, config.matcher, config.command, scope);
+  const path = scope === "global" ? "~/.claude/settings.json" : ".claude/settings.json";
+  return {
+    destination: path,
+    note: `Added hook for '${config.event}' event`,
+  };
+}
+
+function isSafeFilename(filename: string): boolean {
+  if (!filename || filename.includes("..") || filename.includes("/") || filename.startsWith("~")) return false;
+  return /^[\w\-. ]+$/.test(filename);
+}
+
+async function installFile(
+  pkg: RegistryPackage,
+  config: InstallConfigFile,
+  subdir: "commands" | "agents"
+): Promise<InstallResult> {
+  if (!pkg.readme_content) {
+    throw new Error(`No content to install for '${pkg.slug}'`);
+  }
+  if (!isSafeFilename(config.filename)) {
+    throw new Error(`Unsafe filename rejected: '${config.filename}'`);
+  }
+  const dir = resolve(homedir(), ".claude", subdir);
+  mkdirSync(dir, { recursive: true });
+  const dest = resolve(dir, config.filename);
+  writeFileSync(dest, pkg.readme_content);
+  return { destination: `~/.claude/${subdir}/${config.filename}` };
+}
+
+async function installTemplate(
+  pkg: RegistryPackage,
+  config: InstallConfigTemplate,
+  scope: Scope
+): Promise<InstallResult> {
+  if (!pkg.readme_content) {
+    throw new Error(`No content to install for '${pkg.slug}'`);
+  }
+  const dest =
+    scope === "project"
+      ? resolve(process.cwd(), "CLAUDE.md")
+      : resolve(homedir(), ".claude", "CLAUDE.md");
+
+  const content = pkg.readme_content;
+
+  if (!existsSync(dest) || config.merge_strategy === "replace") {
+    writeFileSync(dest, content);
+  } else {
+    const existing = readFileSync(dest, "utf-8");
+    const merged =
+      config.merge_strategy === "prepend"
+        ? `${content}\n\n${existing}`
+        : `${existing}\n\n${content}`;
+    writeFileSync(dest, merged);
+  }
+
+  const displayDest = scope === "project" ? "./CLAUDE.md" : "~/.claude/CLAUDE.md";
+  return { destination: displayDest, note: `Merged via '${config.merge_strategy}' strategy` };
+}
+
+export function uninstallPackage(
+  pkg: RegistryPackage,
+  scope: Scope
+): { success: boolean; message: string } {
+  if (!pkg.install_config) return { success: true, message: "Nothing to undo" };
+
+  switch (pkg.package_type) {
+    case "mcp_server": {
+      const config = pkg.install_config as InstallConfigMcp;
+      const removed = removeMcpServer(config.server_name, scope);
+      return {
+        success: true,
+        message: removed
+          ? `Removed MCP server '${config.server_name}' from settings`
+          : `MCP server '${config.server_name}' was not in settings`,
+      };
+    }
+    case "hook": {
+      const config = pkg.install_config as InstallConfigHook;
+      const removed = removeHook(config.event, config.command, scope);
+      return {
+        success: true,
+        message: removed ? `Removed hook from '${config.event}'` : `Hook was not found in settings`,
+      };
+    }
+    default:
+      return {
+        success: true,
+        message: "File-based package — remove it manually from ~/.claude/commands/ or ~/.claude/agents/",
+      };
+  }
+}

package/src/lib/lock.ts

@@ -0,0 +1,35 @@
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import type { LockFile, LockEntry } from "./types.js";
+
+export function getLockPath(projectDir?: string): string {
+  return resolve(projectDir ?? process.cwd(), ".codeguilds-lock.json");
+}
+
+export function readLock(projectDir?: string): LockFile {
+  const path = getLockPath(projectDir);
+  if (!existsSync(path)) return { version: 1, packages: {} };
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as LockFile;
+  } catch {
+    return { version: 1, packages: {} };
+  }
+}
+
+export function writeLock(lock: LockFile, projectDir?: string): void {
+  writeFileSync(getLockPath(projectDir), JSON.stringify(lock, null, 2) + "\n");
+}
+
+export function addToLock(entry: LockEntry, projectDir?: string): void {
+  const lock = readLock(projectDir);
+  lock.packages[entry.slug] = entry;
+  writeLock(lock, projectDir);
+}
+
+export function removeFromLock(slug: string, projectDir?: string): boolean {
+  const lock = readLock(projectDir);
+  if (!lock.packages[slug]) return false;
+  delete lock.packages[slug];
+  writeLock(lock, projectDir);
+  return true;
+}

package/src/lib/types.ts

@@ -0,0 +1,65 @@
+export type PackageType =
+  | "mcp_server"
+  | "skill"
+  | "agent"
+  | "hook"
+  | "prompt"
+  | "claude_md_template";
+
+export interface InstallConfigMcp {
+  server_name: string;
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}
+
+export interface InstallConfigHook {
+  event: string;
+  matcher: string;
+  command: string;
+}
+
+export interface InstallConfigFile {
+  filename: string;
+}
+
+export interface InstallConfigTemplate {
+  filename: string;
+  merge_strategy: "append" | "prepend" | "replace";
+}
+
+export type InstallConfig =
+  | InstallConfigMcp
+  | InstallConfigHook
+  | InstallConfigFile
+  | InstallConfigTemplate;
+
+export interface RegistryPackage {
+  id: string;
+  slug: string;
+  name: string;
+  description: string;
+  package_type: PackageType;
+  current_version: string;
+  download_count: number;
+  star_count: number;
+  install_config: InstallConfig | null;
+  source_url: string | null;
+  readme_content: string | null;
+  license: string | null;
+  published_at: string | null;
+  publisher: { username: string; display_name: string | null } | null;
+}
+
+export interface LockEntry {
+  slug: string;
+  name: string;
+  current_version: string;
+  package_type: PackageType;
+  installed_at: string;
+}
+
+export interface LockFile {
+  version: 1;
+  packages: Record<string, LockEntry>;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  target: "node18",
+  outExtension: () => ({ js: ".js" }),
+  banner: { js: "#!/usr/bin/env node" },
+  clean: true,
+  minify: false,
+  shims: true,
+});