@dungle-scrubs/tallow 0.8.7 → 0.8.8

package/extensions/tasks/state/index.ts

@@ -18,16 +18,16 @@ import {
 	unlinkSync,
 	watch,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import type { AssistantMessage, TextContent } from "@mariozechner/pi-ai";
 import { atomicWriteFileSync } from "../../_shared/atomic-write.js";
+import { getTallowPath } from "../../_shared/tallow-paths.js";
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
 /** Directory root for team-based shared task lists. */
-export const TEAMS_DIR = join(homedir(), ".tallow", "teams");
+export const TEAMS_DIR = getTallowPath("teams");
 
 /** Max age for team directories before cleanup (7 days in ms). */
 export const TEAM_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;

package/extensions/theme-selector/index.ts

@@ -1,11 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { DynamicBorder } from "@mariozechner/pi-coding-agent";
 import { Container, Key, matchesKey, Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { atomicWriteFileSync } from "../_shared/atomic-write.js";
+import { getTallowSettingsPath } from "../_shared/tallow-paths.js";
 
 /**
  * Theme switcher extension with live preview.
@@ -305,7 +304,7 @@ function filterByTags(themes: readonly ThemeEntry[], tags: string[]): readonly T
  * @returns `false` (disabled), `true` (pick from all), or `string[]` (filter by tags)
  */
 function readRandomThemeSetting(): false | true | string[] {
-	const settingsPath = join(homedir(), ".tallow", "settings.json");
+	const settingsPath = getTallowSettingsPath();
 	try {
 		const raw = readFileSync(settingsPath, "utf-8");
 		const settings = JSON.parse(raw) as { randomThemeOnStart?: boolean | string[] };
@@ -319,10 +318,7 @@ function readRandomThemeSetting(): false | true | string[] {
  * Persist theme selection to settings.json so it survives restarts.
  */
 function persistTheme(themeName: string): void {
-	const agentDir =
-		process.env.PI_CODING_AGENT_DIR ??
-		join(process.env.HOME ?? process.env.USERPROFILE ?? "~", ".tallow");
-	const settingsPath = join(agentDir, "settings.json");
+	const settingsPath = getTallowSettingsPath();
 	try {
 		let settings: Record<string, unknown> = {};
 		if (existsSync(settingsPath)) {

package/extensions/worktree/__tests__/lifecycle.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { execFileSync } from "node:child_process";
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	realpathSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	cleanupStaleWorktrees,
+	createWorktree,
+	removeWorktree,
+	TALLOW_WORKTREE_MARKER_FILE,
+	validateGitRepo,
+} from "../lifecycle.js";
+
+/**
+ * Run a git command and return trimmed stdout.
+ *
+ * @param cwd - Working directory
+ * @param args - Git arguments
+ * @returns Trimmed stdout
+ */
+function git(cwd: string, ...args: string[]): string {
+	const output = execFileSync("git", args, {
+		cwd,
+		encoding: "utf-8",
+		stdio: ["ignore", "pipe", "pipe"],
+	});
+	return output.trim();
+}
+
+/**
+ * Create a temporary git repository with an initial commit.
+ *
+ * @returns Repo root path
+ */
+function createTempRepo(): string {
+	const repo = mkdtempSync(join(tmpdir(), "tallow-worktree-test-"));
+	git(repo, "init");
+	git(repo, "config", "user.email", "test@example.com");
+	git(repo, "config", "user.name", "Test User");
+	writeFileSync(join(repo, "README.md"), "# test\n", "utf-8");
+	git(repo, "add", "README.md");
+	git(repo, "commit", "-m", "init");
+	return repo;
+}
+
+describe("worktree lifecycle", () => {
+	let repoRoot = "";
+
+	beforeEach(() => {
+		repoRoot = createTempRepo();
+	});
+
+	afterEach(() => {
+		rmSync(repoRoot, { force: true, recursive: true });
+	});
+
+	it("creates a detached worktree inside a git repo", () => {
+		const created = createWorktree(repoRoot, { scope: "subagent" });
+		expect(existsSync(created.worktreePath)).toBe(true);
+		expect(created.scope).toBe("subagent");
+		const markerPath = join(created.worktreePath, TALLOW_WORKTREE_MARKER_FILE);
+		expect(existsSync(markerPath)).toBe(true);
+		removeWorktree(created.worktreePath);
+	});
+
+	it("fails validation outside git repositories", () => {
+		const outside = mkdtempSync(join(tmpdir(), "tallow-worktree-nogit-"));
+		try {
+			expect(() => validateGitRepo(outside)).toThrow(
+				/not inside a git repository|not a git repository/i
+			);
+		} finally {
+			rmSync(outside, { force: true, recursive: true });
+		}
+	});
+
+	it("removes worktrees and is idempotent for missing paths", () => {
+		const created = createWorktree(repoRoot, { scope: "session" });
+		const first = removeWorktree(created.worktreePath);
+		expect(first.removed).toBe(true);
+		expect(existsSync(created.worktreePath)).toBe(false);
+
+		const second = removeWorktree(created.worktreePath);
+		expect(second.method).toBe("none");
+		expect(second.removed).toBe(false);
+	});
+
+	it("resolves repository root from nested directories", () => {
+		const nested = join(repoRoot, "nested", "child");
+		mkdirSync(nested, { recursive: true });
+		const root = validateGitRepo(nested).repoRoot;
+		expect(realpathSync(root)).toBe(realpathSync(repoRoot));
+	});
+
+	it("prunes stale managed worktrees whose owner pid is gone", () => {
+		const created = createWorktree(repoRoot, { scope: "session" });
+		const markerPath = join(created.worktreePath, TALLOW_WORKTREE_MARKER_FILE);
+		const marker = JSON.parse(readFileSync(markerPath, "utf-8")) as Record<string, unknown>;
+		marker.pid = 999_999_999;
+		writeFileSync(markerPath, `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
+
+		const cleaned = cleanupStaleWorktrees(repoRoot);
+		expect(cleaned.scannedCount).toBeGreaterThan(0);
+		expect(cleaned.removedCount).toBeGreaterThanOrEqual(1);
+		expect(existsSync(created.worktreePath)).toBe(false);
+	});
+});

package/extensions/worktree/extension.json

@@ -0,0 +1,31 @@
+{
+	"name": "worktree",
+	"version": "0.1.0",
+	"description": "Managed git worktree isolation lifecycle for sessions and subagents.",
+	"whenToUse": "Use when tallow should run in temporary detached git worktrees with reliable cleanup and lifecycle hooks.",
+	"capabilities": {
+		"events": ["before_agent_start", "session_shutdown", "session_start"]
+	},
+	"permissionSurface": {
+		"filesystem": "write",
+		"shell": false,
+		"network": false,
+		"subprocess": true
+	},
+	"category": "integration",
+	"tags": ["worktree", "isolation", "git", "cleanup"],
+	"files": ["index.ts", "lifecycle.ts"],
+	"relationships": [
+		{
+			"name": "subagent-tool",
+			"kind": "enhances",
+			"reason": "Subagent worktree isolation uses the shared lifecycle primitives"
+		},
+		{
+			"name": "hooks",
+			"kind": "enhances",
+			"reason": "Emits worktree lifecycle events for hook automation"
+		}
+	],
+	"npmDependencies": {}
+}

package/extensions/worktree/index.ts

@@ -0,0 +1,149 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+	emitWorktreeLifecycleEvent,
+	type WorktreeLifecycleEventPayload,
+} from "../_shared/interop-events.js";
+import { cleanupStaleWorktrees, removeWorktree, validateGitRepo } from "./lifecycle.js";
+
+/** Env var containing active session worktree path (set by CLI when -w/--worktree is used). */
+const TALLOW_WORKTREE_PATH_ENV = "TALLOW_WORKTREE_PATH";
+
+/** Env var containing original cwd before session worktree activation. */
+const TALLOW_WORKTREE_ORIGINAL_CWD_ENV = "TALLOW_WORKTREE_ORIGINAL_CWD";
+
+/** Marker added to system prompt so worktree context is only injected once. */
+const SESSION_WORKTREE_PROMPT_MARKER = "Session worktree isolation is active.";
+
+/** In-memory state for session-level worktree lifecycle management. */
+interface SessionWorktreeState {
+	readonly originalCwd: string;
+	readonly repoRoot: string;
+	readonly worktreePath: string;
+}
+
+/**
+ * Worktree lifecycle extension.
+ *
+ * Responsibilities:
+ * - prune stale managed worktrees on session startup
+ * - emit session-level worktree lifecycle events for hooks
+ * - inject explicit worktree context into the system prompt
+ * - perform best-effort teardown on session shutdown
+ *
+ * @param pi - Extension API
+ */
+export default function worktreeExtension(pi: ExtensionAPI): void {
+	let sessionState: SessionWorktreeState | undefined;
+	let cleanedUp = false;
+
+	/**
+	 * Best-effort session-worktree cleanup routine.
+	 *
+	 * @param reason - Cleanup trigger reason for diagnostics
+	 */
+	const cleanupSessionWorktree = (reason: "session_shutdown"): void => {
+		if (cleanedUp || !sessionState) return;
+		cleanedUp = true;
+		removeWorktree(sessionState.worktreePath);
+		emitWorktreeLifecycleEvent(pi.events, "worktree_remove", {
+			agentId: undefined,
+			repoRoot: sessionState.repoRoot,
+			scope: "session",
+			timestamp: Date.now(),
+			worktreePath: sessionState.worktreePath,
+		});
+		if (reason === "session_shutdown") {
+			delete process.env[TALLOW_WORKTREE_PATH_ENV];
+			delete process.env[TALLOW_WORKTREE_ORIGINAL_CWD_ENV];
+		}
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		const cleanupRoot = resolveCleanupRoot(ctx.cwd);
+		if (cleanupRoot) {
+			try {
+				cleanupStaleWorktrees(cleanupRoot);
+			} catch {
+				// Startup stale cleanup is best-effort.
+			}
+		}
+
+		sessionState = resolveSessionWorktreeState(ctx.cwd);
+		cleanedUp = false;
+		if (!sessionState) return;
+
+		const payload: WorktreeLifecycleEventPayload = {
+			agentId: undefined,
+			repoRoot: sessionState.repoRoot,
+			scope: "session",
+			timestamp: Date.now(),
+			worktreePath: sessionState.worktreePath,
+		};
+		emitWorktreeLifecycleEvent(pi.events, "worktree_create", payload);
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (!sessionState) return;
+		if (event.systemPrompt.includes(SESSION_WORKTREE_PROMPT_MARKER)) return;
+
+		const hint = [
+			SESSION_WORKTREE_PROMPT_MARKER,
+			`Current cwd is an isolated detached git worktree: ${sessionState.worktreePath}`,
+			`Original cwd before isolation: ${sessionState.originalCwd}`,
+			"Any file edits happen inside this temporary worktree.",
+		].join("\n");
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n${hint}`,
+		};
+	});
+
+	pi.on("session_shutdown", async () => {
+		cleanupSessionWorktree("session_shutdown");
+	});
+}
+
+/**
+ * Resolve cleanup root for startup stale-worktree pruning.
+ *
+ * @param cwd - Current session cwd
+ * @returns Repository root when available
+ */
+function resolveCleanupRoot(cwd: string): string | undefined {
+	const originalCwd = process.env[TALLOW_WORKTREE_ORIGINAL_CWD_ENV];
+	if (originalCwd) {
+		try {
+			return validateGitRepo(originalCwd).repoRoot;
+		} catch {
+			// Fall through to session cwd.
+		}
+	}
+
+	try {
+		return validateGitRepo(cwd).repoRoot;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Build session worktree state from environment metadata.
+ *
+ * @param fallbackCwd - Session cwd fallback when original cwd metadata is absent
+ * @returns Parsed session worktree state when metadata is valid
+ */
+function resolveSessionWorktreeState(fallbackCwd: string): SessionWorktreeState | undefined {
+	const worktreePath = process.env[TALLOW_WORKTREE_PATH_ENV];
+	if (!worktreePath) return undefined;
+	const originalCwd = process.env[TALLOW_WORKTREE_ORIGINAL_CWD_ENV] ?? fallbackCwd;
+
+	try {
+		const repoRoot = validateGitRepo(originalCwd).repoRoot;
+		return {
+			originalCwd,
+			repoRoot,
+			worktreePath,
+		};
+	} catch {
+		return undefined;
+	}
+}