@jaybeeuu/agent-uplink 1.0.0

package/src/commands/mcp.ts

@@ -0,0 +1,35 @@
+import { Command } from "commander";
+import { getCapabilitiesDir } from "../config.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("mcp");
+
+export function makeMcpCommand(): Command {
+  const cmd = new Command("mcp");
+  cmd.description("Manage the MCP (Model Context Protocol) server");
+
+  cmd
+    .command("start")
+    .description("Start the MCP server")
+    .option("--stdio", "Use stdio transport (default, for use with AI tools)")
+    .option("--capabilities-dir <path>", "Override capabilities directory")
+    .action(async (opts: { stdio?: boolean; capabilitiesDir?: string }) => {
+      const capabilitiesDir = opts.capabilitiesDir ?? getCapabilitiesDir();
+
+      // Diagnostic output goes to stderr so stdout stays clean for MCP protocol
+      log.debug("Starting MCP server (stdio)");
+      log.debug(`Capabilities dir: ${capabilitiesDir}`);
+
+      try {
+        const { startStdioServer } = await import("../mcp.js");
+        await startStdioServer(capabilitiesDir);
+      } catch (err) {
+        process.stderr.write(
+          `[agent-uplink] MCP server error: ${err instanceof Error ? err.message : String(err)}\n`
+        );
+        process.exit(1);
+      }
+    });
+
+  return cmd;
+}

package/src/commands/sync.ts

@@ -0,0 +1,49 @@
+import { Command } from "commander";
+import { syncCapabilities, getGitStatus } from "../git.js";
+import { getCapabilitiesDir, getConfigValue } from "../config.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("sync");
+
+export function makeSyncCommand(): Command {
+  const cmd = new Command("sync");
+  cmd
+    .description(
+      "Commit and push all capability changes to the configured git remote"
+    )
+    .option("--dry-run", "Show what would be synced without making changes")
+    .action(async (opts: { dryRun?: boolean }) => {
+      const capabilitiesDir = getCapabilitiesDir();
+
+      if (opts.dryRun) {
+        const status = await getGitStatus(capabilitiesDir);
+        if (status.clean) {
+          log.warn("Nothing to sync.");
+        } else {
+          log.info("Files that would be committed:");
+          for (const f of status.files) {
+            log.dim(f);
+          }
+        }
+        return;
+      }
+
+      try {
+        log.debug(`Syncing ${capabilitiesDir}...`);
+        const result = await syncCapabilities(capabilitiesDir, getConfigValue("gitRemote"));
+
+        if (!result.committed) {
+          log.warn(result.message);
+        } else if (result.pushed) {
+          log.success(result.message);
+        } else {
+          log.warn(result.message);
+        }
+      } catch (err) {
+        log.error(err);
+        process.exit(1);
+      }
+    });
+
+  return cmd;
+}

package/src/config.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  getConfigValue,
+  setConfigValue,
+  getConfigEntries,
+} from "./config.js";
+
+const TMP = join(tmpdir(), `uplink-config-test-${String(process.pid)}`);
+
+beforeEach(() => {
+  mkdirSync(TMP, { recursive: true });
+  // Override home directory for each test
+  process.env["HOME"] = TMP;
+});
+
+afterEach(() => {
+  rmSync(TMP, { recursive: true, force: true });
+  delete process.env["HOME"];
+});
+
+describe("getConfigValue", () => {
+  it("returns default capabilitiesDir when no config file exists", () => {
+    const dir = getConfigValue("capabilitiesDir");
+    expect(dir).toContain(".agent-uplink");
+    expect(dir).toContain("capabilities");
+  });
+
+  it("returns stored value after setConfigValue", () => {
+    setConfigValue("editor", "vim");
+    expect(getConfigValue("editor")).toBe("vim");
+  });
+});
+
+describe("setConfigValue", () => {
+  it("sets and gets individual config values", () => {
+    setConfigValue("editor", "nano");
+    expect(getConfigValue("editor")).toBe("nano");
+  });
+
+  it("leaves other values intact when setting one key", () => {
+    setConfigValue("capabilitiesDir", "/original");
+    setConfigValue("editor", "vim");
+    setConfigValue("editor", "emacs");
+    expect(getConfigValue("capabilitiesDir")).toBe("/original");
+    expect(getConfigValue("editor")).toBe("emacs");
+  });
+
+  it("persists multiple keys in round-trip", () => {
+    setConfigValue("capabilitiesDir", "/some/dir");
+    setConfigValue("editor", "code");
+    setConfigValue("gitRemote", "upstream");
+    expect(getConfigValue("capabilitiesDir")).toBe("/some/dir");
+    expect(getConfigValue("editor")).toBe("code");
+    expect(getConfigValue("gitRemote")).toBe("upstream");
+  });
+});
+
+describe("getConfigEntries", () => {
+  it("returns all config keys with their values and defaults", () => {
+    const entries = getConfigEntries();
+    const keys = entries.map((e) => e.key);
+    expect(keys).toContain("capabilitiesDir");
+  });
+
+  it("value is undefined for unset optional keys", () => {
+    const entry = getConfigEntries().find((e) => e.key === "editor");
+    expect(entry?.value).toBeUndefined();
+  });
+
+  it("value is set when key has been configured", () => {
+    setConfigValue("editor", "vim");
+    const entry = getConfigEntries().find((e) => e.key === "editor");
+    expect(entry?.value).toBe("vim");
+  });
+
+  it("defaultValue is set for keys that have defaults", () => {
+    const entry = getConfigEntries().find((e) => e.key === "capabilitiesDir");
+    expect(entry?.defaultValue).toBeDefined();
+    expect(entry?.defaultValue).toContain("capabilities");
+  });
+});

package/src/config.ts

@@ -0,0 +1,113 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { createLogger } from "./logger.js";
+import { ConfigSchema } from "./types.js";
+import type { Config } from "./types.js";
+
+const log = createLogger("config");
+
+function getConfigDir_(): string {
+  return join(homedir(), ".agent-uplink");
+}
+
+function getConfigFile(): string {
+  return join(getConfigDir_(), "config.json");
+}
+
+function getDefaults(): Config {
+  return {
+    capabilitiesDir: join(getConfigDir_(), "capabilities"),
+  };
+}
+
+export function getConfigDir(): string {
+  return getConfigDir_();
+}
+
+export function getConfigFilePath(): string {
+  return getConfigFile();
+}
+
+function loadRawConfig(): Partial<Config> {
+  const configFile = getConfigFile();
+  if (!existsSync(configFile)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync(configFile, "utf-8");
+    const parsed: unknown = JSON.parse(raw);
+    const result = ConfigSchema.partial().safeParse(parsed);
+    if (!result.success) {
+      log.warn(
+        `Config file at ${configFile} is invalid: ${result.error.message}. Using defaults.`
+      );
+      return {};
+    }
+    return result.data;
+  } catch (err) {
+    log.warn(
+      `Could not read config file at ${configFile}: ${err instanceof Error ? err.message : String(err)}. Using defaults.`
+    );
+    return {};
+  }
+}
+
+function loadConfig(): Config {
+  return { ...getDefaults(), ...loadRawConfig() };
+}
+
+function saveConfig(config: Config): void {
+  const configFile = getConfigFile();
+  const dir = dirname(configFile);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+export function getConfigValue<K extends keyof Config>(key: K): Config[K] {
+  return loadConfig()[key];
+}
+
+export function setConfigValue<K extends keyof Config>(
+  key: K,
+  value: Config[K]
+): void {
+  const config = loadConfig();
+  config[key] = value;
+  saveConfig(config);
+}
+
+export type ConfigEntry = {
+  key: keyof Config;
+  value: Config[keyof Config] | undefined;
+  defaultValue: Config[keyof Config] | undefined;
+};
+
+export function getConfigEntries(): ConfigEntry[] {
+  const raw = loadRawConfig();
+  const defaults = getDefaults();
+  const keys = new Set([
+    ...(Object.keys(defaults) as (keyof Config)[]),
+    ...(Object.keys(raw) as (keyof Config)[]),
+  ]);
+  return [...keys].map((key) => ({
+    key,
+    value: raw[key],
+    defaultValue: defaults[key],
+  }));
+}
+
+export function ensureConfigFile(): void {
+  saveConfig(loadConfig());
+}
+
+export function getCapabilitiesDir(): string {
+  return loadConfig().capabilitiesDir;
+}
+
+export function resetConfig(): void {
+  const capabilitiesDir = getConfigValue("capabilitiesDir");
+  saveConfig({ capabilitiesDir });
+}

package/src/editor.ts

@@ -0,0 +1,47 @@
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { getConfigValue } from "./config.js";
+
+function getDefaultEditor(): string {
+  return (
+    getConfigValue("editor") ??
+    process.env["VISUAL"] ??
+    process.env["EDITOR"] ??
+    (process.platform === "win32" ? "notepad" : "vi")
+  );
+}
+
+export async function openInEditor(
+  filePath: string,
+  editorOverride?: string
+): Promise<void> {
+  if (!existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const editor = editorOverride ?? getDefaultEditor();
+  const parts = editor.split(" ");
+  const cmd = parts[0];
+  const args = [...parts.slice(1), filePath];
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      stdio: "inherit",
+      shell: process.platform === "win32",
+    });
+
+    child.on("exit", (code) => {
+      if (code === 0 || code === null) {
+        resolve();
+      } else {
+        reject(new Error(`Editor exited with code ${code}`));
+      }
+    });
+
+    child.on("error", (err) => {
+      reject(
+        new Error(`Failed to launch editor '${editor}': ${err.message}`)
+      );
+    });
+  });
+}

package/src/git.ts

@@ -0,0 +1,84 @@
+import { simpleGit } from "simple-git";
+import type { SimpleGit } from "simple-git";
+import { existsSync } from "fs";
+import type { SyncResult } from "./types.js";
+
+export function getGit(dir: string): SimpleGit {
+  return simpleGit(dir);
+}
+
+async function isGitRepo(dir: string): Promise<boolean> {
+  if (!existsSync(dir)) return false;
+  try {
+    const git = getGit(dir);
+    await git.status();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function syncCapabilities(
+  dir: string,
+  remote?: string
+): Promise<SyncResult> {
+  const git = getGit(dir);
+
+  const isRepo = await isGitRepo(dir);
+  if (!isRepo) {
+    throw new Error(
+      `'${dir}' is not a git repository. Run 'git init' there first, or use 'uplink config set capabilitiesDir <path>' to point to an existing git repo.`
+    );
+  }
+
+  const status = await git.status();
+  if (status.files.length === 0) {
+    return { committed: false, pushed: false, message: "Nothing to sync." };
+  }
+
+  const changed = status.files.map((f) => f.path).join(", ");
+  const now = new Date().toISOString().slice(0, 10);
+  const commitMessage = `chore: sync capabilities on ${now} (${status.files.length} file(s): ${changed})`;
+
+  await git.add(".");
+  await git.commit(commitMessage);
+
+  const effectiveRemote = remote ?? "origin";
+  let pushed = false;
+
+  try {
+    const remotes = await git.getRemotes();
+    const hasRemote = remotes.some((r) => r.name === effectiveRemote);
+    if (hasRemote) {
+      const branch = (await git.branchLocal()).current;
+      await git.push(effectiveRemote, branch, ["--set-upstream"]);
+      pushed = true;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      committed: true,
+      pushed: false,
+      message: `Committed but push failed: ${msg}`,
+    };
+  }
+
+  return {
+    committed: true,
+    pushed,
+    message: pushed
+      ? `Synced: ${commitMessage}`
+      : `Committed locally (no remote configured): ${commitMessage}`,
+  };
+}
+
+export async function getGitStatus(
+  dir: string
+): Promise<{ clean: boolean; files: string[] }> {
+  const git = getGit(dir);
+  const status = await git.status();
+  return {
+    clean: status.files.length === 0,
+    files: status.files.map((f) => `${f.index}${f.working_dir} ${f.path}`),
+  };
+}

package/src/logger.ts

@@ -0,0 +1,60 @@
+/**
+ * Centralised logging for agent-uplink.
+ *
+ * Debug output is gated behind the DEBUG environment variable using the
+ * standard `debug` package convention, e.g.:
+ *   DEBUG=agent-uplink:*        – enable all modules
+ *   DEBUG=agent-uplink:config   – enable config module only
+ *   DEBUG=agent-uplink:install  – enable install module only
+ */
+import createDebug from "debug";
+import chalk from "chalk";
+
+export function toErrorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  return String(err);
+}
+
+export type Logger = {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (err: unknown, ...extra: unknown[]) => void;
+  success: (...args: unknown[]) => void;
+  dim: (...args: unknown[]) => void;
+};
+
+export function createLogger(namespace: string): Logger {
+  const debugLog = createDebug(`agent-uplink:${namespace}`);
+
+  return {
+    debug(...args) {
+      debugLog(args.map(String).join(" "));
+    },
+
+    info(...args) {
+      console.log(args.map(String).join(" "));
+    },
+
+    warn(...args) {
+      console.warn(chalk.yellow(`⚠ ${args.map(String).join(" ")}`));
+    },
+
+    error(err, ...extra) {
+      const msg = [toErrorMessage(err), ...extra.map(String)].join(" ");
+      console.error(chalk.red(`✗ ${msg}`));
+    },
+
+    success(...args) {
+      console.log(chalk.green(`✓ ${args.map(String).join(" ")}`));
+    },
+
+    dim(...args) {
+      console.log(chalk.dim(`  ${args.map(String).join(" ")}`));
+    },
+  };
+}
+
+/** Shared root logger for the CLI entry point. */
+export const rootLogger = createLogger("cli");

package/src/mcp.ts

@@ -0,0 +1,156 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  createCapability,
+  readCapability,
+  updateCapability,
+  deleteCapability,
+  listCapabilities,
+} from "./capabilities.js";
+import { syncCapabilities } from "./git.js";
+import { getConfigValue } from "./config.js";
+import { CapabilityTypeSchema } from "./types.js";
+
+type McpToolResult = { content: { type: "text"; text: string }[]; isError?: boolean };
+
+function mcpSuccess(text: string): McpToolResult {
+  return { content: [{ type: "text", text }] };
+}
+
+function mcpError(err: unknown): McpToolResult {
+  const msg = err instanceof Error ? err.message : String(err);
+  return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+}
+
+export function createMcpServer(capabilitiesDir: string): McpServer {
+  const server = new McpServer({
+    name: "agent-uplink",
+    version: "1.0.0",
+  });
+
+  server.registerTool(
+    "list_capabilities",
+    {
+      description: "List all capabilities of a given type (skill, agent, instruction)",
+      inputSchema: {
+        type: CapabilityTypeSchema.describe(
+          "Type of capability: skill, agent, or instruction"
+        ),
+      },
+    },
+    ({ type }) => {
+      const items = listCapabilities(capabilitiesDir, type);
+      return mcpSuccess(
+        items.length > 0
+          ? `${type}s:\n${items.map((i) => `- ${i}`).join("\n")}`
+          : `No ${type}s found.`
+      );
+    }
+  );
+
+  server.registerTool(
+    "get_capability",
+    {
+      description: "Get the content of a specific capability",
+      inputSchema: {
+        type: CapabilityTypeSchema.describe("Type of capability"),
+        name: z.string().describe("Name of the capability"),
+      },
+    },
+    ({ type, name }) => {
+      try {
+        const cap = readCapability(capabilitiesDir, type, name);
+        return mcpSuccess(cap.content);
+      } catch (err) {
+        return mcpError(err);
+      }
+    }
+  );
+
+  server.registerTool(
+    "create_capability",
+    {
+      description: "Create a new capability with the given content",
+      inputSchema: {
+        type: CapabilityTypeSchema.describe("Type of capability to create"),
+        name: z.string().describe("Name of the capability"),
+        content: z
+          .string()
+          .optional()
+          .describe("Content for the capability (uses template if omitted)"),
+      },
+    },
+    ({ type, name, content }) => {
+      try {
+        const cap = createCapability(capabilitiesDir, type, name, content);
+        return mcpSuccess(`Created ${type} '${name}' at ${cap.path}`);
+      } catch (err) {
+        return mcpError(err);
+      }
+    }
+  );
+
+  server.registerTool(
+    "update_capability",
+    {
+      description: "Update the content of an existing capability",
+      inputSchema: {
+        type: CapabilityTypeSchema.describe("Type of capability"),
+        name: z.string().describe("Name of the capability"),
+        content: z.string().describe("New content for the capability"),
+      },
+    },
+    ({ type, name, content }) => {
+      try {
+        const cap = updateCapability(capabilitiesDir, type, name, content);
+        return mcpSuccess(`Updated ${type} '${name}' at ${cap.path}`);
+      } catch (err) {
+        return mcpError(err);
+      }
+    }
+  );
+
+  server.registerTool(
+    "delete_capability",
+    {
+      description: "Delete a capability",
+      inputSchema: {
+        type: CapabilityTypeSchema.describe("Type of capability"),
+        name: z.string().describe("Name of the capability to delete"),
+      },
+    },
+    ({ type, name }) => {
+      try {
+        deleteCapability(capabilitiesDir, type, name);
+        return mcpSuccess(`Deleted ${type} '${name}'`);
+      } catch (err) {
+        return mcpError(err);
+      }
+    }
+  );
+
+  server.registerTool(
+    "sync_capabilities",
+    {
+      description: "Commit and push all capability changes to the configured git remote",
+      inputSchema: {},
+    },
+    async () => {
+      try {
+        const result = await syncCapabilities(capabilitiesDir, getConfigValue("gitRemote"));
+        return mcpSuccess(result.message);
+      } catch (err) {
+        return mcpError(err);
+      }
+    }
+  );
+
+  return server;
+}
+
+export async function startStdioServer(capabilitiesDir: string): Promise<void> {
+  const server = createMcpServer(capabilitiesDir);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+export const CapabilityTypeSchema = z.enum(["skill", "agent", "instruction"]);
+export type CapabilityType = z.infer<typeof CapabilityTypeSchema>;
+
+export const ConfigSchema = z.object({
+  capabilitiesDir: z.string(),
+  editor: z.string().optional(),
+  gitRemote: z.string().optional(),
+});
+export type Config = z.infer<typeof ConfigSchema>;
+
+export interface Capability {
+  name: string;
+  type: CapabilityType;
+  path: string;
+  content: string;
+}
+
+export interface SyncResult {
+  committed: boolean;
+  pushed: boolean;
+  message: string;
+}
+
+export type Extension = `.${string}`;
+
+export const CAPABILITY_TYPES: CapabilityType[] = ["skill", "agent", "instruction"];
+
+export const CAPABILITY_EXTENSIONS: { [K in CapabilityType]: Extension } = {
+  skill: ".md",
+  agent: ".md",
+  instruction: ".md",
+};
+
+export const CAPABILITY_DIRS: { [K in CapabilityType]: string } = {
+  skill: "skills",
+  agent: "agents",
+  instruction: "instructions",
+};

package/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts"]
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*", "vitest.config.ts"]
+}