@henryqw/pi-deps 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# `@henryqw/pi-deps`
+
+Prepare locked Node and uv dependencies whenever Git creates a new worktree for an opted-in repository.
+
+## Install
+
+```bash
+pi install npm:@henryqw/pi-deps
+```
+
+Node 22.19 or newer, Git, and each selected package manager must be available on `PATH` used by Git.
+
+## Supported managers
+
+Only current major versions are supported; older majors are not handled and fall back to the lockfile default below.
+
+| Manager | Command | Lockfile |
+| --- | --- | --- |
+| npm | `npm ci` | `package-lock.json`, `npm-shrinkwrap.json` |
+| pnpm | `pnpm install --frozen-lockfile` | `pnpm-lock.yaml` |
+| Yarn | `yarn install --immutable` | `yarn.lock` (Yarn Classic 1.x is not supported) |
+| Bun | `bun install --frozen-lockfile` | `bun.lock`, `bun.lockb` |
+| uv | `uv sync --locked` | `uv.lock` |
+
+## Use
+
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `/deps` | command | Toggle dependency preparation for future worktrees in current repository. |
+
+Run `/deps` once from any worktree to enable preparation through repository's shared `post-checkout` hook. Run it again to disable. Hooks without this package's marker are never overwritten or removed. After updating the package, run `/deps` twice in each opted-in repository to replace the copied hook with the current version. A configured `core.hooksPath` replaces the shared hooks directory, so `/deps` refuses instead of installing where Git would ignore or share the hook.
+
+Only Git-root lockfiles are inspected. npm, pnpm, Yarn, and Bun use frozen installs; uv uses `uv sync --locked`. Node and uv both run when both lockfile types exist. Root npm and uv workspaces remain package-manager concerns; nested independent projects are not scanned.
+
+Creation waits for installs. Missing executables, conflicting Node lockfiles, `packageManager` mismatches, and install failures make worktree command fail while leaving created worktree available for inspection. Unsupported repositories and already-present `node_modules`, `.pnp.cjs`, or `.venv` are skipped. Worktrees created with `git worktree add --no-checkout` never run `post-checkout`, so they are not prepared.
+
+Dependency installation may execute repository-controlled build and install scripts. Enable only repositories you trust.
+
+## Remove
+
+Disable each opted-in repository before removing package because copied Git hook is self-contained:
+
+```text
+/deps
+```
+
+```bash
+pi remove npm:@henryqw/pi-deps
+```
+
+## Development
+
+```bash
+npm test --workspace @henryqw/pi-deps
+npm run typecheck --workspace @henryqw/pi-deps
+npm run pack:check --workspace @henryqw/pi-deps
+```

package/extensions/deps.ts

@@ -0,0 +1,100 @@
+import { randomUUID } from "node:crypto";
+import { link, mkdir, readFile, rename, rm, writeFile, chmod } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const hookSourcePath = fileURLToPath(new URL("../hooks/post-checkout.mjs", import.meta.url));
+const managedHookMarker = "pi-deps-managed-hook";
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+async function existingHook(path: string): Promise<string | undefined> {
+	try {
+		return await readFile(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+export async function toggleDependencyHook(commonGitDir: string): Promise<{ enabled: boolean; path: string }> {
+	const source = await readFile(hookSourcePath, "utf8");
+	const path = join(commonGitDir, "hooks", "post-checkout");
+	const existing = await existingHook(path);
+
+	if (existing !== undefined) {
+		if (!existing.includes(managedHookMarker)) {
+			throw new Error(`Refusing to modify unmanaged Git hook: ${path}`);
+		}
+		// Rename first so the content check happens on the exact inode being removed.
+		const staging = `${path}.pi-deps-${process.pid}-${randomUUID()}`;
+		await rename(path, staging);
+		try {
+			const removed = await readFile(staging, "utf8");
+			if (!removed.includes(managedHookMarker)) {
+				await rename(staging, path);
+				throw new Error(`Refusing to modify unmanaged Git hook: ${path}`);
+			}
+			await rm(staging);
+		} catch (error) {
+			await rm(staging, { force: true });
+			throw error;
+		}
+		return { enabled: false, path };
+	}
+
+	await mkdir(dirname(path), { recursive: true });
+	const temporary = `${path}.pi-deps-${process.pid}-${randomUUID()}`;
+	try {
+		await writeFile(temporary, source, { encoding: "utf8", mode: 0o755, flag: "wx" });
+		await chmod(temporary, 0o755);
+		await link(temporary, path);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+			throw new Error(`Refusing to modify Git hook created concurrently: ${path}`, { cause: error });
+		}
+		throw error;
+	} finally {
+		await rm(temporary, { force: true });
+	}
+	return { enabled: true, path };
+}
+
+export default function depsExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("deps", {
+		description: "Toggle dependency preparation for future Git worktrees",
+		handler: async (args, ctx) => {
+			if (args.trim()) throw new Error("Usage: /deps");
+			const git = (args2: string[]) => pi.exec("git", args2, { cwd: ctx.cwd });
+			const result = await git(["rev-parse", "--git-common-dir"]);
+			if (result.code !== 0 || result.killed) {
+				throw new Error(`Cannot locate shared Git directory: ${result.stderr.trim() || `exit code ${result.code}`}`);
+			}
+			const commonGitDir = result.stdout.trim();
+			if (!commonGitDir) throw new Error("Cannot locate shared Git directory: git returned an empty path");
+
+			// core.hooksPath replaces <commonGitDir>/hooks; refuse instead of writing where Git ignores or shares the hook.
+			const hooksDir = await git(["rev-parse", "--git-path", "hooks"]);
+			if (hooksDir.code !== 0 || hooksDir.killed) {
+				throw new Error(`Cannot locate effective hooks directory: ${hooksDir.stderr.trim() || `exit code ${hooksDir.code}`}`);
+			}
+			const defaultHooksDir = resolve(ctx.cwd, commonGitDir, "hooks");
+			if (resolve(ctx.cwd, hooksDir.stdout.trim()) !== defaultHooksDir) {
+				throw new Error(`Refusing non-default hooks directory (core.hooksPath?): ${hooksDir.stdout.trim()}; expected ${defaultHooksDir}`);
+			}
+
+			try {
+				const toggled = await toggleDependencyHook(resolve(ctx.cwd, commonGitDir));
+				ctx.ui.notify(
+					`Dependency preparation ${toggled.enabled ? "enabled" : "disabled"}: ${toggled.path}`,
+					"info",
+				);
+			} catch (error) {
+				throw new Error(`Cannot toggle dependency preparation: ${errorMessage(error)}`, { cause: error });
+			}
+		},
+	});
+}

package/hooks/post-checkout.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// pi-deps-managed-hook
+
+import { spawnSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const [, , oldHead, , checkoutKind] = process.argv;
+if (!/^0+$/.test(oldHead ?? "") || checkoutKind !== "1") process.exit(0);
+
+const root = process.cwd();
+const path = (name) => join(root, name);
+const isFile = (name) => {
+	try { return statSync(path(name)).isFile(); } catch { return false; }
+};
+const isDirectory = (name) => {
+	try { return statSync(path(name)).isDirectory(); } catch { return false; }
+};
+
+function run(command, args) {
+	console.error(`pi-deps: ${command} ${args.join(" ")}`);
+	const result = spawnSync(command, args, { cwd: root, stdio: "inherit" });
+	if (result.error) {
+		console.error(`pi-deps: failed to start ${command}: ${result.error.message}`);
+		process.exit(result.error.code === "ENOENT" ? 127 : 1);
+	}
+	if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
+function nodeInstall() {
+	const locks = [];
+	if (isFile("package-lock.json") || isFile("npm-shrinkwrap.json")) locks.push("npm");
+	if (isFile("pnpm-lock.yaml")) locks.push("pnpm");
+	if (isFile("yarn.lock")) locks.push("yarn");
+	if (isFile("bun.lock") || isFile("bun.lockb")) locks.push("bun");
+	if (isFile("bun.lock") && isFile("bun.lockb")) throw new Error("Conflicting Bun lockfiles: bun.lock and bun.lockb");
+	if (locks.length === 0) return;
+	if (locks.length > 1) throw new Error(`Conflicting Node lockfiles: ${locks.join(", ")}`);
+	if (!isFile("package.json")) throw new Error("Node lockfile found without package.json");
+
+	let packageJson;
+	try {
+		packageJson = JSON.parse(readFileSync(path("package.json"), "utf8"));
+	} catch (error) {
+		throw new Error(`Cannot read package.json: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const declared = packageJson?.packageManager;
+	let manager = locks[0];
+	if (declared !== undefined) {
+		if (typeof declared !== "string" || !/^(npm|pnpm|yarn|bun)@.+$/.test(declared)) {
+			throw new Error(`Unsupported packageManager: ${JSON.stringify(declared)}`);
+		}
+		manager = declared.slice(0, declared.indexOf("@"));
+		if (manager !== locks[0]) {
+			throw new Error(`packageManager ${manager} does not match ${locks[0]} lockfile`);
+		}
+	}
+
+	if (isDirectory("node_modules") || (manager === "yarn" && isFile(".pnp.cjs"))) return;
+	if (manager === "npm") run("npm", ["ci"]);
+	else if (manager === "pnpm") run("pnpm", ["install", "--frozen-lockfile"]);
+	else if (manager === "bun") run("bun", ["install", "--frozen-lockfile"]);
+	else run("yarn", ["install", "--immutable"]);
+}
+
+try {
+	nodeInstall();
+	if (isFile("uv.lock") && !isDirectory(".venv")) run("uv", ["sync", "--locked"]);
+} catch (error) {
+	console.error(`pi-deps: ${error instanceof Error ? error.message : String(error)}`);
+	process.exit(1);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@henryqw/pi-deps",
+  "version": "0.1.2",
+  "description": "Prepare Node and uv dependencies when opted-in Git worktrees are created.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "git",
+    "worktree",
+    "dependencies"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "hooks",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/deps.ts test/*.test.ts",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-packages.git",
+    "directory": "packages/pi-deps"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryQW/pi-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/deps.ts"
+    ]
+  }
+}