pi-session-cleanup 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0 - 2026-03-05
+
+- Renamed extension from its previous package name to `pi-session-cleanup`
+- Renamed primary command to `/session-cleanup`
+- Added a deprecated legacy alias for backward compatibility
+- Refactored command/picker module names for clarity
+- Upgraded custom picker UI with bordered modal layout, title/status/help lines, and responsive overlay sizing
+- Added production-ready package metadata and README

package/LICENSE

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

@@ -0,0 +1,145 @@
+# pi-session-cleanup
+
+[![npm version](https://img.shields.io/npm/v/pi-session-cleanup?style=flat-square)](https://www.npmjs.com/package/pi-session-cleanup) [![License](https://img.shields.io/github/license/MasuRii/pi-session-cleanup?style=flat-square)](LICENSE)
+
+Interactive session cleanup extension for the [Pi coding agent](https://github.com/mariozechner/pi).
+
+<img width="1389" height="768" alt="image" src="https://github.com/user-attachments/assets/42464ca1-4a6c-4496-b13f-5bcc2093bf59" />
+
+**pi-session-cleanup** provides a focused TUI command for batch-selecting historical sessions and deleting them safely with trash-first fallback and active session protection.
+
+## Features
+
+- **Interactive Session Cleanup** — Browse, select, and delete sessions via an intuitive modal interface
+- **Scope Filtering** — View only orphaned sessions or all historical sessions
+- **Batch Selection Controls** — Multi-select with Space, select all with `a`, keyboard navigation
+- **Safe Delete Flow** — Excludes the currently active session and uses trash-first deletion with unlink fallback
+- **Improved Modal UX** — Centered overlay with bordered layout, concise single-line legend, status summary, and automatic icon fallback
+
+## Installation
+
+### Local Extension Folder
+
+Place this folder in one of Pi's auto-discovery paths:
+
+```text
+~/.pi/agent/extensions/pi-session-cleanup     # Global default (when PI_CODING_AGENT_DIR is unset)
+.pi/extensions/pi-session-cleanup               # Project-specific
+```
+
+Pi will auto-discover the extension on startup.
+
+### As NPM Package
+
+```bash
+pi install npm:pi-session-cleanup
+```
+
+### Git Repository
+
+```bash
+pi install git:github.com/MasuRii/pi-session-cleanup
+```
+
+## Usage
+
+### Commands
+
+| Command | Arguments | Description |
+|---------|-----------|-------------|
+| `/session-cleanup` | — | Opens the session cleanup modal showing orphaned sessions only |
+| `/session-cleanup current` | — | Opens modal with sessions from the current directory |
+| `/session-cleanup all` | — | Opens modal showing all sessions |
+| `/session-cleanup help` | — | Displays usage help |
+
+**Scopes:**
+
+- **Default (no args)** — Shows orphaned sessions (sessions without a matching directory)
+- **`current`** — Shows sessions from the current working directory
+- **`all`** — Shows all historical sessions across all directories
+
+### Modal Controls
+
+When the session picker modal is open:
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` / `j` / `k` | Navigate up/down in the list |
+| `PgUp` / `PgDn` | Page up/down through sessions |
+| `Home` / `End` | Jump to first/last item |
+| `Space` | Toggle selection of current item |
+| `a` | Select all visible sessions |
+| `r` | Refresh the session list |
+| `Enter` | Confirm deletion of selected sessions |
+| `Esc` / `q` / `Ctrl+C` | Cancel and close modal |
+
+### Safety Guards
+
+The extension includes multiple safety mechanisms:
+
+1. **Active Session Protection** — The currently active session is never shown in the list and cannot be deleted
+2. **Trash-First Deletion** — Sessions are moved to trash first; only falls back to permanent deletion if trash is unavailable
+3. **Confirmation Required** — The modal requires explicit `Enter` keypress to proceed with deletion
+4. **Escapable** — `Esc` or `q` immediately cancels without any changes
+
+## Configuration
+
+Configuration is stored at:
+
+```text
+Default global path: ~/.pi/agent/extensions/pi-session-cleanup/config.json
+Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-session-cleanup/config.json when PI_CODING_AGENT_DIR is set
+```
+
+A starter template is provided in `config/config.example.json`. On startup, the extension creates `config.json` with defaults if missing.
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Master on/off switch for the extension |
+| `iconMode` | `"auto" \| "nerd" \| "fallback"` | `"auto"` | Icon rendering mode for the modal UI (`auto` detects Nerd Font usage in supported terminals and safely falls back otherwise) |
+
+### Icon Mode Overrides
+
+You can override icon mode without editing config:
+
+- `PI_SESSION_CLEANUP_ICON_MODE=nerd|fallback|auto`
+- `PI_SESSION_CLEANUP_NERD_FONT=true|false` (or `PI_NERD_FONT=true|false`)
+
+`auto` now prefers Nerd icons when Nerd Font is actually configured (including Windows Terminal profile/default font checks) and falls back to safe icons when detection is unavailable or uncertain.
+
+## Development
+
+```bash
+npm run build    # Type-check with TypeScript
+npm run lint     # Run linting (same as build)
+npm run test     # Run test suite
+npm run check    # Run full verification (build + test)
+npm run package:dry-run
+```
+
+## Publishing
+
+The package metadata follows the same publish-ready shape used by established Pi extensions:
+
+- entrypoint: `index.ts`
+- package exports: `.` → `./index.ts`
+- Pi extension manifest: `pi.extensions`
+- published files: source, README, changelog, license, and config template
+- runtime `config.json`, tests, and build artifacts excluded from npm publication
+
+## Related Pi Extensions
+
+- [pi-hide-messages](https://github.com/MasuRii/pi-hide-messages) — Hide older TUI chat history while preserving full session context
+- [pi-context-injector](https://github.com/MasuRii/pi-context-injector) — Inject compact project context into first-turn and compaction prompts
+- [pi-tool-display](https://github.com/MasuRii/pi-tool-display) — Compact tool rendering and diff visualization
+- [pi-rtk-optimizer](https://github.com/MasuRii/pi-rtk-optimizer) — RTK command rewriting and output compaction
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## License
+
+[MIT](LICENSE) © MasuRii

package/config/config.example.json

@@ -0,0 +1,4 @@
+{
+  "iconMode": "auto",
+  "enabled": true
+}

package/index.ts

@@ -0,0 +1,3 @@
+import sessionCleanupExtension from "./src/index.js";
+
+export default sessionCleanupExtension;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "pi-session-cleanup",
+  "version": "1.0.0",
+  "description": "Pi extension for interactive batch session cleanup and safe deletion.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test:clean": "node -e \"require('node:fs').rmSync('.test-dist', { recursive: true, force: true })\"",
+    "pretest": "npm run test:clean",
+    "test": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.test.json && node --test .test-dist/test/*.test.js",
+    "posttest": "npm run test:clean",
+    "check": "npm run lint && npm run test",
+    "package:dry-run": "npm pack --dry-run"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "session",
+    "cleanup",
+    "delete",
+    "pi-coding-agent",
+    "pi-tui",
+    "session-management",
+    "tui",
+    "safe-delete"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.70.5",
+    "@mariozechner/pi-tui": "^0.70.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-session-cleanup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-session-cleanup/issues"
+  },
+  "homepage": "https://github.com/MasuRii/pi-session-cleanup#readme"
+}

package/src/config-store.ts

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type IconModePreference = "auto" | "nerd" | "fallback";
+
+export interface SessionCleanupConfig {
+  enabled: boolean;
+  iconMode: IconModePreference;
+}
+
+const DEFAULT_CONFIG: SessionCleanupConfig = {
+  enabled: true,
+  iconMode: "auto",
+};
+
+function resolveExtensionRoot(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+function parseIconMode(value: unknown): IconModePreference | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "auto" || normalized === "nerd" || normalized === "fallback") {
+    return normalized;
+  }
+
+  return null;
+}
+
+function readConfigFile(configPath: string): Record<string, unknown> | null {
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    const raw = readFileSync(configPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // Fall back to defaults when config parsing fails.
+  }
+
+  return null;
+}
+
+function ensureConfigFile(configPath: string): void {
+  if (existsSync(configPath)) {
+    return;
+  }
+
+  try {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf8");
+  } catch {
+    // Ignore file system errors and continue with in-memory defaults.
+  }
+}
+
+export function loadSessionCleanupConfig(): SessionCleanupConfig {
+  const configPath = join(resolveExtensionRoot(), "config.json");
+  ensureConfigFile(configPath);
+
+  const raw = readConfigFile(configPath);
+  if (!raw) {
+    return { ...DEFAULT_CONFIG };
+  }
+
+  const enabled = typeof raw.enabled === "boolean" ? raw.enabled : DEFAULT_CONFIG.enabled;
+  const iconMode = parseIconMode(raw.iconMode) ?? DEFAULT_CONFIG.iconMode;
+
+  return {
+    enabled,
+    iconMode,
+  };
+}

package/src/constants.ts

@@ -0,0 +1,3 @@
+export const EXTENSION_ID = "pi-session-cleanup";
+export const SESSION_CLEANUP_COMMAND = "session-cleanup";
+export const SESSION_NIX_COMMAND = "nix";

package/src/index.ts

@@ -0,0 +1,27 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { SESSION_CLEANUP_COMMAND, SESSION_NIX_COMMAND } from "./constants.js";
+import {
+  getSessionCleanupArgumentCompletions,
+  handleSessionCleanupCommand,
+} from "./session-cleanup-command.js";
+import { handleSessionNixCommand } from "./session-nix-command.js";
+
+export default function sessionCleanupExtension(pi: ExtensionAPI): void {
+  pi.registerCommand(SESSION_CLEANUP_COMMAND, {
+    description:
+      "Batch-select previous sessions and delete them with confirmation.",
+    getArgumentCompletions: getSessionCleanupArgumentCompletions,
+    handler: async (args, ctx) => {
+      await handleSessionCleanupCommand(args, ctx);
+    },
+  });
+
+  pi.registerCommand(SESSION_NIX_COMMAND, {
+    description:
+      "Start a new session and automatically delete the previous session.",
+    handler: async (args, ctx) => {
+      await handleSessionNixCommand(args, ctx);
+    },
+  });
+}

package/src/session-agent.ts

@@ -0,0 +1,78 @@
+import { readFile } from "node:fs/promises";
+
+import type { SessionInfo } from "@mariozechner/pi-coding-agent";
+
+import type { SessionCleanupSession } from "./types.js";
+
+function toRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
+}
+
+function normalizeAgentName(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function parseJsonLine(value: string): Record<string, unknown> | null {
+  try {
+    return toRecord(JSON.parse(value));
+  } catch {
+    return null;
+  }
+}
+
+export function extractResponsibleAgentNameFromContent(content: string): string | null {
+  const lines = content.split(/\r?\n/);
+
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const trimmed = lines[index]?.trim();
+    if (!trimmed) {
+      continue;
+    }
+
+    const entry = parseJsonLine(trimmed);
+    if (!entry || entry.type !== "custom" || entry.customType !== "active_agent") {
+      continue;
+    }
+
+    const data = toRecord(entry.data);
+    const normalizedAgentName = normalizeAgentName(data?.name);
+    if (normalizedAgentName) {
+      return normalizedAgentName;
+    }
+
+    if (data?.name === null) {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+export async function resolveResponsibleAgentName(sessionPath: string): Promise<string | null> {
+  if (typeof sessionPath !== "string" || sessionPath.trim().length === 0) {
+    return null;
+  }
+
+  try {
+    const content = await readFile(sessionPath, "utf8");
+    return extractResponsibleAgentNameFromContent(content);
+  } catch {
+    return null;
+  }
+}
+
+export async function enrichSessionWithResponsibleAgent(
+  session: SessionInfo,
+): Promise<SessionCleanupSession> {
+  const responsibleAgentName = await resolveResponsibleAgentName(session.path);
+
+  return {
+    ...session,
+    responsibleAgentName,
+  };
+}