pi-do-always 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aginies
+
+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

@@ -23,7 +23,7 @@ the task's prompt is **filled into the input editor**. Review it, tweak it, pres
 
 |Command|What it does|
 |---|---|
-|`/do-always` or `Ctrl+Shift+P`|Show the numbered task selector|
+|`/do-always` or the shortcut key (default `F4`)|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|
@@ -56,7 +56,7 @@ For development you can also load it explicitly: `npm run dev` (runs `pi --exten
 
 ## Tasks configuration
 
-Tasks are read from JSON files (an array of tasks, or `{"tasks": [...]}`):
+Tasks are read from JSON files (an array of tasks, or the object form `{"tasks": [...], "shortcut": "f4"}`):
 
 |File|Scope|
 |---|---|
@@ -83,6 +83,10 @@ Fields:
 - `description` (optional) — one-line label shown in the selector
 - `prompt` (required) — the text filled into the editor
 
+In the object form you can also configure the selector shortcut:
+
+- `shortcut` (optional) — key that opens the selector, e.g. `"f4"` or `"ctrl+shift+p"`. Set to `null` to disable the shortcut. Defaults to `F4`. The project file's value wins over the global one.
+
 Reload Pi (or start a new session) after editing a config file.
 
 ## Development
@@ -111,3 +115,7 @@ 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).
+
+The gallery page is built from `package.json` (name, description, author, version, license,
+repository, `pi` manifest) plus the README. Optional `pi.image` / `pi.video` fields in
+`package.json` add a gallery preview if you want one.

package/do-always.json

@@ -1,42 +1,45 @@
-[
-	{
-		"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."
-	}
-]
+{
+	"shortcut": "f4",
+	"tasks": [
+		{
+			"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

@@ -7,7 +7,8 @@
  * 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):
+ * Config (JSON array of tasks, or {"tasks": [...], "shortcut": "f4" | null};
+ * project file overrides global by name):
  *   ~/.pi/agent/do-always.json   (global)
  *   <cwd>/.pi/do-always.json     (project)
  *
@@ -19,8 +20,11 @@
  *     }
  *   ]
  *
+ * The object form also accepts "shortcut": a key id (e.g. "f4",
+ * "ctrl+shift+p") or null to disable the keyboard shortcut. Default: F4.
+ *
  * Usage:
- *   /do-always         → numbered selector (or press Ctrl+Shift+P)
+ *   /do-always         → numbered selector (or press the configured shortcut, default F4)
  *   /do-always 2       → fill prompt for task #2
  *   /do-always review  → fill prompt for task named "review"
  *   /do-always list    → print the task list
@@ -33,22 +37,39 @@ 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";
+import { Container, type KeyId, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+import {
+	DEFAULT_SHORTCUT,
+	DEFAULT_TASKS,
+	formatList,
+	isValidKeyId,
+	mergeTasks,
+	parseConfig,
+	resolveShortcut,
+	resolveTask,
+	type DoAlwaysTask,
+} from "./tasks";
 
 /**
- * Load tasks from config files.
+ * Load tasks and the selector shortcut 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[] {
+function loadConfig(cwd: string): { tasks: DoAlwaysTask[]; shortcut: string | null } {
 	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);
+	const global = existsSync(globalPath)
+		? parseConfig(readFileSync(globalPath, "utf-8"), globalPath)
+		: { tasks: [], shortcut: undefined };
+	const project = existsSync(projectPath)
+		? parseConfig(readFileSync(projectPath, "utf-8"), projectPath)
+		: { tasks: [], shortcut: undefined };
+
+	return {
+		tasks: mergeTasks(global.tasks, project.tasks, DEFAULT_TASKS),
+		shortcut: resolveShortcut(global.shortcut, project.shortcut),
+	};
 }
 
 export default function doAlwaysExtension(pi: ExtensionAPI) {
@@ -57,7 +78,7 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		loadedCwd = ctx.cwd;
-		tasks = loadTasks(ctx.cwd);
+		tasks = loadConfig(ctx.cwd).tasks;
 	});
 
 	/** Put the task prompt into the editor (TUI) or send it as a user message (other modes). */
@@ -141,19 +162,29 @@ export default function doAlwaysExtension(pi: ExtensionAPI) {
 	});
 
 	// 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);
-		},
-	});
+	// The key is configurable via the "shortcut" field in do-always.json
+	// (null disables it). It is read once at extension load, so changing it
+	// requires a reload or a new session.
+	const configuredShortcut = loadConfig(process.cwd()).shortcut;
+	if (configuredShortcut !== null) {
+		const shortcutKey = isValidKeyId(configuredShortcut) ? configuredShortcut : DEFAULT_SHORTCUT;
+		if (shortcutKey !== configuredShortcut) {
+			console.warn(`do-always: invalid shortcut "${configuredShortcut}" in do-always.json — using ${DEFAULT_SHORTCUT}`);
+		}
+		pi.registerShortcut(shortcutKey as KeyId, {
+			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);
+			tasks = loadConfig(ctx.cwd).tasks;
 		}
 
 		const arg = args.trim();

package/package.json

@@ -1,10 +1,16 @@
 {
 	"name": "pi-do-always",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"type": "module",
 	"description": "Pi extension: /do-always — pick a common task by number, it fills your prompt",
+	"author": {
+		"name": "aginies",
+		"email": "antoine@ginies.org"
+	},
 	"keywords": [
 		"pi-package",
+		"pi",
+		"pi-coding-agent",
 		"pi-extensions",
 		"do-always"
 	],

package/tasks.ts

@@ -13,8 +13,25 @@ export interface DoAlwaysTask {
 	prompt: string;
 }
 
-/** A config file can be a bare array of tasks, or {"tasks": [...]}. */
-export type DoAlwaysConfig = DoAlwaysTask[] | { tasks: DoAlwaysTask[] };
+/**
+ * A config file can be a bare array of tasks, or {"tasks": [...], "shortcut": ...}.
+ * `shortcut` is a key id string (e.g. "f4", "ctrl+shift+p"), or null to disable
+ * the keyboard shortcut.
+ */
+export type DoAlwaysConfig = DoAlwaysTask[] | { tasks: DoAlwaysTask[]; shortcut?: string | null };
+
+/** Shortcut used when neither config file specifies one. */
+export const DEFAULT_SHORTCUT = "f4";
+
+/** Result of parsing a config file. */
+export interface ParsedDoAlwaysConfig {
+	tasks: DoAlwaysTask[];
+	/**
+	 * The `shortcut` field, if present: a key id string, null when explicitly
+	 * disabled, undefined when the file does not set one.
+	 */
+	shortcut: string | null | undefined;
+}
 
 /** Used when neither config file defines any task. */
 export const DEFAULT_TASKS: DoAlwaysTask[] = [
@@ -70,27 +87,28 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 
 /**
  * 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.
+ * Accepts a bare array of tasks or {"tasks": [...], "shortcut": "f4" | null}.
+ * Invalid entries are skipped with a warning.
+ * Returns empty results when the JSON is malformed or the shape is wrong.
  */
 export function parseConfig(
 	raw: string,
 	path: string,
 	onError: (message: string) => void = () => {},
-): DoAlwaysTask[] {
+): ParsedDoAlwaysConfig {
 	let data: DoAlwaysConfig;
 	try {
 		data = JSON.parse(raw);
 	} catch (err) {
 		onError(`do-always: invalid JSON in ${path}: ${err}`);
-		return [];
+		return { tasks: [], shortcut: undefined };
 	}
 
 	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 [];
+		return { tasks: [], shortcut: undefined };
 	}
 
 	const tasks: DoAlwaysTask[] = [];
@@ -106,7 +124,52 @@ export function parseConfig(
 			onError(`do-always: skipping invalid task in ${path} (each task needs "name" and "prompt")`);
 		}
 	}
-	return tasks;
+
+	let shortcut: string | null | undefined;
+	if (!Array.isArray(data) && "shortcut" in data) {
+		const s = data.shortcut;
+		if (s === null) shortcut = null;
+		else if (typeof s === "string") shortcut = s.trim() === "" ? null : s.trim();
+		else onError(`do-always: ignoring invalid "shortcut" in ${path} (expected a key string or null)`);
+	}
+
+	return { tasks, shortcut };
+}
+
+const KEY_MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+const KEY_SPECIALS = new Set([
+	"escape", "esc", "enter", "return", "tab", "space", "backspace", "delete",
+	"insert", "clear", "home", "end", "pageup", "pagedown", "up", "down",
+	"left", "right", "f1", "f2", "f3", "f4", "f5", "f6", "f7", "f8", "f9",
+	"f10", "f11", "f12",
+]);
+
+/**
+ * Check whether a string is a valid key id (e.g. "f4", "ctrl+shift+p").
+ * Mirrors the KeyId syntax: optional ctrl/shift/alt/super modifiers (each at
+ * most once) followed by a base key (letter, digit, or special key).
+ */
+export function isValidKeyId(key: string): boolean {
+	const parts = key.toLowerCase().split("+");
+	const base = parts[parts.length - 1];
+	if (!base) return false;
+	if (!(/^[a-z0-9]$/.test(base) || KEY_SPECIALS.has(base))) return false;
+	const mods = parts.slice(0, -1);
+	return mods.every((m) => KEY_MODIFIERS.has(m)) && new Set(mods).size === mods.length;
+}
+
+/**
+ * Resolve the shortcut from global and project config. A value present in the
+ * project file wins (null disables); otherwise the global value; otherwise
+ * DEFAULT_SHORTCUT.
+ */
+export function resolveShortcut(
+	globalShortcut: string | null | undefined,
+	projectShortcut: string | null | undefined,
+): string | null {
+	if (projectShortcut !== undefined) return projectShortcut;
+	if (globalShortcut !== undefined) return globalShortcut;
+	return DEFAULT_SHORTCUT;
 }
 
 /**