@dungle-scrubs/tallow 0.8.0

package/extensions/claude-bridge/index.ts

@@ -0,0 +1,188 @@
+/**
+ * Claude Bridge Extension
+ *
+ * Bridges .claude/ directories so tallow discovers Claude Code resources.
+ * Hooks `resources_discover` to inject .claude/skills/ paths into the
+ * pi framework's skill loader, making them available in both the system
+ * prompt and /skill-name commands.
+ *
+ * Agent and command bridging is handled directly by the subagent-tool,
+ * agent-commands-tool, and command-prompt extensions.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const CLAUDE_DIR = ".claude";
+/** Project-level config directories (current + legacy) */
+const PROJECT_CONFIG_DIRS = [".tallow", ".pi"];
+
+/**
+ * Expand ~ prefix to the user's home directory.
+ *
+ * @param p - Path string that may start with ~
+ * @returns Resolved absolute path
+ */
+function expandTilde(p: string): string {
+	if (p === "~") return os.homedir();
+	if (p.startsWith("~/")) return path.join(os.homedir(), p.slice(2));
+	return p;
+}
+
+/**
+ * List subdirectory names inside a directory (non-hidden only).
+ *
+ * @param dir - Directory to scan
+ * @returns Array of subdirectory names
+ */
+function listSubdirNames(dir: string): string[] {
+	try {
+		return fs
+			.readdirSync(dir, { withFileTypes: true })
+			.filter((e) => e.isDirectory() && !e.name.startsWith("."))
+			.map((e) => e.name);
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Read the packages array from a settings.json file.
+ *
+ * @param settingsPath - Absolute path to settings.json
+ * @returns Array of package path strings (unexpanded)
+ */
+function readPackages(settingsPath: string): string[] {
+	try {
+		const content = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
+		return Array.isArray(content.packages) ? content.packages : [];
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Collect all known skill names from tallow's skill sources:
+ * user dir, project dir, and packages referenced in settings.
+ *
+ * This enables collision detection against skills from tallow packages
+ * (e.g. ~/dev/tallow-plugins/fuse/skills/database), not just the
+ * agent home skills directory.
+ *
+ * @param agentDir - Tallow home directory (e.g. ~/.tallow-fuse)
+ * @param cwd - Current working directory
+ * @returns Set of skill directory names already managed by tallow
+ */
+export function collectKnownSkillNames(agentDir: string, cwd: string): Set<string> {
+	const names = new Set<string>();
+
+	// User-level skills (agentDir/skills/)
+	for (const name of listSubdirNames(path.join(agentDir, "skills"))) {
+		names.add(name);
+	}
+
+	// Project-level skills (cwd/.tallow/skills/, cwd/.pi/skills/)
+	for (const configDir of PROJECT_CONFIG_DIRS) {
+		for (const name of listSubdirNames(path.join(cwd, configDir, "skills"))) {
+			names.add(name);
+		}
+	}
+
+	// Package skills (global + project settings)
+	const settingsPaths = [
+		path.join(agentDir, "settings.json"),
+		...PROJECT_CONFIG_DIRS.map((d) => path.join(cwd, d, "settings.json")),
+	];
+
+	const allPackages = new Set<string>();
+	for (const sp of settingsPaths) {
+		for (const pkg of readPackages(sp)) {
+			allPackages.add(expandTilde(pkg));
+		}
+	}
+
+	for (const pkg of allPackages) {
+		for (const name of listSubdirNames(path.join(pkg, "skills"))) {
+			names.add(name);
+		}
+	}
+
+	return names;
+}
+
+/**
+ * Enumerates skill subdirectories in a .claude/skills/ parent,
+ * filtering out entries whose names appear in knownSkillNames.
+ *
+ * Returns SKILL.md file paths (not directories) when possible to avoid
+ * the framework picking up auxiliary .md files (e.g. reference.md).
+ *
+ * @param claudeSkillsDir - Parent .claude/skills/ directory
+ * @param knownSkillNames - Set of skill names already managed by tallow
+ * @returns SKILL.md file paths (or directory fallback) for non-colliding entries
+ */
+export function getNonCollidingSkillPaths(
+	claudeSkillsDir: string,
+	knownSkillNames: ReadonlySet<string>
+): string[] {
+	const paths: string[] = [];
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(claudeSkillsDir, { withFileTypes: true });
+	} catch {
+		return paths;
+	}
+
+	for (const entry of entries) {
+		if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+		if (knownSkillNames.has(entry.name)) continue;
+
+		// Prefer SKILL.md file path over directory to avoid picking up
+		// auxiliary .md files (e.g. reference.md) in the same directory
+		const skillFile = path.join(claudeSkillsDir, entry.name, "SKILL.md");
+		if (fs.existsSync(skillFile)) {
+			paths.push(skillFile);
+		} else {
+			paths.push(path.join(claudeSkillsDir, entry.name));
+		}
+	}
+	return paths;
+}
+
+/**
+ * Registers a resources_discover handler that adds .claude/skills/
+ * to the framework's skill loading paths.
+ *
+ * Filters out skill directories that collide with tallow-managed skills
+ * (from user dir, project dir, and packages) to avoid noisy diagnostics.
+ * Returns SKILL.md file paths instead of directories to prevent auxiliary
+ * .md files from being parsed as skills.
+ *
+ * @param pi - Extension API
+ */
+export default function (pi: ExtensionAPI): void {
+	pi.on("resources_discover", async (event) => {
+		const agentDir = process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".tallow");
+		const cwd = (event as { cwd: string }).cwd;
+		const knownNames = collectKnownSkillNames(agentDir, cwd);
+
+		const skillPaths: string[] = [];
+
+		// User-level: ~/.claude/skills/
+		const userClaudeSkills = path.join(os.homedir(), CLAUDE_DIR, "skills");
+		if (fs.existsSync(userClaudeSkills)) {
+			skillPaths.push(...getNonCollidingSkillPaths(userClaudeSkills, knownNames));
+		}
+
+		// Project-level: cwd/.claude/skills/
+		const projectClaudeSkills = path.resolve(cwd, CLAUDE_DIR, "skills");
+		if (fs.existsSync(projectClaudeSkills)) {
+			skillPaths.push(...getNonCollidingSkillPaths(projectClaudeSkills, knownNames));
+		}
+
+		if (skillPaths.length === 0) return;
+		return { skillPaths };
+	});
+}

package/extensions/clear/extension.json

@@ -0,0 +1,10 @@
+{
+	"name": "clear",
+	"version": "0.1.0",
+	"description": "Alias /clear for /new (start a fresh session)",
+	"category": "alias",
+	"tags": ["session", "alias"],
+	"files": ["index.ts"],
+	"relationships": [],
+	"npmDependencies": {}
+}

package/extensions/clear/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Clear Extension
+ *
+ * Registers /clear as an alias for /new (start a fresh session).
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+/**
+ * Registers the /clear command.
+ * @param pi - Extension API
+ */
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("clear", {
+		description: "Start a new session (alias for /new)",
+		handler: async (_args, ctx) => {
+			await ctx.newSession();
+		},
+	});
+}

package/extensions/command-expansion/__tests__/expansion.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Tests for command-expansion pure functions: argument parsing, placeholder
+ * substitution, and outer command splitting.
+ */
+import { describe, expect, it } from "bun:test";
+import { parseCommandArgs, splitOuterCommand, substituteArgs } from "../index.js";
+
+// ── parseCommandArgs ─────────────────────────────────────────────────────────
+
+describe("parseCommandArgs", () => {
+	it("splits simple space-separated args", () => {
+		expect(parseCommandArgs("a b c")).toEqual(["a", "b", "c"]);
+	});
+
+	it("handles double-quoted args", () => {
+		expect(parseCommandArgs('"hello world" foo')).toEqual(["hello world", "foo"]);
+	});
+
+	it("handles single-quoted args", () => {
+		expect(parseCommandArgs("'hello world' foo")).toEqual(["hello world", "foo"]);
+	});
+
+	it("returns empty array for empty input", () => {
+		expect(parseCommandArgs("")).toEqual([]);
+	});
+
+	it("handles extra whitespace", () => {
+		expect(parseCommandArgs("  a   b  ")).toEqual(["a", "b"]);
+	});
+
+	it("handles tab separation", () => {
+		expect(parseCommandArgs("a\tb")).toEqual(["a", "b"]);
+	});
+
+	it("handles single argument", () => {
+		expect(parseCommandArgs("hello")).toEqual(["hello"]);
+	});
+
+	it("handles mixed quotes", () => {
+		expect(parseCommandArgs("\"first\" 'second' third")).toEqual(["first", "second", "third"]);
+	});
+});
+
+// ── substituteArgs ───────────────────────────────────────────────────────────
+
+describe("substituteArgs", () => {
+	it("replaces $1 placeholder", () => {
+		expect(substituteArgs("Hello $1", ["world"])).toBe("Hello world");
+	});
+
+	it("replaces $ARGUMENTS with all args joined", () => {
+		expect(substituteArgs("Run: $ARGUMENTS", ["a", "b"])).toBe("Run: a b");
+	});
+
+	it("replaces $@ with all args joined", () => {
+		expect(substituteArgs("All: $@", ["x", "y"])).toBe("All: x y");
+	});
+
+	it("replaces missing positional arg with empty string", () => {
+		expect(substituteArgs("Hello $2", ["only-one"])).toBe("Hello ");
+	});
+
+	// biome-ignore lint/suspicious/noTemplateCurlyInString: testing literal placeholder syntax
+	it("handles ${@:N} slice syntax", () => {
+		// biome-ignore lint/suspicious/noTemplateCurlyInString: testing literal placeholder syntax
+		expect(substituteArgs("Rest: ${@:2}", ["a", "b", "c"])).toBe("Rest: b c");
+	});
+
+	// biome-ignore lint/suspicious/noTemplateCurlyInString: testing literal placeholder syntax
+	it("handles ${@:N:L} slice with length", () => {
+		// biome-ignore lint/suspicious/noTemplateCurlyInString: testing literal placeholder syntax
+		expect(substituteArgs("Mid: ${@:2:1}", ["a", "b", "c"])).toBe("Mid: b");
+	});
+
+	it("leaves text without placeholders unchanged", () => {
+		expect(substituteArgs("plain text", ["arg"])).toBe("plain text");
+	});
+
+	it("handles multiple positional args", () => {
+		expect(substituteArgs("$1 and $2", ["first", "second"])).toBe("first and second");
+	});
+
+	it("handles empty args array", () => {
+		expect(substituteArgs("Hello $1", [])).toBe("Hello ");
+	});
+
+	it("handles no args with $ARGUMENTS", () => {
+		expect(substituteArgs("Run: $ARGUMENTS", [])).toBe("Run: ");
+	});
+});
+
+// ── splitOuterCommand ────────────────────────────────────────────────────────
+
+describe("splitOuterCommand", () => {
+	it("extracts command and args", () => {
+		expect(splitOuterCommand("/cmd args here")).toEqual({
+			outerCommand: "/cmd",
+			args: "args here",
+		});
+	});
+
+	it("handles command with no args", () => {
+		expect(splitOuterCommand("/cmd")).toEqual({
+			outerCommand: "/cmd",
+			args: "",
+		});
+	});
+
+	it("returns null for non-command text", () => {
+		expect(splitOuterCommand("not a command")).toBeNull();
+	});
+
+	it("handles nested commands", () => {
+		expect(splitOuterCommand("/cmd1 /cmd2 args")).toEqual({
+			outerCommand: "/cmd1",
+			args: "/cmd2 args",
+		});
+	});
+
+	it("returns null for empty string", () => {
+		expect(splitOuterCommand("")).toBeNull();
+	});
+});

package/extensions/command-expansion/extension.json

@@ -0,0 +1,10 @@
+{
+	"name": "command-expansion",
+	"version": "0.1.0",
+	"description": "Expands nested commands/skills/templates used as arguments to other commands",
+	"category": "command",
+	"tags": ["commands", "skills", "templates", "expansion"],
+	"files": ["index.ts"],
+	"relationships": [],
+	"npmDependencies": {}
+}

package/extensions/command-expansion/index.ts

@@ -0,0 +1,343 @@
+/**
+ * Nested Command Expansion Extension
+ *
+ * Expands nested commands/skills/templates used as arguments to other commands.
+ *
+ * Example:
+ *   /outer-command /skill:inner-skill args
+ *
+ * Before this extension: /skill:inner-skill is passed as literal string
+ * After this extension: /skill:inner-skill is expanded to its content
+ *
+ * Supports:
+ *   - /skill:name args - skill commands
+ *   - /template-name args - prompt templates
+ *   - Recursive expansion (nested within nested)
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { loadSkills, stripFrontmatter } from "@mariozechner/pi-coding-agent";
+
+interface PromptTemplate {
+	name: string;
+	content: string;
+	filePath: string;
+}
+
+interface Skill {
+	name: string;
+	filePath: string;
+	baseDir: string;
+	description: string;
+}
+
+/**
+ * Parse command arguments respecting quoted strings (bash-style).
+ * @internal
+ */
+export function parseCommandArgs(argsString: string): string[] {
+	const args: string[] = [];
+	let current = "";
+	let inQuote: string | null = null;
+
+	for (let i = 0; i < argsString.length; i++) {
+		const char = argsString[i];
+		if (inQuote) {
+			if (char === inQuote) {
+				inQuote = null;
+			} else {
+				current += char;
+			}
+		} else if (char === '"' || char === "'") {
+			inQuote = char;
+		} else if (char === " " || char === "\t") {
+			if (current) {
+				args.push(current);
+				current = "";
+			}
+		} else {
+			current += char;
+		}
+	}
+	if (current) {
+		args.push(current);
+	}
+	return args;
+}
+
+/**
+ * Substitute argument placeholders in template content.
+ * Supports $1, $2, ..., $@, $ARGUMENTS, ${@:N}, ${@:N:L}
+ * @internal
+ */
+export function substituteArgs(content: string, args: string[]): string {
+	let result = content;
+
+	// Replace $1, $2, etc. with positional args FIRST
+	result = result.replace(/\$(\d+)/g, (_, num) => {
+		const index = parseInt(num, 10) - 1;
+		return args[index] ?? "";
+	});
+
+	// Replace ${@:start} or ${@:start:length} with sliced args
+	result = result.replace(/\$\{@:(\d+)(?::(\d+))?\}/g, (_, startStr, lengthStr) => {
+		let start = parseInt(startStr, 10) - 1;
+		if (start < 0) start = 0;
+		if (lengthStr) {
+			const length = parseInt(lengthStr, 10);
+			return args.slice(start, start + length).join(" ");
+		}
+		return args.slice(start).join(" ");
+	});
+
+	const allArgs = args.join(" ");
+	result = result.replace(/\$ARGUMENTS/g, allArgs);
+	result = result.replace(/\$@/g, allArgs);
+
+	return result;
+}
+
+/**
+ * Load prompt templates from ~/.tallow/prompts/ and .tallow/prompts/
+ */
+function loadPromptTemplates(): PromptTemplate[] {
+	const templates: PromptTemplate[] = [];
+	const homeDir = os.homedir();
+
+	const dirs = [
+		path.join(homeDir, ".tallow", "prompts"),
+		path.join(process.cwd(), ".tallow", "prompts"),
+	];
+
+	for (const dir of dirs) {
+		if (!fs.existsSync(dir)) continue;
+
+		try {
+			const files = fs.readdirSync(dir);
+			for (const file of files) {
+				if (!file.endsWith(".md")) continue;
+
+				const filePath = path.join(dir, file);
+				try {
+					const stat = fs.statSync(filePath);
+					if (!stat.isFile()) continue;
+
+					const content = fs.readFileSync(filePath, "utf-8");
+					const name = file.replace(/\.md$/, "");
+
+					// Strip frontmatter to get content
+					const body = stripFrontmatter(content);
+
+					templates.push({
+						name,
+						content: body.trim(),
+						filePath,
+					});
+				} catch {
+					// Skip unreadable files
+				}
+			}
+		} catch {
+			// Skip unreadable directories
+		}
+	}
+
+	return templates;
+}
+
+/**
+ * Expand a skill command to its content.
+ */
+function expandSkill(skillName: string, args: string, skills: Skill[]): string | null {
+	const skill = skills.find((s) => s.name === skillName);
+	if (!skill) return null;
+
+	try {
+		const content = fs.readFileSync(skill.filePath, "utf-8");
+		const body = stripFrontmatter(content).trim();
+		const skillBlock = `<skill name="${skill.name}" location="${skill.filePath}">\nReferences are relative to ${skill.baseDir}.\n\n${body}\n</skill>`;
+		return args ? `${skillBlock}\n\n${args}` : skillBlock;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Expand a prompt template to its content.
+ */
+function expandTemplate(
+	templateName: string,
+	argsString: string,
+	templates: PromptTemplate[]
+): string | null {
+	const template = templates.find((t) => t.name === templateName);
+	if (!template) return null;
+
+	const args = parseCommandArgs(argsString);
+	return substituteArgs(template.content, args);
+}
+
+/**
+ * Check if text starts with a command pattern.
+ * Returns { command, args } if it's a command, null otherwise.
+ */
+function parseCommand(
+	text: string
+): { type: "skill" | "template"; name: string; args: string } | null {
+	if (!text.startsWith("/")) return null;
+
+	const spaceIndex = text.indexOf(" ");
+	const commandPart = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+	const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1);
+
+	if (commandPart.startsWith("skill:")) {
+		return { type: "skill", name: commandPart.slice(6), args };
+	}
+
+	// It's potentially a template (we'll check if it exists later)
+	return { type: "template", name: commandPart, args };
+}
+
+/**
+ * Recursively expand all commands in text.
+ * Handles commands at the start and within arguments.
+ */
+function expandCommands(
+	text: string,
+	skills: Skill[],
+	templates: PromptTemplate[],
+	depth = 0
+): string {
+	// Prevent infinite recursion
+	if (depth > 10) return text;
+
+	// First, try to expand if the text itself starts with a command
+	const parsed = parseCommand(text);
+	if (parsed) {
+		let expanded: string | null = null;
+
+		if (parsed.type === "skill") {
+			// Recursively expand args first
+			const expandedArgs = expandCommands(parsed.args, skills, templates, depth + 1);
+			expanded = expandSkill(parsed.name, expandedArgs, skills);
+		} else if (parsed.type === "template") {
+			// Recursively expand args first
+			const expandedArgs = expandCommands(parsed.args, skills, templates, depth + 1);
+			expanded = expandTemplate(parsed.name, expandedArgs, templates);
+		}
+
+		if (expanded !== null) {
+			// Recursively expand the result in case it contains more commands
+			return expandCommands(expanded, skills, templates, depth + 1);
+		}
+	}
+
+	// If not a command at the start, look for commands in the text
+	// Find the first /command pattern and try to expand it
+	const commandMatch = text.match(/(?:^|\s)(\/\S+)/);
+	if (commandMatch && commandMatch.index !== undefined) {
+		const matchStart = commandMatch.index + (commandMatch[0].startsWith(" ") ? 1 : 0);
+		const beforeCommand = text.slice(0, matchStart);
+		const commandAndRest = text.slice(matchStart);
+
+		// Try to parse and expand this command
+		const parsed = parseCommand(commandAndRest);
+		if (parsed) {
+			let expanded: string | null = null;
+
+			if (parsed.type === "skill") {
+				expanded = expandSkill(parsed.name, parsed.args, skills);
+			} else if (parsed.type === "template") {
+				expanded = expandTemplate(parsed.name, parsed.args, templates);
+			}
+
+			if (expanded !== null) {
+				const result = beforeCommand + expanded;
+				// Recursively expand any remaining commands
+				return expandCommands(result, skills, templates, depth + 1);
+			}
+		}
+	}
+
+	return text;
+}
+
+/**
+ * Extract the outer command and its arguments.
+ * Returns { outerCommand, args } for "/cmd1 /cmd2 args" -> { outerCommand: "/cmd1", args: "/cmd2 args" }
+ * @internal
+ */
+export function splitOuterCommand(text: string): { outerCommand: string; args: string } | null {
+	if (!text.startsWith("/")) return null;
+
+	const spaceIndex = text.indexOf(" ");
+	if (spaceIndex === -1) {
+		return { outerCommand: text, args: "" };
+	}
+
+	return {
+		outerCommand: text.slice(0, spaceIndex),
+		args: text.slice(spaceIndex + 1),
+	};
+}
+
+export default function (pi: ExtensionAPI) {
+	// Load skills and templates once at startup
+	let skills: Skill[] = [];
+	let templates: PromptTemplate[] = [];
+
+	function reloadResources() {
+		try {
+			const loadedSkills = loadSkills();
+			skills = loadedSkills.skills.map((s) => ({
+				name: s.name,
+				filePath: s.filePath,
+				baseDir: s.baseDir,
+				description: s.description || "",
+			}));
+		} catch {
+			skills = [];
+		}
+
+		templates = loadPromptTemplates();
+	}
+
+	// Initial load
+	reloadResources();
+
+	// Reload on session start (in case resources changed)
+	pi.on("session_start", async () => {
+		reloadResources();
+	});
+
+	// Intercept input and expand nested commands
+	pi.on("input", async (event, _ctx) => {
+		const text = event.text;
+
+		// Only process if it looks like a command with arguments
+		const split = splitOuterCommand(text);
+		if (!split || !split.args) {
+			return { action: "continue" as const };
+		}
+
+		// Check if args contain a potential command pattern
+		if (!split.args.match(/\/\S+/)) {
+			return { action: "continue" as const };
+		}
+
+		// Expand nested commands in the arguments
+		const expandedArgs = expandCommands(split.args, skills, templates, 0);
+
+		// If nothing changed, continue normally
+		if (expandedArgs === split.args) {
+			return { action: "continue" as const };
+		}
+
+		// Transform the input with expanded arguments
+		const newText = `${split.outerCommand} ${expandedArgs}`;
+		return { action: "transform" as const, text: newText };
+	});
+}