@ramarivera/pi-television 0.0.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ramiro Rivera
+
+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,40 @@
+# @ramarivera/pi-television
+
+Pi extension that replaces the fuzzy file finder with television (tv) for faster, non-blocking file search
+
+## Install
+
+```sh
+pi install npm:@ramarivera/pi-television@0.0.1
+```
+
+## Local Development
+
+This checkout is live-enabled for Pi through:
+
+```text
+.pi/extensions/television/index.ts
+```
+
+That shim imports the package entrypoint in `src/index.ts`, which imports the extension factory from `src/extension.ts`. Tests use the same symbol so local behavior, package behavior, and manual Pi behavior do not drift.
+
+```sh
+npm install
+npm run check
+npm test
+npm run test:e2e
+npm pack --dry-run
+```
+
+## Publishing
+
+Publishing uses GitHub Actions trusted publishing in `.github/workflows/publish.yml`.
+
+Before the first publish, configure npm trusted publishing:
+
+- owner/repo: `ramarivera/pi-television`
+- workflow: `.github/workflows/publish.yml`
+- environment: blank unless the workflow is changed to require one
+
+No `NPM_TOKEN` is required for trusted publishing.
+

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ramarivera/pi-television",
+  "version": "0.0.2",
+  "description": "Pi extension that replaces the fuzzy file finder with television (tv) for faster, non-blocking file search",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ramiro Rivera",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ramarivera/pi-television.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "biome check . && tsc --noEmit",
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "test": "tsx --test test/**/*.test.ts",
+    "test:e2e": "tsx --test e2e/test/**/*.test.ts",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "coding-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.0",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/src/extension.ts

@@ -0,0 +1,253 @@
+import { spawn } from "node:child_process";
+import { relative, resolve } from "node:path";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  TerminalInputHandler,
+} from "@earendil-works/pi-coding-agent";
+import { decodeKittyPrintable, Key, matchesKey } from "@earendil-works/pi-tui";
+
+export type ExtensionInfo = {
+  name: string;
+  description: string;
+};
+
+export type TelevisionPickResult =
+  | { status: "selected"; path: string }
+  | { status: "cancelled" }
+  | { status: "failed"; message: string };
+
+export type TelevisionRunnerOptions = {
+  cwd: string;
+  query?: string;
+  signal?: AbortSignal;
+};
+
+export type TelevisionRunner = (
+  options: TelevisionRunnerOptions,
+) => Promise<TelevisionPickResult>;
+
+export type TelevisionExtensionOptions = {
+  commandName?: string;
+  shortcut?: string;
+  runner?: TelevisionRunner;
+};
+
+const STATUS_KEY = "pi-television";
+const DEFAULT_COMMAND_NAME = "television";
+const DEFAULT_SHORTCUT = "@";
+
+export const extensionInfo: ExtensionInfo = {
+  name: "television",
+  description:
+    "Pi extension that replaces the fuzzy file finder with television (tv) for faster, non-blocking file search",
+};
+
+function cleanSelectedPath(stdout: string): string | null {
+  const selected = stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  return selected ?? null;
+}
+
+function buildTvArgs(query: string | undefined): string[] {
+  const sourceCommand =
+    "fd --type f --type d --hidden --follow --exclude .git --strip-cwd-prefix";
+  const args = [
+    "--source-command",
+    sourceCommand,
+    "--source-display",
+    "{}",
+    "--source-output",
+    "{}",
+    "--preview-command",
+    "test -d {} && ls -la {} || sed -n '1,160p' {}",
+    "--preview-header",
+    "{}",
+  ];
+
+  if (query?.trim()) {
+    args.push("--input", query.trim());
+  }
+
+  return args;
+}
+
+export function runTelevision(
+  options: TelevisionRunnerOptions,
+): Promise<TelevisionPickResult> {
+  return new Promise((resolvePick) => {
+    if (options.signal?.aborted) {
+      resolvePick({ status: "cancelled" });
+      return;
+    }
+
+    const child = spawn("tv", buildTvArgs(options.query), {
+      cwd: options.cwd,
+      stdio: ["inherit", "pipe", "inherit"],
+    });
+
+    let stdout = "";
+    let settled = false;
+
+    const settle = (result: TelevisionPickResult) => {
+      if (settled) return;
+      settled = true;
+      options.signal?.removeEventListener("abort", onAbort);
+      resolvePick(result);
+    };
+
+    const onAbort = () => {
+      child.kill("SIGTERM");
+      settle({ status: "cancelled" });
+    };
+
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    child.stdout?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    child.on("error", (error) => {
+      settle({ status: "failed", message: error.message });
+    });
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      if (signal) {
+        settle({ status: "cancelled" });
+        return;
+      }
+      if (code === 0) {
+        const path = cleanSelectedPath(stdout);
+        settle(path ? { status: "selected", path } : { status: "cancelled" });
+        return;
+      }
+      if (code === 130 || code === 1) {
+        settle({ status: "cancelled" });
+        return;
+      }
+      settle({
+        status: "failed",
+        message: `television exited with code ${code ?? "unknown"}`,
+      });
+    });
+  });
+}
+
+export function toEditorAttachmentPath(
+  selectedPath: string,
+  cwd: string,
+): string {
+  const absolute = resolve(cwd, selectedPath);
+  const relativePath = relative(cwd, absolute) || ".";
+  const displayPath = relativePath.startsWith("..") ? absolute : relativePath;
+  const normalized = displayPath.split("\\").join("/");
+  if (/[\s"'$`\\]/.test(normalized)) {
+    return `@"${normalized.replace(/(["\\$`])/g, "\\$1")}" `;
+  }
+  return `@${normalized} `;
+}
+
+function shortcutQuery(data: string, shortcut: string): string | null {
+  if (data.startsWith(shortcut)) return data.slice(shortcut.length);
+  return decodeKittyPrintable(data) === shortcut ? "" : null;
+}
+
+function isBoundaryKey(data: string): boolean {
+  return (
+    matchesKey(data, Key.space) ||
+    matchesKey(data, Key.enter) ||
+    matchesKey(data, Key.tab)
+  );
+}
+
+async function pickFile(
+  ctx: ExtensionContext,
+  runner: TelevisionRunner,
+  query: string | undefined,
+): Promise<TelevisionPickResult> {
+  ctx.ui.setStatus(STATUS_KEY, "television: picking file");
+  ctx.ui.setWorkingMessage("television is picking a file");
+  ctx.ui.setWorkingIndicator({ frames: ["tv"], intervalMs: 1000 });
+
+  try {
+    return await runner({ cwd: ctx.cwd, query, signal: ctx.signal });
+  } finally {
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+    ctx.ui.setWorkingMessage();
+    ctx.ui.setWorkingIndicator();
+  }
+}
+
+async function pastePickedFile(
+  ctx: ExtensionContext,
+  runner: TelevisionRunner,
+  query: string | undefined,
+): Promise<TelevisionPickResult> {
+  const result = await pickFile(ctx, runner, query);
+
+  if (result.status === "selected") {
+    ctx.ui.pasteToEditor(toEditorAttachmentPath(result.path, ctx.cwd));
+  } else if (result.status === "failed") {
+    ctx.ui.notify(`television failed: ${result.message}`, "error");
+  }
+
+  return result;
+}
+
+function installShortcut(
+  ctx: ExtensionContext,
+  runner: TelevisionRunner,
+  shortcut: string,
+): void {
+  let pickerOpen = false;
+  let lastKeyWasBoundary = true;
+
+  const handler: TerminalInputHandler = (data) => {
+    if (pickerOpen) return undefined;
+
+    const query = shortcutQuery(data, shortcut);
+    if (query === null) {
+      lastKeyWasBoundary = isBoundaryKey(data);
+      return undefined;
+    }
+
+    if (!lastKeyWasBoundary) {
+      lastKeyWasBoundary = isBoundaryKey(data);
+      return undefined;
+    }
+
+    pickerOpen = true;
+    void pastePickedFile(ctx, runner, query).finally(() => {
+      pickerOpen = false;
+      lastKeyWasBoundary = true;
+    });
+
+    return { consume: true };
+  };
+
+  ctx.ui.onTerminalInput?.(handler);
+}
+
+export function createExtension(options: TelevisionExtensionOptions = {}) {
+  const commandName = options.commandName ?? DEFAULT_COMMAND_NAME;
+  const shortcut = options.shortcut ?? DEFAULT_SHORTCUT;
+  const runner = options.runner ?? runTelevision;
+
+  return {
+    name: extensionInfo.name,
+    register(pi: ExtensionAPI): void {
+      pi.on("session_start", (_event, ctx) => {
+        installShortcut(ctx, runner, shortcut);
+      });
+
+      pi.registerCommand(commandName, {
+        description:
+          "Pick a file with television (tv) and insert it as an @file attachment",
+        handler: async (args, ctx) => {
+          await pastePickedFile(ctx, runner, args.trim());
+        },
+      });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createExtension } from "./extension.ts";
+
+export type {
+  TelevisionExtensionOptions,
+  TelevisionPickResult,
+  TelevisionRunner,
+  TelevisionRunnerOptions,
+} from "./extension.ts";
+export {
+  createExtension,
+  extensionInfo,
+  toEditorAttachmentPath,
+} from "./extension.ts";
+
+export default function televisionExtension(pi: ExtensionAPI): void {
+  createExtension().register(pi);
+}