specshield 3.5.4 → 3.5.5
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/CHANGELOG.md +7 -1
- package/README.md +29 -1
- package/package.json +4 -1
- package/src/cli.js +6 -0
- package/src/commands/telemetry.js +43 -0
- package/src/core/telemetry.js +179 -0
- package/src/core/telemetrySend.js +21 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,12 @@
|
|
|
1
1
|
# SpecShield CLI changelog
|
|
2
2
|
|
|
3
|
-
## Unreleased —
|
|
3
|
+
## Unreleased — opt-in telemetry
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- Opt-in usage telemetry. The CLI asks once at an interactive terminal (default no), never in CI or with `--json`; `SPECSHIELD_TELEMETRY=1` opts in for CI, and `DO_NOT_TRACK=1` or `SPECSHIELD_TELEMETRY=0` always turn it off. Each event has the command, the names of the flags given (never their values), exit code, duration, CLI version, OS and CI provider; never paths, specs, hosts, repository names or results. It's sent by a detached process after the command ends, so exit codes and timing are unchanged. `specshield telemetry status|enable|disable` shows and changes the choice; `SPECSHIELD_TELEMETRY_DEBUG=1` prints events instead of sending them.
|
|
8
|
+
|
|
9
|
+
## 3.5.4 — 2026-11-12 — shadow APIs
|
|
4
10
|
|
|
5
11
|
### Added
|
|
6
12
|
|
package/README.md
CHANGED
|
@@ -57,7 +57,7 @@ What the CLI does:
|
|
|
57
57
|
- [GitHub Actions workflows](#cicd--github-actions)
|
|
58
58
|
|
|
59
59
|
**Reference**
|
|
60
|
-
- [Config File](#config-file) · [All Options](#all-options) · [Exit Codes](#exit-codes)
|
|
60
|
+
- [Config File](#config-file) · [All Options](#all-options) · [Exit Codes](#exit-codes) · [Telemetry (opt-in)](#telemetry-opt-in)
|
|
61
61
|
|
|
62
62
|
**Project**
|
|
63
63
|
- [License](#license) · [Support](#support)
|
|
@@ -1868,6 +1868,34 @@ Per-subcommand flags:
|
|
|
1868
1868
|
|
|
1869
1869
|
---
|
|
1870
1870
|
|
|
1871
|
+
## Telemetry (opt-in)
|
|
1872
|
+
|
|
1873
|
+
The CLI sends nothing unless you opt in. The first time you run a command in an interactive terminal it asks once, defaulting to no. It never asks in CI, without a terminal, or with `--json`.
|
|
1874
|
+
|
|
1875
|
+
```bash
|
|
1876
|
+
specshield telemetry status # whether it's on, and an example of what is sent
|
|
1877
|
+
specshield telemetry enable
|
|
1878
|
+
specshield telemetry disable
|
|
1879
|
+
```
|
|
1880
|
+
|
|
1881
|
+
One event per command run, sent by a background process after the command ends, so it never slows a command down or changes its exit code:
|
|
1882
|
+
|
|
1883
|
+
```json
|
|
1884
|
+
{"id":"3f6c…","version":"3.5.5","command":"gate","flags":["--security","--shadow"],
|
|
1885
|
+
"exitCode":0,"durationMs":1840,"ci":"github","os":"linux","arch":"x64","node":20}
|
|
1886
|
+
```
|
|
1887
|
+
|
|
1888
|
+
**Never sent:** file paths, spec contents, flag values, hosts, repository names or results. `id` is a random id created when you opt in; in CI it's a one-way hash of the CI's numeric project id, so one repository's runs count together without its name.
|
|
1889
|
+
|
|
1890
|
+
| Variable | Effect |
|
|
1891
|
+
|---|---|
|
|
1892
|
+
| `SPECSHIELD_TELEMETRY=1` | Opt in (use this in CI, where there is no prompt) |
|
|
1893
|
+
| `SPECSHIELD_TELEMETRY=0` | Off, whatever was chosen before |
|
|
1894
|
+
| `DO_NOT_TRACK=1` | Off, always |
|
|
1895
|
+
| `SPECSHIELD_TELEMETRY_DEBUG=1` | Print each event to stderr instead of sending it |
|
|
1896
|
+
|
|
1897
|
+
---
|
|
1898
|
+
|
|
1871
1899
|
## License
|
|
1872
1900
|
|
|
1873
1901
|
MIT © SpecShield Software Private Limited
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specshield",
|
|
3
|
-
"version": "3.5.
|
|
3
|
+
"version": "3.5.5",
|
|
4
4
|
"description": "Contract compatibility testing for APIs — catch breaking OpenAPI changes before they reach your consumers, with can-i-deploy deploy gating and GitHub PR checks. (a.k.a. bidirectional contract testing.)",
|
|
5
5
|
"main": "src/cli.js",
|
|
6
6
|
"homepage": "https://specshield.io",
|
|
@@ -85,6 +85,9 @@
|
|
|
85
85
|
],
|
|
86
86
|
"collectCoverageFrom": [
|
|
87
87
|
"src/**/*.js"
|
|
88
|
+
],
|
|
89
|
+
"setupFiles": [
|
|
90
|
+
"<rootDir>/tests/setup/noTelemetry.js"
|
|
88
91
|
]
|
|
89
92
|
},
|
|
90
93
|
"engines": {
|
package/src/cli.js
CHANGED
|
@@ -19,6 +19,9 @@ const waiversCommand = require('./commands/waivers');
|
|
|
19
19
|
const proveCommand = require('./commands/prove');
|
|
20
20
|
const replayCommand = require('./commands/replay');
|
|
21
21
|
const auditCommand = require('./commands/audit');
|
|
22
|
+
const telemetryCommand = require('./commands/telemetry');
|
|
23
|
+
const telemetry = require('./core/telemetry');
|
|
24
|
+
const { loadLocalConfig, saveLocalConfig } = require('./config/localConfig');
|
|
22
25
|
|
|
23
26
|
const program = new Command();
|
|
24
27
|
|
|
@@ -48,6 +51,9 @@ program.addCommand(waiversCommand);
|
|
|
48
51
|
program.addCommand(proveCommand);
|
|
49
52
|
program.addCommand(replayCommand);
|
|
50
53
|
program.addCommand(auditCommand);
|
|
54
|
+
program.addCommand(telemetryCommand);
|
|
55
|
+
|
|
56
|
+
telemetry.install(program, { version, loadConfig: loadLocalConfig, saveConfig: saveLocalConfig });
|
|
51
57
|
|
|
52
58
|
program.parseAsync(process.argv).catch((err) => {
|
|
53
59
|
const logger = require('./utils/logger');
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const { Command } = require('commander');
|
|
4
|
+
const chalk = require('chalk');
|
|
5
|
+
const { loadLocalConfig, saveLocalConfig } = require('../config/localConfig');
|
|
6
|
+
const telemetry = require('../core/telemetry');
|
|
7
|
+
|
|
8
|
+
const EXAMPLE = {
|
|
9
|
+
id: '3f6c…', version: '3.5.5', command: 'gate', flags: ['--security', '--shadow'],
|
|
10
|
+
exitCode: 0, durationMs: 1840, ci: 'github', os: 'linux', arch: 'x64', node: 20,
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
async function setChoice(enabled) {
|
|
14
|
+
await saveLocalConfig(telemetry.withChoice(await loadLocalConfig(), enabled));
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
const cmd = new Command('telemetry');
|
|
18
|
+
|
|
19
|
+
cmd
|
|
20
|
+
.description('Anonymous usage telemetry (opt-in): enable, disable or show what is sent')
|
|
21
|
+
.argument('[action]', 'enable | disable | status', 'status')
|
|
22
|
+
.action(async (action) => {
|
|
23
|
+
if (action === 'enable') {
|
|
24
|
+
await setChoice(true);
|
|
25
|
+
console.log(chalk.green('Telemetry enabled. Thank you — it shows which commands people actually use.'));
|
|
26
|
+
} else if (action === 'disable') {
|
|
27
|
+
await setChoice(false);
|
|
28
|
+
console.log(chalk.green('Telemetry disabled. Nothing will be sent.'));
|
|
29
|
+
} else if (action !== 'status') {
|
|
30
|
+
throw new Error(`unknown action "${action}": use enable, disable or status`);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const s = telemetry.state(await loadLocalConfig());
|
|
34
|
+
const label = s.status === 'on' ? chalk.green('on') : s.status === 'off' ? chalk.yellow('off') : chalk.gray('off (not chosen yet)');
|
|
35
|
+
console.log(`\nTelemetry: ${label}${s.source && s.source !== 'config' ? chalk.gray(` (set by ${s.source})`) : ''}`);
|
|
36
|
+
console.log('\nOne event per command run. Example:');
|
|
37
|
+
console.log(chalk.gray(JSON.stringify(EXAMPLE, null, 2)));
|
|
38
|
+
console.log('\nNever sent: file paths, spec contents, flag values, hosts, repository names or results.');
|
|
39
|
+
console.log('In CI, set SPECSHIELD_TELEMETRY=1 to opt in. DO_NOT_TRACK=1 or SPECSHIELD_TELEMETRY=0 always turn it off.');
|
|
40
|
+
console.log(`SPECSHIELD_TELEMETRY_DEBUG=1 prints each event instead of sending it. ${telemetry.DOCS}`);
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
module.exports = cmd;
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Opt-in usage telemetry. Off unless the user says yes once, or sets
|
|
4
|
+
// SPECSHIELD_TELEMETRY=1 (CI). DO_NOT_TRACK=1 and SPECSHIELD_TELEMETRY=0 always win.
|
|
5
|
+
//
|
|
6
|
+
// One event per command run: the command name, the names of the flags given (never
|
|
7
|
+
// their values), the exit code, the duration, the CLI version, OS, Node major and
|
|
8
|
+
// which CI it ran in. No paths, spec contents, hosts, repo names or results.
|
|
9
|
+
//
|
|
10
|
+
// The event is sent by a detached child process started from the 'exit' handler,
|
|
11
|
+
// so it never delays the command, never changes its exit code and survives
|
|
12
|
+
// process.exit().
|
|
13
|
+
|
|
14
|
+
const crypto = require('crypto');
|
|
15
|
+
const path = require('path');
|
|
16
|
+
const { spawn } = require('child_process');
|
|
17
|
+
|
|
18
|
+
const DEFAULT_URL = 'https://specshield.io/api/telemetry/cli';
|
|
19
|
+
const DOCS = 'https://specshield.io/docs#telemetry';
|
|
20
|
+
|
|
21
|
+
const CI_VARS = [
|
|
22
|
+
['GITHUB_ACTIONS', 'github'], ['GITLAB_CI', 'gitlab'], ['BITBUCKET_BUILD_NUMBER', 'bitbucket'],
|
|
23
|
+
['CIRCLECI', 'circleci'], ['JENKINS_URL', 'jenkins'], ['BUILDKITE', 'buildkite'],
|
|
24
|
+
['TF_BUILD', 'azure'], ['TRAVIS', 'travis'], ['CODEBUILD_BUILD_ID', 'codebuild'], ['CI', 'other'],
|
|
25
|
+
];
|
|
26
|
+
|
|
27
|
+
function ciName(env = process.env) {
|
|
28
|
+
const hit = CI_VARS.find(([v]) => env[v]);
|
|
29
|
+
return hit ? hit[1] : null;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const truthy = (v) => /^(1|true|yes|on)$/i.test(String(v || '').trim());
|
|
33
|
+
const falsy = (v) => /^(0|false|no|off)$/i.test(String(v || '').trim());
|
|
34
|
+
|
|
35
|
+
/** 'on' | 'off' | 'unset', and why. Environment beats the saved choice. */
|
|
36
|
+
function state(config = {}, env = process.env) {
|
|
37
|
+
if (truthy(env.DO_NOT_TRACK)) return { status: 'off', source: 'DO_NOT_TRACK' };
|
|
38
|
+
if (falsy(env.SPECSHIELD_TELEMETRY)) return { status: 'off', source: 'SPECSHIELD_TELEMETRY' };
|
|
39
|
+
if (truthy(env.SPECSHIELD_TELEMETRY)) return { status: 'on', source: 'SPECSHIELD_TELEMETRY' };
|
|
40
|
+
if (config.telemetry === true) return { status: 'on', source: 'config' };
|
|
41
|
+
if (config.telemetry === false) return { status: 'off', source: 'config' };
|
|
42
|
+
return { status: 'unset', source: null };
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* The id that lets runs from one install (or one CI repository) be counted together.
|
|
47
|
+
* Locally: a random id saved on opt-in. In CI: a one-way hash of the CI's numeric
|
|
48
|
+
* project id, so a repository's runs group together without its name being sent.
|
|
49
|
+
*/
|
|
50
|
+
function installId(config = {}, env = process.env) {
|
|
51
|
+
if (config.telemetryId) return config.telemetryId;
|
|
52
|
+
const project = env.GITHUB_REPOSITORY_ID || env.CI_PROJECT_ID || env.BITBUCKET_REPO_UUID;
|
|
53
|
+
if (project) return 'ci-' + crypto.createHash('sha256').update('specshield-telemetry:' + project).digest('hex').slice(0, 32);
|
|
54
|
+
return 'run-' + crypto.randomUUID();
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** "gate", "bdct can-i-deploy", "usage import" — the path below the root program. */
|
|
58
|
+
function commandName(cmd) {
|
|
59
|
+
const names = [];
|
|
60
|
+
for (let c = cmd; c && c.parent; c = c.parent) names.unshift(c.name());
|
|
61
|
+
return names.join(' ');
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Long names of the flags the user typed — never their values. */
|
|
65
|
+
function flagNames(cmd) {
|
|
66
|
+
return cmd.options
|
|
67
|
+
.filter((o) => cmd.getOptionValueSource(o.attributeName()) === 'cli')
|
|
68
|
+
.map((o) => o.long || o.short)
|
|
69
|
+
.filter(Boolean)
|
|
70
|
+
.sort();
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function buildEvent({ cmd, exitCode, durationMs, version, config, env = process.env }) {
|
|
74
|
+
return {
|
|
75
|
+
id: installId(config, env),
|
|
76
|
+
version,
|
|
77
|
+
command: commandName(cmd),
|
|
78
|
+
flags: flagNames(cmd),
|
|
79
|
+
exitCode: Number.isInteger(exitCode) ? exitCode : 0,
|
|
80
|
+
durationMs: Math.max(0, Math.round(durationMs)),
|
|
81
|
+
ci: ciName(env),
|
|
82
|
+
os: process.platform,
|
|
83
|
+
arch: process.arch,
|
|
84
|
+
node: Number(process.versions.node.split('.')[0]),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** Ask once, only when a person is clearly at the keyboard. */
|
|
89
|
+
function shouldPrompt({ config = {}, env = process.env, argv = process.argv, stdin = process.stdin, stderr = process.stderr, command = '' }) {
|
|
90
|
+
if (state(config, env).status !== 'unset') return false;
|
|
91
|
+
if (ciName(env)) return false;
|
|
92
|
+
if (!stdin.isTTY || !stderr.isTTY) return false;
|
|
93
|
+
if (command === 'telemetry' || command.startsWith('telemetry ')) return false;
|
|
94
|
+
if (argv.includes('--json')) return false;
|
|
95
|
+
return true;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const PROMPT = [
|
|
99
|
+
'',
|
|
100
|
+
'Help improve SpecShield? Send anonymous usage data: the command and flag names you',
|
|
101
|
+
'use, exit code, duration, CLI version and OS. Never file paths, specs, values or',
|
|
102
|
+
`results. Change it any time with "specshield telemetry disable". ${DOCS}`,
|
|
103
|
+
'Enable anonymous telemetry? [y/N] ',
|
|
104
|
+
].join('\n');
|
|
105
|
+
|
|
106
|
+
async function ask(stdin = process.stdin, stderr = process.stderr) {
|
|
107
|
+
const readline = require('readline');
|
|
108
|
+
const rl = readline.createInterface({ input: stdin, output: stderr });
|
|
109
|
+
try {
|
|
110
|
+
// Ctrl-D or a closed stdin ends the question with no answer: that's a no. Without the
|
|
111
|
+
// 'close' listener the promise never settles, Node exits 0 and the command never runs.
|
|
112
|
+
const answer = await new Promise((resolve) => {
|
|
113
|
+
rl.on('close', () => resolve(''));
|
|
114
|
+
rl.question(PROMPT, resolve);
|
|
115
|
+
});
|
|
116
|
+
return /^y(es)?$/i.test(String(answer).trim());
|
|
117
|
+
} finally {
|
|
118
|
+
rl.close();
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
function withChoice(config, enabled) {
|
|
123
|
+
const next = { ...config, telemetry: enabled };
|
|
124
|
+
if (enabled && !next.telemetryId) next.telemetryId = crypto.randomUUID();
|
|
125
|
+
if (!enabled) delete next.telemetryId;
|
|
126
|
+
return next;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** Fire and forget from a detached child; prints instead with SPECSHIELD_TELEMETRY_DEBUG=1. */
|
|
130
|
+
function send(event, env = process.env) {
|
|
131
|
+
const body = JSON.stringify(event);
|
|
132
|
+
if (truthy(env.SPECSHIELD_TELEMETRY_DEBUG)) {
|
|
133
|
+
process.stderr.write(`[telemetry] ${body}\n`);
|
|
134
|
+
return;
|
|
135
|
+
}
|
|
136
|
+
try {
|
|
137
|
+
const child = spawn(process.execPath, [path.join(__dirname, 'telemetrySend.js'), env.SPECSHIELD_TELEMETRY_URL || DEFAULT_URL, body], {
|
|
138
|
+
detached: true, stdio: 'ignore', windowsHide: true,
|
|
139
|
+
});
|
|
140
|
+
child.unref();
|
|
141
|
+
} catch {
|
|
142
|
+
// Telemetry must never affect the command.
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/**
|
|
147
|
+
* Wire telemetry into the program: ask once before the first interactive command,
|
|
148
|
+
* and send one event when the process exits.
|
|
149
|
+
*/
|
|
150
|
+
function install(program, { version, loadConfig, saveConfig }) {
|
|
151
|
+
let started = null;
|
|
152
|
+
let config = {};
|
|
153
|
+
|
|
154
|
+
program.hook('preAction', async (_root, actionCommand) => {
|
|
155
|
+
try {
|
|
156
|
+
config = await loadConfig();
|
|
157
|
+
if (shouldPrompt({ config, command: commandName(actionCommand) })) {
|
|
158
|
+
config = withChoice(config, await ask());
|
|
159
|
+
await saveConfig(config);
|
|
160
|
+
process.stderr.write(config.telemetry ? 'Thanks — telemetry enabled.\n\n' : 'Telemetry stays off.\n\n');
|
|
161
|
+
}
|
|
162
|
+
} catch {
|
|
163
|
+
// A broken config file or a closed stdin must not stop the command.
|
|
164
|
+
}
|
|
165
|
+
if (state(config).status !== 'on') return;
|
|
166
|
+
started = { cmd: actionCommand, at: Date.now() };
|
|
167
|
+
});
|
|
168
|
+
|
|
169
|
+
process.on('exit', (code) => {
|
|
170
|
+
if (!started) return;
|
|
171
|
+
const exitCode = typeof code === 'number' ? code : (process.exitCode || 0);
|
|
172
|
+
send(buildEvent({ cmd: started.cmd, exitCode, durationMs: Date.now() - started.at, version, config }));
|
|
173
|
+
});
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
module.exports = {
|
|
177
|
+
install, state, installId, commandName, flagNames, buildEvent, shouldPrompt, withChoice, send, ciName, ask,
|
|
178
|
+
DEFAULT_URL, DOCS,
|
|
179
|
+
};
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Runs detached from the CLI: POST one telemetry event, give up after 3 s, exit quietly.
|
|
4
|
+
// argv: <url> <json body>
|
|
5
|
+
|
|
6
|
+
const [url, body] = process.argv.slice(2);
|
|
7
|
+
|
|
8
|
+
try {
|
|
9
|
+
const target = new URL(url);
|
|
10
|
+
const lib = target.protocol === 'http:' ? require('http') : require('https');
|
|
11
|
+
const req = lib.request(target, {
|
|
12
|
+
method: 'POST',
|
|
13
|
+
headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
|
|
14
|
+
timeout: 3000,
|
|
15
|
+
}, (res) => { res.resume(); res.on('end', () => process.exit(0)); });
|
|
16
|
+
req.on('timeout', () => req.destroy());
|
|
17
|
+
req.on('error', () => process.exit(0));
|
|
18
|
+
req.end(body);
|
|
19
|
+
} catch {
|
|
20
|
+
process.exit(0);
|
|
21
|
+
}
|