Skip to content

Commit e4bd60e

Browse files
fix(cli): set GIT_CLONE_PROTECTION_ACTIVE=0 for skills (GH heygen-com#316) (heygen-com#328)
## Summary Fixes heygen-com#316 — `hyperframes skills` (and `npx skills add heygen-com/hyperframes`) fails with: ``` ■ Failed to clone repository fatal: active \`post-checkout\` hook found during \`git clone\` └ Installation failed ``` ## Root cause Two layers stacked: 1. **Git 2.45+ refuses to execute hooks during `git clone` by default.** The opt-in is `GIT_CLONE_PROTECTION_ACTIVE=0` — the env-var name is intentionally explicit about the trade-off. 2. **Users who ran `git lfs install` globally have a post-checkout hook registered at `core.hooksPath`.** When the upstream `skills` CLI shells out to `git clone` to fetch a repo's `skills/` directory, git detects the user's LFS hook and aborts. The check fires for **any repo**, regardless of whether the cloned repo uses LFS itself — it's protection against the user's own hooks, not the repo's content. Users who have git-lfs installed (very common) hit this for every clone the `skills` CLI does. ## The fix `hyperframes skills` wraps `npx skills add`. The wrapper now sets `GIT_CLONE_PROTECTION_ACTIVE=0` on the spawned child's env via a single helper (`gitCloneFriendlyEnv`) with a docstring at the call site explaining exactly why. The rest of `process.env` is preserved — proxy settings, extra CA certs, locale, etc. stay untouched. ## What this fix doesn't do (deliberately) This is the **code-path-we-own** fix. The deeper root cause is that the upstream `skills` CLI (vercel-labs/skills) should set this env var when it shells out to `git clone`. That would fix the bug for every user invoking `skills` directly — not just those who route through our wrapper. An upstream issue should be opened separately; not landing it as part of this PR. ## Users who call `npx skills add` directly Documented in the new troubleshooting subsection: set the env var manually. ```bash GIT_CLONE_PROTECTION_ACTIVE=0 npx skills add heygen-com/hyperframes ``` ## Tests `packages/cli/src/commands/skills.test.ts` — 2 cases: - Every spawned child has `GIT_CLONE_PROTECTION_ACTIVE=0` - The rest of `process.env` is preserved (not a wiped env) Uses `vi.mock` on `node:child_process` because ESM doesn't allow live-module `vi.spyOn` on re-exported bindings. ## Docs `docs/packages/cli.mdx` — new **Troubleshooting** subsection under the `skills` command. Explains both the automatic fix (`hyperframes skills` users are already covered) and the manual workaround (`npx skills add …` users). ## Closes - heygen-com#316
1 parent 57b59cc commit e4bd60e

3 files changed

Lines changed: 77 additions & 0 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -630,6 +630,26 @@ This is suppressed in CI environments, non-TTY shells, and when `HYPERFRAMES_NO_
630630
| `--cursor` | Install to Cursor (`.cursor/skills/` in current project) |
631631

632632
Skills are fetched from GitHub and include composition authoring, GSAP animation patterns, registry block/component wiring, and other domain-specific knowledge. The `init` command also offers to install skills automatically after scaffolding a project.
633+
634+
#### Troubleshooting: `fatal: active post-checkout hook found during git clone`
635+
636+
If you installed Git LFS globally (`git lfs install`), Git 2.45+ refuses to run the LFS post-checkout hook during any `git clone` — including the clone the upstream `skills` CLI performs under the hood. The error looks like:
637+
638+
```
639+
■ Failed to clone repository
640+
fatal: active `post-checkout` hook found during `git clone`
641+
└ Installation failed
642+
```
643+
644+
**Using `hyperframes skills` is already fine** — as of v0.4.5 the CLI sets `GIT_CLONE_PROTECTION_ACTIVE=0` on the child environment, which is the opt-in knob Git provides for exactly this case. You don't need to do anything.
645+
646+
**If you ran `npx skills add heygen-com/hyperframes` directly** (bypassing the HyperFrames CLI), set the env var yourself:
647+
648+
```bash
649+
GIT_CLONE_PROTECTION_ACTIVE=0 npx skills add heygen-com/hyperframes
650+
```
651+
652+
This is tracked in [GH #316](https://github.com/heygen-com/hyperframes/issues/316). An upstream fix in the `skills` CLI itself is the right long-term answer; until that lands, the env var is the correct workaround.
633653
</Tab>
634654
</Tabs>
635655

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
// ESM forbids `vi.spyOn` on live module exports, so we mock
2+
// `node:child_process` at the loader level and inspect the spawned
3+
// child's env.
4+
5+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
6+
import { EventEmitter } from "node:events";
7+
8+
type SpawnCall = {
9+
command: string;
10+
args: ReadonlyArray<string>;
11+
env: NodeJS.ProcessEnv | undefined;
12+
};
13+
14+
const state: { calls: SpawnCall[] } = { calls: [] };
15+
16+
vi.mock("node:child_process", () => ({
17+
execFileSync: vi.fn(() => Buffer.from("11.0.0")),
18+
spawn: vi.fn(
19+
(command: string, args: ReadonlyArray<string>, opts?: { env?: NodeJS.ProcessEnv }) => {
20+
state.calls.push({ command, args, env: opts?.env });
21+
const fake = new EventEmitter();
22+
setImmediate(() => fake.emit("close", 0, null));
23+
return fake;
24+
},
25+
),
26+
}));
27+
28+
describe("hyperframes skills", () => {
29+
beforeEach(() => {
30+
state.calls = [];
31+
vi.resetModules();
32+
});
33+
34+
afterEach(() => {
35+
vi.restoreAllMocks();
36+
});
37+
38+
it("sets GIT_CLONE_PROTECTION_ACTIVE=0 on the spawned skills CLI child (GH #316)", async () => {
39+
const { default: skillsCmd } = await import("./skills.js");
40+
await skillsCmd.run?.({ args: {}, rawArgs: [], cmd: skillsCmd } as never);
41+
42+
const first = state.calls[0];
43+
expect(first).toBeDefined();
44+
expect(first!.command).toBe("npx");
45+
expect(first!.args).toContain("skills");
46+
expect(first!.args).toContain("add");
47+
expect(first!.env?.GIT_CLONE_PROTECTION_ACTIVE).toBe("0");
48+
});
49+
});

‎packages/cli/src/commands/skills.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,14 @@ function runSkillsAdd(repo: string): Promise<void> {
1717
const child = spawn("npx", ["skills", "add", repo, "--all"], {
1818
stdio: "inherit",
1919
timeout: 120_000,
20+
// GH #316 — the upstream `skills` CLI shells out to `git clone`.
21+
// When Git's clone-hook protection is active (shipped on by
22+
// default in 2.45.1, reverted in 2.45.2, still present on many
23+
// corporate and CI setups), any globally-registered
24+
// `git lfs install` post-checkout hook aborts the clone. The
25+
// `repo` reaching this function is hardcoded in SOURCES below
26+
// — no user input reaches the spawn — so opting out here is safe.
27+
env: { ...process.env, GIT_CLONE_PROTECTION_ACTIVE: "0" },
2028
});
2129
child.on("close", (code, signal) => {
2230
if (code === 0) resolve();

0 commit comments

Comments
 (0)