tmux-ide 2.6.0 → 2.7.0

package/packages/daemon/src/lib/skill-sync.ts

@@ -0,0 +1,155 @@
+/**
+ * Managed sync of the bundled Claude Code skill → `~/.claude/skills/tmux-ide`.
+ *
+ * `skill/SKILL.md` is the manual a coding agent loads to drive tmux-ide. It ships
+ * IN the package, but the copy that agents actually read lives in the user's
+ * `~/.claude/skills/` — so every install AND every update has to keep that copy
+ * fresh, or agents drive an old CLI. This module is that refresh: it copies the
+ * bundled SKILL.md into the tmux-ide skill dir with the version marker rewritten
+ * to the installed package version, and reports whether that was an install, an
+ * update, or a no-op.
+ *
+ * The dir is FULLY MANAGED: overwriting our own `~/.claude/skills/tmux-ide` is
+ * correct, and this NEVER touches anything outside it (user-authored skills in
+ * sibling dirs are safe). The version marker is line 2 of SKILL.md, an HTML
+ * comment ({@link VERSION_MARKER_RE}); {@link parseSkillVersion} reads it and
+ * {@link rewriteVersionMarker} substitutes it at copy time.
+ *
+ * The parse/render helpers are PURE and tested against fixtures; {@link syncSkill}
+ * is the thin io wrapper (tested with tmp dirs). Wired from three places — the
+ * npm `postinstall` (which re-implements the marker rewrite in plain JS since it
+ * can't import TS — see scripts/postinstall.js), `tmux-ide skill-sync` / the dev
+ * path of `tmux-ide update`, and `tmux-ide integration install claude`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getCurrentVersion } from "./update-check.ts";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+/**
+ * Claude Code's config dir: `TMUX_IDE_CLAUDE_DIR` when set (tests / per-run
+ * overrides), else `~/.claude`. Mirrors the {@link ../tui/integrations/claude.ts}
+ * settings override so both halves of the agent setup honor the same scratch dir.
+ */
+export function claudeDir(): string {
+  return process.env.TMUX_IDE_CLAUDE_DIR ?? join(homedir(), ".claude");
+}
+
+/** The fully-managed tmux-ide skill dir: `<claudeDir>/skills/tmux-ide`. */
+export function skillTargetDir(): string {
+  return join(claudeDir(), "skills", "tmux-ide");
+}
+
+/** The installed SKILL.md path (inside {@link skillTargetDir}). */
+export function skillTargetFile(): string {
+  return join(skillTargetDir(), "SKILL.md");
+}
+
+/**
+ * io — the bundled SKILL.md that ships in the package. Resolved relative to this
+ * module, handling BOTH the esbuild-bundled CLI (this file inlines into
+ * `bin/cli.js`, so `here` is `bin/` and the skill is one level up) AND the dev
+ * source tree (`packages/daemon/src/lib/`, four levels below the repo root) — the
+ * same dual-candidate trick as {@link getCurrentVersion}. Returns the first that
+ * exists, else the bundled-layout guess.
+ */
+export function defaultSkillSource(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, "../skill/SKILL.md"), // bundled bin/cli.js → repo root
+    join(here, "../../../../skill/SKILL.md"), // dev src/lib → repo root
+  ];
+  return candidates.find((c) => existsSync(c)) ?? candidates[0]!;
+}
+
+// ---------------------------------------------------------------------------
+// Pure — version marker
+// ---------------------------------------------------------------------------
+
+/**
+ * The version marker line (an HTML comment on line 2 of SKILL.md). The sync
+ * machinery reads it to know which version an installed copy is, and rewrites it
+ * to the installed package version at copy time.
+ */
+export const VERSION_MARKER_RE = /<!--\s*tmux-ide-skill-version:\s*([^\s]+)\s*-->/;
+
+/** PURE — render the marker line for a given version. */
+export function versionMarker(version: string): string {
+  return `<!-- tmux-ide-skill-version: ${version} -->`;
+}
+
+/** PURE — the version in a SKILL.md body, or null when the marker is absent. */
+export function parseSkillVersion(content: string): string | null {
+  const match = content.match(VERSION_MARKER_RE);
+  return match ? match[1]! : null;
+}
+
+/**
+ * PURE — return `content` with its version marker rewritten to `version`. When no
+ * marker is present the content is returned unchanged (the bundled SKILL.md
+ * always carries one; this just never corrupts a hand-stripped file).
+ */
+export function rewriteVersionMarker(content: string, version: string): string {
+  if (!VERSION_MARKER_RE.test(content)) return content;
+  return content.replace(VERSION_MARKER_RE, versionMarker(version));
+}
+
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+
+/** The version marker read off an installed SKILL.md, or null if absent/unreadable. */
+export function installedSkillVersion(dir: string = skillTargetDir()): string | null {
+  const file = join(dir, "SKILL.md");
+  if (!existsSync(file)) return null;
+  try {
+    return parseSkillVersion(readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+/** What a {@link syncSkill} did. */
+export interface SyncResult {
+  /** `installed` = target was absent; `updated` = content changed; `unchanged` = no-op. */
+  action: "installed" | "updated" | "unchanged";
+  /** The written SKILL.md path. */
+  path: string;
+  /** The installed version before an `updated` (the marker we replaced), if any. */
+  from?: string | null;
+  /** The version written into the copy's marker. */
+  to: string;
+}
+
+/**
+ * io — copy the bundled SKILL.md into the managed skill dir with its version
+ * marker rewritten to `version`. Content-driven and idempotent: the RENDERED
+ * source (marker substituted) is compared byte-for-byte against the installed
+ * copy — identical → `unchanged` (no write), absent → `installed`, otherwise
+ * `updated`. Only ever writes inside {@link skillTargetDir}; nothing outside it
+ * is read or touched.
+ */
+export function syncSkill({
+  source = defaultSkillSource(),
+  version = getCurrentVersion(),
+}: { source?: string; version?: string } = {}): SyncResult {
+  const rendered = rewriteVersionMarker(readFileSync(source, "utf-8"), version);
+  const dir = skillTargetDir();
+  const target = join(dir, "SKILL.md");
+
+  const existing = existsSync(target) ? readFileSync(target, "utf-8") : null;
+  if (existing === rendered) {
+    return { action: "unchanged", path: target, to: version };
+  }
+
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(target, rendered, "utf-8");
+
+  if (existing === null) return { action: "installed", path: target, to: version };
+  return { action: "updated", path: target, from: parseSkillVersion(existing), to: version };
+}

package/packages/daemon/src/lib/slugify.ts

@@ -0,0 +1,10 @@
+/**
+ * Convert text to a URL/filename-safe slug.
+ */
+export function slugify(text: string, maxLen = 40): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, maxLen);
+}

package/packages/daemon/src/lib/terminals-store.ts

@@ -0,0 +1,125 @@
+/**
+ * Terminals registry (G20-P1).
+ *
+ * JSON-backed persistence for tab-strip metadata — names, scopes, and
+ * kind. The actual PTY process lives in `PtyBridgeRegistry`; this
+ * store only persists what the UI needs to restore tab labels across
+ * reloads. Atomic writes (temp + rename) so a crash mid-write leaves
+ * the previous list intact.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Terminal, TerminalKind } from "@tmux-ide/contracts";
+
+const TERMINALS_FILE = ".tmux-ide/terminals.json";
+const SAFE_ID = /^[A-Za-z0-9_-]+$/u;
+
+function path(dir: string): string {
+  return join(dir, TERMINALS_FILE);
+}
+
+function ensureDir(dir: string): void {
+  mkdirSync(dirname(path(dir)), { recursive: true });
+}
+
+/** Load the full list for a session. Missing file → empty list. */
+export function loadTerminals(dir: string): Terminal[] {
+  const file = path(dir);
+  if (!existsSync(file)) return [];
+  try {
+    const body = readFileSync(file, "utf-8");
+    const parsed = JSON.parse(body) as { terminals?: unknown };
+    if (!parsed.terminals || !Array.isArray(parsed.terminals)) return [];
+    return parsed.terminals.filter((t): t is Terminal => isTerminal(t)).map((t) => ({ ...t }));
+  } catch {
+    return [];
+  }
+}
+
+function isTerminal(value: unknown): value is Terminal {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.id === "string" &&
+    SAFE_ID.test(v.id) &&
+    typeof v.projectId === "string" &&
+    typeof v.scopeId === "string" &&
+    typeof v.name === "string" &&
+    (v.kind === "shell" || v.kind === "setup" || v.kind === "run" || v.kind === "teardown") &&
+    typeof v.createdAt === "string" &&
+    typeof v.updatedAt === "string"
+  );
+}
+
+function writeAtomic(dir: string, terminals: Terminal[]): void {
+  ensureDir(dir);
+  const file = path(dir);
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ terminals }, null, 2) + "\n");
+  renameSync(tmp, file);
+}
+
+export interface CreateInput {
+  id: string;
+  projectId: string;
+  scopeId: string;
+  name: string;
+  kind: TerminalKind;
+  scripted?: boolean;
+}
+
+/** Insert OR replace a terminal record by id. Idempotent — calling
+ *  `createTerminal` twice with the same deterministic id is a no-op
+ *  on the canonical fields and updates `updatedAt`. */
+export function upsertTerminal(dir: string, input: CreateInput): Terminal {
+  if (!SAFE_ID.test(input.id)) {
+    throw new Error(`invalid terminal id "${input.id}"`);
+  }
+  const existing = loadTerminals(dir);
+  const idx = existing.findIndex((t) => t.id === input.id);
+  const now = new Date().toISOString();
+  const next: Terminal = {
+    id: input.id,
+    projectId: input.projectId,
+    scopeId: input.scopeId,
+    name: input.name,
+    kind: input.kind,
+    createdAt: existing[idx]?.createdAt ?? now,
+    updatedAt: now,
+    ...(input.scripted ? { scripted: true } : {}),
+  };
+  if (idx === -1) existing.push(next);
+  else existing[idx] = next;
+  writeAtomic(dir, existing);
+  return next;
+}
+
+export function renameTerminal(dir: string, id: string, name: string): Terminal | null {
+  const all = loadTerminals(dir);
+  const idx = all.findIndex((t) => t.id === id);
+  if (idx === -1) return null;
+  const trimmed = name.trim();
+  if (!trimmed) throw new Error("name required");
+  const next: Terminal = {
+    ...all[idx]!,
+    name: trimmed,
+    updatedAt: new Date().toISOString(),
+  };
+  all[idx] = next;
+  writeAtomic(dir, all);
+  return next;
+}
+
+export function deleteTerminal(dir: string, id: string): boolean {
+  const all = loadTerminals(dir);
+  const next = all.filter((t) => t.id !== id);
+  if (next.length === all.length) return false;
+  writeAtomic(dir, next);
+  return true;
+}
+
+export function findTerminal(dir: string, id: string): Terminal | null {
+  const all = loadTerminals(dir);
+  return all.find((t) => t.id === id) ?? null;
+}

package/packages/daemon/src/lib/tui-binary.ts

@@ -0,0 +1,165 @@
+/**
+ * Per-platform TUI binary: the runtime-download fallback that lets a clean
+ * `npm i -g tmux-ide` run the full OpenTUI/Solid cockpit WITHOUT `bun`.
+ *
+ * The dev checkout runs the `.tsx` surfaces via bun; an npm install with no bun
+ * needs a self-contained binary. We do NOT bundle that ~70MB blob in the npm
+ * tarball (a surprise on every install) — instead the release workflow
+ * (`.github/workflows/release-binaries.yml`) cross-compiles one per platform and
+ * uploads them as GitHub release assets, and this module downloads the right one
+ * on demand (explicit `tmux-ide update --tui-binary`, or a consented first run).
+ *
+ * The mapping/URL/path helpers are PURE (unit-tested); {@link downloadTuiBinary}
+ * and {@link findDownloadedTui} are the thin io that fetch and probe.
+ */
+import { chmodSync, existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import { getCurrentVersion } from "./update-check.ts";
+
+/** The `<os>-<arch>` tags we publish a prebuilt TUI binary for. */
+export type TuiPlatformTag = "darwin-arm64" | "darwin-x64" | "linux-x64" | "linux-arm64";
+
+/** The GitHub repo the release assets live under. */
+export const RELEASE_REPO = "wavyrai/tmux-ide";
+
+/** A downloaded binary smaller than this is treated as corrupt/truncated. */
+export const MIN_TUI_BINARY_BYTES = 10 * 1024 * 1024;
+
+const SUPPORTED: Record<string, TuiPlatformTag> = {
+  "darwin-arm64": "darwin-arm64",
+  "darwin-x64": "darwin-x64",
+  "linux-x64": "linux-x64",
+  "linux-arm64": "linux-arm64",
+};
+
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+
+/**
+ * PURE — map a Node `process.platform`/`process.arch` pair to the release tag,
+ * or null when we don't publish a binary for it (e.g. windows, freebsd) so the
+ * caller can fall back to the "install bun" message.
+ */
+export function tuiPlatformTag(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): TuiPlatformTag | null {
+  return SUPPORTED[`${platform}-${arch}`] ?? null;
+}
+
+/** PURE — the `bun build --compile --target` flag for a tag (`bun-<tag>`). */
+export function bunTargetForTag(tag: TuiPlatformTag): string {
+  return `bun-${tag}`;
+}
+
+/** PURE — the release asset filename for a tag (gzip-compressed binary). */
+export function releaseAssetName(tag: TuiPlatformTag): string {
+  return `tmux-ide-tui-${tag}.gz`;
+}
+
+/** PURE — strip a leading `v` from a version string; `2.6.1` and `v2.6.1` both → `2.6.1`. */
+export function normalizeVersion(version: string): string {
+  return version.startsWith("v") ? version.slice(1) : version;
+}
+
+/**
+ * PURE — the GitHub download URL for a platform's asset at a given version:
+ * `https://github.com/<repo>/releases/download/v<version>/tmux-ide-tui-<tag>.gz`.
+ */
+export function releaseAssetUrl(version: string, tag: TuiPlatformTag): string {
+  return `https://github.com/${RELEASE_REPO}/releases/download/v${normalizeVersion(version)}/${releaseAssetName(tag)}`;
+}
+
+/**
+ * PURE — where a downloaded binary lives: `<home>/bin/tmux-ide-tui-<tag>-<version>`.
+ * The version is stamped INTO the name so a `tmux-ide update` to a new version
+ * misses the old download and re-fetches (rather than launching a stale binary).
+ */
+export function downloadedTuiPath(home: string, tag: TuiPlatformTag, version: string): string {
+  return join(home, "bin", `tmux-ide-tui-${tag}-${normalizeVersion(version)}`);
+}
+
+// ---------------------------------------------------------------------------
+// io
+// ---------------------------------------------------------------------------
+
+/**
+ * io — the tmux-ide state home (`TMUX_IDE_HOME` override, else `~/.tmux-ide`),
+ * the same resolution the update-check cache and welcome marker use.
+ */
+export function tuiStateHome(): string {
+  return process.env.TMUX_IDE_HOME ?? join(homedir(), ".tmux-ide");
+}
+
+/**
+ * io — locate a previously downloaded per-platform binary for THIS version and
+ * platform, or null. Feeds the resolution order in `tui/compiled.ts` after the
+ * shipped/local compiled binary and before the honest "unavailable" error.
+ */
+export function findDownloadedTui(version: string = getCurrentVersion()): string | null {
+  const tag = tuiPlatformTag();
+  if (!tag) return null;
+  const path = downloadedTuiPath(tuiStateHome(), tag, version);
+  return existsSync(path) ? path : null;
+}
+
+/**
+ * io — download, verify, and install the per-platform TUI binary for the running
+ * version. Fetches the gzip asset, inflates it, rejects anything under
+ * {@link MIN_TUI_BINARY_BYTES} (a truncated download or an HTML error page),
+ * writes it `0o755`, and atomically renames it into place (temp-in-same-dir →
+ * rename, so a crashed download never leaves a half-written executable).
+ *
+ * Throws with an actionable message on an unsupported platform or a failed
+ * fetch. Returns the installed path and byte size.
+ */
+export async function downloadTuiBinary(
+  opts: {
+    version?: string;
+    log?: (msg: string) => void;
+  } = {},
+): Promise<{ path: string; bytes: number }> {
+  const log = opts.log ?? (() => {});
+  const version = normalizeVersion(opts.version ?? getCurrentVersion());
+  const tag = tuiPlatformTag();
+  if (!tag) {
+    throw new Error(
+      `no prebuilt TUI binary is published for ${process.platform}-${process.arch} — ` +
+        `install bun (https://bun.sh) to run the TUI surfaces from source instead`,
+    );
+  }
+
+  const url = releaseAssetUrl(version, tag);
+  const dest = downloadedTuiPath(tuiStateHome(), tag, version);
+  mkdirSync(dirname(dest), { recursive: true });
+
+  log(`downloading ${url}`);
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(
+      `could not download the TUI binary (${url} → HTTP ${res.status} ${res.statusText}). ` +
+        `Check that release v${version} exists and published its assets.`,
+    );
+  }
+
+  const gz = Buffer.from(await res.arrayBuffer());
+  const bin = gunzipSync(gz);
+  if (bin.byteLength < MIN_TUI_BINARY_BYTES) {
+    throw new Error(
+      `the downloaded TUI binary is only ${bin.byteLength} bytes (expected >10MB) — ` +
+        `treating it as corrupt and leaving the previous binary (if any) in place`,
+    );
+  }
+
+  const tmp = `${dest}.${process.pid}.tmp`;
+  writeFileSync(tmp, bin, { mode: 0o755 });
+  chmodSync(tmp, 0o755);
+  renameSync(tmp, dest);
+
+  const mb = (bin.byteLength / 1024 / 1024).toFixed(1);
+  log(`installed ${dest} (${mb} MB)`);
+  return { path: dest, bytes: bin.byteLength };
+}