feat(appstash): add APPSTASH_BASE_DIR env var support

When no baseDir option is passed programmatically, appstash now checks
the APPSTASH_BASE_DIR environment variable before falling back to
os.homedir(). This enables test isolation without overriding HOME.

Priority: baseDir option > APPSTASH_BASE_DIR env var > os.homedir()

Author: pyramation

packages/appstash/__tests__/appstash.test.ts

@@ -132,6 +132,36 @@ describe('appstash', () => {
     });
   });
 
+  describe('APPSTASH_BASE_DIR env var', () => {
+    const originalEnv = process.env.APPSTASH_BASE_DIR;
+
+    afterEach(() => {
+      if (originalEnv === undefined) {
+        delete process.env.APPSTASH_BASE_DIR;
+      } else {
+        process.env.APPSTASH_BASE_DIR = originalEnv;
+      }
+    });
+
+    it('should use APPSTASH_BASE_DIR when no baseDir option is provided', () => {
+      process.env.APPSTASH_BASE_DIR = tempBase;
+      const dirs = appstash('pgpm');
+
+      expect(dirs.root).toBe(path.join(tempBase, '.pgpm'));
+      expect(dirs.config).toBe(path.join(tempBase, '.pgpm', 'config'));
+    });
+
+    it('should prefer baseDir option over APPSTASH_BASE_DIR env var', () => {
+      const otherBase = fs.mkdtempSync(path.join(os.tmpdir(), 'appstash-other-'));
+      process.env.APPSTASH_BASE_DIR = otherBase;
+
+      const dirs = appstash('pgpm', { baseDir: tempBase });
+
+      expect(dirs.root).toBe(path.join(tempBase, '.pgpm'));
+      fs.rmSync(otherBase, { recursive: true, force: true });
+    });
+  });
+
   describe('Edge cases', () => {
     it('should handle tool names with special characters', () => {
       const dirs = appstash('my-app', { baseDir: tempBase });

packages/appstash/src/index.ts

@@ -26,7 +26,7 @@ export interface AppStashResult {
  * Options for appstash()
  */
 export interface AppStashOptions {
-  /** Base directory (defaults to os.homedir()) */
+  /** Base directory (defaults to APPSTASH_BASE_DIR env var, then os.homedir()) */
   baseDir?: string;
   /** Use XDG fallback if home fails (default: true) */
   useXdgFallback?: boolean;
@@ -112,6 +112,8 @@ export function appstash(tool: string, options: AppStashOptions = {}): AppStashR
   let base: string;
   if (baseDir) {
     base = baseDir;
+  } else if (process.env.APPSTASH_BASE_DIR) {
+    base = process.env.APPSTASH_BASE_DIR;
   } else {
     const home = getHomeDir();
     if (!home) {