@yassimba/pi-loom 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,39 @@
+# pi-loom
+
+Loom's woven logo in Pi's header, with a startup notice when a newer Loom CLI is ready to install.
+
+## Try it
+
+From a checkout of this repository, with Pi 0.85.1 or newer:
+
+```sh
+pi -e ./plugins/pi-loom/index.ts
+```
+
+To keep it installed:
+
+```sh
+pi install ./plugins/pi-loom
+```
+
+Restart Pi after installing to run the startup check. The package is also registered in Loom's setup catalog for publication; it is not added to existing installations automatically.
+
+## Behavior
+
+- Replaces Pi's header with a purple, 24-column Unicode braille rendering of the supplied Loom logo, with the name aligned at the top. Narrow terminals show just **Loom**. Pi's other UI and native update notices remain unchanged.
+- At interactive process startup, runs `loom --version` and reads the Loom executable pin from the [published manifest](https://github.com/Yassimba/loom/blob/main/manifest/loom.toml). It does not use GitHub's latest release, which could belong to a different component.
+- If that stable version is newer, shows: `Loom update available: VERSION. Run loom update or use the /loom skill to update.` The skill must be installed separately; `loom update` always remains the direct command.
+- Never installs anything or changes Pi settings. Checks run in the background, with a 1.5-second command timeout and a four-second overall deadline. Missing Loom, unrecognized/development versions, and network failures stay quiet.
+- Skips checks in headless modes and with `PI_OFFLINE=1`, `true`, or `yes`. Switching, forking, or reloading sessions rebrands the header without repeating the check. Shutdown cancels pending work and suppresses late notices.
+
+Only one extension can own Pi's header; another header extension may replace this one. Remove pi-loom with `pi remove ./plugins/pi-loom` (from the same checkout) and reload to return to Pi's normal header.
+
+## Development
+
+From the repository root:
+
+```sh
+node --experimental-strip-types --test test/pi-loom.test.ts
+npm run check
+npm run audit
+```

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@yassimba/pi-loom",
+  "version": "0.2.0",
+  "description": "Loom branding and a startup notice for published Loom updates in Pi.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.6"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "loom"
+  ],
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yassimba/loom.git",
+    "directory": "plugins/pi-loom"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "loom": {
+    "catalog": {
+      "label": "Loom",
+      "description": "Loom branding and a startup notice for published Loom updates in Pi.",
+      "nextAction": "Start Pi to see the Loom header and available Loom updates."
+    }
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { checkLoomUpdate, execVersionCommand } from "./update.ts";
+
+// Frozen 24-column braille rendering of assets/loom-logo.svg; no runtime rasterizer.
+const LOGO = [
+  "          ⢠⣴⣦⡀",
+  "        ⢀⣴⣿⣿⣿⣿⣦⡀",
+  "       ⢶⣿⣿⣿⠋⠙⣿⣿⣿⡦",
+  "    ⢀⣤⡀ ⠙⢿⡿⣢⣾⣿⡿⠋ ⢀⣤⡀",
+  "  ⢀⣴⣿⣿⣿⣦⡀⢠⣾⣿⡿⢋⣄⢀⣴⣿⣿⣿⣦⡀",
+  "⢀⣴⣿⣿⡿⠛⢿⣿⣿⣎⠻⠋⠐⢿⣿⣷⣝⠟⠙⢿⣿⣿⣦⡀",
+  "⠙⢿⣿⣿⣷⣄⣴⣝⢿⣿⣷⠄⣠⣦⡙⢿⣿⣷⣤⣾⣿⣿⡿⠋",
+  "  ⠙⢿⣿⣿⡿⠋ ⠉⣡⣾⣿⡿⠁ ⠙⢿⣿⣿⡿⠋",
+  "    ⠙⠋  ⣠⣾⣿⡿⢫⣾⣷⣄  ⠙⠋",
+  "       ⠺⣿⣿⣿⣄⣠⣿⣿⣿⠗",
+  "        ⠈⠻⣿⣿⣿⣿⠟⠁",
+  "          ⠘⢿⠟⠁",
+];
+
+export default function (pi: ExtensionAPI, exec = execVersionCommand) {
+  let checked = false;
+  const shutdown = new AbortController();
+
+  pi.on("session_start", (event, ctx) => {
+    if (ctx.mode !== "tui" || !ctx.hasUI) return;
+    ctx.ui.setHeader((_tui, theme) => ({
+      render(width) {
+        if (width < 48) return [truncateToWidth(theme.bold("Loom"), width, "")];
+        const labels = [
+          theme.bold("Loom"),
+          theme.fg("muted", "Your opinionated agent setup."),
+          "",
+          `${theme.bold("/loom")} ${theme.fg("dim", "Set up, add tools, or update.")}`,
+        ];
+        return LOGO.map((line, index) => {
+          const label = labels[index] ?? "";
+          // Match the SVG's #8038E9 independently of the active Pi theme.
+          return truncateToWidth(
+            `\x1b[38;2;128;56;233m${line.padEnd(28)}\x1b[39m${label}`,
+            width,
+            "",
+          );
+        });
+      },
+      invalidate() {},
+    }));
+
+    // Pi reconstructs extensions on reload/new/resume/fork. Only process startup
+    // checks; branding still applies to every replacement session.
+    if (checked || event.reason !== "startup") return;
+    checked = true;
+    void checkLoomUpdate(exec, shutdown.signal).then((version) => {
+      if (version && !shutdown.signal.aborted) {
+        ctx.ui.notify(
+          `Loom update available: ${version}. Run loom update or use the /loom skill to update.`,
+          "info",
+        );
+      }
+    });
+  });
+
+  pi.on("session_shutdown", () => shutdown.abort());
+}

package/src/update.ts

@@ -0,0 +1,56 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+// Pi's exec timeout only sends SIGTERM; a wrapper can ignore it indefinitely.
+export const execVersionCommand: ExtensionAPI["exec"] = async (command, args, options) => {
+  const { stdout, stderr } = await promisify(execFile)(command, args, {
+    signal: options?.signal,
+    timeout: options?.timeout,
+    killSignal: "SIGKILL",
+    maxBuffer: 4096,
+    encoding: "utf8",
+  });
+  return { stdout, stderr, code: 0, killed: false };
+};
+
+const MANIFEST_URL = "https://raw.githubusercontent.com/Yassimba/loom/main/manifest/loom.toml";
+const VERSION = String.raw`(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)`;
+
+export function availableLoomVersion(installed: string, manifest: string): string | undefined {
+  const current = installed.trim().match(new RegExp(`^loom (${VERSION})$`));
+  // The published manifest requires one tool per line (also used by the installers).
+  // Match only the Loom executable in [tools], never another component's release.
+  const tools = manifest.split(/^\[tools\]\s*$/m)[1]?.split(/^\[/m)[0];
+  const latest = tools?.match(
+    new RegExp(
+      String.raw`^"github:Yassimba/loom\[exe=loom\]"\s*=\s*\{\s*version\s*=\s*"loom-v(${VERSION})"[^\r\n]*\}\s*(?:#.*)?$`,
+      "m",
+    ),
+  );
+  if (!current || !latest) return undefined;
+  for (let index = 2; index <= 4; index++) {
+    const difference = BigInt(latest[index]) - BigInt(current[index]);
+    if (difference !== 0n) return difference > 0n ? latest[1] : undefined;
+  }
+  return undefined;
+}
+
+export async function checkLoomUpdate(
+  exec: ExtensionAPI["exec"],
+  shutdown: AbortSignal,
+): Promise<string | undefined> {
+  if (/^(1|true|yes)$/i.test(process.env.PI_OFFLINE?.trim() ?? "")) return undefined;
+  const signal = AbortSignal.any([shutdown, AbortSignal.timeout(4000)]);
+  try {
+    const result = await exec("loom", ["--version"], { timeout: 1500, signal });
+    if (result.code !== 0 || result.killed || signal.aborted) return undefined;
+    if (!new RegExp(`^loom ${VERSION}$`).test(result.stdout.trim())) return undefined;
+    const response = await fetch(MANIFEST_URL, { signal });
+    if (!response.ok) return undefined;
+    return availableLoomVersion(result.stdout, await response.text());
+  } catch {
+    // Missing Loom, offline hosts, and failed checks must not interrupt startup.
+    return undefined;
+  }
+}