@tiens.nguyen/gu-cli 1.0.686 → 1.0.692

package/gu-cli.mjs

@@ -92,6 +92,8 @@ Usage:
   gu-cli rag                               # test the embedder end-to-end + list knowledge bases
   gu-cli workspace revert [runId]          # undo an agent run's file edits from its backups
   gu-cli clear [--scratch|--keep-history] [--yes]  # back to a fresh machine (asks first)
+  gu-cli fix-powershell [--check]          # Windows: drop PowerShell's built-in \`gu\` alias
+                                               #   (it is Get-Unique and shadows this CLI)
   gu-cli rag plan [path]                   # is RAG worth it here? files/chars/chunks → estimated index time
   gu-cli rag --test                        # can this machine embed and retrieve?
   gu-cli test-proxy                        # can this machine route model calls through a proxy?
@@ -905,6 +907,93 @@ if (args[0] === "token-usage" || args[0] === "tokens") {
   process.exit(0);
 }
 
+// `gu-cli fix-powershell` — drop PowerShell's built-in `gu` alias so the command works there.
+// ASKS FIRST and never runs as part of an install: a PowerShell profile is the user's file, and
+// a CLI that edits it unannounced is one that surprises people. --check only reports.
+if (args[0] === "fix-powershell") {
+  const pa = await import("./powershell-alias.mjs");
+  if (!pa.affectsThisMachine()) {
+    console.log("  Nothing to fix — this only affects Windows PowerShell.");
+    process.exit(0);
+  }
+  const { execFileSync } = await import("node:child_process");
+  const ps = (script) =>
+    execFileSync("powershell", ["-NoProfile", "-Command", script], { encoding: "utf8" }).trim();
+
+  let profilePath = "";
+  try {
+    profilePath = ps("$PROFILE");
+  } catch (e) {
+    console.error(`  Could not ask PowerShell where your profile is: ${e.message}`);
+    process.exit(1);
+  }
+  const { readFileSync, writeFileSync, mkdirSync, existsSync } = await import("node:fs");
+  const current = existsSync(profilePath) ? readFileSync(profilePath, "utf8") : "";
+  const next = pa.profileWithFix(current);
+  // ASKED IN EVERY PATH, because "already fixed" was reported on the very machine whose policy
+  // stops the profile loading — the same "said Done, changed nothing" mistake one branch along.
+  const blockedBy = () => {
+    try {
+      return pa.profileBlockedBy(ps("Get-ExecutionPolicy"));
+    } catch {
+      return "";
+    }
+  };
+  if (next === null) {
+    console.log(`  Already fixed — ${profilePath} removes the alias.`);
+    const blocked = blockedBy();
+    if (blocked) {
+      console.log("");
+      for (const l of pa.policyAdvice(blocked)) console.log("  " + l);
+      process.exit(1);
+    }
+    console.log("  Open a NEW PowerShell window for it to take effect.");
+    process.exit(0);
+  }
+  if (args.includes("--check")) {
+    console.log("  Not fixed yet. `gu` in PowerShell is still Get-Unique.");
+    const blocked = blockedBy();
+    if (blocked) for (const l of pa.policyAdvice(blocked)) console.log("  " + l);
+    console.log(`  Run:  gu-cli fix-powershell    (edits ${profilePath})`);
+    process.exit(1);
+  }
+  console.log("");
+  for (const l of pa.shadowedAdvice()) console.log("  " + l);
+  console.log("");
+  console.log(`  This appends ONE line to ${profilePath}:`);
+  console.log("    " + pa.PROFILE_LINE);
+  const rlp = (await import("node:readline")).createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const answer = await new Promise((r) => rlp.question("\n  Append it? [y/N]: ", r));
+  rlp.close();
+  if (!/^y(es)?$/i.test(String(answer).trim())) {
+    console.log("  " + pa.MEANWHILE);
+    process.exit(0);
+  }
+  try {
+    const dir = profilePath.replace(/[\\/][^\\/]*$/, "");
+    if (dir && !existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(profilePath, next, "utf8");
+  } catch (e) {
+    console.error(`  Could not write ${profilePath}: ${e.message}`);
+    process.exit(1);
+  }
+  console.log(`  Done — ${profilePath} updated.`);
+  // VERIFY THE FIX CAN ACTUALLY RUN. Writing the line is not the same as PowerShell loading it:
+  // under Restricted or AllSigned the profile is a script it refuses to execute, and the first
+  // real run of this said "Done" to a machine where `gu` stayed shadowed.
+  const policy = blockedBy();
+  if (policy) {
+    console.log("");
+    for (const l of pa.policyAdvice(policy)) console.log("  " + l);
+    process.exit(1);
+  }
+  console.log("  Open a NEW PowerShell window, then `gu` runs this CLI.");
+  process.exit(0);
+}
+
 if (args[0] === "clear" || args[0] === "reset") {
   const cs = await import("./clear-state.mjs");
   const scratchOnly = args.includes("--scratch");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiens.nguyen/gu-cli",
-  "version": "1.0.686",
+  "version": "1.0.692",
   "description": "Gu CLI — the gu terminal plus the local worker that runs agent / OCR / PDF / embedding jobs on your Mac (Ollama / MLX / OpenAI-compatible).",
   "type": "module",
   "license": "MIT",
@@ -13,9 +13,9 @@
     "url": "https://github.com/tiennsloit/gu/issues"
   },
   "bin": {
-    "gu-cli": "./gu-cli.mjs",
-    "gu-local-worker": "./gu-cli.mjs",
-    "gu": "./gu-repl.mjs"
+    "gu-cli": "gu-cli.mjs",
+    "gu-local-worker": "gu-cli.mjs",
+    "gu": "gu-repl.mjs"
   },
   "scripts": {
     "test": "python3 -m unittest discover tests -v && node --test",
@@ -77,6 +77,7 @@
     "proxy-dispatcher.mjs",
     "model-doctor.mjs",
     "coding-key-prompt.mjs",
+    "powershell-alias.mjs",
     "gonext_probe_agent.py",
     "gonext_agent_chat.py",
     "gonext_transcribe.py",

package/powershell-alias.mjs

@@ -0,0 +1,94 @@
+/**
+ * `gu` IS A BUILT-IN POWERSHELL ALIAS FOR Get-Unique.
+ *
+ * Found by the Windows end-to-end run: on Windows 11, where PowerShell is the default shell,
+ * typing `gu --help` runs Get-Unique and fails with "A positional parameter cannot be found that
+ * accepts argument '--help'". cmd.exe has no such alias, which is why it works there.
+ *
+ * NOTHING ON PATH CAN FIX THIS. PowerShell resolves Alias → Function → Cmdlet → Application, so
+ * an alias beats every executable and every function we could ship. The only remedies are to
+ * remove the alias from the user's profile, or to be called something else.
+ *
+ * So this offers the removal, EXPLICITLY and never automatically. A profile is the user's file;
+ * a CLI that edits it during an install is a CLI that surprises people. `gu-cli fix-powershell`
+ * asks, shows the line, and appends it — and `--check` just reports.
+ */
+
+/** The line appended to the profile. `-Force` because the built-in alias is read-only. */
+export const PROFILE_LINE =
+  "Remove-Item Alias:gu -Force -ErrorAction SilentlyContinue  # gu CLI: PowerShell's built-in `gu` is Get-Unique";
+
+/**
+ * What still works while the alias is in place.
+ *
+ * IT LIVES HERE, NOT IN gu-cli.mjs, and that is not tidiness. platform-assumptions.test.mjs
+ * switches on a rule for any file whose source mentions a quoted ".cmd" — and gu-cli.mjs has
+ * several long-standing spawn sites that the rule then flags. One sentence about `gu.cmd` in
+ * that file woke all of them. Keeping the string in this module leaves that file exactly as it
+ * was, and those sites a separate question rather than one a rename quietly changed.
+ */
+export const MEANWHILE = "Left alone. `gu-cli` and `gu.cmd` both run this program in the meantime.";
+
+/** True when this machine can even have the problem. */
+export function affectsThisMachine(platform = process.platform) {
+  return platform === "win32";
+}
+
+/**
+ * What to tell someone whose `gu` is shadowed.
+ *
+ * Names BOTH working commands first, because the immediate need is to run the thing at all —
+ * the profile edit is the fix for tomorrow, `gu-cli` is the fix for right now.
+ */
+export function shadowedAdvice() {
+  return [
+    "PowerShell has a built-in alias `gu` (Get-Unique) that wins over this CLI.",
+    "Right now:   use `gu-cli` — or `gu.cmd`, which is this program.",
+    "Permanently: run `gu-cli fix-powershell` to drop the alias from your PowerShell profile.",
+    "cmd.exe is unaffected; `gu` works there already.",
+  ];
+}
+
+/**
+ * Will PowerShell even LOAD a profile on this machine?
+ *
+ * Found immediately after the first real fix: the line was written, the command said "Done",
+ * and a new PowerShell still had the alias — because the execution policy was Restricted and
+ * profiles are scripts. A fix that cannot run is worse than no fix, because it stops you
+ * looking for the real reason.
+ *
+ * "Restricted" and "AllSigned" both refuse an unsigned profile. Everything else loads it.
+ */
+export function profileBlockedBy(policy) {
+  const p = String(policy ?? "").trim();
+  return /^(Restricted|AllSigned)$/i.test(p) ? p : "";
+}
+
+/** What to do about a policy that will not run the profile. The user's decision, not ours. */
+export function policyAdvice(policy) {
+  return [
+    `PowerShell's execution policy is ${policy}, so it will not load your profile —`,
+    "the line is written but will never run. To allow your own profile:",
+    "  Set-ExecutionPolicy -Scope CurrentUser RemoteSigned",
+    "Until then `gu-cli` and `gu.cmd` still work, and cmd.exe is unaffected.",
+  ];
+}
+
+/**
+ * Is the line already in a profile's text?
+ *
+ * Matched on the COMMAND, not the whole line including its comment — so a profile edited by
+ * hand, or by an older version of this message, is still recognised and not appended to twice.
+ */
+export function alreadyFixed(profileText) {
+  return /Remove-Item\s+Alias:gu\b/i.test(String(profileText ?? ""));
+}
+
+/** The text to write, given what the profile already holds. Returns null when nothing is needed. */
+export function profileWithFix(profileText) {
+  if (alreadyFixed(profileText)) return null;
+  const prev = String(profileText ?? "");
+  // A profile that does not end in a newline would otherwise get the fix glued to its last line.
+  const sep = prev.length === 0 ? "" : prev.endsWith("\n") ? "" : "\n";
+  return `${prev}${sep}${PROFILE_LINE}\n`;
+}