@jaybeeuu/agent-uplink 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,129 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  install-and-build:
+    name: Install & Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Cache node_modules
+        uses: actions/cache/save@v4
+        with:
+          path: node_modules
+          key: node_modules-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: Build
+        run: pnpm build
+
+      - name: Cache build artifacts
+        uses: actions/cache/save@v4
+        with:
+          path: dist/
+          key: dist-${{ runner.os }}-${{ github.sha }}
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    needs: install-and-build
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Restore node_modules
+        uses: actions/cache/restore@v4
+        with:
+          path: node_modules
+          key: node_modules-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: Lint
+        run: pnpm lint
+
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    needs: install-and-build
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Restore node_modules
+        uses: actions/cache/restore@v4
+        with:
+          path: node_modules
+          key: node_modules-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: Restore build artifacts
+        uses: actions/cache/restore@v4
+        with:
+          path: dist/
+          key: dist-${{ runner.os }}-${{ github.sha }}
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: install-and-build
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Restore node_modules
+        uses: actions/cache/restore@v4
+        with:
+          path: node_modules
+          key: node_modules-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+
+      - name: Restore build artifacts
+        uses: actions/cache/restore@v4
+        with:
+          path: dist/
+          key: dist-${{ runner.os }}-${{ github.sha }}
+
+      - name: Test
+        run: pnpm test

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Bickley-Wallace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# agent-uplink
+
+A CLI and MCP server for managing AI capabilities — skills, agents, and instructions — for use with GitHub Copilot and other AI tooling.
+
+Uses standard file structures (`.agents/`) rather than tool-specific directories, and supports MCP (Model Context Protocol) so AI agents can manage capabilities directly.
+
+## Installation
+
+```sh
+pnpm add -g @jaybeeuu/agent-uplink
+```
+
+## Quick start
+
+```sh
+# Create a skill
+uplink skill create my-skill
+
+# Edit an existing instruction
+uplink instruction edit coding-style
+
+# List all agents
+uplink agent list
+
+# Sync changes to git remote
+uplink sync
+
+# Install VS Code integration (user-level settings.json + mcp.json)
+uplink install vscode
+```
+
+## Commands
+
+### Resource management
+
+Each resource type (`skill`, `agent`, `instruction`) supports the same subcommands:
+
+| Command | Description |
+|---------|-------------|
+| `uplink <type> create <name>` | Create a new resource and open it in your editor |
+| `uplink <type> edit <name>` | Open an existing resource in your editor |
+| `uplink <type> list` | List all resources of this type |
+| `uplink <type> show <name>` | Print the content of a resource |
+| `uplink <type> delete <name>` | Delete a resource (prompts for confirmation) |
+
+### Sync
+
+```sh
+uplink sync            # Commit and push all changes
+uplink sync --dry-run  # Show what would be synced
+```
+
+Commits all changes in the capabilities directory with a descriptive message and pushes to the configured remote.
+
+### Configuration
+
+```sh
+uplink config list                        # Show all settings
+uplink config get capabilitiesDir         # Get a specific setting
+uplink config set capabilitiesDir ~/caps  # Set the capabilities directory
+uplink config set editor "code --wait"    # Set your preferred editor
+uplink config set gitRemote upstream      # Set git remote name
+uplink config edit                        # Open config file in your editor
+```
+
+Configuration is stored at `~/.agent-uplink/config.json`.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `capabilitiesDir` | `~/.agent-uplink/capabilities` | Directory where capability files are stored |
+| `editor` | `$VISUAL` / `$EDITOR` / `vi` | Editor command to use |
+| `gitRemote` | `origin` | Git remote to push to |
+
+### Install / Uninstall integrations
+
+```sh
+uplink install vscode    # Configure user-level VS Code / GitHub Copilot
+uplink uninstall vscode  # Remove the VS Code integration
+```
+
+**VS Code** (`uplink install vscode`): Updates `~/.config/Code/User/settings.json` (Linux) with:
+- `chat.agentSkillsLocations` — points at your `skills/` directory
+- `chat.instructionsFilesLocations` — points at your `instructions/` directory
+- `chat.agentFilesLocations` — points at your `agents/` directory
+
+Also writes `~/.config/Code/User/mcp.json` to register the uplink MCP server so GitHub Copilot can use it without any further setup.
+
+### MCP server
+
+```sh
+uplink mcp start           # Start the MCP server (stdio mode)
+```
+
+The MCP server exposes the following tools to AI agents:
+
+| Tool | Description |
+|------|-------------|
+| `list_capabilities` | List capabilities of a given type |
+| `get_capability` | Read the content of a capability |
+| `create_capability` | Create a new capability |
+| `update_capability` | Update an existing capability |
+| `delete_capability` | Delete a capability |
+| `sync_capabilities` | Commit and push all changes |
+
+After `uplink install vscode`, the MCP server is automatically configured at user level so GitHub Copilot can use it without any further setup.
+
+## Capabilities directory structure
+
+```
+<capabilitiesDir>/
+├── skills/
+│   └── <name>.md
+├── agents/
+│   └── <name>.md
+└── instructions/
+    └── <name>.md
+```
+
+The capabilities directory can be a git repository, enabling `uplink sync` to commit and push changes across machines.
+
+## Debug logging
+
+Set the `DEBUG` environment variable to enable verbose output:
+
+```sh
+DEBUG=agent-uplink:*        # Enable all modules
+DEBUG=agent-uplink:config   # Enable config module only
+DEBUG=agent-uplink:install  # Enable install module only
+```
+
+## Development
+
+```sh
+pnpm install        # Install dependencies
+pnpm build          # Compile TypeScript
+pnpm test           # Run tests
+pnpm dev -- <args>  # Run CLI without building (uses tsx)
+```

package/eslint.config.js

@@ -0,0 +1,15 @@
+// @ts-check
+import { base } from "@jaybeeuu/eslint-config/base";
+import globals from "globals";
+
+export default [
+  { ignores: ["dist/**", "node_modules/**"] },
+  ...base,
+  {
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+];

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@jaybeeuu/agent-uplink",
+  "version": "1.0.0",
+  "description": "CLI and MCP for managing skills, agents & instructions for AI tooling",
+  "type": "module",
+  "bin": {
+    "uplink": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "copilot",
+    "agents",
+    "skills",
+    "mcp"
+  ],
+  "author": {
+    "name": "Josh Bickley-Wallace",
+    "url": "https://jaybeeuu.dev"
+  },
+  "license": "MIT",
+  "packageManager": "pnpm@10.32.1",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "debug": "^4.4.3",
+    "enquirer": "^2.4.1",
+    "open": "^10.2.0",
+    "simple-git": "^3.33.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@jaybeeuu/eslint-config": "^5.0.0",
+    "@types/debug": "^4.1.13",
+    "@types/node": "^25.5.0",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/src/capabilities.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, rmSync, existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import {
+  createCapability,
+  readCapability,
+  updateCapability,
+  deleteCapability,
+  listCapabilities,
+  capabilityExists,
+  getCapabilityPath,
+} from "./capabilities.js";
+
+const TMP = join(tmpdir(), `uplink-capabilities-test-${String(process.pid)}`);
+
+beforeEach(() => {
+  mkdirSync(TMP, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TMP, { recursive: true, force: true });
+});
+
+describe("createCapability", () => {
+  it("creates a skill file with a default template", () => {
+    const cap = createCapability(TMP, "skill", "my-skill");
+    expect(cap.name).toBe("my-skill");
+    expect(cap.type).toBe("skill");
+    expect(existsSync(cap.path)).toBe(true);
+    expect(cap.content).toContain("name: my-skill");
+    expect(cap.content).toContain("description: Describe this skill here.");
+    expect(cap.content).toContain("---");
+    expect(cap.content).toContain("# my-skill");
+  });
+
+  it("creates a capability with custom content", () => {
+    const cap = createCapability(TMP, "skill", "custom", "custom content");
+    expect(readFileSync(cap.path, "utf-8")).toBe("custom content");
+  });
+
+  it("creates an agent file with the correct extension", () => {
+    const cap = createCapability(TMP, "agent", "my-agent");
+    expect(cap.path).toMatch(/\.md$/);
+    expect(cap.content).toContain("name: my-agent");
+  });
+
+  it("throws if a capability already exists", () => {
+    createCapability(TMP, "skill", "dup");
+    expect(() => createCapability(TMP, "skill", "dup")).toThrow(
+      /already exists/
+    );
+  });
+});
+
+describe("readCapability", () => {
+  it("reads an existing capability", () => {
+    createCapability(TMP, "skill", "readable", "hello world");
+    const cap = readCapability(TMP, "skill", "readable");
+    expect(cap.content).toBe("hello world");
+    expect(cap.name).toBe("readable");
+  });
+
+  it("throws if capability does not exist", () => {
+    expect(() => readCapability(TMP, "skill", "missing")).toThrow(/not found/);
+  });
+});
+
+describe("updateCapability", () => {
+  it("updates the content of an existing capability", () => {
+    createCapability(TMP, "instruction", "my-inst", "old content");
+    const cap = updateCapability(TMP, "instruction", "my-inst", "new content");
+    expect(cap.content).toBe("new content");
+    expect(readFileSync(cap.path, "utf-8")).toBe("new content");
+  });
+
+  it("throws if capability does not exist", () => {
+    expect(() =>
+      updateCapability(TMP, "skill", "missing", "content")
+    ).toThrow(/not found/);
+  });
+});
+
+describe("deleteCapability", () => {
+  it("deletes an existing capability", () => {
+    const cap = createCapability(TMP, "skill", "deletable", "bye");
+    deleteCapability(TMP, "skill", "deletable");
+    expect(existsSync(cap.path)).toBe(false);
+  });
+
+  it("throws if capability does not exist", () => {
+    expect(() => {
+      deleteCapability(TMP, "skill", "missing");
+    }).toThrow(/not found/);
+  });
+});
+
+describe("listCapabilities", () => {
+  it("returns empty array when no capabilities exist", () => {
+    expect(listCapabilities(TMP, "skill")).toEqual([]);
+  });
+
+  it("lists capabilities sorted alphabetically", () => {
+    createCapability(TMP, "skill", "zebra", "z");
+    createCapability(TMP, "skill", "alpha", "a");
+    createCapability(TMP, "skill", "beta", "b");
+    expect(listCapabilities(TMP, "skill")).toEqual(["alpha", "beta", "zebra"]);
+  });
+
+  it("only lists capabilities of the correct type", () => {
+    createCapability(TMP, "skill", "a-skill", "");
+    createCapability(TMP, "agent", "an-agent", "");
+    expect(listCapabilities(TMP, "skill")).toEqual(["a-skill"]);
+    expect(listCapabilities(TMP, "agent")).toEqual(["an-agent"]);
+  });
+});
+
+describe("capabilityExists", () => {
+  it("returns true for an existing capability", () => {
+    createCapability(TMP, "skill", "exists", "");
+    expect(capabilityExists(TMP, "skill", "exists")).toBe(true);
+  });
+
+  it("returns false for a non-existent capability", () => {
+    expect(capabilityExists(TMP, "skill", "nope")).toBe(false);
+  });
+});
+
+describe("getCapabilityPath", () => {
+  it("returns the correct path for a skill", () => {
+    const path = getCapabilityPath(TMP, "skill", "my-skill");
+    expect(path).toBe(join(TMP, "skills", "my-skill.md"));
+  });
+
+  it("returns the correct path for an agent", () => {
+    const path = getCapabilityPath(TMP, "agent", "my-agent");
+    expect(path).toBe(join(TMP, "agents", "my-agent.md"));
+  });
+});

package/src/capabilities.ts

@@ -0,0 +1,141 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+} from "fs";
+import { join, extname, basename } from "path";
+import {
+  CAPABILITY_DIRS,
+  CAPABILITY_EXTENSIONS,
+  type Capability,
+  type CapabilityType,
+} from "./types.js";
+
+const SKILL_TEMPLATE = (name: string): string =>
+  `---\nname: ${name}\ndescription: Describe this skill here.\n---\n\n# ${name}\n\n## Steps\n\n1. Step one\n`;
+
+const AGENT_TEMPLATE = (name: string): string =>
+  `---\nname: ${name}\ndescription: Describe this agent here.\ntools: []\n---\n\n# ${name}\n\nAgent instructions go here.\n`;
+
+const INSTRUCTION_TEMPLATE = (name: string): string =>
+  `# ${name}\n\nInstruction content goes here.\n`;
+
+const TEMPLATES = {
+  skill: SKILL_TEMPLATE,
+  agent: AGENT_TEMPLATE,
+  instruction: INSTRUCTION_TEMPLATE,
+};
+
+export function getCapabilityDir(capabilitiesDir: string, type: CapabilityType): string {
+  return join(capabilitiesDir, CAPABILITY_DIRS[type]);
+}
+
+export function getCapabilityPath(
+  capabilitiesDir: string,
+  type: CapabilityType,
+  name: string
+): string {
+  const dir = getCapabilityDir(capabilitiesDir, type);
+  return join(dir, name + CAPABILITY_EXTENSIONS[type]);
+}
+
+export function ensureCapabilitiesDir(capabilitiesDir: string): void {
+  for (const dir of Object.values(CAPABILITY_DIRS)) {
+    const fullPath = join(capabilitiesDir, dir);
+    if (!existsSync(fullPath)) {
+      mkdirSync(fullPath, { recursive: true });
+    }
+  }
+}
+
+export function createCapability(
+  capabilitiesDir: string,
+  type: CapabilityType,
+  name: string,
+  content?: string
+): Capability {
+  ensureCapabilitiesDir(capabilitiesDir);
+  const path = getCapabilityPath(capabilitiesDir, type, name);
+
+  if (existsSync(path)) {
+    throw new Error(`${type} '${name}' already exists at ${path}`);
+  }
+
+  const fileContent = content ?? TEMPLATES[type](name);
+  writeFileSync(path, fileContent, "utf-8");
+
+  return { name, type, path, content: fileContent };
+}
+
+export function readCapability(
+  capabilitiesDir: string,
+  type: CapabilityType,
+  name: string
+): Capability {
+  const path = getCapabilityPath(capabilitiesDir, type, name);
+
+  if (!existsSync(path)) {
+    throw new Error(`${type} '${name}' not found`);
+  }
+
+  const content = readFileSync(path, "utf-8");
+  return { name, type, path, content };
+}
+
+export function updateCapability(
+  capabilitiesDir: string,
+  type: CapabilityType,
+  name: string,
+  content: string
+): Capability {
+  const path = getCapabilityPath(capabilitiesDir, type, name);
+
+  if (!existsSync(path)) {
+    throw new Error(`${type} '${name}' not found`);
+  }
+
+  writeFileSync(path, content, "utf-8");
+  return { name, type, path, content };
+}
+
+export function deleteCapability(
+  capabilitiesDir: string,
+  type: CapabilityType,
+  name: string
+): void {
+  const path = getCapabilityPath(capabilitiesDir, type, name);
+
+  if (!existsSync(path)) {
+    throw new Error(`${type} '${name}' not found`);
+  }
+
+  unlinkSync(path);
+}
+
+export function listCapabilities(
+  capabilitiesDir: string,
+  type: CapabilityType
+): string[] {
+  const dir = getCapabilityDir(capabilitiesDir, type);
+
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  const ext = CAPABILITY_EXTENSIONS[type];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(ext))
+    .map((f) => basename(f, extname(f)))
+    .sort();
+}
+
+export function capabilityExists(
+  capabilitiesDir: string,
+  type: CapabilityType,
+  name: string
+): boolean {
+  return existsSync(getCapabilityPath(capabilitiesDir, type, name));
+}

package/src/cli.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { makeCapabilityCommand } from "./commands/capability.js";
+import { makeSyncCommand } from "./commands/sync.js";
+import { makeConfigCommand } from "./commands/config.js";
+import { makeInstallCommand, makeUninstallCommand } from "./commands/install.js";
+import { makeMcpCommand } from "./commands/mcp.js";
+import { rootLogger } from "./logger.js";
+
+const program = new Command();
+
+program
+  .name("uplink")
+  .description(
+    "CLI and MCP for managing AI capabilities: skills, agents, and instructions"
+  )
+  .version("1.0.0");
+
+// Resource management commands
+program.addCommand(makeCapabilityCommand("skill"));
+program.addCommand(makeCapabilityCommand("agent"));
+program.addCommand(makeCapabilityCommand("instruction"));
+
+// Utility commands
+program.addCommand(makeSyncCommand());
+program.addCommand(makeConfigCommand());
+program.addCommand(makeInstallCommand());
+program.addCommand(makeUninstallCommand());
+program.addCommand(makeMcpCommand());
+
+// Parse and execute
+program.parseAsync(process.argv).catch((err: unknown) => {
+  rootLogger.error(err);
+  process.exit(1);
+});