pi-project-switcher 0.4.0 → 0.6.0

package/README.md

@@ -4,12 +4,17 @@ A [pi coding agent](https://github.com/earendil-works/pi) extension to switch be
 
 ## What it does
 
-- **`/project`** — list all projects (direct subdirectories of the base dir) with git branch info, mark the active one
+- **`/project`** — list all projects (direct subdirectories of the base dir) with git branch info, mark the active one. The output adapts to the surface:
+  - **native TUI**: a selection dialog; picking a project switches to it (dismissing shows the plain list)
+  - **Telegram bridge**: the reply in the chat shows one tappable button per project; clicking a button is exactly like typing `/project <name>`
+  - **other surfaces** (rpc/json/print): plain text list
+  - Note: for the Telegram buttons to work, this extension must be loaded **before** `pi-telegram-command-bridge` (package order in `~/.pi/agent/settings.json`) — the switcher needs to see the raw `[telegram] /project` dispatch before the bridge re-dispatches it.
 - **`/project <name>`** — switch the active project:
   - restores the project's last session if one is stored (see below)
   - persists across reloads (session entry)
   - sets the session display name
   - injects the project path into every agent turn's system prompt, so file operations default to the active project
+  - **if the project doesn't exist yet**, offers to create the folder and switch to it (confirmation dialog on dialog-capable surfaces; use `/project <name>!` to skip the dialog — e.g. on headless/RPC surfaces). Unsafe names (path segments, `..`, hidden, absolute) are never created.
 - **Session restore** — a machine-local map (`~/.pi/agent/project-switcher-sessions.json`) remembers the most recent session per project. Switching projects returns you to that project's last session; if none exists (or the file is gone), the switch happens in the current session.
 - **Auto-detection** — if pi starts inside `~/dev/<project>`, that project is active automatically
 
@@ -50,7 +55,7 @@ Single-file TypeScript extension (`index.ts`), loaded directly by pi via jiti
 
 ```bash
 npm install
-npm test        # vitest (17 tests)
+npm test        # vitest (45 tests)
 npm run typecheck
 
 # Run once without installing

package/index.ts

@@ -22,7 +22,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { execSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join, relative, resolve } from "node:path";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
 
 const HOME = homedir();
 const ENTRY_TYPE = "project-switcher-state";
@@ -173,6 +173,92 @@ function rememberSessionFile(project: string, absSessionFile: string): void {
 let activeProject: string | null = null;
 let config: Config | null = null;
 
+// ── Telegram origin detection (input event + flag) ───────────────────────────
+
+/**
+ * Matches a first line dispatched from the pi-telegram bridge: a
+ * `[telegram]` tag (optionally with attributes like `[telegram|thread:x]`)
+ * followed by a bare `/project` with no arguments.
+ */
+const TELEGRAM_STATUS_RE = /^\[telegram(?:\|[^\]]*)?\]\s*\/project\s*$/;
+
+/** How long an armed flag stays valid (ms). Guards against stale flags
+ *  from dispatches that never reached the command handler. */
+const TELEGRAM_FLAG_TTL_MS = 30_000;
+
+/** Armed-at timestamp of a pending Telegram-originated status request, or null. */
+let telegramStatusFlag: number | null = null;
+
+function armTelegramStatusFlag(): void {
+  telegramStatusFlag = Date.now();
+}
+
+/** Consume the flag: returns true (and clears it) when armed and not expired. */
+function consumeTelegramStatusFlag(): boolean {
+  if (telegramStatusFlag === null) return false;
+  const armed = telegramStatusFlag;
+  telegramStatusFlag = null;
+  return Date.now() - armed <= TELEGRAM_FLAG_TTL_MS;
+}
+
+function clearTelegramStatusFlag(): void {
+  telegramStatusFlag = null;
+}
+
+/**
+ * A project name that could alter button markup or the button prompt is
+ * rendered as plain list text only (never gets a button cell).
+ */
+function isUnsafeButtonName(name: string): boolean {
+  return /[{}|`\\\n]/.test(name);
+}
+
+/**
+ * Build the follow-up prompt for a Telegram-originated status request.
+ * Embeds the authoritative project list and a pre-rendered telegram_button
+ * block the agent copies verbatim into its reply.
+ */
+function buildTelegramStatusPrompt(projects: string[]): string {
+  const ordered = [...projects];
+  if (activeProject) {
+    const idx = ordered.indexOf(activeProject);
+    if (idx > 0) {
+      ordered.splice(idx, 1);
+      ordered.unshift(activeProject);
+    } else if (idx === -1) {
+      ordered.unshift(activeProject);
+    }
+  }
+
+  const listLines = ordered
+    .map((p) => `  ${p}${p === activeProject ? " ◀ active" : ""}`)
+    .join("\n");
+
+  const buttonCells = ordered
+    .filter((p) => !isUnsafeButtonName(p))
+    .map((p) =>
+      p === activeProject
+        ? `{✅ ${p} (active)|/project ${p}}`
+        : `{📁 ${p}|/project ${p}}`,
+    )
+    .join("\n");
+  const buttonBlock =
+    buttonCells.length > 0
+      ? "\n\n```telegram_button\n" + buttonCells + "\n```"
+      : "";
+
+  const current = activeProject ? `Active: ${activeProject}` : "No project active";
+
+  return (
+    `[project-switcher] The user ran /project via Telegram and expects the project list in the chat.\n` +
+    `Authoritative list (do not re-derive, do not add or remove entries):\n` +
+    `${current}\n\n${listLines}\n\n` +
+    `Reply in the chat with exactly this list (keep the active marker) followed by the button block below, ` +
+    `copied verbatim. Do not run any command, do not switch projects yourself, and add nothing else.${buttonBlock}`
+  );
+}
+
+
 function getConfig(): Config {
   if (!config) {
     config = loadConfig();
@@ -189,9 +275,50 @@ function isValidProject(name: string): boolean {
   return projects.includes(name);
 }
 
+/** True when a name is safe to materialize as a single directory under the base dir. */
+function isSafeProjectName(name: string): boolean {
+  if (!name || name === "." || name === "..") {
+    return false;
+  }
+  if (name.startsWith(".")) {
+    return false; // hidden
+  }
+  if (name.includes("/") || name.includes("\\")) {
+    return false; // no path segments
+  }
+  if (name.includes("..")) {
+    return false; // no traversal
+  }
+  if (isAbsolute(name)) {
+    return false; // absolute paths
+  }
+  return true;
+}
+
+/**
+ * Plain text project list via the local UI notification channel —
+ * the unchanged default output for non-Telegram surfaces.
+ */
+function notifyPlainProjectList(ctx: any, projects: string[]): void {
+  const current = activeProject ? `Active: ${activeProject}` : "No project active";
+  const lines = projects.map((p) => {
+    const branch = getGitBranch(projectPath(p));
+    const branchStr = branch ? ` [${branch}]` : "";
+    const marker = p === activeProject ? " ◀ active" : "";
+    return `  ${p}${branchStr}${marker}`;
+  });
+  ctx.ui.notify(
+    `${current}\n\nProjects under ${getConfig().baseDir}:\n${lines.join("\n")}`,
+    "info"
+  );
+}
+
 export default function (pi: ExtensionAPI) {
   // ── Restore state on session start ──────────────────────────────────────
   pi.on("session_start", async (_event, ctx) => {
+    // Session switches reset any pending Telegram status flag
+    clearTelegramStatusFlag();
+
     for (const entry of ctx.sessionManager.getEntries()) {
       if (
         entry.type === "custom" &&
@@ -224,6 +351,28 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
+  // ── Telegram origin detection (input event) ────────────────────────────────
+  //
+  // Prompts dispatched from the pi-telegram queue arrive with source
+  // "extension" and a `[telegram]`-tagged first line, BEFORE the command
+  // bridge re-dispatches the bare command line. Recognizing the raw
+  // dispatch here is the only reliable origin signal; the re-dispatched
+  // text is indistinguishable from a native TUI invocation.
+  //
+  // Requires this extension to be listed BEFORE the command bridge in the
+  // package order (the bridge's "handled" result would short-circuit the
+  // input chain before this handler runs otherwise). Wrong order degrades
+  // gracefully: the flag is never armed and the status falls back to the
+  // plain list.
+  pi.on("input", async (event) => {
+    if (event.source !== "extension") return;
+    const firstLine = event.text.split("\n", 1)[0];
+    if (TELEGRAM_STATUS_RE.test(firstLine.trim())) {
+      armTelegramStatusFlag();
+    }
+    // Never transform or handle: the command bridge owns the re-dispatch.
+  });
+
   // ── Inject project context into every agent turn ─────────────────────────
   pi.on("before_agent_start", async (event, _ctx) => {
     if (!activeProject || !isValidProject(activeProject)) {
@@ -242,43 +391,47 @@ export default function (pi: ExtensionAPI) {
     };
   });
 
-  // ── /project command ─────────────────────────────────────────────────────
-  pi.registerCommand("project", {
-    description: "Show or switch active project (/project [name])",
-
-    getArgumentCompletions: (prefix: string) => {
-      const projects = discoverProjects(getConfig().baseDir);
-      const filtered = projects.filter((p) => p.startsWith(prefix));
-      return filtered.length > 0
-        ? filtered.map((p) => ({ value: p, label: p }))
-        : null;
-    },
-
-    handler: async (args, ctx) => {
-      const name = args.trim();
+  // ── Shared switch flow ──────────────────────────────────────────────────
+  //
+  // Single implementation of /project <name> semantics, used by the typed
+  // argument path and the TUI selection dialog. `createOptIn` (trailing
+  // "!") only applies to the typed path; dialog users confirm interactively.
+  const switchToProject = async (rawName: string, ctx: any, createOptIn: boolean): Promise<void> => {
+    const name = rawName;
+
+    if (!isValidProject(name)) {
+      // Offer to create the folder and switch to it (never silently)
+      if (isSafeProjectName(name)) {
+        let create = false;
+        if (createOptIn) {
+          create = true;
+        } else if (ctx.hasUI) {
+          try {
+            create = await ctx.ui.confirm(
+              "Create project?",
+              `Project "${name}" does not exist. Create ${join(getConfig().baseDir, name)} and switch to it?`
+            );
+          } catch {
+            create = false;
+          }
+        }
 
-      // ── No arg: show status ──────────────────────────────────────────────
-      if (!name) {
-        const projects = discoverProjects(getConfig().baseDir);
-        if (projects.length === 0) {
-          ctx.ui.notify(
-            `No projects found under ${getConfig().baseDir}. Set PI_PROJECT_SWITCHER_BASE or create the settings file.`,
-            "warning"
-          );
-          return;
+        if (create) {
+          const newPath = projectPath(name);
+          try {
+            mkdirSync(newPath, { recursive: false });
+            ctx.ui.notify(`Created project folder: ${newPath}`, "info");
+          } catch (err: any) {
+            ctx.ui.notify(
+              `Failed to create project folder ${newPath}: ${err?.message ?? err}`,
+              "error"
+            );
+            return;
+          }
+          // fall through: the folder now exists and the switch proceeds below
         }
-        const current = activeProject ? `Active: ${activeProject}` : "No project active";
-        const lines = projects.map((p) => {
-          const branch = getGitBranch(projectPath(p));
-          const branchStr = branch ? ` [${branch}]` : "";
-          const marker = p === activeProject ? " ◀ active" : "";
-          return `  ${p}${branchStr}${marker}`;
-        });
-        ctx.ui.notify(`${current}\n\nProjects under ${getConfig().baseDir}:\n${lines.join("\n")}`, "info");
-        return;
       }
 
-      // ── Switch project ────────────────────────────────────────────────────
       if (!isValidProject(name)) {
         const available = discoverProjects(getConfig().baseDir).join(", ");
         ctx.ui.notify(
@@ -287,88 +440,157 @@ export default function (pi: ExtensionAPI) {
         );
         return;
       }
+    }
 
-      if (name === activeProject) {
-        ctx.ui.notify(`Already on project: ${name}`, "info");
-        return;
-      }
-
-      const previous = activeProject;
-
-      // Remember the current session under the PREVIOUS project before switching
-      const currentSessionFile = ctx.sessionManager.getSessionFile();
-      if (previous && currentSessionFile) {
-        rememberSessionFile(previous, currentSessionFile);
-      }
+    if (name === activeProject) {
+      ctx.ui.notify(`Already on project: ${name}`, "info");
+      return;
+    }
 
-      // Try to restore the target project's last session
-      const targetSession = getMappedSessionFile(name);
+    const previous = activeProject;
 
-      if (targetSession) {
-        // Persist the switch in the OLD session before replacing it
-        pi.appendEntry(ENTRY_TYPE, { project: name, switchedAt: new Date().toISOString() });
+    // Remember the current session under the PREVIOUS project before switching
+    const currentSessionFile = ctx.sessionManager.getSessionFile();
+    if (previous && currentSessionFile) {
+      rememberSessionFile(previous, currentSessionFile);
+    }
 
-        const result = await ctx.switchSession(targetSession);
-        if (result.cancelled) {
-          // User cancelled; roll back in-memory state
-          activeProject = previous;
-          ctx.ui.notify(`Switch cancelled. Staying on ${previous ?? "no project"}.`, "info");
-          return;
-        }
+    // Try to restore the target project's last session
+    const targetSession = getMappedSessionFile(name);
 
-        // switchSession fires a new session_start, which restores state from
-        // the target session's entries (or auto-detects). Set it explicitly as
-        // a safety net in case the session has no project entry yet.
-        activeProject = name;
-        pi.setSessionName(name);
-        rememberSessionFile(name, targetSession);
+    if (targetSession) {
+      // Persist the switch in the OLD session before replacing it
+      pi.appendEntry(ENTRY_TYPE, { project: name, switchedAt: new Date().toISOString() });
 
-        const path = projectPath(name);
-        const branch = getGitBranch(path);
-        const branchStr = branch ? ` on branch \`${branch}\`` : "";
-        ctx.ui.notify(
-          `Switched to ${name} — session restored: ${basename(targetSession)}\n` +
-          `Workdir: ${path}${branchStr ? ` ${branchStr}` : ""}`,
-          "info"
-        );
+      const result = await ctx.switchSession(targetSession);
+      if (result.cancelled) {
+        // User cancelled; roll back in-memory state
+        activeProject = previous;
+        ctx.ui.notify(`Switch cancelled. Staying on ${previous ?? "no project"}.`, "info");
         return;
       }
 
-      // ── Fallback: no stored session (or file gone) -> same-session switch ─
+      // switchSession fires a new session_start, which restores state from
+      // the target session's entries (or auto-detects). Set it explicitly as
+      // a safety net in case the session has no project entry yet.
       activeProject = name;
-
-      // Persist to session
-      pi.appendEntry(ENTRY_TYPE, { project: name, switchedAt: new Date().toISOString() });
-
-      // Update session name
       pi.setSessionName(name);
+      rememberSessionFile(name, targetSession);
 
       const path = projectPath(name);
       const branch = getGitBranch(path);
       const branchStr = branch ? ` on branch \`${branch}\`` : "";
-      const fromStr = previous ? ` (was: ${previous})` : "";
-
-      // Current session identity — still valid on this path (no session replacement)
-      const currentFile = currentSessionFile ?? ctx.sessionManager.getSessionFile();
-      const sessionLine = currentFile
-        ? `Continuing session: ${basename(currentFile)}`
-        : "Continuing current session";
-
       ctx.ui.notify(
-        `Switched to ${name}${fromStr} — first session in this project\n` +
-        `Workdir: ${path}${branchStr ? ` ${branchStr}` : ""}\n` +
-        sessionLine,
+        `Switched to ${name} — session restored: ${basename(targetSession)}\n` +
+        `Workdir: ${path}${branchStr ? ` ${branchStr}` : ""}`,
         "info"
       );
+      return;
+    }
 
-      // Announce to the agent so it operates in the new context
-      await ctx.waitForIdle();
-      pi.sendUserMessage(
-        `[Project switched to **${name}**]\n` +
-          `Working directory: \`${path}\`${branchStr}\n` +
-          `Please keep all file operations within this project from now on.`,
-        { deliverAs: "followUp" }
-      );
+    // ── Fallback: no stored session (or file gone) -> same-session switch ─
+    activeProject = name;
+
+    // Persist to session
+    pi.appendEntry(ENTRY_TYPE, { project: name, switchedAt: new Date().toISOString() });
+
+    // Update session name
+    pi.setSessionName(name);
+
+    const path = projectPath(name);
+    const branch = getGitBranch(path);
+    const branchStr = branch ? ` on branch \`${branch}\`` : "";
+    const fromStr = previous ? ` (was: ${previous})` : "";
+
+    // Current session identity — still valid on this path (no session replacement)
+    const currentFile = currentSessionFile ?? ctx.sessionManager.getSessionFile();
+    const sessionLine = currentFile
+      ? `Continuing session: ${basename(currentFile)}`
+      : "Continuing current session";
+
+    ctx.ui.notify(
+      `Switched to ${name}${fromStr} — first session in this project\n` +
+      `Workdir: ${path}${branchStr ? ` ${branchStr}` : ""}\n` +
+      sessionLine,
+      "info"
+    );
+
+    // Announce to the agent so it operates in the new context
+    await ctx.waitForIdle();
+    pi.sendUserMessage(
+      `[Project switched to **${name}**]\n` +
+        `Working directory: \`${path}\`${branchStr}\n` +
+        `Please keep all file operations within this project from now on.`,
+      { deliverAs: "followUp" }
+    );
+  };
+
+  // ── /project command ─────────────────────────────────────────────────────
+  pi.registerCommand("project", {
+    description: "Show or switch active project (/project [name])",
+
+    getArgumentCompletions: (prefix: string) => {
+      const projects = discoverProjects(getConfig().baseDir);
+      const filtered = projects.filter((p) => p.startsWith(prefix));
+      return filtered.length > 0
+        ? filtered.map((p) => ({ value: p, label: p }))
+        : null;
+    },
+
+    handler: async (args, ctx) => {
+      let name = args.trim();
+
+      // ── Explicit create opt-in: trailing "!" on the project name ────────
+      const createOptIn = name.endsWith("!");
+      if (createOptIn) {
+        name = name.slice(0, -1).trim();
+      }
+
+      // ── No arg: surface-adaptive status ──────────────────────────────────
+      if (!name) {
+        const projects = discoverProjects(getConfig().baseDir);
+        if (projects.length === 0) {
+          ctx.ui.notify(
+            `No projects found under ${getConfig().baseDir}. Set PI_PROJECT_SWITCHER_BASE or create the settings file.`,
+            "warning"
+          );
+          return;
+        }
+
+        const isTelegramOrigin = consumeTelegramStatusFlag();
+
+        if (isTelegramOrigin) {
+          // Plain list for the local surface (parity with today) …
+          notifyPlainProjectList(ctx, projects);
+          // … then a follow-up turn whose reply reaches the Telegram chat,
+          // with one button per project. The turn also settles the command
+          // bridge's pending dispatch (its agent_start hook clears the
+          // pending settle entry first).
+          await ctx.waitForIdle();
+          pi.sendUserMessage(buildTelegramStatusPrompt(projects), {
+            deliverAs: "followUp",
+          });
+          return;
+        }
+
+        if (ctx.mode === "tui") {
+          // Selection dialog; dismissing falls back to the plain list.
+          const choice = await ctx.ui.select("Switch project", projects);
+          if (choice !== undefined) {
+            await switchToProject(choice, ctx, false);
+            return;
+          }
+          notifyPlainProjectList(ctx, projects);
+          return;
+        }
+
+        // rpc/json/print and any other surface: unchanged plain list
+        notifyPlainProjectList(ctx, projects);
+        return;
+      }
+
+      // ── Switch project ────────────────────────────────────────────────────
+      await switchToProject(name, ctx, createOptIn);
     },
   });
 }

package/package.json

@@ -1 +1 @@
-{"name": "pi-project-switcher", "version": "0.4.0", "description": "pi coding agent extension: switch between projects under a configurable base directory via /project", "main": "index.ts", "type": "module", "scripts": {"test": "vitest run", "test:watch": "vitest", "typecheck": "tsc --noEmit"}, "keywords": ["pi", "pi-package", "pi-extension", "project", "switcher", "project-switching"], "author": "stefclawd", "license": "MIT", "repository": {"type": "git", "url": "git+https://github.com/stefclawd/pi-project-switcher.git"}, "bugs": {"url": "https://github.com/stefclawd/pi-project-switcher/issues"}, "homepage": "https://github.com/stefclawd/pi-project-switcher#readme", "files": ["index.ts", "README.md", "LICENSE"], "engines": {"node": ">=22.19.0"}, "pi": {"extensions": ["./index.ts"]}, "devDependencies": {"@earendil-works/pi-coding-agent": "^0.85.1", "@types/node": "^24.0.0", "typescript": "^5.7.0", "vitest": "^3.0.0"}}
+{"name": "pi-project-switcher", "version": "0.6.0", "description": "pi coding agent extension: switch between projects under a configurable base directory via /project", "main": "index.ts", "type": "module", "scripts": {"test": "vitest run", "test:watch": "vitest", "typecheck": "tsc --noEmit"}, "keywords": ["pi", "pi-package", "pi-extension", "project", "switcher", "project-switching"], "author": "stefclawd", "license": "MIT", "repository": {"type": "git", "url": "git+https://github.com/stefclawd/pi-project-switcher.git"}, "bugs": {"url": "https://github.com/stefclawd/pi-project-switcher/issues"}, "homepage": "https://github.com/stefclawd/pi-project-switcher#readme", "files": ["index.ts", "README.md", "LICENSE"], "engines": {"node": ">=22.19.0"}, "pi": {"extensions": ["./index.ts"]}, "devDependencies": {"@earendil-works/pi-coding-agent": "^0.85.1", "@types/node": "^24.0.0", "typescript": "^5.7.0", "vitest": "^3.0.0"}}