@shdwsdk/cli 1.2.2 → 1.3.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/LICENSE +21 -21
- package/README.md +26 -26
- package/dist/codegen.d.ts.map +1 -1
- package/dist/codegen.js +83 -82
- package/dist/codegen.js.map +1 -1
- package/dist/connectivity.js +1 -1
- package/dist/connectivity.js.map +1 -1
- package/dist/wizard.d.ts.map +1 -1
- package/dist/wizard.js +17 -16
- package/dist/wizard.js.map +1 -1
- package/package.json +58 -56
- package/src/bin.ts +12 -12
- package/src/codegen.ts +165 -167
- package/src/connectivity.ts +131 -131
- package/src/env.ts +144 -144
- package/src/index.ts +31 -31
- package/src/wizard.ts +262 -266
package/src/wizard.ts
CHANGED
|
@@ -1,266 +1,262 @@
|
|
|
1
|
-
// ============================================================================
|
|
2
|
-
// @shdwsdk/cli — Interactive Setup Wizard (npx @shdwsdk/sdk init / npx shdw-init)
|
|
3
|
-
// ============================================================================
|
|
4
|
-
|
|
5
|
-
import { stdin as defaultInput, stdout as defaultOutput } from "node:process";
|
|
6
|
-
import { createInterface } from "node:readline/promises";
|
|
7
|
-
import {
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
}
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
if (arg === "--
|
|
48
|
-
opts.
|
|
49
|
-
} else if (arg === "--
|
|
50
|
-
opts.
|
|
51
|
-
} else if (arg === "--
|
|
52
|
-
opts.
|
|
53
|
-
} else if (arg === "--
|
|
54
|
-
opts.
|
|
55
|
-
} else if (arg === "--
|
|
56
|
-
opts.
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
--
|
|
76
|
-
--
|
|
77
|
-
--
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
const
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
)
|
|
137
|
-
|
|
138
|
-
const
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
)
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
//
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
)
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
)
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
return;
|
|
264
|
-
}
|
|
265
|
-
await runInitWizard(parsed);
|
|
266
|
-
}
|
|
1
|
+
// ============================================================================
|
|
2
|
+
// @shdwsdk/cli — Interactive Setup Wizard (npx @shdwsdk/sdk init / npx shdw-init)
|
|
3
|
+
// ============================================================================
|
|
4
|
+
|
|
5
|
+
import { stdin as defaultInput, stdout as defaultOutput } from "node:process";
|
|
6
|
+
import { createInterface } from "node:readline/promises";
|
|
7
|
+
import { GRID_REGION_FACTORS, resolveGridRegionFactor } from "@shdwsdk/sdk";
|
|
8
|
+
import { MODEL_ENERGY_COEFFICIENTS, resolveModelCoefficient } from "@shdwsdk/energy-model";
|
|
9
|
+
import { generateShdwBoilerplateFile } from "./codegen.js";
|
|
10
|
+
import {
|
|
11
|
+
DEFAULT_SHDW_INGEST_ENDPOINT,
|
|
12
|
+
testShdwConnectivity,
|
|
13
|
+
type ConnectivityTestResult,
|
|
14
|
+
} from "./connectivity.js";
|
|
15
|
+
import { injectShdwEnvVariables } from "./env.js";
|
|
16
|
+
|
|
17
|
+
export interface CliWizardOptions {
|
|
18
|
+
cwd?: string;
|
|
19
|
+
apiKey?: string;
|
|
20
|
+
region?: string;
|
|
21
|
+
model?: string;
|
|
22
|
+
outputPath?: string;
|
|
23
|
+
endpoint?: string;
|
|
24
|
+
skipPing?: boolean;
|
|
25
|
+
customFetch?: typeof fetch;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export interface CliWizardResult {
|
|
29
|
+
apiKeyPrefix: string;
|
|
30
|
+
gridRegion: string;
|
|
31
|
+
modelPattern: string;
|
|
32
|
+
envFilePath: string;
|
|
33
|
+
boilerplateFilePath: string;
|
|
34
|
+
connectivity: ConnectivityTestResult | null;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export function parseCliArgs(argv: readonly string[]): CliWizardOptions & {
|
|
38
|
+
help?: boolean;
|
|
39
|
+
} {
|
|
40
|
+
const opts: CliWizardOptions & { help?: boolean } = {};
|
|
41
|
+
for (let i = 0; i < argv.length; i++) {
|
|
42
|
+
const arg = argv[i];
|
|
43
|
+
if (arg === "--help" || arg === "-h") {
|
|
44
|
+
opts.help = true;
|
|
45
|
+
} else if (arg === "--skip-ping") {
|
|
46
|
+
opts.skipPing = true;
|
|
47
|
+
} else if (arg === "--api-key" && argv[i + 1]) {
|
|
48
|
+
opts.apiKey = argv[++i];
|
|
49
|
+
} else if (arg === "--region" && argv[i + 1]) {
|
|
50
|
+
opts.region = argv[++i];
|
|
51
|
+
} else if (arg === "--model" && argv[i + 1]) {
|
|
52
|
+
opts.model = argv[++i];
|
|
53
|
+
} else if ((arg === "--out" || arg === "--output") && argv[i + 1]) {
|
|
54
|
+
opts.outputPath = argv[++i];
|
|
55
|
+
} else if (arg === "--endpoint" && argv[i + 1]) {
|
|
56
|
+
opts.endpoint = argv[++i];
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
return opts;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function printHelp(): void {
|
|
63
|
+
defaultOutput.write(`
|
|
64
|
+
SHDWsdk (@shdwsdk/sdk) Interactive Setup Wizard
|
|
65
|
+
|
|
66
|
+
Usage:
|
|
67
|
+
npx @shdwsdk/sdk init
|
|
68
|
+
npx shdw-init
|
|
69
|
+
|
|
70
|
+
Options:
|
|
71
|
+
--api-key <key> SHDW API key (shdw_live_*)
|
|
72
|
+
--region <region> Primary cloud datacenter region (e.g., us-west-2, eu-north-1)
|
|
73
|
+
--model <pattern> Primary AI model id (e.g., claude-sonnet-5-5, gpt-6.1-sol, gemini-3.8-flash)
|
|
74
|
+
--out <path> Boilerplate output path (default: src/lib/shdw.ts)
|
|
75
|
+
--endpoint <url> Custom telemetry ingest URL (default: ${DEFAULT_SHDW_INGEST_ENDPOINT})
|
|
76
|
+
--skip-ping Skip the live connectivity validation ping
|
|
77
|
+
-h, --help Show this help message
|
|
78
|
+
`);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
export async function runInitWizard(
|
|
82
|
+
options: CliWizardOptions = {}
|
|
83
|
+
): Promise<CliWizardResult> {
|
|
84
|
+
const cwd = options.cwd ?? process.cwd();
|
|
85
|
+
const regions = Object.values(GRID_REGION_FACTORS);
|
|
86
|
+
const models = [...MODEL_ENERGY_COEFFICIENTS];
|
|
87
|
+
|
|
88
|
+
const needsInteractive =
|
|
89
|
+
!options.apiKey || !options.region || !options.model || !options.outputPath;
|
|
90
|
+
|
|
91
|
+
const rl = needsInteractive
|
|
92
|
+
? createInterface({ input: defaultInput, output: defaultOutput })
|
|
93
|
+
: null;
|
|
94
|
+
|
|
95
|
+
try {
|
|
96
|
+
if (needsInteractive) {
|
|
97
|
+
defaultOutput.write(
|
|
98
|
+
"\n=== SHDWsdk (@shdwsdk/sdk) Setup Wizard — Scope 3 Carbon & AI-BOM ===\n\n"
|
|
99
|
+
);
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// 1. Prompt for SHDW API Key (shdw_live_*)
|
|
103
|
+
let apiKey = options.apiKey?.trim() ?? "";
|
|
104
|
+
while (!apiKey && rl) {
|
|
105
|
+
const answer = await rl.question(
|
|
106
|
+
"1. Enter your SHDW API key (shdw_live_*): "
|
|
107
|
+
);
|
|
108
|
+
const trimmed = answer.trim();
|
|
109
|
+
if (trimmed.length < 12) {
|
|
110
|
+
defaultOutput.write(
|
|
111
|
+
" Invalid API key. Please enter a valid key (at least 12 characters, e.g., shdw_live_...).\n"
|
|
112
|
+
);
|
|
113
|
+
continue;
|
|
114
|
+
}
|
|
115
|
+
if (!trimmed.startsWith("shdw_live_") && !trimmed.startsWith("shdw_test_")) {
|
|
116
|
+
defaultOutput.write(
|
|
117
|
+
" Note: Production keys typically start with 'shdw_live_'. Proceeding with provided key.\n"
|
|
118
|
+
);
|
|
119
|
+
}
|
|
120
|
+
apiKey = trimmed;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
// 2. Select Primary Cloud Data Center Region
|
|
124
|
+
let selectedRegion = options.region?.trim() ?? "";
|
|
125
|
+
if (!selectedRegion && rl) {
|
|
126
|
+
defaultOutput.write(
|
|
127
|
+
"\n2. Select your primary cloud data center region:\n"
|
|
128
|
+
);
|
|
129
|
+
regions.forEach((r, idx) => {
|
|
130
|
+
defaultOutput.write(
|
|
131
|
+
` [${idx + 1}] ${r.region.padEnd(16)} — ${r.displayName} (${r.intensityGco2PerKwh} gCO2e/kWh)\n`
|
|
132
|
+
);
|
|
133
|
+
});
|
|
134
|
+
const defaultIdx = regions.findIndex((r) => r.region === "us-west-2") + 1;
|
|
135
|
+
const answer = await rl.question(
|
|
136
|
+
` Choose region number or code [default: ${defaultIdx} (us-west-2)]: `
|
|
137
|
+
);
|
|
138
|
+
const trimmed = answer.trim();
|
|
139
|
+
if (!trimmed) {
|
|
140
|
+
selectedRegion = "us-west-2";
|
|
141
|
+
} else {
|
|
142
|
+
const num = Number(trimmed);
|
|
143
|
+
if (Number.isInteger(num) && num >= 1 && num <= regions.length) {
|
|
144
|
+
selectedRegion = regions[num - 1]?.region ?? "us-west-2";
|
|
145
|
+
} else {
|
|
146
|
+
selectedRegion = resolveGridRegionFactor(trimmed).region;
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
const resolvedRegion = resolveGridRegionFactor(
|
|
151
|
+
selectedRegion || "us-west-2"
|
|
152
|
+
);
|
|
153
|
+
|
|
154
|
+
// 3. Select Primary AI Model Pattern
|
|
155
|
+
let selectedModel = options.model?.trim() ?? "";
|
|
156
|
+
if (!selectedModel && rl) {
|
|
157
|
+
defaultOutput.write("\n3. Select your primary AI model in production:\n");
|
|
158
|
+
models.forEach((m, idx) => {
|
|
159
|
+
defaultOutput.write(
|
|
160
|
+
` [${idx + 1}] ${m.modelPattern.padEnd(22)} — ${m.displayName}\n`
|
|
161
|
+
);
|
|
162
|
+
});
|
|
163
|
+
const answer = await rl.question(
|
|
164
|
+
` Choose model number or id [default: 1 (${models[0]?.modelPattern ?? "claude-sonnet-5-5"})]: `
|
|
165
|
+
);
|
|
166
|
+
const trimmed = answer.trim();
|
|
167
|
+
if (!trimmed) {
|
|
168
|
+
selectedModel = models[0]?.modelPattern ?? "claude-sonnet-5-5";
|
|
169
|
+
} else {
|
|
170
|
+
const num = Number(trimmed);
|
|
171
|
+
if (Number.isInteger(num) && num >= 1 && num <= models.length) {
|
|
172
|
+
selectedModel = models[num - 1]?.modelPattern ?? "claude-sonnet-5-5";
|
|
173
|
+
} else {
|
|
174
|
+
selectedModel = trimmed;
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
const resolvedModel = resolveModelCoefficient(
|
|
179
|
+
selectedModel || models[0]?.modelPattern || "claude-sonnet-5-5"
|
|
180
|
+
);
|
|
181
|
+
// Keep the id the user will actually send to their provider; the catalog
|
|
182
|
+
// match is only used to pick provider-specific boilerplate.
|
|
183
|
+
const effectiveModelPattern = selectedModel || resolvedModel.modelPattern;
|
|
184
|
+
|
|
185
|
+
// 4. Output Path for Boilerplate File
|
|
186
|
+
let outputPath = options.outputPath?.trim() ?? "";
|
|
187
|
+
if (!outputPath && rl) {
|
|
188
|
+
const answer = await rl.question(
|
|
189
|
+
"\n4. Boilerplate integration file path [default: src/lib/shdw.ts]: "
|
|
190
|
+
);
|
|
191
|
+
outputPath = answer.trim() || "src/lib/shdw.ts";
|
|
192
|
+
}
|
|
193
|
+
if (!outputPath) {
|
|
194
|
+
outputPath = "src/lib/shdw.ts";
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
// 5. Environment File Injection (.env / .env.local)
|
|
198
|
+
const envResult = injectShdwEnvVariables({
|
|
199
|
+
cwd,
|
|
200
|
+
apiKey,
|
|
201
|
+
gridRegion: resolvedRegion.region,
|
|
202
|
+
});
|
|
203
|
+
defaultOutput.write(
|
|
204
|
+
`\n[1/3] ${envResult.createdNew ? "Created" : "Updated"} ${envResult.fileName} (${envResult.filePath})\n`
|
|
205
|
+
);
|
|
206
|
+
|
|
207
|
+
// 6. Boilerplate Code Generation
|
|
208
|
+
const codeResult = generateShdwBoilerplateFile({
|
|
209
|
+
cwd,
|
|
210
|
+
outputPath,
|
|
211
|
+
modelPattern: effectiveModelPattern,
|
|
212
|
+
gridRegion: resolvedRegion.region,
|
|
213
|
+
});
|
|
214
|
+
defaultOutput.write(
|
|
215
|
+
`[2/3] Generated ${codeResult.providerLabel} integration at ${codeResult.relativePath}\n`
|
|
216
|
+
);
|
|
217
|
+
|
|
218
|
+
// 7. Live Connectivity Test (<= 1500ms AbortController timeout)
|
|
219
|
+
let connectivity: ConnectivityTestResult | null = null;
|
|
220
|
+
if (!options.skipPing) {
|
|
221
|
+
defaultOutput.write(
|
|
222
|
+
"[3/3] Testing live connectivity (1500ms timeout guard)...\n"
|
|
223
|
+
);
|
|
224
|
+
connectivity = await testShdwConnectivity({
|
|
225
|
+
apiKey,
|
|
226
|
+
modelPattern: effectiveModelPattern,
|
|
227
|
+
gridRegion: resolvedRegion.region,
|
|
228
|
+
endpoint: options.endpoint,
|
|
229
|
+
timeoutMs: 1500,
|
|
230
|
+
customFetch: options.customFetch,
|
|
231
|
+
});
|
|
232
|
+
defaultOutput.write(
|
|
233
|
+
` ${connectivity.ok ? "OK:" : "WARN:"} ${connectivity.message}\n`
|
|
234
|
+
);
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
defaultOutput.write(
|
|
238
|
+
`\nSetup complete. Import your wrapped AI client from "./${codeResult.relativePath.replace(/\.ts$/, "")}" to begin tracking Scope 3 carbon & AI-BOM lineage.\n\n`
|
|
239
|
+
);
|
|
240
|
+
|
|
241
|
+
return {
|
|
242
|
+
apiKeyPrefix: apiKey.slice(0, 14),
|
|
243
|
+
gridRegion: resolvedRegion.region,
|
|
244
|
+
modelPattern: effectiveModelPattern,
|
|
245
|
+
envFilePath: envResult.filePath,
|
|
246
|
+
boilerplateFilePath: codeResult.filePath,
|
|
247
|
+
connectivity,
|
|
248
|
+
};
|
|
249
|
+
} finally {
|
|
250
|
+
rl?.close();
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
export async function runCliFromArgv(argv: readonly string[]): Promise<void> {
|
|
255
|
+
const cleaned = argv[0] === "init" ? argv.slice(1) : argv;
|
|
256
|
+
const parsed = parseCliArgs(cleaned);
|
|
257
|
+
if (parsed.help) {
|
|
258
|
+
printHelp();
|
|
259
|
+
return;
|
|
260
|
+
}
|
|
261
|
+
await runInitWizard(parsed);
|
|
262
|
+
}
|