pi-do-always 0.18.0 → 0.19.0

package/README.md

@@ -11,6 +11,26 @@ type to filter, scroll or click, or navigate with arrows + Enter → the task's
 
 ![do-always — the numbered task selector](pi.image.png)
 
+## Install
+
+Install it from npm as a Pi package, which loads the bundled `index.ts` (and its `tasks.ts`) without
+managing symlinks:
+
+```bash
+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 npm:pi-do-always`).
+
+Alternatively, you can install from the git repo or symlink a local checkout for development:
+
+```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 ./extensions/pi-do-always/index.ts`).
+
 ## Usage
 
 |Command|What it does|
@@ -199,26 +219,6 @@ notification instead, so you can reply with the item numbers to execute. The
 questionnaire is offered only on the single auto-run path (selector pick,
 `/do-always <n>`, commit picker) — chain steps never get it.
 
-## Install
-
-Install it from npm as a Pi package, which loads the bundled `index.ts` (and its `tasks.ts`) without
-managing symlinks:
-
-```bash
-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 npm:pi-do-always`).
-
-Alternatively, you can install from the git repo or symlink a local checkout for development:
-
-```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 ./extensions/pi-do-always/index.ts`).
-
 ## Tasks configuration
 
 Tasks are read from JSON files (an array of tasks, or the object form `{"tasks": [...], "shortcut": "f4"}`):
@@ -246,6 +246,7 @@ locations above to make it your own:
 Fields:
 
 - `name` (required) — short unique id, used for `/do-always <name>`
+- `aliases` (optional) — an array of short names that also resolve to this task on the command line. Each alias is case-insensitive and is tried before the task's own name, so `/do-always r` can stand in for `/do-always review`. An invalid value (not an array of strings) is ignored with a warning.
 - `category` (optional) — group header the task is shown under in the selector (e.g. `"Plan"`, `"Do"`). Matching is case-insensitive and the header is title-cased, so `"plan"` and `"Plan"` land in the same `Plan` group. Tasks without a category fall under `Other`. The built-in defaults are grouped into `Plan`, `Browse`, `Do`, `Docs`, and `Ops`.
 - `description` (optional) — one-line label shown in the selector
 - `prompt` (required) — the text filled into the editor (supports `{{placeholders}}` — see [Prompt placeholders](#prompt-placeholders))
@@ -265,6 +266,14 @@ In the object form you can also configure the selector shortcut:
 - `report` (optional) — whether chain runs write a Markdown report file in the project root (one per run, appended as each step finishes). Default `true`; set `false` to disable. The project file's value wins over the global one. See [Chains](#chains).
 - `questionnaire` (optional) — whether completed auto-run tasks whose reply carries a plan block offer the selection questionnaire. Default `true`; set `false` to keep the plain summary notification. The project file's value wins over the global one. See [Plan questionnaire](#plan-questionnaire).
 - `hidePlan` (optional) — whether the raw `plan` block is stripped from the transcript after a completed auto-run task (TUI only — in non-TUI modes the block is always kept). Default `true`; set `false` to keep the block visible in the conversation. The project file's value wins over the global one.
+- `aliases` (optional) — a global alias map: an object that maps short alias strings to task names, e.g. `{ "rc": "Review changes", "bl": "Build" }`. Each alias is case-insensitive and is tried before the task's own name, so `/do-always rc` resolves to the task named `Review changes`. Keys and values are trimmed; entries with empty keys or non-string values are silently dropped. The project file's value wins over the global one.
+
+```json
+{
+  "tasks": [ { "name": "review", "prompt": "…" } ],
+  "aliases": { "r": "review", "rc": "review changes" }
+}
+```
 
 Example project file that only *adds* tasks without overriding the global set:
 

package/extensions/pi-do-always/do-always.json

@@ -61,7 +61,7 @@
 			"name": "Build",
 			"category": "Do",
 			"description": "Test build is ok and fix issues",
-			"prompt": "Build the project (run the build script, e.g. `npm run build`, plus type check if available). If the build fails, diagnose the errors and fix them, then re-build until it succeeds. Summarize what was broken and what you changed."
+			"prompt": "Build the project (run the project's build command — e.g. `npm run build`, `cargo build`, `go build`, `make`, `mvn package`; find the build entry point — plus type check if available). If the build fails, diagnose the errors and fix them, then re-build until it succeeds. Summarize what was broken and what you changed."
 		},
 		{
 			"name": "Tests",
@@ -73,14 +73,14 @@
 			"name": "Readme",
 			"category": "Docs",
 			"description": "Update the README.md",
-			"prompt": "Update the README.md to match the current state of the project. Check the code, scripts, and configuration, then update the README.md sections that are now out of date (description, installation, usage, configuration). Keep it concise and accurate."
+			"prompt": "Update the project's README (e.g. README.md) 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": "Release",
 			"category": "Ops",
 			"description": "Prepare a release (version, changelog, tag)",
 			"when": "git",
-			"prompt": "Prepare a release for this project (branch {{branch}}): check `git log` since the last tag, then bump the version in package.json (or the equivalent location) to the next version, and add a changelog entry under that exact version summarizing the changes. The changelog entry must use the same version number now set in package.json — never add a changelog section for a version that package.json does not yet contain, and never leave an 'Unreleased' or placeholder version heading. Create a git tag if git present. Do not push."
+			"prompt": "Prepare a release for this project (branch {{branch}}): check `git log` since the last tag, then bump the project's version to the next version in its version manifest (e.g. package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml — find where the current version is declared), and add a changelog entry under that exact version summarizing the changes (in the project's changelog file, e.g. CHANGELOG.md). The changelog entry must use the same version number now set in the version manifest — never add a changelog section for a version the manifest does not yet contain, and never leave an 'Unreleased' or placeholder version heading. Create a git tag if git present. Do not push."
 		},
 		{
 			"name": "Commit",

package/extensions/pi-do-always/tasks.ts

@@ -86,6 +86,14 @@ export interface DoAlwaysTask {
 	 * category by default).
 	 */
 	hidePlan?: boolean;
+	/**
+	 * Short names that resolve to this task on the command line. Each alias
+	 * is case-insensitive and is tried before the task's own name. Aliases
+	 * must be single words (no spaces) and must not collide with other
+	 * tasks' aliases or names (a collision is silently resolved to the
+	 * first-encountered task).
+	 */
+	aliases?: string[];
 }
 
 /** The set of known guard types (used for validation at parse time). */
@@ -147,6 +155,13 @@ type DoAlwaysConfig =
 			 * block visible in the transcript.
 			 */
 			hidePlan?: boolean;
+			/**
+			 * A global alias map: `{ "rc": "Review changes" }` maps a short
+			 * alias string to a task name. Aliases are case-insensitive and
+			 * are tried before the task's own name. Invalid entries (non-string
+			 * values, empty keys) are silently ignored.
+			 */
+			aliases?: Record<string, string>;
 		};
 
 /** Shortcut used when neither config file specifies one. */
@@ -182,6 +197,11 @@ interface ParsedDoAlwaysConfig {
 	 * undefined when the file does not set one (default: on).
 	 */
 	hidePlan: boolean | undefined;
+	/**
+	 * A global alias map parsed from the config object: `{ "rc": "Review changes" }`.
+	 * undefined when the file does not set one.
+	 */
+	aliases: Record<string, string> | undefined;
 }
 
 import { existsSync } from "node:fs";
@@ -426,14 +446,14 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		category: "Docs",
 		description: "Update the README.md",
 		prompt:
-			"Update the README.md to match the current state of the project. Check the code, scripts, and configuration, then update the README.md sections that are now out of date (description, installation, usage, configuration). Keep it concise and accurate.",
+			"Update the project's README (e.g. README.md) 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: "Build",
 		category: "Do",
 		description: "Test build is ok and fix issues",
 		prompt:
-			"Build the project (run the build script, e.g. `npm run build`, plus type check if available). If the build fails, diagnose the errors and fix them, then re-build until it succeeds. Summarize what was broken and what you changed.",
+			"Build the project (run the project's build command — e.g. `npm run build`, `cargo build`, `go build`, `make`, `mvn package`; find the build entry point — plus type check if available). If the build fails, diagnose the errors and fix them, then re-build until it succeeds. Summarize what was broken and what you changed.",
 	},
 	{
 		name: "Security",
@@ -462,7 +482,7 @@ export const DEFAULT_TASKS: DoAlwaysTask[] = [
 		description: "Prepare a release (version, changelog, tag)",
 		when: "git",
 		prompt:
-			"Prepare a release for this project (branch {{branch}}): check `git log` since the last tag, then bump the version in package.json (or the equivalent location) to the next version, and add a changelog entry under that exact version summarizing the changes. The changelog entry must use the same version number now set in package.json — never add a changelog section for a version that package.json does not yet contain, and never leave an 'Unreleased' or placeholder version heading. Create a git tag if git present. Do not push.",
+			"Prepare a release for this project (branch {{branch}}): check `git log` since the last tag, then bump the project's version to the next version in its version manifest (e.g. package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml — find where the current version is declared), and add a changelog entry under that exact version summarizing the changes (in the project's changelog file, e.g. CHANGELOG.md). The changelog entry must use the same version number now set in the version manifest — never add a changelog section for a version the manifest does not yet contain, and never leave an 'Unreleased' or placeholder version heading. Create a git tag if git present. Do not push.",
 	},
 	{
 		name: "Commit",
@@ -518,14 +538,14 @@ export function parseConfig(
 		data = JSON.parse(raw);
 	} catch (err) {
 		onError(`do-always: invalid JSON in ${path}: ${err}`);
-		return { tasks: [], shortcut: undefined, report: undefined, questionnaire: undefined, hidePlan: undefined };
+		return { tasks: [], shortcut: undefined, report: undefined, questionnaire: undefined, hidePlan: undefined, aliases: 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 { tasks: [], shortcut: undefined, report: undefined, questionnaire: undefined, hidePlan: undefined };
+		return { tasks: [], shortcut: undefined, report: undefined, questionnaire: undefined, hidePlan: undefined, aliases: undefined };
 	}
 
 	const tasks: DoAlwaysTask[] = [];
@@ -544,6 +564,13 @@ export function parseConfig(
 				if (typeof t.notForCommits === "boolean") task.notForCommits = t.notForCommits;
 				if (typeof t.questionnaire === "boolean") task.questionnaire = t.questionnaire;
 				if (typeof t.hidePlan === "boolean") task.hidePlan = t.hidePlan;
+				if (t.aliases !== undefined) {
+					if (Array.isArray(t.aliases) && t.aliases.every((a) => typeof a === "string")) {
+						task.aliases = t.aliases.filter((a) => a.trim() !== "");
+					} else {
+						onError(`do-always: ignoring invalid "aliases" in ${path} (expected an array of strings)`);
+					}
+				}
 				if (t.browser !== undefined) {
 					if (typeof t.browser === "string" && BROWSER_TYPES.includes(t.browser as BrowserType)) {
 						task.browser = t.browser as BrowserType;
@@ -602,8 +629,20 @@ export function parseConfig(
 		if (typeof data.hidePlan === "boolean") hidePlan = data.hidePlan;
 		else onError(`do-always: ignoring invalid "hidePlan" in ${path} (expected true or false)`);
 	}
+	let aliases: Record<string, string> | undefined;
+	if (!Array.isArray(data) && "aliases" in data) {
+		if (typeof data.aliases === "object" && data.aliases !== null && !Array.isArray(data.aliases)) {
+			const map: Record<string, string> = {};
+			for (const [k, v] of Object.entries(data.aliases)) {
+				if (typeof k === "string" && k.trim() !== "" && typeof v === "string") {
+					map[k.trim()] = v.trim();
+				}
+			}
+			if (Object.keys(map).length > 0) aliases = map;
+		}
+	}
 
-	return { tasks, shortcut, merge, report, questionnaire, hidePlan };
+	return { tasks, shortcut, merge, report, questionnaire, hidePlan, aliases };
 }
 
 const KEY_MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
@@ -996,7 +1035,11 @@ export function resolveTask(tasks: DoAlwaysTask[], arg: string): DoAlwaysTask |
 		const n = Number(a);
 		return n >= 1 && n <= tasks.length ? tasks[n - 1] : undefined;
 	}
-	return tasks.find((t) => t.name.toLowerCase() === a.toLowerCase());
+	// Try aliases first (case-insensitive), then the task's own name.
+	const lower = a.toLowerCase();
+	const aliasMatch = tasks.find((t) => t.aliases?.some((alias) => alias.toLowerCase() === lower));
+	if (aliasMatch) return aliasMatch;
+	return tasks.find((t) => t.name.toLowerCase() === lower);
 }
 
 /** Matches a `{{key}}` placeholder: key is [A-Za-z0-9_]+, optional inner whitespace. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-do-always",
-	"version": "0.18.0",
+	"version": "0.19.0",
 	"type": "module",
 	"description": "Pi extension: /do-always — pick a common task by number, it fills your prompt",
 	"author": {