@leantli/agent-handoff 0.5.3 → 0.6.0

package/README.md

@@ -66,7 +66,7 @@ For project-specific decisions or branch-specific context:
 
 ```bash
 agent-handoff learn --scope project --kind decision --note "Use TypeScript for the CLI."
-agent-handoff learn --scope branch --kind context --note "This branch is testing v0.5."
+agent-handoff learn --scope branch --kind context --note "This branch is testing the sync workflow."
 ```
 
 ## Cross-Device Sync
@@ -74,27 +74,17 @@ 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. 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:
+Cross-device sync is optional. Create a dedicated private repository for the
+vault. Do not use a project code repository as the vault. Then run:
 
 ```bash
 agent-handoff sync init git@github.com:you/agent-handoff-vault.git
 agent-handoff sync
 ```
 
+Use a private repository because the vault can contain project background,
+preferences, decisions, and handoff notes.
+
 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.
@@ -102,6 +92,10 @@ 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.
+If `sync init` says the local vault has unsynced memory and the remote already
+has data, back up or manually merge the local vault before joining that remote.
+If git reports a conflict or active operation, resolve the conflict in the vault,
+finish or abort the active git operation, then run `agent-handoff sync` again.
 
 ## How Projects Are Identified
 
@@ -167,7 +161,6 @@ 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, createGitHubSyncRepo, enableHandoff, enableSync, getStatus, learn, syncVault, writeCheckpoint, } from "./core.js";
+import { HandoffError, buildStartPacket, 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.3")
+        .version(`agent-handoff ${packageVersion()}`)
         .exitOverride()
         .configureOutput({
         writeOut: (str) => stdout.write(str),
@@ -92,26 +92,9 @@ 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.")
+        .description("Enable cross-device sync with a dedicated private vault repository.")
         .option("--vault <path>", "Vault directory. Defaults to HOME/vault.")
         .action((gitUrl, options) => {
         const result = enableSync({ home: globalHome(program), vault: options.vault, syncUrl: gitUrl });
@@ -158,6 +141,13 @@ function readNote(options, stdin) {
     }
     return readFileSync(0, "utf8");
 }
+function packageVersion() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (typeof pkg.version !== "string") {
+        throw new HandoffError("package.json is missing a string version");
+    }
+    return pkg.version;
+}
 function printProblems(problems, stdout) {
     for (const problem of problems) {
         stdout.write(`- ${problem}\n`);

package/dist/core.d.ts

@@ -16,13 +16,6 @@ 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;
@@ -46,7 +39,6 @@ export interface Status {
     syncConfigured: boolean;
     syncUrl?: string;
 }
-type GitHubRemoteProtocol = "https" | "ssh";
 export declare function setupHome(opts?: {
     home?: string;
     vault?: string;
@@ -66,12 +58,6 @@ 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

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { hostname, homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 export const DEFAULT_HOME = join(homedir(), ".agent-handoff");
 export const CONFIG_FILE = "config.json";
@@ -130,39 +130,6 @@ 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)
@@ -282,6 +249,9 @@ export function syncVault(opts = {}) {
     if (syncProblem)
         throw new HandoffError(syncProblem);
     const outputs = [];
+    if (hasActiveGitOperation(setup.vault) || hasUnmergedFiles(setup.vault)) {
+        throw syncConflictError(setup.vault);
+    }
     gitChecked(setup.vault, ["add", "-A"]);
     const staged = gitRun(setup.vault, ["diff", "--cached", "--quiet"]).status !== 0;
     if (staged) {
@@ -299,6 +269,9 @@ export function syncVault(opts = {}) {
     const pull = gitRun(setup.vault, ["pull", "--rebase", "--autostash", "origin", branch]);
     const ignoredEmptyRemotePull = pull.status !== 0 && isEmptyRemotePull(pull.output);
     if (pull.status !== 0 && !ignoredEmptyRemotePull) {
+        if (hasActiveGitOperation(setup.vault) || hasUnmergedFiles(setup.vault)) {
+            throw syncConflictError(setup.vault, pull.output);
+        }
         throw new HandoffError(pull.output.trim() || "git pull failed");
     }
     if (!ignoredEmptyRemotePull && pull.output.trim())
@@ -482,55 +455,6 @@ 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)
@@ -789,26 +713,6 @@ 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,
@@ -823,6 +727,24 @@ function gitRun(root, args) {
         output: `${result.stdout ?? ""}${result.stderr ?? ""}${error}`,
     };
 }
+function hasUnmergedFiles(vault) {
+    const result = gitRun(vault, ["diff", "--name-only", "--diff-filter=U"]);
+    return result.status === 0 && result.output.trim().length > 0;
+}
+function hasActiveGitOperation(vault) {
+    return ["rebase-merge", "rebase-apply", "MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"].some((name) => gitPathExists(vault, name));
+}
+function gitPathExists(vault, name) {
+    const path = gitOutput(vault, ["rev-parse", "--git-path", name]);
+    if (!path)
+        return false;
+    return existsSync(isAbsolute(path) ? path : join(vault, path));
+}
+function syncConflictError(vault, detail) {
+    const message = `sync conflict in ${vault}; resolve conflicts in that vault, finish or abort the active git operation, then run agent-handoff sync again`;
+    const trimmed = detail?.trim();
+    return new HandoffError(trimmed ? `${message}\n\n${trimmed}` : message);
+}
 function isEmptyRemotePull(output) {
     const lowered = output.toLowerCase();
     return lowered.includes("couldn't find remote ref") || lowered.includes("could not find remote ref");

package/dist/index.d.ts

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

package/dist/index.js

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

package/package.json

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

package/resources/agent-handoff.SKILL.md

@@ -24,20 +24,12 @@ agent-handoff.
 
 ## Cross-Device Sync Setup
 
-Use a private vault repository for sync. The vault can contain project context,
-preferences, decisions, and handoff notes.
+Use a dedicated private vault repository for sync. Do not use a project code
+repository as the vault. 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:
+If the user asks you to set up cross-device sync, make sure the vault repository
+they created is private, then run:
 
 ```bash
 agent-handoff sync init <private-git-url>
@@ -47,6 +39,15 @@ 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`.
 
+If `sync init` says the local vault has unsynced memory and the remote already
+has data, keep the local files and report it. The user or agent should back up
+or manually merge the local vault before joining that remote.
+
+If sync fails because git reports a conflict or active operation, keep the local
+files and report the conflict. The user or agent should resolve it inside the
+vault, finish or abort the active git operation, then run `agent-handoff sync`
+again.
+
 ## During Work
 
 Use `learn` only for stable facts that should survive future sessions, clones,