feat(cli): add managed GitHub ref installs

Co-Authored-By: Paperclip <noreply@paperclip.ing>

cli/src/__tests__/install-command.test.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { installCommand, resolveNpmInstallRequest } from "../commands/install.js";
+import { installCommand, installGitPayload, resolveGitHubRef, resolveGitInstallRequest, resolveNpmInstallRequest } from "../commands/install.js";
 import { uninstallCommand } from "../commands/uninstall.js";
 import {
   INSTALL_MANIFEST_VERSION,
@@ -51,6 +51,40 @@ describe("managed install commands", () => {
     expect(() => resolveNpmInstallRequest({ version: "latest" })).toThrow();
   });
 
+  it("resolves branch, tag, full SHA, and short SHA refs through GitHub", async () => {
+    const sha = "a".repeat(40);
+    const runCommand = vi.fn(async (_file: string, _args: string[]) => ({ stdout: JSON.stringify({ sha }), stderr: "" }));
+    for (const ref of ["master", "v1.2.3", sha, sha.slice(0, 12)]) {
+      await expect(resolveGitHubRef("paperclipai/paperclip", ref, runCommand)).resolves.toBe(sha);
+    }
+    expect(runCommand.mock.calls.map((call) => call[1].at(-1))).toEqual([
+      "https://api.github.com/repos/paperclipai/paperclip/commits/master",
+      "https://api.github.com/repos/paperclipai/paperclip/commits/v1.2.3",
+      `https://api.github.com/repos/paperclipai/paperclip/commits/${sha}`,
+      `https://api.github.com/repos/paperclipai/paperclip/commits/${sha.slice(0, 12)}`,
+    ]);
+  });
+
+  it("supports fork overrides and classifies SHA refs as pinned", () => {
+    expect(resolveGitInstallRequest({ ref: "feature/test", repo: "HenkDz/paperclip" })).toEqual({ repo: "HenkDz/paperclip", ref: "feature/test", pinned: false });
+    expect(resolveGitInstallRequest({ ref: "abcdef1" })).toEqual({ repo: "paperclipai/paperclip", ref: "abcdef1", pinned: true });
+    expect(() => resolveGitInstallRequest({ repo: "HenkDz/paperclip" })).toThrow("requires --ref");
+  });
+
+  it("reuses a SHA-keyed git payload without downloading or rebuilding", async () => {
+    const sha = "b".repeat(40);
+    const paths = resolveInstallStorePaths();
+    const payloadPath = payloadPathFor(paths, "git", sha.slice(0, 12));
+    const packageRoot = path.join(payloadPath, "node_modules", "paperclipai");
+    fs.mkdirSync(path.join(packageRoot, "dist"), { recursive: true });
+    fs.writeFileSync(path.join(packageRoot, "package.json"), JSON.stringify({ version: "0.3.1" }));
+    fs.writeFileSync(path.join(packageRoot, "dist", "index.js"), "#!/usr/bin/env node\n");
+    const runCommand = vi.fn(async (_file: string, _args: string[]) => ({ stdout: "0.3.1\n", stderr: "" }));
+    await expect(installGitPayload("paperclipai/paperclip", sha, runCommand, paths)).resolves.toEqual({ payloadPath, reused: true, version: "0.3.1" });
+    expect(runCommand).toHaveBeenCalledOnce();
+    expect(runCommand.mock.calls[0]?.[0]).toBe(process.execPath);
+  });
+
   it("installs through the shim, reports provenance, and uninstalls without deleting user data", async () => {
     const version = "2026.720.0";
     const runCommand = vi.fn(async (file: string, args: string[], _options?: unknown) => {

cli/src/__tests__/update-command.test.ts

@@ -53,6 +53,35 @@ describe("update command", () => {
     expect(() => resolveUpdateRequest(manifest, { latest: true, canary: true })).toThrow("only one");
   });
 
+  it("re-resolves a moving git branch and activates the new SHA payload", async () => {
+    const paths = resolveInstallStorePaths(); initializeInstallStore(paths);
+    const oldSha = "1".repeat(40); const newSha = "2".repeat(40);
+    const oldPayload = payloadPathFor(paths, "git", oldSha.slice(0, 12));
+    const executable = createPayload(oldPayload, "0.3.1");
+    fs.writeFileSync(path.join(oldPayload, "node_modules", "paperclipai", "package.json"), JSON.stringify({ version: "0.3.1" }));
+    const newPayload = payloadPathFor(paths, "git", newSha.slice(0, 12));
+    createPayload(newPayload, "0.3.1");
+    fs.writeFileSync(path.join(newPayload, "node_modules", "paperclipai", "package.json"), JSON.stringify({ version: "0.3.1" }));
+    flipCurrentAtomic(oldPayload, paths);
+    writeInstallManifestAtomic({ schemaVersion: 1, source: "git", version: "0.3.1", channel: "pinned", repo: "paperclipai/paperclip", ref: "master", sha: oldSha, payloadPath: oldPayload, installedAt: "2026-07-22T00:00:00.000Z", previous: [] }, paths);
+    const backup = vi.fn(async () => undefined);
+    const runCommand = vi.fn(async (file: string) => file === "curl" ? { stdout: JSON.stringify({ sha: newSha }), stderr: "" } : { stdout: "0.3.1\n", stderr: "" });
+    await updateCommand({}, { paths, executablePath: executable, runCommand, backup, now: () => new Date("2026-07-22T12:00:00Z") });
+    expect(backup).toHaveBeenCalledOnce();
+    expect(readInstallManifest(paths)?.sha).toBe(newSha);
+    expect(fs.realpathSync(paths.currentPath)).toBe(fs.realpathSync(newPayload));
+  });
+
+  it("reports SHA git installs as pinned without resolving again", async () => {
+    const paths = resolveInstallStorePaths(); initializeInstallStore(paths);
+    const sha = "3".repeat(40); const payload = payloadPathFor(paths, "git", sha.slice(0, 12)); const executable = createPayload(payload, "0.3.1");
+    flipCurrentAtomic(payload, paths);
+    writeInstallManifestAtomic({ schemaVersion: 1, source: "git", version: "0.3.1", channel: "pinned", repo: "paperclipai/paperclip", ref: sha.slice(0, 12), sha, payloadPath: payload, installedAt: "2026-07-22T00:00:00.000Z", previous: [] }, paths);
+    const runCommand = vi.fn(async () => ({ stdout: "", stderr: "" }));
+    await updateCommand({}, { paths, executablePath: executable, runCommand });
+    expect(runCommand).not.toHaveBeenCalled();
+  });
+
   it("requires explicit confirmation before downgrading", async () => {
     const paths = resolveInstallStorePaths(); initializeInstallStore(paths);
     const payload = payloadPathFor(paths, "npm", "2.0.0"); const entrypoint = createPayload(payload, "2.0.0"); flipCurrentAtomic(payload, paths);