pi-link 0.1.17 → 0.3.0

package/bin/pi-link.mjs

@@ -8,9 +8,7 @@
 //   pi-link --list [--global|-g] List pi-link sessions in current cwd (or everywhere).
 //   pi-link --resolve <name> [--global|-g]
 //                                Print just the session path (machine-readable).
-//
-// Deprecated subcommand forms `pi-link list` / `pi-link resolve <name>` still
-// work for one release with a stderr warning.
+//   pi-link --version            Print the installed pi-link version.
 
 import { readdir, stat } from "fs/promises";
 import { createReadStream, existsSync, readFileSync } from "fs";
@@ -19,6 +17,12 @@ import { join } from "path";
 import { homedir } from "os";
 import { spawn } from "child_process";
 
+// Canonicalize a link/session name: trim + collapse internal whitespace.
+// Must match the extension's normalizeName (index.ts).
+function normalizeName(s) {
+  return s.trim().replace(/\s+/g, " ");
+}
+
 // ── Pi config resolution ───────────────────────────────────────────────────
 // Match Pi's session-dir lookup order so list/resolve/<name> see what Pi sees.
 // Custom sessionDir → flat layout; default → <agentDir>/sessions/<encoded-cwd>.
@@ -67,32 +71,49 @@ function resolveSessionDir(cwd, agentDir) {
 }
 
 // Reads a session JSONL file and returns its display name, cwd, id, link
-// status, and message count.
+// status, and message count. Returns null when `scopeCwd` is given and the
+// session's header names a different cwd.
 //
 // Name precedence: latest valid `link-name` custom entry wins as the
 // authoritative pi-link name. `session_info.name` is only a fallback for
 // sessions that never set a link-name. Historical link-names are not aliases.
-async function getSessionMeta(filePath) {
+//
+// A scoped scan only ever keeps sessions from `scopeCwd`, so a session whose
+// header names another cwd is abandoned there instead of being read to EOF for
+// a name that would be filtered out anyway. Pi writes that header as the first
+// complete line of the file, before any history.
+//
+// Only `undefined` means unscoped: a normalized scope is the empty string at
+// POSIX root, which is a real scope and must not read as "no scope".
+async function getSessionMeta(filePath, scopeCwd) {
   let linkName;
   let sessionName;
   let cwd;
   let id;
   let hasLinkName = false;
   let messages = 0;
-  const rl = createInterface({ input: createReadStream(filePath, "utf-8"), crlfDelay: Infinity });
+  const input = createReadStream(filePath, "utf-8");
+  const rl = createInterface({ input, crlfDelay: Infinity });
   for await (const line of rl) {
     if (!line) continue;
     try {
       const entry = JSON.parse(line);
       if (entry.type === "session") {
-        if (typeof entry.cwd === "string") cwd = entry.cwd;
+        if (typeof entry.cwd === "string") {
+          if (scopeCwd !== undefined && normalizePath(entry.cwd) !== scopeCwd) {
+            rl.close();
+            input.destroy();
+            return null;
+          }
+          cwd = entry.cwd;
+        }
         if (typeof entry.id === "string") id = entry.id;
       } else if (entry.type === "session_info" && typeof entry.name === "string") {
-        sessionName = entry.name.trim().replace(/\s+/g, " ") || undefined;
+        sessionName = normalizeName(entry.name) || undefined;
       } else if (entry.type === "custom" && entry.customType === "link-name") {
         hasLinkName = true;
         if (entry.data && typeof entry.data.name === "string") {
-          const n = entry.data.name.trim().replace(/\s+/g, " ");
+          const n = normalizeName(entry.data.name);
           if (n) linkName = n;
         }
       } else if (entry.type === "message" || entry.type === "user" || entry.type === "assistant") {
@@ -142,9 +163,10 @@ function relTime(d) {
   return d.toISOString().slice(0, 10);
 }
 
-async function loadSessionRecord(filePath) {
+async function loadSessionRecord(filePath, scopeCwd) {
   try {
-    const meta = await getSessionMeta(filePath);
+    const meta = await getSessionMeta(filePath, scopeCwd);
+    if (!meta) return null; // known-foreign: not even worth a stat
     const stats = await stat(filePath);
     return { ...meta, modified: stats.mtime, path: filePath };
   } catch {
@@ -152,11 +174,12 @@ async function loadSessionRecord(filePath) {
   }
 }
 
-// Returns meta + mtime + path for every readable session in `dir`. Custom
-// layout is flat (<dir>/*.jsonl); default layout has one subdir level per
-// encoded cwd (<dir>/<sub>/*.jsonl). Errors on individual files/dirs are
-// silently skipped — active or partially-written sessions are tolerated.
-async function scanSessions(dir, isCustom) {
+// Returns meta + mtime + path for every readable session in `dir`, or only
+// those from `scopeCwd` when it is given. Custom layout is flat
+// (<dir>/*.jsonl); default layout has one subdir level per encoded cwd
+// (<dir>/<sub>/*.jsonl). Errors on individual files/dirs are silently skipped
+// — active or partially-written sessions are tolerated.
+async function scanSessions(dir, isCustom, scopeCwd) {
   let entries;
   try {
     entries = await readdir(dir, { withFileTypes: true });
@@ -168,7 +191,7 @@ async function scanSessions(dir, isCustom) {
   if (isCustom) {
     for (const entry of entries) {
       if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
-      tasks.push(loadSessionRecord(join(dir, entry.name)));
+      tasks.push(loadSessionRecord(join(dir, entry.name), scopeCwd));
     }
   } else {
     for (const sub of entries) {
@@ -178,7 +201,7 @@ async function scanSessions(dir, isCustom) {
       try { files = await readdir(subPath); } catch { continue; }
       for (const file of files) {
         if (!file.endsWith(".jsonl")) continue;
-        tasks.push(loadSessionRecord(join(subPath, file)));
+        tasks.push(loadSessionRecord(join(subPath, file), scopeCwd));
       }
     }
   }
@@ -186,28 +209,28 @@ async function scanSessions(dir, isCustom) {
   return (await Promise.all(tasks)).filter((s) => s !== null);
 }
 
-// Find sessions whose current display name matches `targetName`. Returns both
-// local-cwd matches and all matches (cross-cwd) so the caller can default to
-// local while still surfacing a hint when non-local matches exist. Falls back
-// to `session_info.name` for sessions without a link-name (so `pi-link <name>`
+// Find sessions whose current display name matches `targetName`, restricted to
+// `scopeCwd` when given and searched across every cwd when not. Falls back to
+// `session_info.name` for sessions without a link-name (so `pi-link <name>`
 // can attach link to a previously-unlinked named session).
-async function findSessionsByName(targetName, dir, isCustom) {
-  const localCwd = normalizePath(process.cwd());
-  const all = (await scanSessions(dir, isCustom))
+//
+// The cwd predicate is applied here as well as in the scan: a session whose
+// header carries no cwd is not rejected early, and must still be left out of a
+// scoped result.
+async function findSessionsByName(targetName, dir, isCustom, scopeCwd) {
+  return (await scanSessions(dir, isCustom, scopeCwd))
     .filter((s) => s.name === targetName)
+    .filter((s) => scopeCwd === undefined || (s.cwd && normalizePath(s.cwd) === scopeCwd))
     .map((s) => ({ path: s.path, cwd: s.cwd || "?", modified: s.modified }))
     .sort((a, b) => b.modified.getTime() - a.modified.getTime());
-  const local = all.filter((s) => normalizePath(s.cwd) === localCwd);
-  return { local, all };
 }
 
-// List pi-link sessions (those with at least one link-name entry). Default
-// scope is current cwd; `all` widens to every directory.
-async function listSessions({ all, dir, isCustom }) {
-  const localCwd = normalizePath(process.cwd());
-  return (await scanSessions(dir, isCustom))
+// List pi-link sessions (those with at least one link-name entry), restricted
+// to `scopeCwd` when given and covering every cwd when not.
+async function listSessions({ dir, isCustom, scopeCwd }) {
+  return (await scanSessions(dir, isCustom, scopeCwd))
     .filter((s) => s.hasLinkName)
-    .filter((s) => all || (s.cwd && normalizePath(s.cwd) === localCwd))
+    .filter((s) => scopeCwd === undefined || (s.cwd && normalizePath(s.cwd) === scopeCwd))
     .map((s) => ({
       name: s.name || "(unnamed)",
       cwd: s.cwd || "?",
@@ -237,20 +260,9 @@ function renderTable(rows, columns) {
 
 const rawArgs = process.argv.slice(2);
 
-// Reject pi-link flags renamed in 0.1.12 with a clear pointer to the new name.
-// Same intent as `rejectManagedFlag` (specific message > generic "Unknown argument")
-// but for our own renames, not Pi-managed flags.
-function rejectRenamedFlag(token) {
-  if (token === "--all" || token === "-a") {
-    const replacement = token === "-a" ? "-g" : "--global";
-    console.error(`Error: ${token} was renamed to ${replacement}.`);
-    process.exit(1);
-  }
-}
-
 // Reject Pi flags that pi-link manages, plus --link-name (which exists at the
 // `pi` level for link-only naming, but the wrapper's combined-mode contract
-// conflicts with it). Called from Phase 6 (mode entry) and Phase 7 (after
+// conflicts with it). Called from Phase 4 (mode entry) and Phase 5 (after
 // launcher name), so it fires on both `pi-link --session foo` and
 // `pi-link foo --session bar` with the friendly message.
 function rejectManagedFlag(token) {
@@ -288,22 +300,27 @@ function printHelp() {
   console.error("Usage: pi-link <name> [--global|-g] [pi flags...]");
   console.error("       pi-link --list [--global|-g]");
   console.error("       pi-link --resolve <name> [--global|-g]");
+  console.error("       pi-link --version");
   console.error("");
   console.error("By default, name lookup is scoped to the current cwd.");
   console.error("--global / -g widens the search to sessions in any cwd.");
 }
 
-function printDeprecationWarning(form) {
-  const canonical = form === "list" ? "--list" : "--resolve";
-  console.error(
-    `Warning: 'pi-link ${form}' is deprecated. Use 'pi-link ${canonical}' instead. ` +
-    `(Subcommand form will be removed in a future release.)`,
-  );
+function printVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
+    );
+    console.log(pkg.version ?? "unknown");
+  } catch {
+    console.log("unknown");
+  }
 }
 
 function describeMode(mode) {
   switch (mode) {
     case "help": return "--help";
+    case "version": return "--version";
     case "list": return "--list";
     case "resolve": return "--resolve";
     case "launcher": return "session name";
@@ -313,23 +330,19 @@ function describeMode(mode) {
 
 // ── Parser ─────────────────────────────────────────────────────────────────
 //
-// Single sequential pass populates `state`; dispatcher reads it. Phases (per
-// PLAN-cli-flags.md):
-//   1. Renamed-flag rejection (always-on for --all/-a)
-//   2. Global flags (--global, --help, --)
-//   3. Mode-selecting flags (--list, --resolve, --resolve=<name>)
-//   4. Deprecated subcommands (list, resolve <name>) — only at mode-null position
-//   5. Mode-specific extra-token rejection (with deprecated-resolve leniency)
-//   6. Launcher mode entry (mode null + bare positional)
-//   7. Launcher passthrough (mode launcher) with orphan-positional rejection
+// Single sequential pass populates `state`; dispatcher reads it. Phases:
+//   1. Global flags (--global, --help, --version, --)
+//   2. Mode-selecting flags (--list, --resolve, --resolve=<name>)
+//   3. Mode-specific extra-token rejection
+//   4. Launcher mode entry (mode null + bare positional)
+//   5. Launcher passthrough (mode launcher) with orphan-positional rejection
 
 const state = {
-  mode: null, // null | "help" | "list" | "resolve" | "launcher"
+  mode: null, // null | "help" | "version" | "list" | "resolve" | "launcher"
   resolveName: null,
   launcherName: null,
   global: false,
   piPassthrough: [],
-  deprecated: null, // null | "list" | "resolve"
 };
 
 function setMode(mode) {
@@ -344,10 +357,7 @@ let lastWasFlag = false;
 for (let i = 0; i < rawArgs.length; i++) {
   const a = rawArgs[i];
 
-  // Phase 1: renamed-flag rejection.
-  rejectRenamedFlag(a);
-
-  // Phase 2: global flags / scope-affecting tokens.
+  // Phase 1: global flags / scope-affecting tokens.
   if (a === "--global" || a === "-g") {
     state.global = true;
     lastWasFlag = false;
@@ -357,6 +367,10 @@ for (let i = 0; i < rawArgs.length; i++) {
     setMode("help"); // errors if combined with another mode
     continue;
   }
+  if (a === "--version") {
+    setMode("version"); // errors if combined with another mode
+    continue;
+  }
   if (a === "--") {
     // `--` only meaningful in launcher mode (separates pi flags from positionals).
     if (state.mode !== "launcher") {
@@ -369,7 +383,7 @@ for (let i = 0; i < rawArgs.length; i++) {
     break;
   }
 
-  // Phase 3: mode-selecting flags.
+  // Phase 2: mode-selecting flags.
   if (a === "--list") {
     setMode("list");
     continue;
@@ -392,57 +406,36 @@ for (let i = 0; i < rawArgs.length; i++) {
     continue;
   }
 
-  // Phase 4: deprecated subcommands (only at mode-null position).
-  if (state.mode === null && (a === "list" || a === "resolve")) {
-    state.deprecated = a;
-    if (a === "list") {
-      setMode("list");
-    } else {
-      setMode("resolve");
-      const next = rawArgs[i + 1];
-      if (next !== undefined && !next.startsWith("-")) {
-        state.resolveName = next;
-        i++;
-      }
-      // else: leave null; Phase 5 leniency or post-parse validation handles it.
-    }
-    continue;
-  }
-
-  // Phase 5: mode-specific extra-token rejection.
+  // Phase 3: mode-specific extra-token rejection.
   if (state.mode === "help") {
     fail(`--help does not accept arguments: ${a}`);
   }
+  if (state.mode === "version") {
+    fail(`--version does not accept arguments: ${a}`);
+  }
   if (state.mode === "list") {
     fail(`--list does not accept argument: ${a}\n  Usage: pi-link --list [--global|-g]`);
   }
   if (state.mode === "resolve") {
-    // Deprecated-form leniency: `pi-link resolve --global foo` was order-independent;
-    // if we entered via deprecated path and haven't bound a name yet, take this.
-    if (
-      state.deprecated === "resolve" &&
-      state.resolveName === null &&
-      !a.startsWith("-")
-    ) {
-      state.resolveName = a;
-      continue;
-    }
     fail(`--resolve accepts exactly one name; got extra: ${a}`);
   }
 
-  // Phase 6: launcher mode entry. state.mode === null here, no name set yet.
-  // (lastWasFlag is still false here — only Phase 7 sets it, and Phase 7 requires launcher mode.)
+  // Phase 4: launcher mode entry. state.mode === null here, no name set yet.
+  // (lastWasFlag is still false here — only Phase 5 sets it, and Phase 5 requires launcher mode.)
   if (state.mode === null) {
     rejectManagedFlag(a);
     if (a.startsWith("-")) {
       fail(`Unknown argument: ${a}\n  Usage: pi-link <name> [--global|-g] [pi flags...]`);
     }
+    if (a === "list" || a === "resolve") {
+      fail(`'pi-link ${a}' was removed. Use 'pi-link --${a}'.`);
+    }
     state.mode = "launcher";
     state.launcherName = a;
     continue;
   }
 
-  // Phase 7: launcher mode, name set. Tokens go to passthrough or get rejected.
+  // Phase 5: launcher mode, name set. Tokens go to passthrough or get rejected.
   rejectManagedFlag(a);
   if (a.startsWith("-")) {
     state.piPassthrough.push(a);
@@ -466,24 +459,20 @@ if (state.mode === "resolve") {
   if (state.resolveName === null) {
     fail(`--resolve requires a name argument.\n  Usage: pi-link --resolve <name> [--global|-g]`);
   }
-  const normalized = state.resolveName.trim().replace(/\s+/g, " ");
+  const normalized = normalizeName(state.resolveName);
   if (!normalized) {
     fail(`--resolve requires a non-empty name argument.\n  Usage: pi-link --resolve <name> [--global|-g]`);
   }
   state.resolveName = normalized;
 }
 if (state.mode === "launcher") {
-  const normalized = state.launcherName.trim().replace(/\s+/g, " ");
+  const normalized = normalizeName(state.launcherName);
   if (!normalized) {
     fail(`session name cannot be empty.\n  Usage: pi-link <name> [--global|-g] [pi flags...]`);
   }
   state.launcherName = normalized;
 }
 
-if (state.deprecated) {
-  printDeprecationWarning(state.deprecated);
-}
-
 // ── Dispatch ───────────────────────────────────────────────────────────────
 
 switch (state.mode) {
@@ -492,6 +481,10 @@ switch (state.mode) {
     printHelp();
     process.exit(0);
     break; // unreachable; present to satisfy no-fallthrough lints
+  case "version":
+    printVersion();
+    process.exit(0);
+    break; // unreachable; present to satisfy no-fallthrough lints
   case "list":
     await runList(state);
     break;
@@ -507,9 +500,14 @@ switch (state.mode) {
 
 // ── Mode handlers ──────────────────────────────────────────────────────────
 
+// A local operation scans only its own cwd; `--global` scans every cwd.
+function localScope(state) {
+  return state.global ? undefined : normalizePath(process.cwd());
+}
+
 async function runList(state) {
   const { dir, isCustom } = resolveSessionDir(process.cwd(), resolveAgentDir());
-  const sessions = await listSessions({ all: state.global, dir, isCustom });
+  const sessions = await listSessions({ dir, isCustom, scopeCwd: localScope(state) });
   if (sessions.length === 0) {
     console.log(state.global ? "No pi-link sessions found." : "No pi-link sessions found in this cwd.");
     console.log("Start one: pi-link <name>");
@@ -517,18 +515,18 @@ async function runList(state) {
   }
   const columns = state.global
     ? [
-        { header: "NAME", get: (s) => s.name },
-        { header: "CWD", get: (s) => displayPath(s.cwd) },
-        { header: "MODIFIED", get: (s) => relTime(s.modified), dim: true },
-        { header: "MESSAGES", get: (s) => s.messages, dim: true },
-        { header: "ID", get: (s) => s.id, dim: true },
-      ]
+      { header: "NAME", get: (s) => s.name },
+      { header: "CWD", get: (s) => displayPath(s.cwd) },
+      { header: "MODIFIED", get: (s) => relTime(s.modified), dim: true },
+      { header: "MESSAGES", get: (s) => s.messages, dim: true },
+      { header: "ID", get: (s) => s.id, dim: true },
+    ]
     : [
-        { header: "NAME", get: (s) => s.name },
-        { header: "MODIFIED", get: (s) => relTime(s.modified), dim: true },
-        { header: "MESSAGES", get: (s) => s.messages, dim: true },
-        { header: "ID", get: (s) => s.id, dim: true },
-      ];
+      { header: "NAME", get: (s) => s.name },
+      { header: "MODIFIED", get: (s) => relTime(s.modified), dim: true },
+      { header: "MESSAGES", get: (s) => s.messages, dim: true },
+      { header: "ID", get: (s) => s.id, dim: true },
+    ];
   console.log(renderTable(sessions, columns));
   if (process.stdout.isTTY) {
     console.log("");
@@ -539,8 +537,7 @@ async function runList(state) {
 async function runResolve(state) {
   const name = state.resolveName; // already normalized
   const { dir, isCustom } = resolveSessionDir(process.cwd(), resolveAgentDir());
-  const { local, all } = await findSessionsByName(name, dir, isCustom);
-  const matches = state.global ? all : local;
+  const matches = await findSessionsByName(name, dir, isCustom, localScope(state));
   if (matches.length === 1) {
     process.stdout.write(matches[0].path);
     return; // exit 0
@@ -549,18 +546,17 @@ async function runResolve(state) {
     printCandidates(name, matches); // exits 1
   }
   // matches.length === 0 → not found; exit 2 to distinguish from ambiguous.
+  // A local scan never reads names from other cwds, so the advice is offered
+  // without claiming anything is there.
   console.error(`No session named "${name}" found${state.global ? "" : " in this cwd"}.`);
-  if (!state.global && all.length > 0) {
-    console.error(`(${all.length} match${all.length === 1 ? "" : "es"} in other cwds — try --global to consider ${all.length === 1 ? "it" : "them"}.)`);
-  }
+  if (!state.global) console.error("Use --global to search other cwds.");
   process.exit(2);
 }
 
 async function runLauncher(state) {
   const name = state.launcherName; // already normalized
   const { dir, isCustom } = resolveSessionDir(process.cwd(), resolveAgentDir());
-  const { local, all } = await findSessionsByName(name, dir, isCustom);
-  const matches = state.global ? all : local;
+  const matches = await findSessionsByName(name, dir, isCustom, localScope(state));
   if (matches.length > 1) {
     printCandidates(name, matches);
   }
@@ -570,9 +566,8 @@ async function runLauncher(state) {
     console.error(`Resuming session: ${matches[0].path}`);
     piArgs.push("--session", matches[0].path);
   } else {
-    if (!state.global && all.length > local.length) {
-      const elsewhere = all.length - local.length;
-      console.error(`No "${name}" in this cwd. (${elsewhere} match${elsewhere === 1 ? "" : "es"} in other cwds — use --global to consider ${elsewhere === 1 ? "it" : "them"}.)`);
+    if (!state.global) {
+      console.error(`No "${name}" found in this cwd. Use --global to search other cwds.`);
     }
     console.error("Starting new session.");
   }