facult 1.0.1

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "facult",
+  "version": "1.0.1",
+  "description": "Manage coding-agent skills and MCP configs across tools.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hack-dance/facult.git"
+  },
+  "homepage": "https://github.com/hack-dance/facult#readme",
+  "bugs": {
+    "url": "https://github.com/hack-dance/facult/issues"
+  },
+  "keywords": [
+    "cli",
+    "agents",
+    "mcp",
+    "skills",
+    "bun"
+  ],
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin/facult.cjs",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "facult": "bin/facult.cjs"
+  },
+  "scripts": {
+    "facult": "bun run ./src/index.ts",
+    "scan": "bun run ./src/index.ts scan",
+    "build": "bun run scripts/build-binary.ts",
+    "build:verify": "./dist/facult --help",
+    "install:dev": "bun run scripts/install-cli.ts --mode=dev --force",
+    "install:bin": "bun run build && bun run scripts/install-cli.ts --mode=bin --force",
+    "install:status": "bun run scripts/install-status.ts",
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "type-check": "tsc --noEmit",
+    "test": "bun test",
+    "test:ci": "bun run scripts/test-ci.ts",
+    "pack:dry-run": "npm pack --dry-run",
+    "release:dry-run": "bunx semantic-release --dry-run --no-ci",
+    "release": "bunx semantic-release",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.13",
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/commit-analyzer": "13.0.1",
+    "@semantic-release/git": "10.0.1",
+    "@semantic-release/github": "11.0.6",
+    "@semantic-release/npm": "12.0.2",
+    "@semantic-release/release-notes-generator": "14.1.0",
+    "@types/bun": "latest",
+    "conventional-changelog-conventionalcommits": "^8.0.0",
+    "husky": "^9.1.7",
+    "semantic-release": "25.0.2",
+    "typescript": "5.9.3",
+    "ultracite": "7.1.1"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "@opentui/core": "^0.1.75",
+    "jsonc-parser": "^3.3.1",
+    "yaml": "^2.8.2"
+  }
+}

package/src/adapters/claude-cli.ts

@@ -0,0 +1,18 @@
+import { generateMcpConfig, parseMcpConfig } from "./mcp";
+import { parseSkillsDir } from "./skills";
+import type { ToolAdapter } from "./types";
+import { detectExplicitVersion } from "./version";
+
+export const claudeCliAdapter: ToolAdapter = {
+  id: "claude",
+  name: "Claude CLI",
+  versions: ["v1"],
+  detectVersion: detectExplicitVersion,
+  getDefaultPaths: () => ({
+    mcp: "~/.claude.json",
+    skills: "~/.claude/skills",
+  }),
+  parseMcp: (config) => parseMcpConfig(config),
+  generateMcp: (canonical) => generateMcpConfig(canonical, "mcpServers"),
+  parseSkills: async (skillsDir) => await parseSkillsDir(skillsDir),
+};

package/src/adapters/claude-desktop.ts

@@ -0,0 +1,15 @@
+import { generateMcpConfig, parseMcpConfig } from "./mcp";
+import type { ToolAdapter } from "./types";
+import { detectExplicitVersion } from "./version";
+
+export const claudeDesktopAdapter: ToolAdapter = {
+  id: "claude-desktop",
+  name: "Claude Desktop",
+  versions: ["v1"],
+  detectVersion: detectExplicitVersion,
+  getDefaultPaths: () => ({
+    mcp: "~/Library/Application Support/Claude/claude_desktop_config.json",
+  }),
+  parseMcp: (config) => parseMcpConfig(config),
+  generateMcp: (canonical) => generateMcpConfig(canonical, "mcpServers"),
+};

package/src/adapters/clawdbot.ts

@@ -0,0 +1,18 @@
+import { generateMcpConfig, parseMcpConfig } from "./mcp";
+import { parseSkillsDir } from "./skills";
+import type { ToolAdapter } from "./types";
+import { detectExplicitVersion } from "./version";
+
+export const clawdbotAdapter: ToolAdapter = {
+  id: "clawdbot",
+  name: "Clawdbot",
+  versions: ["v1"],
+  detectVersion: detectExplicitVersion,
+  getDefaultPaths: () => ({
+    mcp: "~/.clawdbot/mcp.json",
+    skills: "~/.clawdbot/skills",
+  }),
+  parseMcp: (config) => parseMcpConfig(config),
+  generateMcp: (canonical) => generateMcpConfig(canonical, "mcpServers"),
+  parseSkills: async (skillsDir) => await parseSkillsDir(skillsDir),
+};

package/src/adapters/codex.ts

@@ -0,0 +1,19 @@
+import { generateMcpConfig, parseMcpConfig } from "./mcp";
+import { parseSkillsDir } from "./skills";
+import type { ToolAdapter } from "./types";
+import { detectExplicitVersion } from "./version";
+
+export const codexAdapter: ToolAdapter = {
+  id: "codex",
+  name: "Codex",
+  versions: ["v1"],
+  detectVersion: detectExplicitVersion,
+  getDefaultPaths: () => ({
+    mcp: "~/.codex/mcp.json",
+    skills: "~/.codex/skills",
+    config: "~/.config/openai/codex.json",
+  }),
+  parseMcp: (config) => parseMcpConfig(config),
+  generateMcp: (canonical) => generateMcpConfig(canonical, "mcpServers"),
+  parseSkills: async (skillsDir) => await parseSkillsDir(skillsDir),
+};

package/src/adapters/cursor.ts

@@ -0,0 +1,18 @@
+import { generateMcpConfig, parseMcpConfig } from "./mcp";
+import { parseSkillsDir } from "./skills";
+import type { ToolAdapter } from "./types";
+import { detectExplicitVersion } from "./version";
+
+export const cursorAdapter: ToolAdapter = {
+  id: "cursor",
+  name: "Cursor",
+  versions: ["v1"],
+  detectVersion: detectExplicitVersion,
+  getDefaultPaths: () => ({
+    mcp: "~/.cursor/mcp.json",
+    skills: "~/.cursor/skills",
+  }),
+  parseMcp: (config) => parseMcpConfig(config),
+  generateMcp: (canonical) => generateMcpConfig(canonical, "mcpServers"),
+  parseSkills: async (skillsDir) => await parseSkillsDir(skillsDir),
+};

package/src/adapters/index.ts

@@ -0,0 +1,69 @@
+import { claudeCliAdapter } from "./claude-cli";
+import { claudeDesktopAdapter } from "./claude-desktop";
+import { clawdbotAdapter } from "./clawdbot";
+import { codexAdapter } from "./codex";
+import { cursorAdapter } from "./cursor";
+import { referenceAdapter } from "./reference";
+import type { ResolveVersionOptions, ToolAdapter } from "./types";
+
+const registry = new Map<string, ToolAdapter>();
+
+export function registerAdapter(adapter: ToolAdapter) {
+  if (registry.has(adapter.id)) {
+    throw new Error(`Adapter already registered: ${adapter.id}`);
+  }
+  registry.set(adapter.id, adapter);
+}
+
+export function getAdapter(id: string): ToolAdapter | undefined {
+  return registry.get(id);
+}
+
+export function getAllAdapters(): ToolAdapter[] {
+  return Array.from(registry.values()).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function clearAdapters() {
+  registry.clear();
+}
+
+export async function resolveAdapterVersion(
+  adapter: ToolAdapter,
+  configPath: string,
+  options: ResolveVersionOptions = {}
+): Promise<string> {
+  const warn = options.warn ?? console.warn;
+  const fallback =
+    options.fallbackVersion ?? adapter.versions.at(-1) ?? "unknown";
+
+  if (!adapter.detectVersion) {
+    warn(
+      `Adapter ${adapter.id} has no version detection; using fallback ${fallback}.`
+    );
+    return fallback;
+  }
+
+  const detected = await adapter.detectVersion(configPath);
+  if (detected && adapter.versions.includes(detected)) {
+    return detected;
+  }
+
+  if (detected && !adapter.versions.includes(detected)) {
+    warn(
+      `Adapter ${adapter.id} detected unsupported version ${detected}; using fallback ${fallback}.`
+    );
+    return fallback;
+  }
+
+  warn(
+    `Adapter ${adapter.id} could not detect a version; using fallback ${fallback}.`
+  );
+  return fallback;
+}
+
+registerAdapter(referenceAdapter);
+registerAdapter(cursorAdapter);
+registerAdapter(codexAdapter);
+registerAdapter(claudeCliAdapter);
+registerAdapter(claudeDesktopAdapter);
+registerAdapter(clawdbotAdapter);

package/src/adapters/mcp.ts

@@ -0,0 +1,270 @@
+import type { CanonicalMcpConfig, CanonicalMcpServer } from "./types";
+
+type McpContainer = "mcpServers" | "servers" | "mcp";
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return !!v && typeof v === "object" && !Array.isArray(v);
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((item) => typeof item === "string");
+}
+
+function isStringRecord(v: unknown): v is Record<string, string> {
+  if (!isPlainObject(v)) {
+    return false;
+  }
+  return Object.values(v).every((val) => typeof val === "string");
+}
+
+const SERVER_KNOWN_KEYS = new Set([
+  "transport",
+  "command",
+  "args",
+  "url",
+  "env",
+]);
+
+function normalizeArgs(value: unknown): string[] | undefined {
+  if (isStringArray(value)) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(String);
+  }
+  return undefined;
+}
+
+function normalizeEnv(value: unknown): Record<string, string> | undefined {
+  if (isStringRecord(value)) {
+    return value;
+  }
+  if (!isPlainObject(value)) {
+    return undefined;
+  }
+  const entries = Object.entries(value).filter(
+    ([, v]) => typeof v === "string"
+  );
+  if (!entries.length) {
+    return undefined;
+  }
+  return Object.fromEntries(entries.map(([k, v]) => [k, String(v)]));
+}
+
+function setKnownServerField(
+  out: CanonicalMcpServer,
+  key: string,
+  value: unknown
+): boolean {
+  switch (key) {
+    case "transport":
+      out.transport = typeof value === "string" ? value : out.transport;
+      return true;
+    case "command":
+      out.command = typeof value === "string" ? value : out.command;
+      return true;
+    case "args":
+      out.args = normalizeArgs(value);
+      return true;
+    case "url":
+      out.url = typeof value === "string" ? value : out.url;
+      return true;
+    case "env":
+      out.env = normalizeEnv(value);
+      return true;
+    default:
+      return false;
+  }
+}
+
+function canonicalizeServer(config: unknown): CanonicalMcpServer {
+  if (!isPlainObject(config)) {
+    return {
+      vendorExtensions: { raw: config },
+    };
+  }
+
+  const out: CanonicalMcpServer = {};
+  const vendor: Record<string, unknown> = {};
+
+  for (const [k, v] of Object.entries(config)) {
+    if (!(SERVER_KNOWN_KEYS.has(k) && setKnownServerField(out, k, v))) {
+      vendor[k] = v;
+    }
+  }
+
+  if (Object.keys(vendor).length) {
+    out.vendorExtensions = vendor;
+  }
+
+  return out;
+}
+
+function detectContainer(
+  obj: Record<string, unknown>
+): { container: McpContainer; servers: Record<string, unknown> } | null {
+  if (isPlainObject(obj.mcpServers)) {
+    return { container: "mcpServers", servers: obj.mcpServers };
+  }
+  if (isPlainObject(obj.mcp)) {
+    const mcp = obj.mcp as Record<string, unknown>;
+    if (isPlainObject(mcp.servers)) {
+      return { container: "mcp", servers: mcp.servers };
+    }
+  }
+  if (isPlainObject(obj.servers)) {
+    return { container: "servers", servers: obj.servers };
+  }
+  return null;
+}
+
+function extractMcpVendorExtensions(value: unknown): Record<string, unknown> {
+  if (!isPlainObject(value)) {
+    return { mcp: value };
+  }
+  const { servers: _servers, ...rest } = value as Record<string, unknown>;
+  if (Object.keys(rest).length) {
+    return { mcp: rest };
+  }
+  return {};
+}
+
+function extractServers(config: unknown): {
+  servers: Record<string, unknown>;
+  vendorExtensions: Record<string, unknown>;
+  container: McpContainer | null;
+} {
+  if (!isPlainObject(config)) {
+    return { servers: {}, vendorExtensions: {}, container: null };
+  }
+
+  const obj = config as Record<string, unknown>;
+  const detected = detectContainer(obj);
+  const container = detected?.container ?? null;
+  const servers = detected?.servers ?? {};
+
+  const vendorExtensions: Record<string, unknown> = {};
+
+  for (const [k, v] of Object.entries(obj)) {
+    if (container === "mcpServers" && k === "mcpServers") {
+      continue;
+    }
+    if (container === "servers" && k === "servers") {
+      continue;
+    }
+    if (container === "mcp" && k === "mcp") {
+      Object.assign(vendorExtensions, extractMcpVendorExtensions(v));
+      continue;
+    }
+    vendorExtensions[k] = v;
+  }
+
+  return { servers, vendorExtensions, container };
+}
+
+export function parseMcpConfig(config: unknown): CanonicalMcpConfig {
+  const { servers, vendorExtensions } = extractServers(config);
+  const canonical: CanonicalMcpConfig = {
+    servers: {},
+  };
+
+  for (const [name, cfg] of Object.entries(servers)) {
+    canonical.servers[name] = canonicalizeServer(cfg);
+  }
+
+  if (Object.keys(vendorExtensions).length) {
+    canonical.vendorExtensions = vendorExtensions;
+  }
+
+  return canonical;
+}
+
+function generateServerConfig(server: CanonicalMcpServer): unknown {
+  const known: Record<string, unknown> = {};
+  const hasKnownKeys = (key: keyof CanonicalMcpServer) =>
+    server[key] !== undefined;
+
+  if (hasKnownKeys("transport")) {
+    known.transport = server.transport;
+  }
+  if (hasKnownKeys("command")) {
+    known.command = server.command;
+  }
+  if (hasKnownKeys("args")) {
+    known.args = server.args;
+  }
+  if (hasKnownKeys("url")) {
+    known.url = server.url;
+  }
+  if (hasKnownKeys("env")) {
+    known.env = server.env;
+  }
+
+  const vendor = isPlainObject(server.vendorExtensions)
+    ? (server.vendorExtensions as Record<string, unknown>)
+    : null;
+
+  if (vendor && "raw" in vendor && Object.keys(known).length === 0) {
+    const rawValue = vendor.raw;
+    if (Object.keys(vendor).length === 1) {
+      return rawValue;
+    }
+  }
+
+  if (vendor) {
+    for (const [k, v] of Object.entries(vendor)) {
+      if (!(k in known)) {
+        known[k] = v;
+      }
+    }
+  }
+
+  return known;
+}
+
+export function generateMcpConfig(
+  canonical: CanonicalMcpConfig,
+  container: McpContainer = "mcpServers"
+): Record<string, unknown> {
+  const servers: Record<string, unknown> = {};
+  for (const [name, server] of Object.entries(canonical.servers ?? {})) {
+    servers[name] = generateServerConfig(server);
+  }
+
+  const vendor = isPlainObject(canonical.vendorExtensions)
+    ? (canonical.vendorExtensions as Record<string, unknown>)
+    : {};
+
+  const out: Record<string, unknown> = {};
+
+  if (container === "mcp") {
+    const mcpObj: Record<string, unknown> = { servers };
+    if (isPlainObject(vendor.mcp)) {
+      Object.assign(mcpObj, vendor.mcp as Record<string, unknown>);
+    }
+    out.mcp = mcpObj;
+  } else if (container === "servers") {
+    out.servers = servers;
+  } else {
+    out.mcpServers = servers;
+  }
+
+  for (const [k, v] of Object.entries(vendor)) {
+    if (k === "mcp" && container === "mcp") {
+      continue;
+    }
+    if (k === "servers" && container === "servers") {
+      continue;
+    }
+    if (k === "mcpServers" && container === "mcpServers") {
+      continue;
+    }
+    out[k] = v;
+  }
+
+  return out;
+}
+
+export function isPlainObjectValue(v: unknown): v is Record<string, unknown> {
+  return isPlainObject(v);
+}

package/src/adapters/reference.ts

@@ -0,0 +1,9 @@
+import type { ToolAdapter } from "./types";
+import { detectExplicitVersion } from "./version";
+
+export const referenceAdapter: ToolAdapter = {
+  id: "reference",
+  name: "Reference Adapter",
+  versions: ["v1"],
+  detectVersion: detectExplicitVersion,
+};

package/src/adapters/skills.ts

@@ -0,0 +1,47 @@
+import { readdir } from "node:fs/promises";
+import { basename, join } from "node:path";
+import type { CanonicalSkill } from "./types";
+
+async function listSubdirs(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(dir, entry.name));
+  } catch {
+    return [];
+  }
+}
+
+async function skillFromDir(dir: string): Promise<CanonicalSkill | null> {
+  const path = join(dir, "SKILL.md");
+  try {
+    const file = Bun.file(path);
+    const st = await file.stat();
+    if (!st.isFile()) {
+      return null;
+    }
+    const body = await file.text();
+    return {
+      name: basename(dir),
+      body,
+      path: dir,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function parseSkillsDir(
+  skillsDir: string
+): Promise<CanonicalSkill[]> {
+  const dirs = await listSubdirs(skillsDir);
+  const out: CanonicalSkill[] = [];
+  for (const dir of dirs) {
+    const skill = await skillFromDir(dir);
+    if (skill) {
+      out.push(skill);
+    }
+  }
+  return out;
+}

package/src/adapters/types.ts

@@ -0,0 +1,42 @@
+export interface CanonicalMcpServer {
+  transport?: string;
+  command?: string;
+  args?: string[];
+  url?: string;
+  env?: Record<string, string>;
+  vendorExtensions?: Record<string, unknown>;
+}
+
+export interface CanonicalMcpConfig {
+  servers: Record<string, CanonicalMcpServer>;
+  vendorExtensions?: Record<string, unknown>;
+}
+
+export interface CanonicalSkill {
+  name: string;
+  body?: string;
+  path?: string;
+}
+
+export interface AdapterDefaultPaths {
+  mcp?: string;
+  skills?: string | string[];
+  config?: string;
+}
+
+export interface ToolAdapter {
+  id: string;
+  name: string;
+  versions: string[];
+  detectVersion?: (configPath: string) => Promise<string | null>;
+  parseMcp?: (config: unknown, version?: string) => CanonicalMcpConfig;
+  parseSkills?: (skillsDir: string) => Promise<CanonicalSkill[]>;
+  generateMcp?: (canonical: CanonicalMcpConfig, version?: string) => unknown;
+  generateSkillsDir?: (skills: CanonicalSkill[]) => Promise<void>;
+  getDefaultPaths?: () => AdapterDefaultPaths;
+}
+
+export interface ResolveVersionOptions {
+  fallbackVersion?: string;
+  warn?: (message: string) => void;
+}

package/src/adapters/version.ts

@@ -0,0 +1,18 @@
+export async function detectExplicitVersion(
+  configPath: string
+): Promise<string | null> {
+  try {
+    const raw = await Bun.file(configPath).text();
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const version = parsed.version;
+    if (typeof version === "string") {
+      return version;
+    }
+    if (typeof version === "number") {
+      return String(version);
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}