@jaybeeuu/agent-uplink 1.0.0

package/src/commands/capability.ts

@@ -0,0 +1,98 @@
+import { readFileSync } from "fs";
+import { Command } from "commander";
+import {
+  createCapability,
+  listCapabilities,
+  deleteCapability,
+  getCapabilityPath,
+  capabilityExists,
+} from "../capabilities.js";
+import { getCapabilitiesDir, getConfigValue } from "../config.js";
+import { openInEditor } from "../editor.js";
+import { createLogger } from "../logger.js";
+import type { CapabilityType } from "../types.js";
+
+export function makeCapabilityCommand(type: CapabilityType): Command {
+  const log = createLogger(`capability:${type}`);
+
+  const cmd = new Command(type);
+  cmd.description(`Manage ${type}s`);
+
+  cmd
+    .command("create <name>")
+    .description(`Create a new ${type}`)
+    .action(async (name: string) => {
+      const capabilitiesDir = getCapabilitiesDir();
+      const capability = createCapability(capabilitiesDir, type, name);
+      log.success(`Created ${type} '${name}' at ${capability.path}`);
+      await openInEditor(capability.path, getConfigValue("editor"));
+    });
+
+  cmd
+    .command("edit <name>")
+    .description(`Edit an existing ${type}`)
+    .action(async (name: string) => {
+      const capabilitiesDir = getCapabilitiesDir();
+      if (!capabilityExists(capabilitiesDir, type, name)) {
+        throw new Error(`${type} '${name}' not found`);
+      }
+      const path = getCapabilityPath(capabilitiesDir, type, name);
+      await openInEditor(path, getConfigValue("editor"));
+      log.success(`Done editing ${type} '${name}'`);
+    });
+
+  cmd
+    .command("list")
+    .description(`List all ${type}s`)
+    .action(() => {
+      const capabilitiesDir = getCapabilitiesDir();
+      const items = listCapabilities(capabilitiesDir, type);
+      if (items.length === 0) {
+        log.warn(`No ${type}s found.`);
+      } else {
+        log.info(`${type}s (${items.length}):`);
+        for (const item of items) {
+          log.info(`  • ${item}`);
+        }
+      }
+    });
+
+  cmd
+    .command("delete <name>")
+    .description(`Delete a ${type}`)
+    .option("-f, --force", "Skip confirmation")
+    .action(async (name: string, opts: { force?: boolean }) => {
+      const capabilitiesDir = getCapabilitiesDir();
+      if (!opts.force) {
+        const { prompt } = await import("enquirer");
+        const response = await prompt<{ confirmed: boolean }>({
+          type: "confirm",
+          name: "confirmed",
+          message: `Delete ${type} '${name}'?`,
+          initial: false,
+        });
+        if (!response.confirmed) {
+          log.info("Aborted.");
+          return;
+        }
+      }
+      deleteCapability(capabilitiesDir, type, name);
+      log.success(`Deleted ${type} '${name}'`);
+    });
+
+  cmd
+    .command("show <name>")
+    .description(`Show the content of a ${type}`)
+    .action((name: string) => {
+      const capabilitiesDir = getCapabilitiesDir();
+      const path = getCapabilityPath(capabilitiesDir, type, name);
+      if (!capabilityExists(capabilitiesDir, type, name)) {
+        throw new Error(`${type} '${name}' not found`);
+      }
+      const content = readFileSync(path, "utf-8");
+      log.info(`--- ${type}: ${name} ---`);
+      log.info(content);
+    });
+
+  return cmd;
+}

package/src/commands/config.ts

@@ -0,0 +1,108 @@
+import { Command } from "commander";
+import {
+  getConfigValue,
+  setConfigValue,
+  getConfigEntries,
+  getConfigFilePath,
+  ensureConfigFile,
+  resetConfig,
+} from "../config.js";
+import { openInEditor } from "../editor.js";
+import { createLogger } from "../logger.js";
+import type { Config } from "../types.js";
+
+const log = createLogger("config-cmd");
+
+// Using a satisfies check to ensure this record covers every key of Config.
+// TypeScript will error if a key is added to Config but omitted here.
+const CONFIG_KEYS_RECORD = {
+  capabilitiesDir: "capabilitiesDir",
+  editor: "editor",
+  gitRemote: "gitRemote",
+} as const satisfies { [K in keyof Config]: K };
+
+const VALID_KEYS = Object.keys(CONFIG_KEYS_RECORD) as (keyof Config)[];
+
+function formatDefault(value: string | undefined): string {
+  return value !== undefined ? `(default: ${value})` : "(not set)";
+}
+
+export function makeConfigCommand(): Command {
+  const cmd = new Command("config");
+  cmd.description("Manage uplink configuration");
+
+  cmd
+    .command("get [key]")
+    .description("Get a configuration value (or all values if no key given)")
+    .action((key?: string) => {
+      if (!key) {
+        log.info("Current configuration:");
+        for (const { key: k, value, defaultValue } of getConfigEntries()) {
+          const display = value !== undefined ? value : formatDefault(defaultValue);
+          log.info(`  ${k}: ${display}`);
+        }
+        return;
+      }
+
+      if (!VALID_KEYS.includes(key as keyof Config)) {
+        log.error(`Unknown config key '${key}'. Valid keys: ${VALID_KEYS.join(", ")}`);
+        process.exit(1);
+      }
+
+      const entry = getConfigEntries().find((e) => e.key === key);
+      if (entry?.value === undefined) {
+        log.info(`${key}: ${formatDefault(entry?.defaultValue)}`);
+      } else {
+        log.info(`${key}: ${entry.value}`);
+      }
+    });
+
+  cmd
+    .command("set <key> <value>")
+    .description("Set a configuration value")
+    .action((key: string, value: string) => {
+      if (!VALID_KEYS.includes(key as keyof Config)) {
+        log.error(`Unknown config key '${key}'. Valid keys: ${VALID_KEYS.join(", ")}`);
+        process.exit(1);
+      }
+      setConfigValue(key as keyof Config, value as Config[keyof Config]);
+      log.success(`Set ${key} = ${value}`);
+    });
+
+  cmd
+    .command("list")
+    .description("List all configuration values")
+    .action(() => {
+      log.info("Configuration:");
+      for (const { key, value, defaultValue } of getConfigEntries()) {
+        const display = value !== undefined ? value : formatDefault(defaultValue);
+        log.info(`  ${key}: ${display}`);
+      }
+    });
+
+  cmd
+    .command("edit")
+    .description("Open the configuration file in your editor")
+    .action(async () => {
+      const configFile = getConfigFilePath();
+      // Ensure the config file exists before opening
+      ensureConfigFile();
+      try {
+        await openInEditor(configFile, getConfigValue("editor"));
+        log.success(`Done editing config`);
+      } catch (err) {
+        log.error(err);
+        process.exit(1);
+      }
+    });
+
+  cmd
+    .command("reset")
+    .description("Reset configuration to defaults")
+    .action(() => {
+      resetConfig();
+      log.success("Configuration reset to defaults");
+    });
+
+  return cmd;
+}

package/src/commands/install.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, rmSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  INTEGRATIONS,
+} from "./install.js";
+
+const TMP = join(tmpdir(), `uplink-install-test-${String(process.pid)}`);
+
+beforeEach(() => {
+  mkdirSync(TMP, { recursive: true });
+  process.env["HOME"] = TMP;
+});
+
+afterEach(() => {
+  rmSync(TMP, { recursive: true, force: true });
+  delete process.env["HOME"];
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the VS Code user dir for the current fake HOME, by replicating the
+ * same logic as getVSCodeUserDir() but using the overridden HOME.
+ */
+function vscodeUserDir(): string {
+  // On Linux the path is ~/.config/Code/User
+  // We override HOME so homedir() returns TMP, but getVSCodeUserDir() calls
+  // homedir() which is cached at module load. Use the direct path.
+  return join(TMP, ".config", "Code", "User");
+}
+
+function readJson(path: string): { [key: string]: unknown } {
+  return JSON.parse(readFileSync(path, "utf-8")) as { [key: string]: unknown };
+}
+
+// ---------------------------------------------------------------------------
+// vscode integration
+// ---------------------------------------------------------------------------
+
+describe("vscode install", () => {
+  it("creates settings.json and mcp.json in VS Code user dir", () => {
+    const capabilitiesDir = join(TMP, "capabilities");
+    const userDir = vscodeUserDir();
+    mkdirSync(userDir, { recursive: true });
+
+    const vscode = INTEGRATIONS["vscode"];
+    if (!vscode) throw new Error("vscode integration not defined");
+    vscode.install(capabilitiesDir);
+
+    const settings = readJson(join(userDir, "settings.json"));
+    expect(settings).toMatchObject({
+      "chat.agentSkillsLocations": { [join(capabilitiesDir, "skills")]: false },
+      "chat.instructionsFilesLocations": { [join(capabilitiesDir, "instructions")]: false },
+      "chat.agentFilesLocations": { [join(capabilitiesDir, "agents")]: false },
+    });
+
+    const mcp = readJson(join(userDir, "mcp.json"));
+    expect(mcp).toHaveProperty("servers.agent-uplink");
+  });
+
+  it("merges into an existing settings.json without overwriting other keys", () => {
+    const capabilitiesDir = join(TMP, "capabilities");
+    const userDir = vscodeUserDir();
+    mkdirSync(userDir, { recursive: true });
+
+    writeFileSync(
+      join(userDir, "settings.json"),
+      JSON.stringify({ "editor.fontSize": 14 }, null, 2),
+      "utf-8"
+    );
+
+    const vscode = INTEGRATIONS["vscode"];
+    if (!vscode) throw new Error("vscode integration not defined");
+    vscode.install(capabilitiesDir);
+
+    const settings = readJson(join(userDir, "settings.json"));
+    expect(settings).toMatchObject({
+      "editor.fontSize": 14,
+      "chat.agentSkillsLocations": { [join(capabilitiesDir, "skills")]: false },
+      "chat.instructionsFilesLocations": { [join(capabilitiesDir, "instructions")]: false },
+      "chat.agentFilesLocations": { [join(capabilitiesDir, "agents")]: false },
+    });
+  });
+
+  it("uninstall removes agent-uplink keys from settings.json and mcp.json", () => {
+    const capabilitiesDir = join(TMP, "capabilities");
+    const userDir = vscodeUserDir();
+    mkdirSync(userDir, { recursive: true });
+
+    const vscode = INTEGRATIONS["vscode"];
+    if (!vscode) throw new Error("vscode integration not defined");
+    vscode.install(capabilitiesDir);
+    vscode.uninstall();
+
+    const settings = readJson(join(userDir, "settings.json"));
+    expect(settings).not.toHaveProperty("chat.agentSkillsLocations");
+    expect(settings).not.toHaveProperty("chat.instructionsFilesLocations");
+    expect(settings).not.toHaveProperty("chat.agentFilesLocations");
+
+    const mcp = readJson(join(userDir, "mcp.json"));
+    expect(mcp).not.toHaveProperty("servers.agent-uplink");
+  });
+
+  it("uninstall only removes our entries, leaving others intact", () => {
+    const capabilitiesDir = join(TMP, "capabilities");
+    const userDir = vscodeUserDir();
+    mkdirSync(userDir, { recursive: true });
+
+    writeFileSync(
+      join(userDir, "settings.json"),
+      JSON.stringify({
+        "chat.agentSkillsLocations": { "/other/skills": false },
+        "chat.instructionsFilesLocations": { "/other/instructions": false },
+        "chat.agentFilesLocations": { "/other/agents": false },
+      }, null, 2),
+      "utf-8"
+    );
+
+    const vscode = INTEGRATIONS["vscode"];
+    if (!vscode) throw new Error("vscode integration not defined");
+    vscode.install(capabilitiesDir);
+
+    const settingsAfterInstall = readJson(join(userDir, "settings.json"));
+    expect(settingsAfterInstall).toMatchObject({
+      "chat.agentSkillsLocations": {
+        "/other/skills": false,
+        [join(capabilitiesDir, "skills")]: false,
+      },
+      "chat.instructionsFilesLocations": {
+        "/other/instructions": false,
+        [join(capabilitiesDir, "instructions")]: false,
+      },
+      "chat.agentFilesLocations": {
+        "/other/agents": false,
+        [join(capabilitiesDir, "agents")]: false,
+      },
+    });
+
+    vscode.uninstall();
+
+    const settingsAfterUninstall = readJson(join(userDir, "settings.json"));
+    expect(settingsAfterUninstall).toMatchObject({
+      "chat.agentSkillsLocations": { "/other/skills": false },
+      "chat.instructionsFilesLocations": { "/other/instructions": false },
+      "chat.agentFilesLocations": { "/other/agents": false },
+    });
+    expect(settingsAfterUninstall["chat.agentSkillsLocations"]).not.toHaveProperty(join(capabilitiesDir, "skills"));
+    expect(settingsAfterUninstall["chat.instructionsFilesLocations"]).not.toHaveProperty(join(capabilitiesDir, "instructions"));
+    expect(settingsAfterUninstall["chat.agentFilesLocations"]).not.toHaveProperty(join(capabilitiesDir, "agents"));
+  });
+});

package/src/commands/install.ts

@@ -0,0 +1,323 @@
+import { Command } from "commander";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+import { homedir, platform } from "os";
+import { z } from "zod";
+import { getCapabilitiesDir } from "../config.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("install");
+
+// ---------------------------------------------------------------------------
+// Zod schemas for parsing VS Code config files
+// ---------------------------------------------------------------------------
+
+const LocationsSchema = z.record(z.string(), z.boolean());
+const McpServerSchema = z.object({
+  env: z.object({ UPLINK_CAPABILITIES_DIR: z.string().optional() }).optional(),
+}).loose();
+const McpServersSchema = z.record(z.string(), McpServerSchema);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function deepMerge(
+  target: { [key: string]: unknown },
+  source: { [key: string]: unknown }
+): { [key: string]: unknown } {
+  const result = { ...target };
+  for (const [key, value] of Object.entries(source)) {
+    if (
+      value !== null &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      typeof result[key] === "object" &&
+      result[key] !== null &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = deepMerge(
+        result[key] as { [key: string]: unknown },
+        value as { [key: string]: unknown }
+      );
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function readJsonFile(path: string): { [key: string]: unknown } {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as { [key: string]: unknown };
+  } catch {
+    return {};
+  }
+}
+
+function writeJsonFile(path: string, data: unknown): void {
+  const dir = join(path, "..");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+
+/**
+ * Returns the path to the VS Code user-level configuration directory.
+ * Platform-specific: Linux uses ~/.config/Code/User, macOS uses
+ * ~/Library/Application Support/Code/User, Windows uses %APPDATA%/Code/User.
+ */
+export function getVSCodeUserDir(): string {
+  const home = homedir();
+  const p = platform();
+  if (p === "darwin") {
+    return join(home, "Library", "Application Support", "Code", "User");
+  }
+  if (p === "win32") {
+    return join(
+      process.env["APPDATA"] ?? join(home, "AppData", "Roaming"),
+      "Code",
+      "User"
+    );
+  }
+  return join(home, ".config", "Code", "User");
+}
+
+// ---------------------------------------------------------------------------
+// Integration definitions
+// ---------------------------------------------------------------------------
+
+export interface Integration {
+  name: string;
+  description: string;
+  install(capabilitiesDir: string): void;
+  uninstall(): void;
+}
+
+export const INTEGRATIONS: { [key: string]: Integration | undefined } = {
+  vscode: {
+    name: "VS Code",
+    description:
+      "Configure user-level VS Code settings and MCP server for GitHub Copilot",
+
+    install(capabilitiesDir: string) {
+      const userDir = getVSCodeUserDir();
+
+      // User settings.json
+      const settingsPath = join(userDir, "settings.json");
+      const settings = readJsonFile(settingsPath);
+
+      // Skills → chat.agentSkillsLocations
+      const skillsDir = join(capabilitiesDir, "skills");
+      const existingSkillsLocations = LocationsSchema.catch({}).parse(
+        settings["chat.agentSkillsLocations"]
+      );
+      settings["chat.agentSkillsLocations"] = {
+        ...existingSkillsLocations,
+        [skillsDir]: false,
+      };
+
+      // Instructions → chat.instructionsFilesLocations
+      const instructionsDir = join(capabilitiesDir, "instructions");
+      const existingInstructionsLocations = LocationsSchema.catch({}).parse(
+        settings["chat.instructionsFilesLocations"]
+      );
+      settings["chat.instructionsFilesLocations"] = {
+        ...existingInstructionsLocations,
+        [instructionsDir]: false,
+      };
+
+      // Agents → chat.agentFilesLocations
+      const agentsDir = join(capabilitiesDir, "agents");
+      const existingAgentLocations = LocationsSchema.catch({}).parse(
+        settings["chat.agentFilesLocations"]
+      );
+      settings["chat.agentFilesLocations"] = {
+        ...existingAgentLocations,
+        [agentsDir]: false,
+      };
+
+      writeJsonFile(settingsPath, settings);
+      log.dim(`Updated ${settingsPath}`);
+
+      // User mcp.json — register the uplink MCP server
+      const mcpPath = join(userDir, "mcp.json");
+      const mergedMcp = deepMerge(readJsonFile(mcpPath), {
+        servers: {
+          "agent-uplink": {
+            type: "stdio",
+            command: "uplink",
+            args: ["mcp", "start", "--stdio"],
+            env: { UPLINK_CAPABILITIES_DIR: capabilitiesDir },
+          },
+        },
+      });
+      writeJsonFile(mcpPath, mergedMcp);
+      log.dim(`Updated ${mcpPath}`);
+    },
+
+    uninstall() {
+      const userDir = getVSCodeUserDir();
+
+      // Determine capabilitiesDir from stored MCP config (fallback to current config)
+      const mcpPath = join(userDir, "mcp.json");
+      let capabilitiesDir: string;
+      if (existsSync(mcpPath)) {
+        const mcp = readJsonFile(mcpPath);
+        const servers = McpServersSchema.nullable().catch(null).parse(mcp["servers"]);
+        capabilitiesDir =
+          servers?.["agent-uplink"]?.env?.UPLINK_CAPABILITIES_DIR ?? getCapabilitiesDir();
+      } else {
+        capabilitiesDir = getCapabilitiesDir();
+      }
+
+      // Remove our skill/instruction entries from the instructions array in settings.json
+      const settingsPath = join(userDir, "settings.json");
+      if (existsSync(settingsPath)) {
+        const settings = readJsonFile(settingsPath);
+
+        // Remove our skills entry from chat.agentSkillsLocations
+        const skillsDir = join(capabilitiesDir, "skills");
+        const skillsLocations = LocationsSchema.nullable().catch(null).parse(
+          settings["chat.agentSkillsLocations"]
+        );
+        if (skillsLocations) {
+          const { [skillsDir]: _removedSkills, ...restSkills } = skillsLocations;
+          if (Object.keys(restSkills).length === 0) {
+            delete settings["chat.agentSkillsLocations"];
+          } else {
+            settings["chat.agentSkillsLocations"] = restSkills;
+          }
+        }
+
+        // Remove our instruction entry from chat.instructionsFilesLocations
+        const instructionsDir = join(capabilitiesDir, "instructions");
+        const instructionsLocations = LocationsSchema.nullable().catch(null).parse(
+          settings["chat.instructionsFilesLocations"]
+        );
+        if (instructionsLocations) {
+          const { [instructionsDir]: _removedInstructions, ...restInstructions } = instructionsLocations;
+          if (Object.keys(restInstructions).length === 0) {
+            delete settings["chat.instructionsFilesLocations"];
+          } else {
+            settings["chat.instructionsFilesLocations"] = restInstructions;
+          }
+        }
+
+        // Remove agents directory from chat.agentFilesLocations
+        const agentsDir = join(capabilitiesDir, "agents");
+        const agentLocations = LocationsSchema.nullable().catch(null).parse(
+          settings["chat.agentFilesLocations"]
+        );
+        if (agentLocations) {
+          const { [agentsDir]: _removedAgents, ...restAgents } = agentLocations;
+          if (Object.keys(restAgents).length === 0) {
+            delete settings["chat.agentFilesLocations"];
+          } else {
+            settings["chat.agentFilesLocations"] = restAgents;
+          }
+        }
+
+        writeJsonFile(settingsPath, settings);
+        log.dim(`Cleaned ${settingsPath}`);
+      }
+
+      // Remove agent-uplink server from mcp.json
+      if (existsSync(mcpPath)) {
+        const mcp = readJsonFile(mcpPath);
+        const servers = McpServersSchema.nullable().catch(null).parse(mcp["servers"]);
+        if (servers) {
+          const { "agent-uplink": _removed, ...rest } = servers;
+          if (Object.keys(rest).length === 0) {
+            delete mcp["servers"];
+          } else {
+            mcp["servers"] = rest;
+          }
+        }
+        writeJsonFile(mcpPath, mcp);
+        log.dim(`Cleaned ${mcpPath}`);
+      }
+    },
+  },
+};
+
+const INTEGRATION_NAMES = Object.keys(INTEGRATIONS).join(", ");
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+export function makeInstallCommand(): Command {
+  const cmd = new Command("install");
+  cmd
+    .description(
+      `Install a tool integration globally (${INTEGRATION_NAMES})`
+    )
+    .argument("<integration>", `Integration to install (${INTEGRATION_NAMES})`)
+    .action((integration: string) => {
+      const capabilitiesDir = getCapabilitiesDir();
+      const integrationDef = INTEGRATIONS[integration];
+
+      if (!integrationDef) {
+        log.error(
+          `Unknown integration '${integration}'. Available: ${INTEGRATION_NAMES}`
+        );
+        process.exit(1);
+      }
+
+      log.info(`Installing ${integrationDef.name} integration...`);
+      log.dim(`Capabilities directory: ${capabilitiesDir}`);
+
+      try {
+        integrationDef.install(capabilitiesDir);
+        log.success(
+          `${integrationDef.name} integration installed successfully.`
+        );
+      } catch (err) {
+        log.error(
+          `Installation failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+        process.exit(1);
+      }
+    });
+
+  return cmd;
+}
+
+export function makeUninstallCommand(): Command {
+  const cmd = new Command("uninstall");
+  cmd
+    .description(
+      `Uninstall a tool integration (${INTEGRATION_NAMES})`
+    )
+    .argument(
+      "<integration>",
+      `Integration to remove (${INTEGRATION_NAMES})`
+    )
+    .action((integration: string) => {
+      const integrationDef = INTEGRATIONS[integration];
+
+      if (!integrationDef) {
+        log.error(
+          `Unknown integration '${integration}'. Available: ${INTEGRATION_NAMES}`
+        );
+        process.exit(1);
+      }
+
+      log.info(`Uninstalling ${integrationDef.name} integration...`);
+
+      try {
+        integrationDef.uninstall();
+        log.success(
+          `${integrationDef.name} integration uninstalled successfully.`
+        );
+      } catch (err) {
+        log.error(
+          `Uninstall failed: ${err instanceof Error ? err.message : String(err)}`
+        );
+        process.exit(1);
+      }
+    });
+
+  return cmd;
+}