@ggcode-cli/ggcode 1.1.2 → 1.1.4

package/README.md

@@ -1,10 +1,16 @@
 # @ggcode-cli/ggcode
 
-`@ggcode-cli/ggcode` is a thin npm wrapper for the `ggcode` terminal agent.
+`@ggcode-cli/ggcode` installs the native `ggcode` binary from GitHub Releases.
 
-It does not bundle the native binary in the package. Instead, the wrapper downloads the latest
-`ggcode` GitHub Release for your platform on install or first run, caches it locally, and then
-launches it for you.
+During package installation it downloads the matching release archive, verifies it, and places the
+real `ggcode` executable in a stable CLI location:
+
+- macOS / Linux: prefers `/usr/local/bin`, falls back to `~/.local/bin`
+- Windows: prefers `%USERPROFILE%\\AppData\\Local\\Programs\\ggcode\\bin`, falls back to `%USERPROFILE%\\.local\\bin`
+
+If that directory is not on `PATH`, the installer updates your shell/user PATH and asks you to
+reopen the terminal. The npm package keeps a separate `ggcode-bootstrap` helper command for manual
+repair, but normal usage should be the real `ggcode` binary.
 
 ## Install
 
@@ -20,14 +26,19 @@ Then run:
 ggcode
 ```
 
-If you install it locally, use `npx ggcode` or `./node_modules/.bin/ggcode`.
+If the native install needs to be retried manually, run:
+
+```bash
+ggcode-bootstrap
+```
 
 ## What it does
 
 - Detects your platform and architecture
 - Downloads the latest matching `ggcode` binary from GitHub Releases
 - Verifies the downloaded archive with `checksums.txt`
-- Extracts and caches the binary for reuse
+- Installs the real binary into a stable PATH location
+- Updates `PATH` when needed so future `ggcode` launches bypass the wrapper
 
 ## Pin a specific ggcode release
 

package/bin/{ggcode.js → ggcode-bootstrap.js}

@@ -4,8 +4,12 @@ const { spawnSync } = require("child_process");
 const { ensureInstalled } = require("../lib/install");
 
 async function main() {
-  const binary = await ensureInstalled(process.env.GGCODE_INSTALL_VERSION, true);
-  const result = spawnSync(binary, process.argv.slice(2), {
+  const install = await ensureInstalled(process.env.GGCODE_INSTALL_VERSION, true);
+  if (install.needsRestart) {
+    console.error(`ggcode was installed to ${install.installDir}.`);
+    console.error("Reopen your terminal, then run `ggcode` directly.");
+  }
+  const result = spawnSync(install.binaryPath, process.argv.slice(2), {
     stdio: "inherit",
     env: { ...process.env, GGCODE_WRAPPER_KIND: "npm" },
   });
@@ -16,6 +20,6 @@ async function main() {
 }
 
 main().catch((err) => {
-  console.error(`ggcode npm wrapper failed: ${err.message}`);
+  console.error(`ggcode npm bootstrap failed: ${err.message}`);
   process.exit(1);
 });

package/lib/install.js

@@ -8,6 +8,9 @@ const { execFileSync } = require("child_process");
 const OWNER = "topcheer";
 const REPO = "ggcode";
 const BINARY = process.platform === "win32" ? "ggcode.exe" : "ggcode";
+const MARKER_START = "# >>> ggcode PATH >>>";
+const MARKER_END = "# <<< ggcode PATH <<<";
+const METADATA = ".ggcode-wrapper.json";
 
 function normalizeVersion(version) {
   const selected = (version || "").trim();
@@ -50,30 +53,195 @@ function releaseBase(version) {
   return `https://github.com/${OWNER}/${REPO}/releases/download/${version}`;
 }
 
-function cacheRoot() {
+function preferredInstallDirs() {
+  const home = os.homedir();
   if (process.platform === "win32") {
-    return path.join(process.env.LOCALAPPDATA || os.tmpdir(), "ggcode", "npm");
+    return [
+      path.join(home, "AppData", "Local", "Programs", "ggcode", "bin"),
+      path.join(home, ".local", "bin"),
+    ];
   }
-  return path.join(os.homedir(), ".cache", "ggcode", "npm");
+  return ["/usr/local/bin", path.join(home, ".local", "bin")];
 }
 
-function installRoot(version, target) {
-  return path.join(cacheRoot(), version, `${target.platform}-${process.arch}`);
+function metadataPath(dir) {
+  return path.join(dir, METADATA);
 }
 
-function binaryPath(version, target) {
-  return path.join(installRoot(version, target), target.binaryName);
+function pathEntries(value) {
+  return (value || "")
+    .split(path.delimiter)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+function samePath(a, b) {
+  const normalize = (value) => {
+    let result = path.resolve(value);
+    if (process.platform === "win32") {
+      result = result.replace(/[\\/]+$/, "").toLowerCase();
+    }
+    return result;
+  };
+  return normalize(a) === normalize(b);
+}
+
+function isPermissionError(err) {
+  return Boolean(err && ["EACCES", "EPERM"].includes(err.code));
+}
+
+function readMetadata(dir) {
+  try {
+    return JSON.parse(fs.readFileSync(metadataPath(dir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeMetadata(dir, version) {
+  fs.writeFileSync(metadataPath(dir), JSON.stringify({ version }, null, 2) + "\n", "utf8");
+}
+
+function findInstalledBinary(requestedVersion, target) {
+  for (const dir of preferredInstallDirs()) {
+    const binary = path.join(dir, target.binaryName);
+    if (!fs.existsSync(binary)) {
+      continue;
+    }
+    if (requestedVersion === "latest") {
+      return { dir, binary, version: readMetadata(dir)?.version || "unknown" };
+    }
+    const metadata = readMetadata(dir);
+    if (metadata && metadata.version === requestedVersion) {
+      return { dir, binary, version: metadata.version };
+    }
+  }
+  return null;
+}
+
+function installBinary(dir, target, extracted, version) {
+  fs.mkdirSync(dir, { recursive: true });
+  const dest = path.join(dir, target.binaryName);
+  const temp = `${dest}.tmp-${process.pid}`;
+  fs.copyFileSync(extracted, temp);
+  if (process.platform !== "win32") {
+    fs.chmodSync(temp, 0o755);
+  }
+  fs.rmSync(dest, { force: true });
+  fs.renameSync(temp, dest);
+  writeMetadata(dir, version);
+  return dest;
+}
+
+function ensureInstalledPath(dir) {
+  const currentEntries = pathEntries(process.env.PATH);
+  if (currentEntries.some((entry) => samePath(entry, dir))) {
+    return false;
+  }
+  if (process.platform === "win32") {
+    return ensureWindowsUserPath(dir);
+  }
+  return ensureUnixPath(dir);
+}
+
+function ensureWindowsUserPath(dir) {
+  const script = [
+    `$dir = ${powershellString(dir)}`,
+    "$current = [Environment]::GetEnvironmentVariable('Path', 'User')",
+    "$parts = @()",
+    "if ($current) { $parts = $current -split ';' | Where-Object { $_ -and $_.Trim() -ne '' } }",
+    "$exists = $parts | Where-Object { $_.TrimEnd('\\\\') -ieq $dir.TrimEnd('\\\\') }",
+    "if (-not $exists) {",
+    "  $new = @($dir) + $parts",
+    "  [Environment]::SetEnvironmentVariable('Path', ($new -join ';'), 'User')",
+    "  Write-Output 'updated'",
+    "} else {",
+    "  Write-Output 'unchanged'",
+    "}",
+  ].join("; ");
+  const output = execFileSync("powershell", ["-NoProfile", "-Command", script], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+  process.env.PATH = [dir, ...pathEntries(process.env.PATH)].join(path.delimiter);
+  return output === "updated";
+}
+
+function ensureUnixPath(dir) {
+  const files = profileTargets();
+  let changed = false;
+  for (const file of files) {
+    const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    const after = upsertPathBlock(before, dir);
+    if (after !== before) {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, after, "utf8");
+      changed = true;
+    }
+  }
+  process.env.PATH = [dir, ...pathEntries(process.env.PATH)].join(path.delimiter);
+  return changed;
+}
+
+function profileTargets() {
+  const home = os.homedir();
+  const shell = path.basename(process.env.SHELL || "");
+  const preferred = [];
+  if (shell === "zsh") {
+    preferred.push(".zshrc", ".zprofile");
+  } else if (shell === "bash") {
+    preferred.push(".bashrc", ".bash_profile");
+  }
+  preferred.push(".profile");
+
+  const existing = [".zshrc", ".zprofile", ".bashrc", ".bash_profile", ".profile"].filter((name) =>
+    fs.existsSync(path.join(home, name)),
+  );
+  const targets = [];
+  for (const name of [...preferred, ...existing]) {
+    const file = path.join(home, name);
+    if (!targets.some((entry) => samePath(entry, file))) {
+      targets.push(file);
+    }
+  }
+  return targets;
+}
+
+function upsertPathBlock(content, dir) {
+  const block = `${MARKER_START}\nexport PATH="${dir}:$PATH"\n${MARKER_END}\n`;
+  const pattern = new RegExp(`${escapeRegExp(MARKER_START)}[\\s\\S]*?${escapeRegExp(MARKER_END)}\\n?`, "m");
+  if (pattern.test(content)) {
+    return content.replace(pattern, block);
+  }
+  const suffix = content && !content.endsWith("\n") ? "\n" : "";
+  return `${content}${suffix}${block}`;
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function powershellString(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
 }
 
 async function ensureInstalled(version, quiet) {
   const requestedVersion = normalizeVersion(version);
-  const resolvedVersion = await resolveReleaseVersion(requestedVersion);
   const target = resolveTarget();
-  const dest = binaryPath(resolvedVersion, target);
-  if (fs.existsSync(dest)) {
-    return dest;
+  const existing = findInstalledBinary(requestedVersion, target);
+  if (existing) {
+    const pathUpdated = ensureInstalledPath(existing.dir);
+    return {
+      binaryPath: existing.binary,
+      installDir: existing.dir,
+      version: existing.version,
+      pathUpdated,
+      installedNow: false,
+      needsRestart: pathUpdated,
+    };
   }
 
+  const resolvedVersion = await resolveReleaseVersion(requestedVersion);
   const base = releaseBase(resolvedVersion);
   const archiveURL = `${base}/${target.archiveName}`;
   const checksumsURL = `${base}/checksums.txt`;
@@ -88,7 +256,7 @@ async function ensureInstalled(version, quiet) {
   fs.writeFileSync(archivePath, archive);
 
   if (!quiet) {
-    process.stderr.write(`Downloading ggcode ${resolvedVersion} from GitHub Releases...\n`);
+    process.stderr.write(`Installing ggcode ${resolvedVersion}...\n`);
   }
 
   extractArchive(target, archivePath, extractDir);
@@ -97,13 +265,34 @@ async function ensureInstalled(version, quiet) {
     throw new Error(`Could not find ${target.binaryName} inside ${target.archiveName}`);
   }
 
-  const root = installRoot(resolvedVersion, target);
-  fs.mkdirSync(root, { recursive: true });
-  fs.copyFileSync(extracted, dest);
-  if (process.platform !== "win32") {
-    fs.chmodSync(dest, 0o755);
+  let installDir = null;
+  let usedFallback = false;
+  let lastErr = null;
+  const installDirs = preferredInstallDirs();
+  for (const [index, dir] of installDirs.entries()) {
+    try {
+      const binaryPath = installBinary(dir, target, extracted, resolvedVersion);
+      installDir = dir;
+      usedFallback = index > 0;
+      const pathUpdated = ensureInstalledPath(dir);
+      return {
+        binaryPath,
+        installDir,
+        version: resolvedVersion,
+        pathUpdated,
+        installedNow: true,
+        needsRestart: pathUpdated,
+        usedFallback,
+      };
+    } catch (err) {
+      if (!isPermissionError(err) || index === installDirs.length - 1) {
+        lastErr = err;
+        break;
+      }
+    }
   }
-  return dest;
+
+  throw lastErr || new Error("Failed to install ggcode");
 }
 
 async function resolveReleaseVersion(version) {
@@ -140,7 +329,7 @@ function verifyChecksum(assetName, archive, checksumsText) {
 
 function extractArchive(target, archivePath, extractDir) {
   if (target.archiveExt === ".zip") {
-    const command = `Expand-Archive -LiteralPath '${archivePath.replace(/'/g, "''")}' -DestinationPath '${extractDir.replace(/'/g, "''")}' -Force`;
+    const command = `Expand-Archive -LiteralPath ${powershellString(archivePath)} -DestinationPath ${powershellString(extractDir)} -Force`;
     execFileSync("powershell", ["-NoProfile", "-Command", command], { stdio: "ignore" });
     return;
   }
@@ -175,7 +364,7 @@ function downloadBuffer(url) {
       https
         .get(target, (res) => {
           if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-            get(res.headers.location);
+            get(new URL(res.headers.location, target).toString());
             return;
           }
           if (res.statusCode !== 200) {
@@ -220,4 +409,6 @@ module.exports = {
   normalizeVersion,
   resolveReleaseVersion,
   resolveTarget,
+  upsertPathBlock,
+  preferredInstallDirs,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggcode-cli/ggcode",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Thin npm wrapper that installs the ggcode GitHub Release binary",
   "license": "MIT",
   "repository": {
@@ -16,7 +16,7 @@
     "provenance": true
   },
   "bin": {
-    "ggcode": "bin/ggcode.js"
+    "ggcode-bootstrap": "bin/ggcode-bootstrap.js"
   },
   "files": [
     "bin",

package/scripts/postinstall.js

@@ -2,7 +2,16 @@
 
 const { ensureInstalled } = require("../lib/install");
 
-ensureInstalled(process.env.GGCODE_INSTALL_VERSION, false).catch((err) => {
-  console.warn(`ggcode postinstall warning: ${err.message}`);
-  console.warn("The wrapper will try again on first run.");
-});
+ensureInstalled(process.env.GGCODE_INSTALL_VERSION, false)
+  .then((install) => {
+    const action = install.installedNow ? "installed" : "already available";
+    console.warn(`ggcode ${install.version} ${action} at ${install.binaryPath}`);
+    if (install.needsRestart) {
+      console.warn("Reopen your terminal, then run `ggcode` directly.");
+    }
+    console.warn("If you ever need to repair the bootstrap flow, run `ggcode-bootstrap`.");
+  })
+  .catch((err) => {
+    console.warn(`ggcode postinstall warning: ${err.message}`);
+    console.warn("Run `ggcode-bootstrap` to retry the native binary installation.");
+  });