@shdwsdk/cli 0.0.0-stage → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/wizard.js ADDED
@@ -0,0 +1,193 @@
1
+ // ============================================================================
2
+ // @shdwsdk/cli — Interactive Setup Wizard (npx @shdwsdk/sdk init / npx shdw-init)
3
+ // ============================================================================
4
+ import { stdin as defaultInput, stdout as defaultOutput } from "node:process";
5
+ import { createInterface } from "node:readline/promises";
6
+ import { GRID_REGION_FACTORS, MODEL_ENERGY_COEFFICIENTS, resolveGridRegionFactor, resolveModelCoefficient, } from "@shdwsdk/sdk";
7
+ import { generateShdwBoilerplateFile } from "./codegen.js";
8
+ import { DEFAULT_SHDW_INGEST_ENDPOINT, testShdwConnectivity, } from "./connectivity.js";
9
+ import { injectShdwEnvVariables } from "./env.js";
10
+ export function parseCliArgs(argv) {
11
+ const opts = {};
12
+ for (let i = 0; i < argv.length; i++) {
13
+ const arg = argv[i];
14
+ if (arg === "--help" || arg === "-h") {
15
+ opts.help = true;
16
+ }
17
+ else if (arg === "--skip-ping") {
18
+ opts.skipPing = true;
19
+ }
20
+ else if (arg === "--api-key" && argv[i + 1]) {
21
+ opts.apiKey = argv[++i];
22
+ }
23
+ else if (arg === "--region" && argv[i + 1]) {
24
+ opts.region = argv[++i];
25
+ }
26
+ else if (arg === "--model" && argv[i + 1]) {
27
+ opts.model = argv[++i];
28
+ }
29
+ else if ((arg === "--out" || arg === "--output") && argv[i + 1]) {
30
+ opts.outputPath = argv[++i];
31
+ }
32
+ else if (arg === "--endpoint" && argv[i + 1]) {
33
+ opts.endpoint = argv[++i];
34
+ }
35
+ }
36
+ return opts;
37
+ }
38
+ function printHelp() {
39
+ defaultOutput.write(`
40
+ SHDWsdk (@shdwsdk/sdk) Interactive Setup Wizard
41
+
42
+ Usage:
43
+ npx @shdwsdk/sdk init
44
+ npx shdw-init
45
+
46
+ Options:
47
+ --api-key <key> SHDW API key (shdw_live_*)
48
+ --region <region> Primary cloud datacenter region (e.g., us-west-2, eu-north-1)
49
+ --model <pattern> Primary AI model pattern (e.g., claude-3-7-sonnet, gpt-4o, gemini-2.5-pro)
50
+ --out <path> Boilerplate output path (default: src/lib/shdw.ts)
51
+ --endpoint <url> Custom telemetry ingest URL (default: ${DEFAULT_SHDW_INGEST_ENDPOINT})
52
+ --skip-ping Skip the live connectivity validation ping
53
+ -h, --help Show this help message
54
+ `);
55
+ }
56
+ export async function runInitWizard(options = {}) {
57
+ const cwd = options.cwd ?? process.cwd();
58
+ const regions = Object.values(GRID_REGION_FACTORS);
59
+ const models = [...MODEL_ENERGY_COEFFICIENTS];
60
+ const needsInteractive = !options.apiKey || !options.region || !options.model || !options.outputPath;
61
+ const rl = needsInteractive
62
+ ? createInterface({ input: defaultInput, output: defaultOutput })
63
+ : null;
64
+ try {
65
+ if (needsInteractive) {
66
+ defaultOutput.write("\n=== SHDWsdk (@shdwsdk/sdk) Setup Wizard — Scope 3 Carbon & AI-BOM ===\n\n");
67
+ }
68
+ // 1. Prompt for SHDW API Key (shdw_live_*)
69
+ let apiKey = options.apiKey?.trim() ?? "";
70
+ while (!apiKey && rl) {
71
+ const answer = await rl.question("1. Enter your SHDW API key (shdw_live_*): ");
72
+ const trimmed = answer.trim();
73
+ if (trimmed.length < 12) {
74
+ defaultOutput.write(" Invalid API key. Please enter a valid key (at least 12 characters, e.g., shdw_live_...).\n");
75
+ continue;
76
+ }
77
+ if (!trimmed.startsWith("shdw_live_") && !trimmed.startsWith("shdw_test_")) {
78
+ defaultOutput.write(" Note: Production keys typically start with 'shdw_live_'. Proceeding with provided key.\n");
79
+ }
80
+ apiKey = trimmed;
81
+ }
82
+ // 2. Select Primary Cloud Data Center Region
83
+ let selectedRegion = options.region?.trim() ?? "";
84
+ if (!selectedRegion && rl) {
85
+ defaultOutput.write("\n2. Select your primary cloud data center region:\n");
86
+ regions.forEach((r, idx) => {
87
+ defaultOutput.write(` [${idx + 1}] ${r.region.padEnd(16)} — ${r.displayName} (${r.intensityGco2PerKwh} gCO2e/kWh)\n`);
88
+ });
89
+ const defaultIdx = regions.findIndex((r) => r.region === "us-west-2") + 1;
90
+ const answer = await rl.question(` Choose region number or code [default: ${defaultIdx} (us-west-2)]: `);
91
+ const trimmed = answer.trim();
92
+ if (!trimmed) {
93
+ selectedRegion = "us-west-2";
94
+ }
95
+ else {
96
+ const num = Number(trimmed);
97
+ if (Number.isInteger(num) && num >= 1 && num <= regions.length) {
98
+ selectedRegion = regions[num - 1]?.region ?? "us-west-2";
99
+ }
100
+ else {
101
+ selectedRegion = resolveGridRegionFactor(trimmed).region;
102
+ }
103
+ }
104
+ }
105
+ const resolvedRegion = resolveGridRegionFactor(selectedRegion || "us-west-2");
106
+ // 3. Select Primary AI Model Pattern
107
+ let selectedModel = options.model?.trim() ?? "";
108
+ if (!selectedModel && rl) {
109
+ defaultOutput.write("\n3. Select your primary AI model in production:\n");
110
+ models.forEach((m, idx) => {
111
+ defaultOutput.write(` [${idx + 1}] ${m.modelPattern.padEnd(22)} — ${m.displayName}\n`);
112
+ });
113
+ const answer = await rl.question(" Choose model number or pattern [default: 1 (claude-3-7-sonnet)]: ");
114
+ const trimmed = answer.trim();
115
+ if (!trimmed) {
116
+ selectedModel = "claude-3-7-sonnet";
117
+ }
118
+ else {
119
+ const num = Number(trimmed);
120
+ if (Number.isInteger(num) && num >= 1 && num <= models.length) {
121
+ selectedModel = models[num - 1]?.modelPattern ?? "claude-3-7-sonnet";
122
+ }
123
+ else {
124
+ selectedModel = trimmed;
125
+ }
126
+ }
127
+ }
128
+ const resolvedModel = resolveModelCoefficient(selectedModel || "claude-3-7-sonnet");
129
+ const effectiveModelPattern = resolvedModel.modelPattern === "default-frontier" && selectedModel
130
+ ? selectedModel
131
+ : resolvedModel.modelPattern;
132
+ // 4. Output Path for Boilerplate File
133
+ let outputPath = options.outputPath?.trim() ?? "";
134
+ if (!outputPath && rl) {
135
+ const answer = await rl.question("\n4. Boilerplate integration file path [default: src/lib/shdw.ts]: ");
136
+ outputPath = answer.trim() || "src/lib/shdw.ts";
137
+ }
138
+ if (!outputPath) {
139
+ outputPath = "src/lib/shdw.ts";
140
+ }
141
+ // 5. Environment File Injection (.env / .env.local)
142
+ const envResult = injectShdwEnvVariables({
143
+ cwd,
144
+ apiKey,
145
+ gridRegion: resolvedRegion.region,
146
+ });
147
+ defaultOutput.write(`\n[1/3] ${envResult.createdNew ? "Created" : "Updated"} ${envResult.fileName} (${envResult.filePath})\n`);
148
+ // 6. Boilerplate Code Generation
149
+ const codeResult = generateShdwBoilerplateFile({
150
+ cwd,
151
+ outputPath,
152
+ modelPattern: effectiveModelPattern,
153
+ gridRegion: resolvedRegion.region,
154
+ });
155
+ defaultOutput.write(`[2/3] Generated ${codeResult.providerLabel} integration at ${codeResult.relativePath}\n`);
156
+ // 7. Live Connectivity Test (<= 1500ms AbortController timeout)
157
+ let connectivity = null;
158
+ if (!options.skipPing) {
159
+ defaultOutput.write("[3/3] Testing live connectivity (1500ms timeout guard)...\n");
160
+ connectivity = await testShdwConnectivity({
161
+ apiKey,
162
+ modelPattern: effectiveModelPattern,
163
+ gridRegion: resolvedRegion.region,
164
+ endpoint: options.endpoint,
165
+ timeoutMs: 1500,
166
+ customFetch: options.customFetch,
167
+ });
168
+ defaultOutput.write(` ${connectivity.ok ? "OK:" : "WARN:"} ${connectivity.message}\n`);
169
+ }
170
+ defaultOutput.write(`\nSetup complete. Import your wrapped AI client from "./${codeResult.relativePath.replace(/\.ts$/, "")}" to begin tracking Scope 3 carbon & AI-BOM lineage.\n\n`);
171
+ return {
172
+ apiKeyPrefix: apiKey.slice(0, 14),
173
+ gridRegion: resolvedRegion.region,
174
+ modelPattern: effectiveModelPattern,
175
+ envFilePath: envResult.filePath,
176
+ boilerplateFilePath: codeResult.filePath,
177
+ connectivity,
178
+ };
179
+ }
180
+ finally {
181
+ rl?.close();
182
+ }
183
+ }
184
+ export async function runCliFromArgv(argv) {
185
+ const cleaned = argv[0] === "init" ? argv.slice(1) : argv;
186
+ const parsed = parseCliArgs(cleaned);
187
+ if (parsed.help) {
188
+ printHelp();
189
+ return;
190
+ }
191
+ await runInitWizard(parsed);
192
+ }
193
+ //# sourceMappingURL=wizard.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"wizard.js","sourceRoot":"","sources":["../src/wizard.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,47 @@
1
1
  {
2
2
  "name": "@shdwsdk/cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.2.0",
4
+ "description": "Interactive CLI setup wizard for @shdwsdk/sdk — configures environment variables, generates boilerplate, and verifies telemetry connectivity.",
5
+ "type": "module",
6
+ "main": "./dist/index.js",
7
+ "types": "./dist/index.d.ts",
8
+ "bin": {
9
+ "shdw-init": "./dist/bin.js",
10
+ "shdw": "./dist/bin.js"
11
+ },
12
+ "exports": {
13
+ ".": {
14
+ "types": "./dist/index.d.ts",
15
+ "import": "./dist/index.js"
16
+ }
17
+ },
18
+ "files": [
19
+ "dist",
20
+ "src"
21
+ ],
22
+ "scripts": {
23
+ "build": "tsc -p tsconfig.json",
24
+ "typecheck": "tsc -p tsconfig.json --noEmit",
25
+ "test": "vitest run"
26
+ },
27
+ "dependencies": {
28
+ "@shdwsdk/sdk": "^1.2.0"
29
+ },
30
+ "devDependencies": {
31
+ "@types/node": "^22.0.0",
32
+ "typescript": "^5.6.3",
33
+ "vitest": "^2.1.5"
34
+ },
35
+ "keywords": [
36
+ "shdw",
37
+ "shdwsdk",
38
+ "cli",
39
+ "ai-carbon",
40
+ "scope-3",
41
+ "ai-bom"
42
+ ],
43
+ "license": "MIT",
44
+ "publishConfig": {
45
+ "access": "public"
46
+ }
47
+ }
package/src/bin.ts ADDED
@@ -0,0 +1,12 @@
1
+ #!/usr/bin/env node
2
+ // ============================================================================
3
+ // @shdwsdk/cli — Executable Bin Entrypoint (npx shdw-init / npx @shdwsdk/cli init)
4
+ // ============================================================================
5
+
6
+ import { runCliFromArgv } from "./wizard.js";
7
+
8
+ runCliFromArgv(process.argv.slice(2)).catch((err: unknown) => {
9
+ const message = err instanceof Error ? err.message : String(err);
10
+ process.stderr.write(`SHDWsdk CLI Error: ${message}\n`);
11
+ process.exitCode = 1;
12
+ });
package/src/codegen.ts ADDED
@@ -0,0 +1,167 @@
1
+ // ============================================================================
2
+ // @shdwsdk/cli — Boilerplate Integration Code Generator
3
+ // Generates a pre-configured `src/lib/shdw.ts` (or custom path) wired with
4
+ // `ShdwTelemetryClient` and `wrapClient` for the user's selected AI model
5
+ // provider and cloud datacenter grid region.
6
+ // ============================================================================
7
+
8
+ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
9
+ import { dirname, resolve } from "node:path";
10
+ import {
11
+ resolveGridRegionFactor,
12
+ resolveModelCoefficient,
13
+ } from "@shdwsdk/sdk";
14
+
15
+ export interface GenerateBoilerplateParams {
16
+ cwd: string;
17
+ outputPath?: string;
18
+ modelPattern: string;
19
+ gridRegion: string;
20
+ }
21
+
22
+ export interface GeneratedBoilerplateResult {
23
+ filePath: string;
24
+ relativePath: string;
25
+ overwroteExisting: boolean;
26
+ providerLabel: string;
27
+ }
28
+
29
+ export function buildBoilerplateSource(params: {
30
+ modelPattern: string;
31
+ gridRegion: string;
32
+ }): { source: string; providerLabel: string } {
33
+ const modelCoeff = resolveModelCoefficient(params.modelPattern);
34
+ const gridFactor = resolveGridRegionFactor(params.gridRegion);
35
+
36
+ const header = `// ============================================================================
37
+ // SHDWsdk Integration (${modelCoeff.displayName})
38
+ // Region: ${gridFactor.displayName} (${gridFactor.intensityGco2PerKwh} gCO2e/kWh)
39
+ // Strictly non-blocking: <=1500ms AbortController timeout & silent fallback.
40
+ // ============================================================================
41
+
42
+ `;
43
+
44
+ if (modelCoeff.provider === "anthropic") {
45
+ return {
46
+ providerLabel: "Anthropic",
47
+ source: `${header}import Anthropic from "@anthropic-ai/sdk";
48
+ import { ShdwTelemetryClient } from "@shdwsdk/sdk";
49
+
50
+ export const shdw = new ShdwTelemetryClient({
51
+ apiKey: process.env.SHDW_API_KEY ?? "",
52
+ endpoint: "https://shdwsdk.ai/api/v1/ingest-telemetry",
53
+ defaultGridRegion: process.env.SHDW_GRID_REGION ?? "${gridFactor.region}",
54
+ defaultWorkloadName: "Production Anthropic AI Service",
55
+ timeoutMs: 1500,
56
+ });
57
+
58
+ export const anthropic = shdw.wrapClient(new Anthropic(), {
59
+ provider: "anthropic",
60
+ gridRegion: process.env.SHDW_GRID_REGION ?? "${gridFactor.region}",
61
+ defaultModel: "${params.modelPattern}",
62
+ });
63
+ `,
64
+ };
65
+ }
66
+
67
+ if (modelCoeff.provider === "gemini") {
68
+ return {
69
+ providerLabel: "Google Gemini",
70
+ source: `${header}import { GoogleGenerativeAI } from "@google/generative-ai";
71
+ import { ShdwTelemetryClient } from "@shdwsdk/sdk";
72
+
73
+ export const shdw = new ShdwTelemetryClient({
74
+ apiKey: process.env.SHDW_API_KEY ?? "",
75
+ endpoint: "https://shdwsdk.ai/api/v1/ingest-telemetry",
76
+ defaultGridRegion: process.env.SHDW_GRID_REGION ?? "${gridFactor.region}",
77
+ defaultWorkloadName: "Production Google Gemini Service",
78
+ timeoutMs: 1500,
79
+ });
80
+
81
+ const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY ?? "");
82
+
83
+ export const geminiModel = shdw.wrapClient(
84
+ genAI.getGenerativeModel({ model: "${params.modelPattern}" }),
85
+ {
86
+ provider: "gemini",
87
+ gridRegion: process.env.SHDW_GRID_REGION ?? "${gridFactor.region}",
88
+ defaultModel: "${params.modelPattern}",
89
+ }
90
+ );
91
+ `,
92
+ };
93
+ }
94
+
95
+ if (modelCoeff.provider === "openai") {
96
+ return {
97
+ providerLabel: "OpenAI",
98
+ source: `${header}import OpenAI from "openai";
99
+ import { ShdwTelemetryClient } from "@shdwsdk/sdk";
100
+
101
+ export const shdw = new ShdwTelemetryClient({
102
+ apiKey: process.env.SHDW_API_KEY ?? "",
103
+ endpoint: "https://shdwsdk.ai/api/v1/ingest-telemetry",
104
+ defaultGridRegion: process.env.SHDW_GRID_REGION ?? "${gridFactor.region}",
105
+ defaultWorkloadName: "Production OpenAI Service",
106
+ timeoutMs: 1500,
107
+ });
108
+
109
+ export const openai = shdw.wrapClient(new OpenAI(), {
110
+ provider: "openai",
111
+ gridRegion: process.env.SHDW_GRID_REGION ?? "${gridFactor.region}",
112
+ defaultModel: "${params.modelPattern}",
113
+ });
114
+ `,
115
+ };
116
+ }
117
+
118
+ // Custom / OpenAI-compatible (Mistral, Llama, DeepSeek, Cohere)
119
+ return {
120
+ providerLabel: modelCoeff.vendorGroup,
121
+ source: `${header}import OpenAI from "openai";
122
+ import { ShdwTelemetryClient } from "@shdwsdk/sdk";
123
+
124
+ export const shdw = new ShdwTelemetryClient({
125
+ apiKey: process.env.SHDW_API_KEY ?? "",
126
+ endpoint: "https://shdwsdk.ai/api/v1/ingest-telemetry",
127
+ defaultGridRegion: process.env.SHDW_GRID_REGION ?? "${gridFactor.region}",
128
+ defaultWorkloadName: "Production ${modelCoeff.vendorGroup} Service",
129
+ timeoutMs: 1500,
130
+ });
131
+
132
+ // Works with any OpenAI-compatible client (Mistral, vLLM, DeepSeek, Together, etc.)
133
+ export const aiClient = shdw.wrapClient(
134
+ new OpenAI({
135
+ apiKey: process.env.AI_PROVIDER_API_KEY ?? process.env.OPENAI_API_KEY ?? "",
136
+ }),
137
+ {
138
+ provider: "custom",
139
+ gridRegion: process.env.SHDW_GRID_REGION ?? "${gridFactor.region}",
140
+ defaultModel: "${params.modelPattern}",
141
+ }
142
+ );
143
+ `,
144
+ };
145
+ }
146
+
147
+ export function generateShdwBoilerplateFile(
148
+ params: GenerateBoilerplateParams
149
+ ): GeneratedBoilerplateResult {
150
+ const relativePath = params.outputPath?.trim() || "src/lib/shdw.ts";
151
+ const filePath = resolve(params.cwd, relativePath);
152
+ const overwroteExisting = existsSync(filePath);
153
+
154
+ mkdirSync(dirname(filePath), { recursive: true });
155
+ const { source, providerLabel } = buildBoilerplateSource({
156
+ modelPattern: params.modelPattern,
157
+ gridRegion: params.gridRegion,
158
+ });
159
+ writeFileSync(filePath, source, "utf8");
160
+
161
+ return {
162
+ filePath,
163
+ relativePath,
164
+ overwroteExisting,
165
+ providerLabel,
166
+ };
167
+ }
@@ -0,0 +1,131 @@
1
+ // ============================================================================
2
+ // @shdwsdk/cli — Live Connectivity Validation Ping
3
+ // Sends a lightweight validation ping to the SHDWsdk ingestion endpoint using
4
+ // an AbortController strictly clamped to <= 1500ms.
5
+ // ============================================================================
6
+
7
+ import { calculateFootprint, resolveModelCoefficient } from "@shdwsdk/sdk";
8
+
9
+ export const DEFAULT_SHDW_INGEST_ENDPOINT =
10
+ "https://shdwsdk.ai/api/v1/ingest-telemetry";
11
+ const MAX_CONNECTIVITY_TIMEOUT_MS = 1500;
12
+
13
+ export interface ConnectivityTestResult {
14
+ ok: boolean;
15
+ status: number | null;
16
+ latencyMs: number;
17
+ endpoint: string;
18
+ message: string;
19
+ }
20
+
21
+ export async function testShdwConnectivity(params: {
22
+ apiKey: string;
23
+ modelPattern: string;
24
+ gridRegion: string;
25
+ endpoint?: string;
26
+ timeoutMs?: number;
27
+ customFetch?: typeof fetch;
28
+ }): Promise<ConnectivityTestResult> {
29
+ const endpoint = params.endpoint ?? DEFAULT_SHDW_INGEST_ENDPOINT;
30
+ const timeoutMs = Math.min(
31
+ MAX_CONNECTIVITY_TIMEOUT_MS,
32
+ Math.max(100, params.timeoutMs ?? MAX_CONNECTIVITY_TIMEOUT_MS)
33
+ );
34
+ const fetchImpl = params.customFetch ?? globalThis.fetch.bind(globalThis);
35
+
36
+ const coeff = resolveModelCoefficient(params.modelPattern);
37
+ const footprint = calculateFootprint({
38
+ modelName: params.modelPattern,
39
+ promptTokens: 1,
40
+ completionTokens: 1,
41
+ gridRegion: params.gridRegion,
42
+ });
43
+
44
+ const controller = new AbortController();
45
+ const timeoutId = setTimeout(() => {
46
+ try {
47
+ controller.abort();
48
+ } catch {
49
+ // Ignore abort errors
50
+ }
51
+ }, timeoutMs);
52
+
53
+ const startedAt = Date.now();
54
+
55
+ try {
56
+ const res = await fetchImpl(endpoint, {
57
+ method: "POST",
58
+ headers: {
59
+ "Content-Type": "application/json",
60
+ "X-SHDW-Key": params.apiKey,
61
+ "X-SHDW-SDK-Version": "1.2.0-cli-init",
62
+ },
63
+ body: JSON.stringify({
64
+ events: [
65
+ {
66
+ model_name: params.modelPattern,
67
+ provider: coeff.provider,
68
+ prompt_tokens: 1,
69
+ completion_tokens: 1,
70
+ estimated_energy_kwh: footprint.estimatedEnergyKwh,
71
+ carbon_gco2e: footprint.carbonGco2e,
72
+ grid_region: footprint.gridRegion,
73
+ grid_intensity_gco2_kwh: footprint.gridIntensityGco2PerKwh,
74
+ is_streaming: false,
75
+ latency_ms: 1,
76
+ timestamp: new Date().toISOString(),
77
+ workload_name: "CLI Setup Verification Ping",
78
+ },
79
+ ],
80
+ }),
81
+ signal: controller.signal,
82
+ });
83
+
84
+ const latencyMs = Math.max(1, Date.now() - startedAt);
85
+
86
+ if (res.ok || res.status === 202) {
87
+ return {
88
+ ok: true,
89
+ status: res.status,
90
+ latencyMs,
91
+ endpoint,
92
+ message: `Connected (${res.status}) in ${latencyMs}ms — API key and telemetry route verified.`,
93
+ };
94
+ }
95
+
96
+ if (res.status === 401 || res.status === 403) {
97
+ return {
98
+ ok: false,
99
+ status: res.status,
100
+ latencyMs,
101
+ endpoint,
102
+ message: `Endpoint reachable (${res.status}), but API key was rejected. Verify your shdw_live_* key in the Dashboard.`,
103
+ };
104
+ }
105
+
106
+ return {
107
+ ok: false,
108
+ status: res.status,
109
+ latencyMs,
110
+ endpoint,
111
+ message: `Endpoint returned HTTP ${res.status} in ${latencyMs}ms. Local config was saved; telemetry will fail silently until the endpoint recovers.`,
112
+ };
113
+ } catch (err: unknown) {
114
+ const latencyMs = Math.max(1, Date.now() - startedAt);
115
+ const isAbort =
116
+ err instanceof Error &&
117
+ (err.name === "AbortError" || err.message.toLowerCase().includes("abort"));
118
+
119
+ return {
120
+ ok: false,
121
+ status: null,
122
+ latencyMs,
123
+ endpoint,
124
+ message: isAbort
125
+ ? `Connectivity check timed out after ${timeoutMs}ms (non-blocking guard active). Local config was saved.`
126
+ : `Could not reach ${endpoint} (${err instanceof Error ? err.message : "network error"}). Local config was saved.`,
127
+ };
128
+ } finally {
129
+ clearTimeout(timeoutId);
130
+ }
131
+ }