pi-do-always 0.1.0

package/README.md

@@ -0,0 +1,113 @@
+# pi-do-always
+
+A [Pi](https://github.com/earendil-works/pi) extension that gives you a `/do-always` command for your
+repeated "do the usual" prompts.
+
+Type `/do-always` → a numbered list of tasks appears → press a number (or arrows + Enter) →
+the task's prompt is **filled into the input editor**. Review it, tweak it, press Enter to run.
+
+```text
+┌ do-always — pick a task                                           ┐
+│ 1. review   — Review code and double-check changes                │
+│ 2. readme   — Update the README                                   │
+│ 3. tests    — Run tests and fix failures                          │
+│ 4. commit   — Prepare a clean commit                              │
+│ 5. cleanup  — Propose a plan to clean up dead code and duplicates │
+│ 6. release  — Prepare a release (version, changelog, tag)         │
+│ 7. security — Security audit — plan proposal                      │
+│ 8. perf     — Performance review — plan proposal                  │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+## Usage
+
+|Command|What it does|
+|---|---|
+|`/do-always` or `Ctrl+Shift+P`|Show the numbered task selector|
+|`/do-always 2`|Fill the prompt for task #2 directly|
+|`/do-always review`|Fill the prompt for the task named `review` (task names autocomplete after `/do-always`)|
+|`/do-always list`|Print the task list|
+|`/do-always list-details`|Show the full prompt text each task will inject|
+
+In non-interactive modes (no TUI) there is no editor to fill, so the selected prompt is sent
+as a user message instead.
+
+## Install
+
+Install it as a Pi package, which loads the bundled `index.ts` (and its `tasks.ts`) without
+managing symlinks:
+
+```bash
+pi install ./pi-always              # from a local copy of this repo
+pi install git:github.com/aginies/pi-always   # from the git repo
+```
+
+(It is not on npm yet; once published it will be `pi install npm:pi-do-always`.)
+
+Manage it with `pi list` (to see installed sources) and `pi remove <source>` using the same
+source you installed with (e.g. `pi remove git:github.com/aginies/pi-always`). Alternatively, it is auto-discovered from
+the extensions directory, so you can symlink it instead:
+
+```bash
+ln -s "$PWD" ~/.pi/agent/extensions/do-always   # uninstall with: rm that symlink
+```
+
+For development you can also load it explicitly: `npm run dev` (runs `pi --extension ./index.ts`).
+
+## Tasks configuration
+
+Tasks are read from JSON files (an array of tasks, or `{"tasks": [...]}`):
+
+|File|Scope|
+|---|---|
+|`~/.pi/agent/do-always.json`|Global (all projects)|
+|`<project>/.pi/do-always.json`|Project-local; overrides global tasks with the same `name`|
+
+If neither file exists, the built-in defaults (review, readme, tests, commit, cleanup, release, security, perf) are used.
+This repo ships a sample in [`do-always.json`](./do-always.json) — copy it to one of the
+locations above to make it your own:
+
+```json
+[
+  {
+    "name": "review",
+    "description": "Review code and double-check changes",
+    "prompt": "Review the recent code changes in this project. Check `git status` and `git diff` ..."
+  }
+]
+```
+
+Fields:
+
+- `name` (required) — short unique id, used for `/do-always <name>`
+- `description` (optional) — one-line label shown in the selector
+- `prompt` (required) — the text filled into the editor
+
+Reload Pi (or start a new session) after editing a config file.
+
+## Development
+
+```bash
+npm install        # dev dependencies (pi packages + typescript)
+npm run typecheck  # tsc --noEmit
+npm test           # run the unit tests (node:test + tsx, in test/)
+```
+
+The pure task logic (`parseConfig`, `mergeTasks`, `resolveTask`, `formatList`) lives in
+[`tasks.ts`](./tasks.ts) with no Pi dependencies, so it is unit-tested independently of the
+Pi runtime. The extension (`index.ts`) imports that logic and adds only the Pi UI.
+
+No build step is needed — Pi loads the TypeScript directly via jiti.
+
+## Publishing
+
+To publish on npm:
+
+```bash
+npm login
+npm publish
+```
+
+`@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` are declared as `peerDependencies`
+with a `"*"` range and are **not** bundled — Pi supplies them to extensions. The `pi-package`
+keyword makes this package eligible for the [Pi package gallery](https://pi.dev/packages).

package/do-always.json

@@ -0,0 +1,42 @@
+[
+	{
+		"name": "review",
+		"description": "Review code and double-check changes",
+		"prompt": "Review the recent code changes in this project. Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Do a plan proposal for the fixes."
+	},
+	{
+		"name": "readme",
+		"description": "Update the README",
+		"prompt": "Update the README to match the current state of the project. Check the code, scripts, and configuration, then update the README sections that are now out of date (description, installation, usage, configuration). Keep it concise and accurate."
+	},
+	{
+		"name": "tests",
+		"description": "Run tests and fix failures",
+		"prompt": "Run the project's test suite (and type check / lint if available). If anything fails, diagnose and fix the failures, then re-run until green. Summarize the results."
+	},
+	{
+		"name": "commit",
+		"description": "Prepare a clean commit",
+		"prompt": "Prepare the working tree for a clean commit: review `git status` and `git diff`, stage the relevant changes, and write a clear commit message describing what changed and why. Do not push."
+	},
+	{
+		"name": "cleanup",
+		"description": "Propose a plan to clean up dead code and duplicates",
+		"prompt": "Scan the project for dead code, unused imports, commented-out blocks, and duplicated logic. Do a plan proposal for the removals and consolidations, keeping behavior unchanged. Do not make any changes yet."
+	},
+	{
+		"name": "release",
+		"description": "Prepare a release (version, changelog, tag)",
+		"prompt": "Prepare a release for this project: check `git log` since the last tag, update the version in package.json (or the equivalent location), add a changelog entry summarizing the changes, and create a git tag. Do not push."
+	},
+	{
+		"name": "security",
+		"description": "Security audit — plan proposal",
+		"prompt": "Audit this project for security issues: hardcoded secrets or credentials, unsafe patterns (injection, path traversal, unsafe deserialization), and vulnerable or outdated dependencies. Do a plan proposal for the fixes. Do not make any changes yet."
+	},
+	{
+		"name": "perf",
+		"description": "Performance review — plan proposal",
+		"prompt": "Review this project for likely performance bottlenecks: inefficient algorithms, redundant I/O or computation, missing caching, and memory leaks. Do a plan proposal for the optimizations, prioritized by impact. Do not make any changes yet."
+	}
+]

package/index.ts

@@ -0,0 +1,202 @@
+/**
+ * do-always — Pi extension
+ *
+ * Registers /do-always: shows a numbered list of common tasks
+ * ("review code and double-check changes", "update the README", ...).
+ * Pick one by number (press 1-9), or navigate with arrows + Enter.
+ * The selected task's prompt is filled into the input editor — review,
+ * tweak, then press Enter to run it.
+ *
+ * Config (JSON array of tasks; project file overrides global by name):
+ *   ~/.pi/agent/do-always.json   (global)
+ *   <cwd>/.pi/do-always.json     (project)
+ *
+ *   [
+ *     {
+ *       "name": "review",
+ *       "description": "Review code and double-check changes",
+ *       "prompt": "Review the recent changes..."
+ *     }
+ *   ]
+ *
+ * Usage:
+ *   /do-always         → numbered selector (or press Ctrl+Shift+P)
+ *   /do-always 2       → fill prompt for task #2
+ *   /do-always review  → fill prompt for task named "review"
+ *   /do-always list    → print the task list
+ *   /do-always list-details → show the full prompt text each task injects
+ *
+ * If no config file exists, built-in default tasks are used.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { Container, Key, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+import { DEFAULT_TASKS, formatList, mergeTasks, parseConfig, resolveTask, type DoAlwaysTask } from "./tasks";
+
+/**
+ * Load tasks from config files.
+ * Project-local tasks override global tasks with the same name; new ones are appended.
+ * Falls back to DEFAULT_TASKS when nothing is defined.
+ */
+function loadTasks(cwd: string): DoAlwaysTask[] {
+	const globalPath = join(getAgentDir(), "do-always.json");
+	const projectPath = join(cwd, CONFIG_DIR_NAME, "do-always.json");
+
+	const globalTasks = existsSync(globalPath) ? parseConfig(readFileSync(globalPath, "utf-8"), globalPath) : [];
+	const projectTasks = existsSync(projectPath) ? parseConfig(readFileSync(projectPath, "utf-8"), projectPath) : [];
+
+	return mergeTasks(globalTasks, projectTasks, DEFAULT_TASKS);
+}
+
+export default function doAlwaysExtension(pi: ExtensionAPI) {
+	let tasks: DoAlwaysTask[] = [];
+	let loadedCwd = ""; // cwd the cached `tasks` were loaded for
+
+	pi.on("session_start", async (_event, ctx) => {
+		loadedCwd = ctx.cwd;
+		tasks = loadTasks(ctx.cwd);
+	});
+
+	/** Put the task prompt into the editor (TUI) or send it as a user message (other modes). */
+	async function fillPrompt(task: DoAlwaysTask, ctx: ExtensionContext): Promise<void> {
+		if (ctx.mode === "tui") {
+			ctx.ui.setEditorText(task.prompt);
+			ctx.ui.notify(`do-always: prompt for "${task.name}" filled — press Enter to run`, "info");
+		} else {
+			await pi.sendUserMessage(task.prompt);
+		}
+	}
+
+	/** Numbered selector: press 1-9 to pick, or arrows + Enter, Esc to cancel. */
+	async function showSelector(ctx: ExtensionContext): Promise<void> {
+		const items: SelectItem[] = tasks.map((t, i) => ({
+			value: String(i),
+			label: `${i + 1}. ${t.name}`,
+			description: t.description,
+		}));
+
+		const selected = await ctx.ui.custom<number | null>((tui, theme, _kb, done) => {
+			let settled = false;
+			const finish = (value: number | null) => {
+				if (settled) return;
+				settled = true;
+				done(value);
+			};
+
+			const container = new Container();
+			container.addChild(new Text(theme.fg("accent", theme.bold("do-always — pick a task"))));
+
+			const selectList = new SelectList(items, Math.min(items.length, 10), {
+				selectedPrefix: (text) => theme.fg("accent", text),
+				selectedText: (text) => theme.fg("accent", text),
+				description: (text) => theme.fg("muted", text),
+				scrollInfo: (text) => theme.fg("dim", text),
+				noMatch: (text) => theme.fg("warning", text),
+			});
+			selectList.onSelect = (item) => finish(Number(item.value));
+			selectList.onCancel = () => finish(null);
+			container.addChild(selectList);
+			container.addChild(new Text(theme.fg("dim", "1-9 pick by number  •  ↑↓ navigate  •  enter select  •  esc cancel")));
+
+			return {
+				render(width: number) {
+					return container.render(width);
+				},
+				invalidate() {
+					container.invalidate();
+				},
+				handleInput(data: string) {
+					// Direct pick by number (1-9)
+					if (/^[1-9]$/.test(data) && Number(data) <= tasks.length) {
+						finish(Number(data) - 1);
+						return;
+					}
+					selectList.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		});
+
+		if (selected === null || selected === undefined) return;
+		await fillPrompt(tasks[selected], ctx);
+	}
+
+	pi.registerCommand("do-always", {
+		description: "Pick a common task (review, readme, ...) by number — fills the prompt",
+		getArgumentCompletions: (prefix) => {
+			const p = prefix.trim().toLowerCase();
+			const matches = [
+				{ value: "list", label: "list" },
+				{ value: "list-details", label: "list-details" },
+				...tasks.map((t, i) => ({ value: t.name, label: `${i + 1}. ${t.name}` })),
+			].filter((c) => c.value.toLowerCase().includes(p));
+			return matches.length > 0 ? matches : null;
+		},
+		handler: async (args, ctx) => {
+			await runDoAlways(args, ctx);
+		},
+	});
+
+	// Keyboard shortcut: open the task selector without typing the command.
+	pi.registerShortcut(Key.ctrlShift("p"), {
+		description: "do-always: pick a common task",
+		handler: async (ctx) => {
+			await runDoAlways("", ctx);
+		},
+	});
+
+	async function runDoAlways(args: string, ctx: ExtensionContext): Promise<void> {
+		// Reload when the active directory changes, so switching projects
+		// mid-session serves the right config instead of stale tasks.
+		if (ctx.cwd !== loadedCwd) {
+			loadedCwd = ctx.cwd;
+			tasks = loadTasks(ctx.cwd);
+		}
+
+		const arg = args.trim();
+
+		if (!arg) {
+			if (ctx.mode === "tui") {
+				await showSelector(ctx);
+			} else {
+				ctx.ui.notify(`do-always tasks (use /do-always <number|name>):\n${formatList(tasks)}`, "info");
+			}
+			return;
+		}
+
+		if (arg.toLowerCase() === "list") {
+			ctx.ui.notify(formatList(tasks), "info");
+			return;
+		}
+
+		if (arg.toLowerCase() === "list-details") {
+			// Display only — the description is metadata; selecting a task injects just its prompt.
+			const details = tasks
+				.map((t, i) => {
+					const lines = [`${i + 1}. ${t.name}`];
+					if (t.description) lines.push(`   description: ${t.description}`);
+					lines.push("   prompt (this is what gets injected on select):");
+					for (const line of t.prompt.split("\n")) lines.push(`   ${line}`);
+					return lines.join("\n");
+				})
+				.join("\n\n");
+			if (ctx.mode === "tui") {
+				await ctx.ui.editor("do-always — task details (only the prompt is injected; esc to close)", details);
+			} else {
+				ctx.ui.notify(details, "info");
+			}
+			return;
+		}
+
+		const task = resolveTask(tasks, arg);
+		if (!task) {
+			const available = tasks.map((t, i) => `${i + 1}=${t.name}`).join(", ");
+			ctx.ui.notify(`do-always: unknown task "${arg}". Available: ${available}`, "error");
+			return;
+		}
+		await fillPrompt(task, ctx);
+	}
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "pi-do-always",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "Pi extension: /do-always — pick a common task by number, it fills your prompt",
+	"keywords": [
+		"pi-package",
+		"pi-extensions",
+		"do-always"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/aginies/pi-always"
+	},
+	"homepage": "https://github.com/aginies/pi-always",
+	"bugs": {
+		"url": "https://github.com/aginies/pi-always/issues"
+	},
+	"files": [
+		"index.ts",
+		"tasks.ts",
+		"do-always.json",
+		"README.md"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"scripts": {
+		"dev": "pi --extension ./index.ts",
+		"typecheck": "tsc --noEmit",
+		"test": "node --import tsx --test test/**/*.test.ts"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "^0.87.1",
+		"@earendil-works/pi-tui": "^0.87.1",
+		"@types/node": "^22.0.0",
+		"tsx": "^4.19.0",
+		"typescript": "^5.5.0"
+	}
+}

package/tasks.ts

@@ -0,0 +1,143 @@
+/**
+ * do-always — pure task logic (no Pi dependencies).
+ *
+ * Kept separate from index.ts so it can be unit-tested without the Pi runtime.
+ */
+
+export interface DoAlwaysTask {
+	/** Short unique name, usable as /do-always <name> */
+	name: string;
+	/** Short one-line description shown next to the task in the selector */
+	description?: string;
+	/** Prompt filled into the editor when the task is selected */
+	prompt: string;
+}
+
+/** A config file can be a bare array of tasks, or {"tasks": [...]}. */
+export type DoAlwaysConfig = DoAlwaysTask[] | { tasks: DoAlwaysTask[] };
+
+/** Used when neither config file defines any task. */
+export const DEFAULT_TASKS: DoAlwaysTask[] = [
+	{
+		name: "review",
+		description: "Review code and double-check changes",
+		prompt:
+			"Review the recent code changes in this project. Check `git status` and `git diff` to see what changed, then double-check the changes for bugs, edge cases, security issues, and consistency with the rest of the codebase. Do a plan proposal for the fixes.",
+	},
+	{
+		name: "readme",
+		description: "Update the README",
+		prompt:
+			"Update the README to match the current state of the project. Check the code, scripts, and configuration, then update the README sections that are now out of date (description, installation, usage, configuration). Keep it concise and accurate.",
+	},
+	{
+		name: "tests",
+		description: "Run tests and fix failures",
+		prompt:
+			"Run the project's test suite (and type check / lint if available). If anything fails, diagnose and fix the failures, then re-run until green. Summarize the results.",
+	},
+	{
+		name: "commit",
+		description: "Prepare a clean commit",
+		prompt:
+			"Prepare the working tree for a clean commit: review `git status` and `git diff`, stage the relevant changes, and write a clear commit message describing what changed and why. Do not push.",
+	},
+	{
+		name: "cleanup",
+		description: "Propose a plan to clean up dead code and duplicates",
+		prompt:
+			"Scan the project for dead code, unused imports, commented-out blocks, and duplicated logic. Do a plan proposal for the removals and consolidations, keeping behavior unchanged. Do not make any changes yet.",
+	},
+	{
+		name: "release",
+		description: "Prepare a release (version, changelog, tag)",
+		prompt:
+			"Prepare a release for this project: check `git log` since the last tag, update the version in package.json (or the equivalent location), add a changelog entry summarizing the changes, and create a git tag. Do not push.",
+	},
+	{
+		name: "security",
+		description: "Security audit — plan proposal",
+		prompt:
+			"Audit this project for security issues: hardcoded secrets or credentials, unsafe patterns (injection, path traversal, unsafe deserialization), and vulnerable or outdated dependencies. Do a plan proposal for the fixes. Do not make any changes yet.",
+	},
+	{
+		name: "perf",
+		description: "Performance review — plan proposal",
+		prompt:
+			"Review this project for likely performance bottlenecks: inefficient algorithms, redundant I/O or computation, missing caching, and memory leaks. Do a plan proposal for the optimizations, prioritized by impact. Do not make any changes yet.",
+	},
+];
+
+/**
+ * Parse and validate a config file's contents.
+ * Accepts a bare array of tasks or {"tasks": [...]}. Invalid entries are skipped with a warning.
+ * Returns [] when the JSON is malformed or the shape is wrong.
+ */
+export function parseConfig(
+	raw: string,
+	path: string,
+	onError: (message: string) => void = () => {},
+): DoAlwaysTask[] {
+	let data: DoAlwaysConfig;
+	try {
+		data = JSON.parse(raw);
+	} catch (err) {
+		onError(`do-always: invalid JSON in ${path}: ${err}`);
+		return [];
+	}
+
+	const list = Array.isArray(data) ? data : data?.tasks;
+
+	if (!Array.isArray(list)) {
+		onError(`do-always: ${path} must be a JSON array of tasks or {"tasks": [...]}`);
+		return [];
+	}
+
+	const tasks: DoAlwaysTask[] = [];
+	for (const entry of list) {
+		const t = entry as Partial<DoAlwaysTask> | null;
+		if (t && typeof t.name === "string" && t.name.length > 0 && typeof t.prompt === "string" && t.prompt.length > 0) {
+			tasks.push({
+				name: t.name,
+				description: typeof t.description === "string" ? t.description : undefined,
+				prompt: t.prompt,
+			});
+		} else {
+			onError(`do-always: skipping invalid task in ${path} (each task needs "name" and "prompt")`);
+		}
+	}
+	return tasks;
+}
+
+/**
+ * Merge project-local tasks over global tasks.
+ * A project task with a name matching a global task replaces it; new names are appended.
+ * Returns fallback when the merged result is empty.
+ */
+export function mergeTasks(globalTasks: DoAlwaysTask[], projectTasks: DoAlwaysTask[], fallback: DoAlwaysTask[]): DoAlwaysTask[] {
+	const merged = [...globalTasks];
+	for (const task of projectTasks) {
+		const idx = merged.findIndex((t) => t.name === task.name);
+		if (idx >= 0) merged[idx] = task;
+		else merged.push(task);
+	}
+	return merged.length > 0 ? merged : fallback;
+}
+
+/**
+ * Resolve a task from a command argument: by number (1-based) or by name (case-insensitive).
+ */
+export function resolveTask(tasks: DoAlwaysTask[], arg: string): DoAlwaysTask | undefined {
+	const a = arg.trim();
+	if (!a) return undefined;
+	if (/^\d+$/.test(a)) {
+		const n = Number(a);
+		return n >= 1 && n <= tasks.length ? tasks[n - 1] : undefined;
+	}
+	return tasks.find((t) => t.name.toLowerCase() === a.toLowerCase());
+}
+
+/** Render a numbered, one-line-per-task list. */
+export function formatList(tasks: DoAlwaysTask[]): string {
+	return tasks.map((t, i) => `${i + 1}. ${t.name} — ${t.description ?? ""}`).join("\n");
+}