@context-forge/core 0.13.0 → 0.13.2

package/dist/guides/gitExec.d.ts

@@ -2,6 +2,14 @@ export interface GitExecResult {
     stdout: string;
     stderr: string;
 }
+/**
+ * Offline/network remediation guidance for guide installation. Defined once and
+ * reused wherever a guide-install failure is surfaced, so the advice cannot drift
+ * between call sites (#78).
+ */
+export declare const GUIDE_OFFLINE_REMEDIATION: string;
+/** Append remediation guidance when a message looks like a network/DNS failure. */
+export declare function withNetworkErrorHint(message: string): string;
 /**
  * Execute a git command safely using execFile (no shell injection).
  * @param args - arguments to pass to git (e.g., ['clone', url, dir])

package/dist/guides/gitExec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gitExec.d.ts","sourceRoot":"","sources":["../../src/guides/gitExec.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAc3E;AAED,mDAAmD;AACnD,wBAAsB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAOvD;AAED,2DAA2D;AAC3D,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7D"}
+{"version":3,"file":"gitExec.d.ts","sourceRoot":"","sources":["../../src/guides/gitExec.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAyBD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAE4B,CAAC;AAEnE,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAkB3E;AAED,mDAAmD;AACnD,wBAAsB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAOvD;AAED,2DAA2D;AAC3D,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO7D"}

package/dist/guides/gitExec.js

@@ -1,5 +1,40 @@
 // Safe shell execution wrapper for git commands
 import { execFile } from 'child_process';
+// Guide install/update must never block on interactive input — the remote is always
+// expected to be publicly accessible. Without this, a credential helper (e.g. Git
+// Credential Manager) can silently pop a browser sign-in and hang the CLI forever.
+const GIT_NONINTERACTIVE_ENV = { GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never' };
+/** Strip embedded credentials (user:token@host) from URL-like args before they reach error messages/logs. */
+function redactCredentials(args) {
+    return args.map((arg) => arg.replace(/^(\w+:\/\/)[^/@\s]+@/, '$1')).join(' ');
+}
+// Substrings git/curl/Node emit for DNS, proxy, and connectivity failures.
+const NETWORK_ERROR_PATTERNS = [
+    /could not resolve host/i,
+    /could not connect to/i,
+    /connection timed out/i,
+    /network is unreachable/i,
+    /ssl certificate problem/i,
+    /failed to connect/i,
+    /enotfound/i,
+    /econnrefused/i,
+    /etimedout/i,
+];
+/**
+ * Offline/network remediation guidance for guide installation. Defined once and
+ * reused wherever a guide-install failure is surfaced, so the advice cannot drift
+ * between call sites (#78).
+ */
+export const GUIDE_OFFLINE_REMEDIATION = 'Check your VPN/proxy connection, or install offline by pointing guide.source ' +
+    'at a local path or mirror (cf config set guide.source <path>).';
+/** Append remediation guidance when a message looks like a network/DNS failure. */
+export function withNetworkErrorHint(message) {
+    if (!NETWORK_ERROR_PATTERNS.some((pattern) => pattern.test(message))) {
+        return message;
+    }
+    return (`${message}\n` +
+        `  This looks like a network/DNS problem reaching the remote. ${GUIDE_OFFLINE_REMEDIATION}`);
+}
 /**
  * Execute a git command safely using execFile (no shell injection).
  * @param args - arguments to pass to git (e.g., ['clone', url, dir])
@@ -7,9 +42,10 @@ import { execFile } from 'child_process';
  */
 export function gitExec(args, cwd) {
     return new Promise((resolve, reject) => {
-        execFile('git', args, { cwd }, (error, stdout, stderr) => {
+        execFile('git', args, { cwd, env: { ...process.env, ...GIT_NONINTERACTIVE_ENV } }, (error, stdout, stderr) => {
             if (error) {
-                reject(new Error(`git ${args.join(' ')} failed in ${cwd}: ${stderr.trim() || error.message}`));
+                const detail = stderr.trim() || error.message;
+                reject(new Error(withNetworkErrorHint(`git ${redactCredentials(args)} failed in ${cwd}: ${detail}`)));
                 return;
             }
             resolve({ stdout: stdout.trim(), stderr: stderr.trim() });

package/dist/guides/gitExec.js.map

@@ -1 +1 @@
-{"version":3,"file":"gitExec.js","sourceRoot":"","sources":["../../src/guides/gitExec.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAOzC;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,IAAc,EAAE,GAAW;IACjD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACvD,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CACJ,IAAI,KAAK,CACP,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,GAAG,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,OAAO,EAAE,CAC5E,CACF,CAAC;gBACF,OAAO;YACT,CAAC;YACD,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5D,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,CAAC,WAAW,EAAE,uBAAuB,CAAC,EAAE,GAAG,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"gitExec.js","sourceRoot":"","sources":["../../src/guides/gitExec.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAOzC,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,MAAM,sBAAsB,GAAG,EAAE,mBAAmB,EAAE,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC;AAEtF,6GAA6G;AAC7G,SAAS,iBAAiB,CAAC,IAAc;IACvC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,sBAAsB,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChF,CAAC;AAED,2EAA2E;AAC3E,MAAM,sBAAsB,GAAG;IAC7B,yBAAyB;IACzB,uBAAuB;IACvB,uBAAuB;IACvB,yBAAyB;IACzB,0BAA0B;IAC1B,oBAAoB;IACpB,YAAY;IACZ,eAAe;IACf,YAAY;CACb,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GACpC,+EAA+E;IAC/E,gEAAgE,CAAC;AAEnE,mFAAmF;AACnF,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACrE,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,CACL,GAAG,OAAO,IAAI;QACd,gEAAgE,yBAAyB,EAAE,CAC5F,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,IAAc,EAAE,GAAW;IACjD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CACN,KAAK,EACL,IAAI,EACJ,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,sBAAsB,EAAE,EAAE,EAC3D,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YACxB,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,OAAO,CAAC;gBAC9C,MAAM,CACJ,IAAI,KAAK,CAAC,oBAAoB,CAAC,OAAO,iBAAiB,CAAC,IAAI,CAAC,cAAc,GAAG,KAAK,MAAM,EAAE,CAAC,CAAC,CAC9F,CAAC;gBACF,OAAO;YACT,CAAC;YACD,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5D,CAAC,CACF,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAW;IACzC,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,CAAC,WAAW,EAAE,uBAAuB,CAAC,EAAE,GAAG,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/guides/index.d.ts

@@ -1,5 +1,6 @@
 export { GuideManager } from './GuideManager.js';
 export { GuideDetector } from './GuideDetector.js';
 export { type GuideInfo, type GuideMethod, type InstallResult, type UpdateResult, type DetectionResult, type InstallStrategy, DEFAULT_SOURCE_GIT, DEFAULT_SOURCE_API, GUIDE_RELATIVE_PATH, VERSION_MARKER_FILE, } from './types.js';
+export { GUIDE_OFFLINE_REMEDIATION } from './gitExec.js';
 export { type BranchGuardVerdict, evaluateBranchGuard, BranchGuardBlockedError, BranchGuardWarnError, } from './branchGuard.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/guides/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guides/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,kBAAkB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guides/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EACL,KAAK,kBAAkB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}

package/dist/guides/index.js

@@ -2,5 +2,7 @@
 export { GuideManager } from './GuideManager.js';
 export { GuideDetector } from './GuideDetector.js';
 export { DEFAULT_SOURCE_GIT, DEFAULT_SOURCE_API, GUIDE_RELATIVE_PATH, VERSION_MARKER_FILE, } from './types.js';
+// gitExec itself stays internal; only the shared remediation text is public (#78).
+export { GUIDE_OFFLINE_REMEDIATION } from './gitExec.js';
 export { evaluateBranchGuard, BranchGuardBlockedError, BranchGuardWarnError, } from './branchGuard.js';
 //# sourceMappingURL=index.js.map

package/dist/guides/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/guides/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAOL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAEL,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/guides/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAOL,kBAAkB,EAClB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,mFAAmF;AACnF,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAEL,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC"}

package/dist/guides/strategies/TarballStrategy.d.ts

@@ -11,7 +11,10 @@ export declare class TarballStrategy implements InstallStrategy {
     detect(_projectPath: string, targetDir: string): Promise<DetectionResult | null>;
     install(_projectPath: string, source: string, targetDir: string): Promise<InstallResult>;
     update(_projectPath: string, targetDir: string): Promise<UpdateResult>;
-    /** Fetch latest tag from remote using git ls-remote */
+    /**
+     * Fetch latest tag from remote using git ls-remote. Real failures (network,
+     * auth, invalid remote) propagate — only a genuinely tag-less remote yields null.
+     */
     private fetchLatestTag;
     /** Download tarball from GitHub API and extract to targetDir */
     private downloadAndExtract;

package/dist/guides/strategies/TarballStrategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TarballStrategy.d.ts","sourceRoot":"","sources":["../../../src/guides/strategies/TarballStrategy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAIjG;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMpF;AAED,qBAAa,eAAgB,YAAW,eAAe;IAC/C,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAYhF,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAaxF,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA4B5E,uDAAuD;YACzC,cAAc;IAgC5B,gEAAgE;YAClD,kBAAkB;CAgCjC"}
+{"version":3,"file":"TarballStrategy.d.ts","sourceRoot":"","sources":["../../../src/guides/strategies/TarballStrategy.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAIjG;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMpF;AAED,qBAAa,eAAgB,YAAW,eAAe;IAC/C,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAYhF,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAaxF,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA4B5E;;;OAGG;YACW,cAAc;IA4B5B,gEAAgE;YAClD,kBAAkB;CAyCjC"}

package/dist/guides/strategies/TarballStrategy.js

@@ -6,7 +6,7 @@ import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
 import { extract } from 'tar';
 import { VERSION_MARKER_FILE, DEFAULT_SOURCE_GIT } from '../types.js';
-import { gitExec } from '../gitExec.js';
+import { gitExec, withNetworkErrorHint } from '../gitExec.js';
 /**
  * Parse owner/repo from a GitHub source URL.
  * Supports: https://github.com/{owner}/{repo}.git and https://github.com/{owner}/{repo}
@@ -65,43 +65,51 @@ export class TarballStrategy {
         writeFileSync(join(targetDir, VERSION_MARKER_FILE), latestTag, 'utf-8');
         return { success: true, previousVersion, newVersion: latestTag, method: 'manual' };
     }
-    /** Fetch latest tag from remote using git ls-remote */
+    /**
+     * Fetch latest tag from remote using git ls-remote. Real failures (network,
+     * auth, invalid remote) propagate — only a genuinely tag-less remote yields null.
+     */
     async fetchLatestTag(source) {
-        try {
-            const { stdout } = await gitExec(['ls-remote', '--tags', '--sort=-v:refname', source], process.cwd());
-            const tagPattern = /refs\/tags\/(v?\d+\.\d+\.\d+)$/;
-            const tags = [];
-            for (const line of stdout.split('\n')) {
-                const match = tagPattern.exec(line.trim());
-                if (match)
-                    tags.push(match[1]);
-            }
-            if (tags.length === 0)
-                return null;
-            // Sort descending
-            tags.sort((a, b) => {
-                const pa = a.replace(/^v/, '').split('.').map(Number);
-                const pb = b.replace(/^v/, '').split('.').map(Number);
-                for (let i = 0; i < 3; i++) {
-                    if (pa[i] !== pb[i])
-                        return pb[i] - pa[i];
-                }
-                return 0;
-            });
-            return tags[0];
+        const { stdout } = await gitExec(['ls-remote', '--tags', '--sort=-v:refname', source], process.cwd());
+        const tagPattern = /refs\/tags\/(v?\d+\.\d+\.\d+)$/;
+        const tags = [];
+        for (const line of stdout.split('\n')) {
+            const match = tagPattern.exec(line.trim());
+            if (match)
+                tags.push(match[1]);
         }
-        catch {
+        if (tags.length === 0)
             return null;
-        }
+        // Sort descending
+        tags.sort((a, b) => {
+            const pa = a.replace(/^v/, '').split('.').map(Number);
+            const pb = b.replace(/^v/, '').split('.').map(Number);
+            for (let i = 0; i < 3; i++) {
+                if (pa[i] !== pb[i])
+                    return pb[i] - pa[i];
+            }
+            return 0;
+        });
+        return tags[0];
     }
     /** Download tarball from GitHub API and extract to targetDir */
     async downloadAndExtract(source, tag, targetDir) {
         const { owner, repo } = parseGitHubOwnerRepo(source);
         const url = `https://api.github.com/repos/${owner}/${repo}/tarball/${tag}`;
-        const response = await fetch(url, {
-            headers: { Accept: 'application/vnd.github+json' },
-            redirect: 'follow',
-        });
+        let response;
+        try {
+            response = await fetch(url, {
+                headers: { Accept: 'application/vnd.github+json' },
+                redirect: 'follow',
+            });
+        }
+        catch (err) {
+            // Node's fetch throws TypeError('fetch failed') with the real DNS/connection
+            // reason on err.cause.message — surface that, not the generic wrapper text.
+            const cause = err instanceof Error && err.cause instanceof Error ? err.cause.message : undefined;
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(withNetworkErrorHint(cause ? `${message}: ${cause}` : message));
+        }
         if (!response.ok) {
             throw new Error(`Failed to download tarball: ${response.status} ${response.statusText}`);
         }

package/dist/guides/strategies/TarballStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"TarballStrategy.js","sourceRoot":"","sources":["../../../src/guides/strategies/TarballStrategy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TarballStrategy.js","sourceRoot":"","sources":["../../../src/guides/strategies/TarballStrategy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@context-forge/core",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Core context generation engine for Context Forge — template processing, project state, prompt assembly",
   "type": "module",
   "main": "dist/index.js",