copilot-ship 1.0.0-beta.1

package/README.md

@@ -0,0 +1,68 @@
+# copilot-ship
+
+Ship GitHub Copilot plugin artifacts into canonical Copilot directories.
+
+## npm vs npx (quick explanation)
+
+- **npm** is the package manager used to install/publish packages.
+- **npx** runs a package's CLI command (usually from npm) without requiring a permanent global install.
+
+Before publishing, you can test this project fully from local source.
+
+## Build and test locally (no publish required)
+
+### 1. Install dependencies
+
+```bash
+npm ci
+```
+
+### 2. Build TypeScript
+
+```bash
+npm run build
+```
+
+### 3. Run local checks
+
+```bash
+npm test
+```
+
+### 4. Run the CLI directly from local build output
+
+```bash
+node dist/index.js --help
+```
+
+### 5. End-to-end install test against the plugin marketplace repo
+
+```bash
+# from this repo root
+node dist/index.js add https://github.com/github/copilot-plugins --plugin spark -y
+node dist/index.js list
+```
+
+Or using the global command (after `npm link`):
+
+```bash
+copilot-ship add https://github.com/github/copilot-plugins --plugin spark -y
+copilot-ship list
+```
+
+This ships artifacts into `./.github/` by default.
+
+## Optional: test as if globally installed
+
+If you want to invoke `copilot-ship` directly (without `node dist/index.js`):
+
+```bash
+npm link
+copilot-ship --help
+```
+
+When done:
+
+```bash
+npm unlink -g copilot-ship
+```

package/dist/constants.js

@@ -0,0 +1,13 @@
+import os from "node:os";
+import path from "node:path";
+export const MARKETPLACE_MANIFEST = path.join(".claude-plugin", "marketplace.json");
+export const PROJECT_INSTALL_ROOT = ".github";
+export const GLOBAL_INSTALL_ROOT = path.join(os.homedir(), ".copilot");
+export const DIRECTORY_TARGETS = {
+    agents: "agents",
+    hooks: "hooks",
+    instructions: "instructions",
+    prompts: "prompts",
+    skills: "skills",
+};
+export const COPILOT_INSTRUCTIONS_FILE = "copilot-instructions.md";

package/dist/index.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import { cancel, confirm, intro, isCancel, log, multiselect, outro, spinner, } from "@clack/prompts";
+import { installFromMarketplace, listInstalledArtifacts, } from "./installer.js";
+async function main() {
+    const parsedArgs = parseArgs(process.argv.slice(2));
+    if (parsedArgs.command === "help") {
+        printUsage();
+        return;
+    }
+    intro("copilot-ship");
+    try {
+        if (parsedArgs.command === "add") {
+            await runAdd(parsedArgs);
+        }
+        else {
+            await runList(parsedArgs.flags.scope);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log.error(message);
+        process.exitCode = 1;
+    }
+    finally {
+        outro("Done.");
+    }
+}
+async function runAdd(parsedArgs) {
+    if (!parsedArgs.source) {
+        throw new Error("The add command requires a source.");
+    }
+    const activity = spinner();
+    activity.start("Resolving source and preparing install plan");
+    let result;
+    try {
+        result = await installFromMarketplace(parsedArgs.source, parsedArgs.flags, async (plugins) => {
+            activity.stop("Marketplace loaded");
+            let selected = plugins;
+            if (parsedArgs.flags.pluginName) {
+                const plugin = plugins.find((candidate) => candidate.plugin.name === parsedArgs.flags.pluginName);
+                if (!plugin) {
+                    throw new Error(`Plugin "${parsedArgs.flags.pluginName}" was not found in the selected marketplace scope.`);
+                }
+                selected = [plugin];
+            }
+            else if (!parsedArgs.flags.installAll && plugins.length > 1) {
+                if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                    throw new Error("Interactive plugin selection requires a TTY. Use --plugin or --all instead.");
+                }
+                const selection = await multiselect({
+                    message: "Select plugins to install",
+                    options: plugins.map((candidate) => ({
+                        ...(candidate.plugin.description ? { hint: candidate.plugin.description } : {}),
+                        label: candidate.plugin.name,
+                        value: candidate.plugin.name,
+                    })),
+                    required: true,
+                });
+                if (isCancel(selection)) {
+                    cancel("Installation cancelled.");
+                    process.exit(0);
+                }
+                const selectedNames = new Set(Array.isArray(selection) ? selection : []);
+                selected = plugins.filter((candidate) => selectedNames.has(candidate.plugin.name));
+            }
+            if (!parsedArgs.flags.yes) {
+                const accepted = await confirm({
+                    message: `Install ${selected.length} plugin(s) into ${resultTargetDescription(parsedArgs.flags.scope)}?`,
+                });
+                if (isCancel(accepted) || !accepted) {
+                    cancel("Installation cancelled.");
+                    process.exit(0);
+                }
+            }
+            activity.start("Installing selected plugins");
+            return selected;
+        });
+    }
+    catch (error) {
+        activity.error("Install failed");
+        throw error;
+    }
+    activity.stop(`Installed ${result.installedPlugins.length} plugin(s) into ${result.targetRoot}`);
+    for (const warning of result.warnings) {
+        log.warn(warning);
+    }
+    for (const plan of result.installedPlugins) {
+        log.success(`${plan.plugin.name}`);
+        for (const entry of plan.entries) {
+            log.step(`  ${entry.targetRelativePath}`);
+        }
+    }
+}
+async function runList(scope) {
+    const result = await listInstalledArtifacts(scope);
+    if (result.groups.length === 0) {
+        log.info(`No Copilot artifacts installed in ${result.targetRoot}`);
+        return;
+    }
+    log.info(`Installed artifacts in ${result.targetRoot}`);
+    for (const group of result.groups) {
+        log.step(group.kind);
+        for (const entry of group.entries) {
+            log.step(`  ${entry}`);
+        }
+    }
+}
+function parseArgs(argv) {
+    const flags = {
+        installAll: false,
+        scope: "project",
+        yes: false,
+    };
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === undefined) {
+            continue;
+        }
+        switch (argument) {
+            case "add":
+            case "list":
+            case "help":
+                positionals.push(argument);
+                break;
+            case "-g":
+            case "--global":
+                flags.scope = "global";
+                break;
+            case "-y":
+            case "--yes":
+                flags.yes = true;
+                break;
+            case "--all":
+                flags.installAll = true;
+                break;
+            case "--plugin": {
+                const nextValue = argv[index + 1];
+                if (!nextValue) {
+                    throw new Error("Expected a value after --plugin.");
+                }
+                flags.pluginName = nextValue;
+                index += 1;
+                break;
+            }
+            case "-h":
+            case "--help":
+                return { command: "help", flags };
+            default:
+                positionals.push(argument);
+                break;
+        }
+    }
+    const command = positionals[0];
+    if (!command) {
+        return { command: "help", flags };
+    }
+    if (command !== "add" && command !== "list" && command !== "help") {
+        throw new Error(`Unknown command "${command}".`);
+    }
+    if (command === "list") {
+        return { command, flags };
+    }
+    if (command === "help") {
+        return { command, flags };
+    }
+    const source = positionals[1];
+    if (!source) {
+        throw new Error("Usage: copilot-ship add <source> [--plugin <name> | --all] [-g] [-y]");
+    }
+    return {
+        command,
+        flags,
+        source,
+    };
+}
+function printUsage() {
+    console.log(`copilot-ship
+
+Usage:
+  copilot-ship add <source> [--plugin <name> | --all] [-g] [-y]
+  copilot-ship list [-g]
+
+Sources:
+  owner/repo
+  https://github.com/owner/repo
+  https://github.com/owner/repo/tree/main/plugins/my-plugin
+  git@github.com:owner/repo.git
+  ./local-path
+`);
+}
+function resultTargetDescription(scope) {
+    return scope === "global" ? "~/.copilot" : ".github";
+}
+void main();

package/dist/installer.js

@@ -0,0 +1,374 @@
+import { execFile } from "node:child_process";
+import { access, copyFile, mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { COPILOT_INSTRUCTIONS_FILE, DIRECTORY_TARGETS, GLOBAL_INSTALL_ROOT, MARKETPLACE_MANIFEST, PROJECT_INSTALL_ROOT, } from "./constants.js";
+const execFileAsync = promisify(execFile);
+export async function resolveSource(source) {
+    const localPath = await tryResolveLocalPath(source);
+    if (localPath) {
+        return {
+            cleanup: undefined,
+            marketplaceRoot: await findMarketplaceRoot(localPath),
+            requestedPath: localPath,
+        };
+    }
+    const parsedGitHubSource = parseGitHubSource(source);
+    if (!parsedGitHubSource) {
+        throw new Error(`Unsupported source "${source}". Use a local path, owner/repo shorthand, a GitHub URL, or a git@github.com URL.`);
+    }
+    const tempRoot = await createTempDirectory();
+    const checkoutRoot = path.join(tempRoot, "source");
+    const cloneArgs = ["clone", "--quiet", "--depth", "1"];
+    if (parsedGitHubSource.branch) {
+        cloneArgs.push("--branch", parsedGitHubSource.branch, "--single-branch");
+    }
+    cloneArgs.push(parsedGitHubSource.cloneUrl, checkoutRoot);
+    try {
+        await execFileAsync("git", cloneArgs);
+    }
+    catch (error) {
+        await rm(tempRoot, { force: true, recursive: true });
+        throw wrapExecError(`Failed to clone ${parsedGitHubSource.cloneUrl}`, error);
+    }
+    const requestedPath = path.resolve(checkoutRoot, parsedGitHubSource.subpath ?? ".");
+    try {
+        await access(requestedPath);
+    }
+    catch {
+        await rm(tempRoot, { force: true, recursive: true });
+        throw new Error(`Resolved source path "${parsedGitHubSource.subpath ?? "."}" does not exist in ${parsedGitHubSource.cloneUrl}.`);
+    }
+    return {
+        cleanup: async () => rm(tempRoot, { force: true, recursive: true }),
+        marketplaceRoot: await findMarketplaceRoot(requestedPath),
+        requestedPath,
+    };
+}
+export async function installFromMarketplace(source, flags, selectPlugins) {
+    const resolvedSource = await resolveSource(source);
+    try {
+        const manifest = await readMarketplaceManifest(resolvedSource.marketplaceRoot);
+        const warnings = [];
+        const skippedPlugins = [];
+        const localCandidates = [];
+        for (const plugin of manifest.plugins) {
+            if (typeof plugin.source !== "string") {
+                skippedPlugins.push(plugin.name);
+                warnings.push(`Skipped plugin "${plugin.name}": external marketplace sources are deferred to MVP2.`);
+                continue;
+            }
+            const pluginRoot = path.resolve(resolvedSource.marketplaceRoot, plugin.source);
+            await assertDirectory(pluginRoot, `Plugin "${plugin.name}" points to missing directory "${plugin.source}".`);
+            localCandidates.push({ plugin, pluginRoot });
+        }
+        const scopedCandidates = narrowCandidatesByRequestedPath(localCandidates, resolvedSource.requestedPath);
+        const candidatePool = scopedCandidates.length > 0 ? scopedCandidates : localCandidates;
+        if (candidatePool.length === 0) {
+            throw new Error("No installable plugins were found in the marketplace.");
+        }
+        const selectedCandidates = await selectPlugins(candidatePool);
+        if (selectedCandidates.length === 0) {
+            throw new Error("No plugins were selected.");
+        }
+        const targetRoot = getInstallRoot(flags.scope);
+        const installPlans = await Promise.all(selectedCandidates.map(async (candidate) => ({
+            entries: await discoverArtifacts(candidate.pluginRoot, targetRoot),
+            plugin: candidate.plugin,
+            pluginRoot: candidate.pluginRoot,
+        })));
+        const installablePlans = installPlans.filter((plan) => {
+            if (plan.entries.length === 0) {
+                warnings.push(`Plugin "${plan.plugin.name}" has no supported Copilot artifacts.`);
+                return false;
+            }
+            return true;
+        });
+        if (installablePlans.length === 0) {
+            throw new Error("Nothing to install: the selected plugins do not contain supported Copilot artifacts.");
+        }
+        await ensureNoConflicts(installablePlans);
+        await copyInstallPlans(installablePlans);
+        return {
+            installedPlugins: installablePlans,
+            skippedPlugins,
+            sourceRoot: resolvedSource.marketplaceRoot,
+            targetRoot,
+            warnings,
+        };
+    }
+    finally {
+        await resolvedSource.cleanup?.();
+    }
+}
+export async function listInstalledArtifacts(scope) {
+    const targetRoot = getInstallRoot(scope);
+    const groups = [];
+    const instructionsPath = path.join(targetRoot, COPILOT_INSTRUCTIONS_FILE);
+    if (await pathExists(instructionsPath)) {
+        groups.push({
+            entries: [COPILOT_INSTRUCTIONS_FILE],
+            kind: "copilot-instructions",
+        });
+    }
+    for (const kind of Object.keys(DIRECTORY_TARGETS)) {
+        const root = path.join(targetRoot, DIRECTORY_TARGETS[kind]);
+        const entries = await collectRelativeFiles(root);
+        if (entries.length > 0) {
+            groups.push({ entries, kind });
+        }
+    }
+    return {
+        groups,
+        targetRoot,
+    };
+}
+function getInstallRoot(scope) {
+    return scope === "global" ? GLOBAL_INSTALL_ROOT : path.resolve(process.cwd(), PROJECT_INSTALL_ROOT);
+}
+async function readMarketplaceManifest(marketplaceRoot) {
+    const manifestPath = path.join(marketplaceRoot, MARKETPLACE_MANIFEST);
+    let raw;
+    try {
+        raw = await readFile(manifestPath, "utf8");
+    }
+    catch {
+        throw new Error(`MVP1 requires a marketplace manifest at "${manifestPath}".`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw wrapExecError(`Failed to parse marketplace manifest at "${manifestPath}"`, error);
+    }
+    if (!isMarketplaceManifest(parsed)) {
+        throw new Error(`Marketplace manifest at "${manifestPath}" is missing a valid "plugins" array.`);
+    }
+    return parsed;
+}
+async function findMarketplaceRoot(startingPath) {
+    let currentPath = path.resolve(startingPath);
+    const stats = await readdirOrNull(currentPath);
+    if (stats === null) {
+        currentPath = path.dirname(currentPath);
+    }
+    while (true) {
+        const candidate = path.join(currentPath, MARKETPLACE_MANIFEST);
+        if (await pathExists(candidate)) {
+            return currentPath;
+        }
+        const parent = path.dirname(currentPath);
+        if (parent === currentPath) {
+            break;
+        }
+        currentPath = parent;
+    }
+    throw new Error(`MVP1 requires a marketplace manifest. None was found from "${startingPath}" upward.`);
+}
+function narrowCandidatesByRequestedPath(candidates, requestedPath) {
+    const resolvedRequestedPath = path.resolve(requestedPath);
+    return candidates.filter((candidate) => {
+        const pluginRoot = path.resolve(candidate.pluginRoot);
+        return isSamePath(pluginRoot, resolvedRequestedPath) || isDescendantOf(resolvedRequestedPath, pluginRoot);
+    });
+}
+async function discoverArtifacts(pluginRoot, targetRoot) {
+    const entries = [];
+    const repoInstructions = path.join(pluginRoot, COPILOT_INSTRUCTIONS_FILE);
+    if (await pathExists(repoInstructions)) {
+        entries.push({
+            kind: "copilot-instructions",
+            sourcePath: repoInstructions,
+            targetPath: path.join(targetRoot, COPILOT_INSTRUCTIONS_FILE),
+            targetRelativePath: COPILOT_INSTRUCTIONS_FILE,
+        });
+    }
+    for (const kind of Object.keys(DIRECTORY_TARGETS)) {
+        const sourceRoot = path.join(pluginRoot, DIRECTORY_TARGETS[kind]);
+        if (!(await pathExists(sourceRoot))) {
+            continue;
+        }
+        const files = await walkFiles(sourceRoot);
+        for (const file of files) {
+            const relativePath = path.relative(sourceRoot, file);
+            entries.push({
+                kind,
+                sourcePath: file,
+                targetPath: path.join(targetRoot, DIRECTORY_TARGETS[kind], relativePath),
+                targetRelativePath: path.join(DIRECTORY_TARGETS[kind], relativePath),
+            });
+        }
+    }
+    return entries.sort((left, right) => left.targetRelativePath.localeCompare(right.targetRelativePath));
+}
+async function ensureNoConflicts(plans) {
+    const seenTargets = new Map();
+    const fileConflicts = [];
+    for (const plan of plans) {
+        for (const entry of plan.entries) {
+            const existingSource = seenTargets.get(entry.targetPath);
+            if (existingSource) {
+                throw new Error(`Install conflict: "${entry.targetRelativePath}" would be written by both "${existingSource}" and "${plan.plugin.name}".`);
+            }
+            seenTargets.set(entry.targetPath, plan.plugin.name);
+            if (await pathExists(entry.targetPath)) {
+                fileConflicts.push(entry.targetPath);
+            }
+        }
+    }
+    if (fileConflicts.length > 0) {
+        throw new Error(`Install conflict: target file already exists:\n${fileConflicts.map((conflict) => `- ${conflict}`).join("\n")}`);
+    }
+}
+async function copyInstallPlans(plans) {
+    for (const plan of plans) {
+        for (const entry of plan.entries) {
+            await mkdir(path.dirname(entry.targetPath), { recursive: true });
+            await copyFile(entry.sourcePath, entry.targetPath);
+        }
+    }
+}
+async function collectRelativeFiles(root) {
+    if (!(await pathExists(root))) {
+        return [];
+    }
+    const files = await walkFiles(root);
+    return files
+        .map((file) => path.relative(root, file))
+        .sort((left, right) => left.localeCompare(right));
+}
+async function walkFiles(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await walkFiles(fullPath)));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+async function assertDirectory(directoryPath, errorMessage) {
+    const children = await readdirOrNull(directoryPath);
+    if (children === null) {
+        throw new Error(errorMessage);
+    }
+}
+async function pathExists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readdirOrNull(targetPath) {
+    try {
+        return await readdir(targetPath);
+    }
+    catch {
+        return null;
+    }
+}
+async function tryResolveLocalPath(source) {
+    const expandedSource = source.startsWith("~/") ? path.join(os.homedir(), source.slice(2)) : source;
+    const shouldTreatAsPath = expandedSource.startsWith(".") || expandedSource.startsWith("/") || expandedSource.startsWith("~");
+    if (!shouldTreatAsPath) {
+        const candidate = path.resolve(expandedSource);
+        if (!(await pathExists(candidate))) {
+            return null;
+        }
+        return candidate;
+    }
+    const resolved = path.resolve(expandedSource);
+    return (await pathExists(resolved)) ? resolved : null;
+}
+function parseGitHubSource(source) {
+    const shorthandMatch = source.match(/^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/);
+    if (shorthandMatch) {
+        const owner = shorthandMatch[1];
+        const repo = shorthandMatch[2];
+        if (!owner || !repo) {
+            return null;
+        }
+        return { cloneUrl: `https://github.com/${owner}/${stripGitSuffix(repo)}.git` };
+    }
+    const sshMatch = source.match(/^git@github\.com:([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/);
+    if (sshMatch) {
+        return { cloneUrl: source };
+    }
+    let url;
+    try {
+        url = new URL(source);
+    }
+    catch {
+        return null;
+    }
+    if (url.hostname !== "github.com") {
+        return null;
+    }
+    const segments = url.pathname.split("/").filter(Boolean);
+    if (segments.length < 2) {
+        return null;
+    }
+    const owner = segments[0];
+    const repoSegment = segments[1];
+    if (!owner || !repoSegment) {
+        return null;
+    }
+    const repo = stripGitSuffix(repoSegment);
+    const cloneUrl = `https://github.com/${owner}/${repo}.git`;
+    if (segments[2] === "tree" && segments[3]) {
+        return {
+            branch: segments[3],
+            cloneUrl,
+            subpath: segments.slice(4).join("/"),
+        };
+    }
+    return { cloneUrl };
+}
+function stripGitSuffix(repo) {
+    return repo.endsWith(".git") ? repo.slice(0, -4) : repo;
+}
+function isMarketplaceManifest(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return Array.isArray(record.plugins) && record.plugins.every(isMarketplacePlugin);
+}
+function isMarketplacePlugin(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return typeof record.name === "string" && "source" in record;
+}
+function isSamePath(left, right) {
+    return path.resolve(left) === path.resolve(right);
+}
+function isDescendantOf(child, parent) {
+    const relative = path.relative(parent, child);
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+async function createTempDirectory() {
+    return mkdtemp(path.join(os.tmpdir(), "copilot-ship-"));
+}
+function wrapExecError(prefix, error) {
+    if (typeof error === "object" && error !== null && "stderr" in error) {
+        const stderr = String(error.stderr ?? "").trim();
+        if (stderr.length > 0) {
+            return new Error(`${prefix}: ${stderr}`);
+        }
+    }
+    if (error instanceof Error) {
+        return new Error(`${prefix}: ${error.message}`);
+    }
+    return new Error(prefix);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "copilot-ship",
+  "version": "1.0.0-beta.1",
+  "description": "Ship GitHub Copilot plugin artifacts into canonical Copilot directories.",
+  "type": "module",
+  "bin": {
+    "copilot-ship": "dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run typecheck"
+  },
+  "keywords": [
+    "copilot",
+    "github-copilot",
+    "cli",
+    "plugin"
+  ],
+  "author": "",
+  "license": "ISC",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.4.0"
+  },
+  "devDependencies": {
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/node": "^25.8.0",
+    "semantic-release": "^24.2.9",
+    "typescript": "^6.0.3"
+  }
+}