garrytan / gstack / pull / 1111

#1111 · Import Universal v1.0.0

merged cross-platform @dev-ananta · 27 files changed · +4,539 −101

Net change

+4,438

Lines added

+4,539

Lines removed

−101

Files touched

gstack ships as a Claude Code workflow toolkit, currently macOS-only. This PR is the lift to universal support: Windows, macOS, and Linux, addressing three real blockers identified in CROSS_PLATFORM_ANALYSIS.md: (a) Mach-O-only binaries, (b) 100+ hardcoded ~/.gstack paths, (c) a Bash-only setup script.

The fix lands a new lib/paths.ts + lib/binary-locator.ts as the cross-platform shim, a setup.bat alongside the existing setup, and refactors make-pdf/src/pdftotext.ts to discover its dependency on PATH/Program Files/Snap rather than assuming Homebrew.

nice / correct info / context consider blocker

lib/paths.ts

NEW

+216

@@ cross-platform path utilities @@

import * as os from 'os';

import * as path from 'path';

export const IS_WINDOWS = process.platform === 'win32';

export const IS_MAC = process.platform === 'darwin';

export const IS_LINUX = process.platform === 'linux';

export function getHomeDir(): string {

return os.homedir();

}

export function getConfigDir(): string {

return path.join(getHomeDir(), '.gstack');

}

export function getTempDir(): string {

return os.tmpdir();

}

nice · platform flags

Module-level IS_WINDOWS / IS_MAC / IS_LINUX constants computed once, exported for callers. Cheaper than calling process.platform in hot paths, and they read clearer at call sites.

nice · getHomeDir

Uses os.homedir() instead of ~ string expansion. The original SKILL.md templates with ~/.gstack/... won't survive Windows shells; centralizing the resolver here is the right call.

info · getTempDir

Wraps os.tmpdir() — on Windows resolves to %TEMP% (typically C:\Users\<user>\AppData\Local\Temp). Replaces the hardcoded /tmp in make-pdf.

consider · XDG_CONFIG_HOME

On Linux, ~/.gstack works but ignores $XDG_CONFIG_HOME. Tools that follow XDG (Helix, fish, etc.) would expect ~/.config/gstack/. Not blocking — just worth a follow-up.

make-pdf/src/pdftotext.ts

+39 · −38

@@ resolution order — comment block @@

* Resolution order for the pdftotext binary:

* 2. `which pdftotext` on PATH

* 3. standard Homebrew paths on macOS

* Resolution order for the pdftotext binary (cross-platform):

* 2. Automatic discovery via lib/binary-locator

* - Searches: Program Files, Homebrew, /usr/bin, Snap, etc.

* - Platform-aware for Windows, macOS, Linux

@@ resolvePdftotext — sync → async @@

export function resolvePdftotext(): PdftotextInfo {

export async function resolvePdftotext(): Promise<PdftotextInfo> {

const envOverride = process.env.PDFTOTEXT_BIN;

if (envOverride && isExecutable(envOverride)) {

return describeBinary(envOverride);

}

// env override first (sync check); then platform-aware search

const located = await findBinary('pdftotext', { searchPaths: getPdfPlatformPaths() });

setup.bat

NEW

+95

@@ Windows setup — entry point @@

@echo off

REM gstack setup - Windows batch version

REM For Windows users who want to set up gstack without WSL/Git Bash

set "GSTACK_DIR=%~dp0"

set "GSTACK_DIR=%GSTACK_DIR:~0,-1%"

echo Home: %USERPROFILE%

echo gstack: %GSTACK_DIR%

package.json

+2 · −1

@@ build scripts @@

"build": "bun build --compile browse/src/cli.ts --outfile browse/dist/browse"

"build": "bun run scripts/build-binaries.ts",

"build:all": "bun run scripts/build-binaries.ts --all-platforms"

Takeaway

Solid, well-scoped lift. The two pieces that matter — lib/paths.ts as the cross-platform path resolver and lib/binary-locator.ts as the cross-platform binary discoverer — are shims in the good sense: they encapsulate platform divergence behind named functions so the rest of the codebase doesn't have to think about it.

One real blocker: resolvePdftotext went sync → async, which is a breaking change every caller has to absorb. The PR catches the local callers but it's worth grepping templates that ship to user-installed locations before merging.