@leantli/agent-handoff 0.5.2 → 0.5.3

package/README.md

@@ -74,8 +74,21 @@ agent-handoff learn --scope branch --kind context --note "This branch is testing
 Local cross-session memory works immediately after `agent-handoff enable`. No
 git repository is needed for the vault.
 
-Cross-device sync is optional. To share memory across devices, create a private
-git repository for the vault, then run:
+Cross-device sync is optional. The vault repository should be private because it
+can contain project background, preferences, decisions, and handoff notes.
+
+If GitHub CLI (`gh`) is installed and authenticated, let `agent-handoff` create
+the private repository:
+
+```bash
+agent-handoff sync create you/agent-handoff-vault
+agent-handoff sync
+```
+
+`sync create` always uses `gh repo create --private`. If the repository already
+exists and is public, `agent-handoff` refuses to use it.
+
+If you create the repository manually, make it private, then run:
 
 ```bash
 agent-handoff sync init git@github.com:you/agent-handoff-vault.git
@@ -86,6 +99,10 @@ Run `agent-handoff sync init <same-git-url>` once on each device that should
 share the vault. After that, run `agent-handoff sync` before starting on another
 device and after writing useful checkpoints.
 
+By default the vault lives at `~/.agent-handoff/vault`. Use `--home` or
+`--vault` when you need a different location. `agent-handoff sync` commits local
+vault changes, pulls/rebases remote vault changes, then pushes the result.
+
 ## How Projects Are Identified
 
 By default, `agent-handoff` identifies the current project from the git `origin`
@@ -150,6 +167,7 @@ agent-handoff enable      # create local memory and install the user skill
 agent-handoff start       # print context for the current project and branch
 agent-handoff checkpoint  # write a session checkpoint
 agent-handoff learn       # store durable global/project/branch memory
+agent-handoff sync create # create a private GitHub vault repo with gh
 agent-handoff sync init   # enable optional cross-device sync
 agent-handoff sync        # pull/rebase and push the vault
 agent-handoff status      # quick readiness and sync-state check

package/dist/cli.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { Command, CommanderError, Option } from "commander";
-import { HandoffError, buildStartPacket, enableHandoff, enableSync, getStatus, learn, syncVault, writeCheckpoint, } from "./core.js";
+import { HandoffError, buildStartPacket, createGitHubSyncRepo, enableHandoff, enableSync, getStatus, learn, syncVault, writeCheckpoint, } from "./core.js";
 export function main(argv = process.argv.slice(2), opts = {}) {
     const stdout = opts.stdout ?? process.stdout;
     const stderr = opts.stderr ?? process.stderr;
@@ -25,7 +25,7 @@ function buildProgram(stdout, stderr, stdin, cwd) {
     program
         .name("agent-handoff")
         .description("Shared vault handoff memory for coding agents.")
-        .version("agent-handoff 0.5.2")
+        .version("agent-handoff 0.5.3")
         .exitOverride()
         .configureOutput({
         writeOut: (str) => stdout.write(str),
@@ -92,6 +92,23 @@ function buildProgram(stdout, stderr, stdin, cwd) {
         stdout.write(`Learned ${result.kind}: ${result.path}\n`);
     });
     const sync = program.command("sync").description("Sync the handoff vault.");
+    sync
+        .command("create <repository>")
+        .description("Create a private GitHub repository with gh and enable cross-device sync.")
+        .option("--vault <path>", "Vault directory. Defaults to HOME/vault.")
+        .addOption(new Option("--protocol <protocol>", "Git remote protocol to store in config.").choices(["https", "ssh"]).default("https"))
+        .action((repository, options) => {
+        const result = createGitHubSyncRepo({
+            home: globalHome(program),
+            vault: options.vault,
+            repository,
+            protocol: options.protocol,
+        });
+        stdout.write(`${result.created ? "Created" : "Using existing"} private GitHub repository: ${result.repository}\n`);
+        stdout.write(`Cross-device sync enabled: ${result.syncUrl}\n`);
+        stdout.write(`Vault: ${result.setup.vault}\n`);
+        stdout.write("Run agent-handoff sync to push local memory.\n");
+    });
     sync
         .command("init <git-url>")
         .description("Enable cross-device sync with a private git repository.")

package/dist/core.d.ts

@@ -16,6 +16,13 @@ export interface EnableResult {
     setup: SetupResult;
     skill: InstallSkillResult;
 }
+export interface CreateGitHubSyncRepoResult {
+    repository: string;
+    created: boolean;
+    isPrivate: boolean;
+    syncUrl: string;
+    setup: SetupResult;
+}
 export interface CheckpointResult {
     path: string;
     projectId: string;
@@ -39,6 +46,7 @@ export interface Status {
     syncConfigured: boolean;
     syncUrl?: string;
 }
+type GitHubRemoteProtocol = "https" | "ssh";
 export declare function setupHome(opts?: {
     home?: string;
     vault?: string;
@@ -58,6 +66,12 @@ export declare function enableSync(opts: {
     vault?: string;
     syncUrl: string;
 }): SetupResult;
+export declare function createGitHubSyncRepo(opts: {
+    home?: string;
+    vault?: string;
+    repository: string;
+    protocol?: GitHubRemoteProtocol;
+}): CreateGitHubSyncRepoResult;
 export declare function deriveProjectId(root?: string, projectId?: string): string;
 export declare function currentBranch(root?: string): string;
 export declare function buildStartPacket(opts?: {

package/dist/core.js

@@ -130,6 +130,39 @@ export function enableHandoff(opts = {}) {
 export function enableSync(opts) {
     return setupHome({ home: opts.home, vault: opts.vault, syncUrl: opts.syncUrl });
 }
+export function createGitHubSyncRepo(opts) {
+    const repository = normalizeGitHubRepository(opts.repository);
+    const protocol = opts.protocol ?? "https";
+    let created = false;
+    let info = inspectGitHubRepo(repository);
+    if (!info) {
+        ghChecked([
+            "repo",
+            "create",
+            repository,
+            "--private",
+            "--description",
+            "Private vault for agent-handoff shared coding-agent context.",
+        ]);
+        created = true;
+        info = inspectGitHubRepo(repository);
+        if (!info) {
+            throw new HandoffError(`created GitHub repository ${repository} but could not inspect it with gh`);
+        }
+    }
+    if (!info.isPrivate) {
+        throw new HandoffError(`GitHub repository ${repository} is public; use a private repository for agent-handoff sync`);
+    }
+    const syncUrl = githubRepoSyncUrl(info, protocol);
+    const setup = enableSync({ home: opts.home, vault: opts.vault, syncUrl });
+    return {
+        repository: info.nameWithOwner ?? repository,
+        created,
+        isPrivate: info.isPrivate,
+        syncUrl,
+        setup,
+    };
+}
 export function deriveProjectId(root = ".", projectId) {
     const rootPath = resolve(root);
     if (projectId)
@@ -449,6 +482,55 @@ function syncConfigProblem(vault, syncUrl) {
     }
     return null;
 }
+function normalizeGitHubRepository(value) {
+    const repository = value.trim().replace(/\/+$/g, "").replace(/\.git$/i, "");
+    if (repository.includes("://") || repository.startsWith("git@")) {
+        throw new HandoffError("GitHub repository must be in owner/name form, for example leantli/agent-handoff-vault");
+    }
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) {
+        throw new HandoffError("GitHub repository must be in owner/name form, for example leantli/agent-handoff-vault");
+    }
+    return repository;
+}
+function inspectGitHubRepo(repository) {
+    const result = ghRun(["repo", "view", repository, "--json", "nameWithOwner,isPrivate,url,sshUrl"]);
+    if (result.status !== 0) {
+        if (/could not resolve|not found|repository not found/i.test(result.output))
+            return null;
+        throw new HandoffError(result.output.trim() || `cannot inspect GitHub repository ${repository} with gh`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(result.output);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new HandoffError(`gh repo view returned invalid JSON: ${detail}`);
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new HandoffError("gh repo view returned invalid repository data");
+    }
+    const data = raw;
+    if (typeof data.isPrivate !== "boolean") {
+        throw new HandoffError("gh repo view returned invalid repository privacy data");
+    }
+    return {
+        nameWithOwner: typeof data.nameWithOwner === "string" ? data.nameWithOwner : undefined,
+        isPrivate: data.isPrivate,
+        url: typeof data.url === "string" ? data.url : undefined,
+        sshUrl: typeof data.sshUrl === "string" ? data.sshUrl : undefined,
+    };
+}
+function githubRepoSyncUrl(info, protocol) {
+    const raw = protocol === "ssh" ? info.sshUrl : info.url;
+    if (!raw) {
+        throw new HandoffError(`GitHub repository is missing a ${protocol} clone URL`);
+    }
+    if (raw.startsWith("https://github.com/") && !raw.endsWith(".git")) {
+        return `${raw}.git`;
+    }
+    return raw;
+}
 function loadSetup(home) {
     const config = readConfig(home);
     if (!config)
@@ -707,6 +789,26 @@ function gitChecked(root, args) {
     }
     return result.output.trim();
 }
+function ghChecked(args) {
+    const result = ghRun(args);
+    if (result.status !== 0) {
+        throw new HandoffError(result.output.trim() || `gh ${args.join(" ")} failed`);
+    }
+    return result.output.trim();
+}
+function ghRun(args) {
+    const result = spawnSync("gh", args, {
+        encoding: "utf8",
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: GIT_TIMEOUT_MS,
+    });
+    const error = result.error ? `\n${result.error.message}` : "";
+    return {
+        status: result.status ?? 1,
+        output: `${result.stdout ?? ""}${result.stderr ?? ""}${error}`,
+    };
+}
 function gitRun(root, args) {
     const result = spawnSync("git", args, {
         cwd: root,

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { HandoffError, buildStartPacket, enableHandoff, enableSync, getStatus, learn, normalizeProjectId, syncVault, writeCheckpoint, } from "./core.js";
-export type { CheckpointResult, EnableResult, LearnResult, Status, } from "./core.js";
+export { HandoffError, buildStartPacket, createGitHubSyncRepo, enableHandoff, enableSync, getStatus, learn, normalizeProjectId, syncVault, writeCheckpoint, } from "./core.js";
+export type { CheckpointResult, CreateGitHubSyncRepoResult, EnableResult, LearnResult, Status, } from "./core.js";

package/dist/index.js

@@ -1 +1 @@
-export { HandoffError, buildStartPacket, enableHandoff, enableSync, getStatus, learn, normalizeProjectId, syncVault, writeCheckpoint, } from "./core.js";
+export { HandoffError, buildStartPacket, createGitHubSyncRepo, enableHandoff, enableSync, getStatus, learn, normalizeProjectId, syncVault, writeCheckpoint, } from "./core.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leantli/agent-handoff",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Shared vault handoff memory for coding agents.",
   "type": "module",
   "license": "MIT",

package/resources/agent-handoff.SKILL.md

@@ -22,6 +22,31 @@ When beginning work in a repository:
 Do not edit `AGENTS.md`, `CLAUDE.md`, or other instruction files to install
 agent-handoff.
 
+## Cross-Device Sync Setup
+
+Use a private vault repository for sync. The vault can contain project context,
+preferences, decisions, and handoff notes.
+
+If the user asks you to create the GitHub sync repository, run:
+
+```bash
+agent-handoff sync create <owner>/<repo>
+agent-handoff sync
+```
+
+`sync create` uses GitHub CLI (`gh`) and creates the repository as private. If an
+existing repository is public, do not use it for sync.
+
+If the user already has a private git repository for the vault, run:
+
+```bash
+agent-handoff sync init <private-git-url>
+agent-handoff sync
+```
+
+On another device, install and enable the CLI, then run `sync init` with the same
+private git URL, `agent-handoff sync`, and `agent-handoff start`.
+
 ## During Work
 
 Use `learn` only for stable facts that should survive future sessions, clones,