pi-short-links 0.1.0

package/extensions/tui-dashboard.ts

@@ -0,0 +1,97 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { Box, Container, Loader, matchesKey, Text } from "@earendil-works/pi-tui";
+import { formatTable } from "../lib/format-table.ts";
+
+interface DashboardRow {
+  component: string;
+  role: string;
+}
+
+const DEMO_ROWS: DashboardRow[] = [
+  { component: "Box", role: "Padded container with optional background" },
+  { component: "Loader", role: "Animated spinner while content loads" },
+  { component: "Text table", role: "Column-aligned rows via formatTable()" },
+];
+
+async function showDashboard(ctx: ExtensionCommandContext): Promise<void> {
+  if (!ctx.hasUI) {
+    return;
+  }
+
+  await ctx.ui.custom(
+    (tui, theme, _kb, done) => {
+      const container = new Container();
+      const box = new Box(1, 1, (text) => theme.bg("toolPendingBg", text));
+      const title = new Text(theme.fg("accent", theme.bold("Template TUI Dashboard")), 0, 0);
+      const tableLines = formatTable(DEMO_ROWS, [
+        { header: "Component", render: (row) => row.component },
+        { header: "Role", render: (row) => row.role },
+      ]);
+      const table = new Text(tableLines.map((line) => theme.fg("text", line)).join("\n"), 0, 0);
+      const footer = new Text(theme.fg("dim", "Press Enter or Esc to close"), 0, 0);
+      const loader = new Loader(
+        tui,
+        (text) => theme.fg("accent", text),
+        (text) => theme.fg("muted", text),
+        "Composing dashboard…",
+      );
+
+      box.addChild(title);
+      box.addChild(loader);
+      container.addChild(box);
+
+      loader.start();
+
+      let closed = false;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const close = () => {
+        if (closed) {
+          return;
+        }
+        closed = true;
+        if (timer !== undefined) {
+          clearTimeout(timer);
+        }
+        loader.stop();
+        done(undefined);
+      };
+
+      timer = setTimeout(() => {
+        if (closed) {
+          return;
+        }
+        loader.stop();
+        box.removeChild(loader);
+        box.addChild(table);
+        box.addChild(footer);
+        tui.requestRender();
+      }, 1200);
+
+      return {
+        render: (width: number) => container.render(width),
+        invalidate: () => container.invalidate(),
+        handleInput: (data: string) => {
+          if (matchesKey(data, "enter") || matchesKey(data, "escape")) {
+            close();
+          }
+        },
+      };
+    },
+    { overlay: true },
+  );
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.hasUI) {
+      ctx.ui.setStatus("template-tui", "dashboard ready");
+    }
+  });
+
+  pi.registerCommand("template-dashboard", {
+    description: "Show composed TUI components (Box, Loader, table)",
+    handler: async (_args, ctx) => {
+      await showDashboard(ctx);
+    },
+  });
+}

package/lib/config-contract.ts

@@ -0,0 +1,46 @@
+export type ConfigFieldRule =
+  | { type: "string"; minLength: number }
+  | { type: "boolean" };
+
+export const packageLayoutConfigRules = {
+  title: { type: "string", minLength: 1 },
+  statusLabel: { type: "string", minLength: 1 },
+  showSkillHint: { type: "boolean" },
+} as const satisfies Record<string, ConfigFieldRule>;
+
+export const packageLayoutConfigSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: Object.keys(packageLayoutConfigRules),
+  properties: packageLayoutConfigRules,
+} as const;
+
+export type PackageLayoutConfig = {
+  [Key in keyof typeof packageLayoutConfigRules]:
+    (typeof packageLayoutConfigRules)[Key]["type"] extends "string" ? string : boolean;
+};
+
+export function parsePackageLayoutConfig(input: unknown): PackageLayoutConfig {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("Package layout config must be an object");
+  }
+  const record = input as Record<string, unknown>;
+  const prototype = Object.getPrototypeOf(input);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError("Package layout config must be a plain object");
+  }
+  const allowed = new Set(Object.keys(packageLayoutConfigRules));
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) throw new TypeError(`Unknown package layout config field: ${key}`);
+  }
+  for (const [key, rule] of Object.entries(packageLayoutConfigRules)) {
+    const value = record[key];
+    if (!Object.hasOwn(record, key) || typeof value !== rule.type) {
+      throw new TypeError(`${key} must be ${rule.type}`);
+    }
+    if (rule.type === "string" && typeof value === "string" && value.length < rule.minLength) {
+      throw new TypeError(`${key} must contain at least ${rule.minLength} character`);
+    }
+  }
+  return record as PackageLayoutConfig;
+}

package/lib/error-contract.ts

@@ -0,0 +1,72 @@
+export type KnownErrorKind = "missing" | "invalid" | "conflict" | "permission" | "network";
+
+export type ClassifiedError = {
+  kind: KnownErrorKind;
+  exitCode: number;
+  retryable: boolean;
+  message: string;
+};
+
+type CodeCarrier = Error & { code?: unknown };
+
+const ERROR_CODES = {
+  missing: new Set(["ENOENT"]),
+  conflict: new Set(["EEXIST", "ENOTEMPTY"]),
+  permission: new Set(["EACCES", "EPERM"]),
+  network: new Set(["ECONNRESET", "ETIMEDOUT", "EAI_AGAIN", "ENOTFOUND"]),
+} as const;
+
+const ERROR_EXIT_CODES = {
+  missing: 66,
+  invalid: 65,
+  conflict: 73,
+  permission: 77,
+  network: 75,
+} as const satisfies Record<KnownErrorKind, number>;
+
+function errorCode(error: unknown): string | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const code = (error as CodeCarrier).code;
+  return typeof code === "string" ? code : undefined;
+}
+
+function knownKindForCode(code: string | undefined): KnownErrorKind | undefined {
+  if (!code) return undefined;
+  for (const [kind, codes] of Object.entries(ERROR_CODES)) {
+    if ((codes as ReadonlySet<string>).has(code)) return kind as KnownErrorKind;
+  }
+  return undefined;
+}
+
+function isInvalidError(error: unknown): boolean {
+  return error instanceof SyntaxError || error instanceof TypeError || error instanceof RangeError;
+}
+
+export function classifyErrorForCli(error: unknown): ClassifiedError {
+  const kind = knownKindForCode(errorCode(error)) ?? (isInvalidError(error) ? "invalid" : undefined);
+  if (!kind) throw error;
+
+  const message = error instanceof Error && error.message ? error.message : kind;
+  return {
+    kind,
+    exitCode: ERROR_EXIT_CODES[kind],
+    retryable: kind === "network",
+    message: `${kind}: ${message}`,
+  };
+}
+
+export async function fallbackAfterCanonicalRecheck<T>(
+  action: () => Promise<T>,
+  readCanonical: () => Promise<T | undefined>,
+  fallback: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await action();
+  } catch (error) {
+    const classified = classifyErrorForCli(error);
+    if (classified.kind !== "missing") throw error;
+    const canonical = await readCanonical();
+    if (canonical !== undefined) return canonical;
+    return fallback();
+  }
+}

package/lib/format-table.ts

@@ -0,0 +1,46 @@
+export interface TableColumn<T> {
+  header: string;
+  width?: number;
+  align?: "left" | "right";
+  render: (row: T) => string;
+}
+
+export interface FormatTableOptions {
+  gap?: number;
+}
+
+function padCell(value: string, width: number, align: "left" | "right"): string {
+  if (value.length >= width) {
+    return value.slice(0, width);
+  }
+
+  const padding = " ".repeat(width - value.length);
+  return align === "right" ? `${padding}${value}` : `${value}${padding}`;
+}
+
+export function formatTable<T>(
+  rows: T[],
+  columns: TableColumn<T>[],
+  options: FormatTableOptions = {},
+): string[] {
+  const gap = options.gap ?? 2;
+  const gapText = " ".repeat(gap);
+  const renderedRows = rows.map((row) => columns.map((column) => column.render(row)));
+
+  const widths = columns.map((column, colIndex) => {
+    const headerWidth = column.header.length;
+    const dataWidth = renderedRows.reduce((max, row) => Math.max(max, row[colIndex]!.length), 0);
+    return column.width ?? Math.max(headerWidth, dataWidth);
+  });
+
+  const formatRow = (cells: string[]) =>
+    cells
+      .map((cell, index) => padCell(cell, widths[index]!, columns[index]!.align ?? "left"))
+      .join(gapText);
+
+  const header = formatRow(columns.map((column) => column.header));
+  const divider = formatRow(widths.map((width) => "─".repeat(width)));
+  const body = renderedRows.map((row) => formatRow(row));
+
+  return [header, divider, ...body];
+}

package/lib/greeting.ts

@@ -0,0 +1,16 @@
+export type GreetingMode = "short" | "friendly";
+
+export interface GreetingInput {
+  name: string;
+  mode: GreetingMode;
+}
+
+export function formatGreeting(input: GreetingInput): string {
+  const name = input.name.trim() || "Pi";
+
+  if (input.mode === "friendly") {
+    return `Hello, ${name}! Your TypeScript-first Pi package is working.`;
+  }
+
+  return `Hello, ${name}!`;
+}

package/lib/shorten.ts

@@ -0,0 +1,177 @@
+import * as os from "node:os";
+import { pathToFileURL } from "node:url";
+
+const URL_RE = /https?:\/\/[^\s<>\[\]()"`']+/g;
+const ABS_PATH_RE = /(?:^|[\s`"'(])((?:\/|~\/)[^\s<>\[\]()"`']+)/g;
+const MD_LINK_RE = /\[[^\]]*\]\([^)]+\)/g;
+
+export type ShortenOptions = {
+	maxWidth: number;
+	homeDir?: string;
+	cwd?: string;
+};
+
+export function getMaxLabelWidth(columns: number | undefined = process.stdout.columns): number {
+	const cols = typeof columns === "number" && columns > 0 ? columns : 80;
+	// Leave room for transcript chrome / markdown punctuation.
+	return Math.max(24, cols - 8);
+}
+
+export function isTruthyEnv(value: string | undefined): boolean {
+	return /^(1|true|yes)$/i.test(value ?? "");
+}
+
+export function shouldForceHyperlinks(
+	env: NodeJS.ProcessEnv = process.env,
+): boolean {
+	if (isTruthyEnv(env.FORCE_HYPERLINK)) return true;
+	const term = env.TERM_PROGRAM?.toLowerCase() ?? "";
+	return term === "orca";
+}
+
+function stripTrailingPunctuation(value: string): { core: string; trailing: string } {
+	let end = value.length;
+	while (end > 0 && /[.,;:!?)\]}'"]/.test(value[end - 1]!)) {
+		end -= 1;
+	}
+	return { core: value.slice(0, end), trailing: value.slice(end) };
+}
+
+export function formatUrlLabel(url: string, maxWidth: number): string {
+	try {
+		const parsed = new URL(url);
+		const host = parsed.host;
+		const path = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+		const tailSource = path === "/" ? "" : path.replace(/\/+$/, "");
+		const tail = tailSource.slice(-12);
+		if (!tail) {
+			return host.length <= maxWidth ? host : `${host.slice(0, Math.max(1, maxWidth - 1))}…`;
+		}
+		const candidate = `${host}/…${tail.replace(/^\//, "")}`;
+		if (candidate.length <= maxWidth) return candidate;
+		const budget = Math.max(8, maxWidth - 1);
+		return `${candidate.slice(0, budget)}…`;
+	} catch {
+		if (url.length <= maxWidth) return url;
+		return `${url.slice(0, Math.max(1, maxWidth - 1))}…`;
+	}
+}
+
+export function formatPathLabel(
+	rawPath: string,
+	maxWidth: number,
+	homeDir: string = os.homedir(),
+): string {
+	let display = rawPath;
+	if (rawPath.startsWith(homeDir)) {
+		display = `~${rawPath.slice(homeDir.length)}`;
+	}
+
+	if (display.length <= maxWidth) return display;
+
+	const isHome = display.startsWith("~/");
+	const isAbs = display.startsWith("/");
+	const body = isHome ? display.slice(2) : isAbs ? display.slice(1) : display;
+	const parts = body.split("/").filter(Boolean);
+	const file = parts.at(-1) ?? body;
+	const first = parts[0];
+
+	let candidate: string;
+	if (isHome && first && first !== file) {
+		candidate = `~/${first}/…/${file}`;
+	} else if (isHome) {
+		candidate = `~/…/${file}`;
+	} else if (isAbs && first && first !== file) {
+		candidate = `/${first}/…/${file}`;
+	} else if (isAbs) {
+		candidate = `/…/${file}`;
+	} else {
+		candidate = `…/${file}`;
+	}
+
+	if (candidate.length <= maxWidth) return candidate;
+	const budget = Math.max(8, maxWidth - 1);
+	return `${candidate.slice(0, budget)}…`;
+}
+
+function toFileHref(rawPath: string, homeDir: string, cwd?: string): string {
+	let absolute = rawPath;
+	if (rawPath.startsWith("~/")) {
+		absolute = `${homeDir}${rawPath.slice(1)}`;
+	} else if (!rawPath.startsWith("/") && cwd) {
+		absolute = `${cwd.replace(/\/+$/, "")}/${rawPath}`;
+	}
+	return pathToFileURL(absolute).href;
+}
+
+function protectMatches(text: string, pattern: RegExp): {
+	text: string;
+	slots: string[];
+} {
+	const slots: string[] = [];
+	const next = text.replace(pattern, (match) => {
+		const idx = slots.length;
+		slots.push(match);
+		return `\u0000MD${idx}\u0000`;
+	});
+	return { text: next, slots };
+}
+
+function restoreSlots(text: string, slots: string[]): string {
+	return text.replace(/\u0000MD(\d+)\u0000/g, (_m, idx) => slots[Number(idx)] ?? "");
+}
+
+function rewritePlainSegment(segment: string, options: ShortenOptions): string {
+	const homeDir = options.homeDir ?? os.homedir();
+	const maxWidth = options.maxWidth;
+
+	const protectedMd = protectMatches(segment, MD_LINK_RE);
+	let text = protectedMd.text;
+
+	text = text.replace(URL_RE, (raw) => {
+		const { core, trailing } = stripTrailingPunctuation(raw);
+		if (core.length <= maxWidth) return raw;
+		const label = formatUrlLabel(core, maxWidth);
+		return `[${label}](${core})${trailing}`;
+	});
+
+	text = text.replace(ABS_PATH_RE, (full, pathPart: string) => {
+		const prefix = full.slice(0, full.length - pathPart.length);
+		const { core, trailing } = stripTrailingPunctuation(pathPart);
+		if (core.length <= maxWidth) return full;
+		// Skip URL-looking leftovers.
+		if (/^https?:/i.test(core)) return full;
+		const label = formatPathLabel(core, maxWidth, homeDir);
+		const href = toFileHref(core, homeDir, options.cwd);
+		return `${prefix}[${label}](${href})${trailing}`;
+	});
+
+	return restoreSlots(text, protectedMd.slots);
+}
+
+/**
+ * Rewrite long bare URLs/paths outside fenced code blocks into short markdown links.
+ */
+export function shortenAssistantText(input: string, options: ShortenOptions): string {
+	if (!input || options.maxWidth < 8) return input;
+
+	const parts: string[] = [];
+	let i = 0;
+	while (i < input.length) {
+		const open = input.indexOf("```", i);
+		if (open === -1) {
+			parts.push(rewritePlainSegment(input.slice(i), options));
+			break;
+		}
+		parts.push(rewritePlainSegment(input.slice(i, open), options));
+		const close = input.indexOf("```", open + 3);
+		if (close === -1) {
+			parts.push(input.slice(open));
+			break;
+		}
+		parts.push(input.slice(open, close + 3));
+		i = close + 3;
+	}
+
+	return parts.join("");
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "pi-short-links",
+  "version": "0.1.0",
+  "description": "Shorten long URLs and file paths in Pi assistant output so OSC 8 / click targets fit the pane width.",
+  "type": "module",
+  "license": "MIT",
+  "author": "eiei114",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "osc8",
+    "hyperlink",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiei114/pi-short-links.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiei114/pi-short-links/issues"
+  },
+  "homepage": "https://github.com/eiei114/pi-short-links#readme",
+  "files": [
+    "extensions/",
+    "lib/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/shorten.test.mjs",
+    "pack:check": "npm pack --dry-run",
+    "ci": "npm run typecheck && npm test && npm run pack:check"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/short-links.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.1",
+    "@types/node": "^26.0.0",
+    "typescript": "^7.0.2"
+  }
+}