@atlaskit/ads-cli 0.11.0 → 0.12.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/CHANGELOG.md +27 -9
- package/README.md +115 -19
- package/dist/cjs/atlas-cli.js +74 -11
- package/dist/cjs/commands/run-tool.js +1 -1
- package/dist/cjs/fetch-atlas-version-policy.js +68 -0
- package/dist/cjs/get-atlas-release-version.js +9 -0
- package/dist/cjs/get-atlas-version-policy.js +135 -0
- package/dist/cjs/is-atlas-release-outdated.js +13 -0
- package/dist/cjs/output/format-token.js +5 -2
- package/dist/cjs/parse-atlas-release-build.js +18 -0
- package/dist/cjs/types.js +1 -1
- package/dist/es2019/atlas-cli.js +51 -2
- package/dist/es2019/commands/run-tool.js +1 -1
- package/dist/es2019/fetch-atlas-version-policy.js +56 -0
- package/dist/es2019/get-atlas-release-version.js +1 -0
- package/dist/es2019/get-atlas-version-policy.js +86 -0
- package/dist/es2019/is-atlas-release-outdated.js +7 -0
- package/dist/es2019/output/format-token.js +5 -2
- package/dist/es2019/parse-atlas-release-build.js +12 -0
- package/dist/es2019/types.js +1 -1
- package/dist/esm/atlas-cli.js +74 -11
- package/dist/esm/commands/run-tool.js +1 -1
- package/dist/esm/fetch-atlas-version-policy.js +62 -0
- package/dist/esm/get-atlas-release-version.js +3 -0
- package/dist/esm/get-atlas-version-policy.js +128 -0
- package/dist/esm/is-atlas-release-outdated.js +7 -0
- package/dist/esm/output/format-token.js +5 -2
- package/dist/esm/parse-atlas-release-build.js +12 -0
- package/dist/esm/types.js +1 -1
- package/dist/types/atlas-cli.d.ts +2 -2
- package/dist/types/commands/run-tool.d.ts +1 -1
- package/dist/types/envelope/types.d.ts +4 -4
- package/dist/types/fetch-atlas-version-policy.d.ts +4 -0
- package/dist/types/get-atlas-release-version.d.ts +1 -0
- package/dist/types/get-atlas-version-policy.d.ts +9 -0
- package/dist/types/is-atlas-release-outdated.d.ts +1 -0
- package/dist/types/parse-atlas-release-build.d.ts +5 -0
- package/dist/types/types.d.ts +1 -1
- package/package.json +13 -8
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,29 @@
|
|
|
1
1
|
# @atlaskit/ads-cli
|
|
2
2
|
|
|
3
|
+
## 0.12.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [`ba02fecea90d9`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/ba02fecea90d9) -
|
|
8
|
+
Add an Atlas-only minimum supported release gate controlled by an ADS Statlas policy, with checks
|
|
9
|
+
cached for 24 hours using file-system-cache and UPGRADE_REQUIRED errors. Policy lookup failures
|
|
10
|
+
leave commands usable, including unexpected initialization errors.
|
|
11
|
+
|
|
12
|
+
Warn at one to six stable releases behind and require an upgrade at seven or more behind. One
|
|
13
|
+
pipeline runs manually or daily without input variables, releasing and promoting only when the ADS
|
|
14
|
+
CLI package version changes. It automatically calculates the policy from stable release history,
|
|
15
|
+
even when release is skipped. With fewer than eight stable releases, the policy only warns.
|
|
16
|
+
|
|
17
|
+
## 0.11.1
|
|
18
|
+
|
|
19
|
+
### Patch Changes
|
|
20
|
+
|
|
21
|
+
- [`9b565c62c7a8d`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/9b565c62c7a8d) -
|
|
22
|
+
Return the canonical per-token description from the tokens package in detailed token searches and
|
|
23
|
+
CLI JSON output. Show that description as the CLI's token guidance instead of generic category
|
|
24
|
+
guidance, while retaining CSS property hints and compact search results.
|
|
25
|
+
- Updated dependencies
|
|
26
|
+
|
|
3
27
|
## 0.11.0
|
|
4
28
|
|
|
5
29
|
### Minor Changes
|
|
@@ -67,15 +91,9 @@
|
|
|
67
91
|
{
|
|
68
92
|
"name": "Avatar",
|
|
69
93
|
"package": "@atlaskit/avatar",
|
|
70
|
-
"props": [
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
"examples": [
|
|
74
|
-
/* ... */
|
|
75
|
-
],
|
|
76
|
-
"designSource": {
|
|
77
|
-
/* ... */
|
|
78
|
-
},
|
|
94
|
+
"props": [/* ... */],
|
|
95
|
+
"examples": [/* ... */],
|
|
96
|
+
"designSource": {/* ... */},
|
|
79
97
|
}
|
|
80
98
|
```
|
|
81
99
|
|
package/README.md
CHANGED
|
@@ -135,7 +135,9 @@ exists; JSON output reports the skills, `AGENTS.md`, Atlas, and next-step status
|
|
|
135
135
|
same compact fields shown by the human rows rather than embedding every component prop and
|
|
136
136
|
example. Each search record includes a machine-readable `followUp`; run that exact detail command
|
|
137
137
|
for the full component, token, or icon data. Exact detail commands retain the information shown by
|
|
138
|
-
their human view, including token `
|
|
138
|
+
their human view, including the canonical token `description`, shared `usageGuidelines`, token
|
|
139
|
+
`usage`, and an icon `import`. Individual token views use the tokens package's per-token
|
|
140
|
+
description as their guidance, falling back to category guidance only if no description exists.
|
|
139
141
|
`manifest --json` is the intentional exception: it remains the full CLI contract.
|
|
140
142
|
- **Lookups never silently guess.** `component`/`token`/`icon <name>` — and a fuzzy
|
|
141
143
|
`lint-rules <term>` — render the entry whose name matches exactly (case-insensitively). If there
|
|
@@ -282,8 +284,8 @@ The `--json` envelope is shared unchanged by the npm and Atlas distributions.
|
|
|
282
284
|
|
|
283
285
|
## Atlas CLI distribution
|
|
284
286
|
|
|
285
|
-
The same command surface is available as `atlas ads`. Its entrypoint
|
|
286
|
-
|
|
287
|
+
The same command surface is available as `atlas ads`. Its entrypoint applies the Atlas release
|
|
288
|
+
policy below, then delegates to `run()` for shared command parsing, output, and exit codes.
|
|
287
289
|
|
|
288
290
|
Build the self-contained JavaScript bundle from the `platform/` directory:
|
|
289
291
|
|
|
@@ -296,25 +298,119 @@ The `.atlas-plugin` descriptor declares the `ads` plugin and the `atlas-cli-plug
|
|
|
296
298
|
namespace. Every upload fetches `manifest.toml` from Statlas before adding a release, so the remote
|
|
297
299
|
manifest history remains canonical.
|
|
298
300
|
|
|
299
|
-
|
|
301
|
+
The Atlas build and release scripts are TypeScript, executed with AFM's `run-ts` runner. They use
|
|
302
|
+
Node APIs for files and SHA-256 checksums and a TOML parser for manifest changes; packaging still
|
|
303
|
+
invokes `afm`, `tar` and the Atlas CLI.
|
|
304
|
+
|
|
305
|
+
### Release and promotion
|
|
306
|
+
|
|
307
|
+
The
|
|
308
|
+
[`ads-cli-release` pipeline](../../../../pipeline-definitions/pipelines/custom/platform/design-system/ads-cli-release.ts)
|
|
309
|
+
runs manually from `master` or on a schedule, with no input variables. See its configuration for the
|
|
310
|
+
schedule and CI setup. To run it manually, select `master` and `ads-cli-release` in Bitbucket's
|
|
311
|
+
**Run pipeline** dialog.
|
|
312
|
+
|
|
313
|
+
1. Compare `@atlaskit/ads-cli`'s `package.json` version with `package_version` on the latest stable
|
|
314
|
+
manifest entry. If unchanged, skip building, uploading and promoting; still check the policy.
|
|
315
|
+
Existing entries lack this field, so the first run releases once to establish the baseline.
|
|
316
|
+
2. When changed, derive the Atlas release version from the pipeline build number and commit SHA.
|
|
317
|
+
Build and test the plugin, package all five platforms, smoke-test the Linux AMD64 executable, and
|
|
318
|
+
upload to `alpha`. The manifest is published after the artifacts.
|
|
319
|
+
3. Verify all archives and checksums exist, promote that exact release to `stable`, and verify it.
|
|
320
|
+
4. Read stable release history and publish the warning and blocking thresholds. **Warn from one
|
|
321
|
+
stable version behind; require an update at seven or more versions behind.** Sort distinct stable
|
|
322
|
+
releases by numeric build number: recommend the newest release, and set the minimum to the
|
|
323
|
+
seventh newest (six behind). Builds older than that minimum are seven or more behind and must
|
|
324
|
+
update. Alpha-only releases do not count. Seven releases need not mean seven days.
|
|
325
|
+
|
|
326
|
+
With fewer than eight stable releases, publish only a warning threshold. A release or promotion
|
|
327
|
+
failure stops the job before the minimum changes. An invalid policy or unavailable minimum-release
|
|
328
|
+
artifact also stops policy publication, leaving the previous minimum intact. Retrying a partially
|
|
329
|
+
completed build resumes from its existing alpha or stable release without rebuilding it. Older
|
|
330
|
+
pipeline runs are rejected if promoting them would replace a newer stable build.
|
|
331
|
+
|
|
332
|
+
This is the single ADS CLI release pipeline: it replaces the separate upload, promotion and policy
|
|
333
|
+
pipelines. Manual and scheduled runs share a concurrency group to prevent concurrent manifest or
|
|
334
|
+
policy writers. Each new release records its source package version in `package_version`.
|
|
335
|
+
|
|
336
|
+
When rolling this out, remove any older external schedule that releases/promotes this plugin so
|
|
337
|
+
there is only one scheduled release workflow. The ADS AI tooling code-generation pipeline remains
|
|
338
|
+
separate.
|
|
300
339
|
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
340
|
+
The Statlas namespace authorization and Atlas plugin registry entry are one-time external
|
|
341
|
+
prerequisites. Until the registry entry is available, use `atlas atlasdev exec` to exercise a
|
|
342
|
+
packaged binary in the Atlas runtime. The AFM package scripts own the Node.js executable build; the
|
|
343
|
+
generic `atlas atlasdev plugin build` command doesn't drive this package.
|
|
344
|
+
|
|
345
|
+
### Minimum supported Atlas release
|
|
346
|
+
|
|
347
|
+
Atlas builds embed the release's `VERSION` (`<pipeline-build-number>-<8-character-commit>`).
|
|
348
|
+
`atlas ads --version` reports that release identifier. The Atlas entrypoint checks an ADS-owned
|
|
349
|
+
policy at `https://statlas.prod.atl-paas.net/atlas-cli-plugin-ads/version-policy.json` before
|
|
350
|
+
executing a command. For example:
|
|
351
|
+
|
|
352
|
+
```json
|
|
353
|
+
{
|
|
354
|
+
"enabled": true,
|
|
355
|
+
"minimumVersion": "26396603-5ec9e9f7",
|
|
356
|
+
"recommendedVersion": "26400000-abcdef12"
|
|
357
|
+
}
|
|
304
358
|
```
|
|
305
359
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
360
|
+
When enabled, a build below `recommendedVersion` prints an actionable warning to stderr and still
|
|
361
|
+
runs. This includes JSON callers: stdout and the successful JSON envelope are unchanged. Builds at
|
|
362
|
+
the newest stable release or newer (including alpha) do not warn.
|
|
363
|
+
|
|
364
|
+
A build below `minimumVersion` exits `1` before returning ADS content and tells the caller to run
|
|
365
|
+
`atlas plugin upgrade --name ads --channel stable`. JSON callers receive an `ads-cli/error` envelope
|
|
366
|
+
with `error.code: "UPGRADE_REQUIRED"`. The minimum itself is allowed (with a warning if behind the
|
|
367
|
+
recommendation). Help and version output remain available. The npm distribution and unversioned
|
|
368
|
+
local builds do not perform this Atlas-only check.
|
|
369
|
+
|
|
370
|
+
The policy, including disabled and failed checks, is cached for 24 hours using `file-system-cache`
|
|
371
|
+
under `$ATLAS_CACHE/ads/` (default `~/.cache/atlassian/atlas/ads/`). The library manages cache
|
|
372
|
+
filenames and expiry. This is a rolling 24-hour interval from each check, including disabled
|
|
373
|
+
policies and failed lookups. A failed lookup allows usage and is retried after that interval. This
|
|
374
|
+
avoids a remote request for each lookup. Cache writes are best-effort; unreadable or incomplete
|
|
375
|
+
cache entries trigger a fresh check. A missing policy, invalid response, network failure or
|
|
376
|
+
unexpected policy initialization error allows execution. The network request has a 1.5-second
|
|
377
|
+
deadline. A valid unexpired cached minimum can still block an older plugin while offline, for up to
|
|
378
|
+
24 hours after the check. An expired policy is not enforced when refreshing it fails. Requests
|
|
379
|
+
include `Pragma: no-cache`, which
|
|
380
|
+
[Statlas explicitly uses to bypass its ten-minute proxy cache](https://bitbucket.org/atlassian/statlas/src/main/nginx/nginx.conf).
|
|
381
|
+
This was also verified against the ADS manifest (`X-Statlas-Cache: BYPASS`). The 24-hour local cache
|
|
382
|
+
still applies, so policy changes can take up to 24 hours to reach a machine. This is not an
|
|
383
|
+
immediate rollout guarantee: allow for service propagation and verify the result with a released
|
|
384
|
+
binary after its cache refreshes. Browsers and other clients that omit the bypass header can see the
|
|
385
|
+
proxy-cached policy for longer.
|
|
386
|
+
|
|
387
|
+
**Rollout:** existing binaries cannot acquire this check retroactively. Users must first upgrade to
|
|
388
|
+
a release containing it. The pipeline verifies the recommended and minimum releases are available on
|
|
389
|
+
stable before publishing the policy. This check does not automatically upgrade machines; the
|
|
390
|
+
scheduled pipeline advances the thresholds as described above.
|
|
391
|
+
|
|
392
|
+
### Policy tooling
|
|
393
|
+
|
|
394
|
+
The combined `ads-cli-release` pipeline calculates the policy automatically from stable release
|
|
395
|
+
history, without input variables or manual overrides. It validates all five platforms' archives and
|
|
396
|
+
checksums before publishing. A confirmed missing policy can be created; authentication errors,
|
|
397
|
+
service failures and malformed existing policies stop publication. An unchanged policy is not
|
|
398
|
+
republished.
|
|
399
|
+
|
|
400
|
+
The namespace permits the AFM Bitbucket build identity to publish. Live uploads, promotions and
|
|
401
|
+
policy writes require Statlas write access; ordinary developer uploads are not authorized.
|
|
402
|
+
Publishing requires `BITBUCKET_BRANCH=master`. For a read-only local preview from `platform/`:
|
|
309
403
|
|
|
310
|
-
|
|
311
|
-
|
|
404
|
+
```sh
|
|
405
|
+
afm workspace @atlaskit/ads-cli release:atlas:policy --dry-run
|
|
406
|
+
```
|
|
312
407
|
|
|
313
|
-
|
|
314
|
-
`
|
|
315
|
-
|
|
408
|
+
The preview validates the automatic thresholds and saves
|
|
409
|
+
`build/atlas/version-policy/version-policy.json` without writing to Statlas. The pipeline also reads
|
|
410
|
+
back the published policy into `published-policy.json` for verification. Both files are pipeline
|
|
411
|
+
artifacts.
|
|
316
412
|
|
|
317
|
-
The
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
413
|
+
The publisher omits `--lifecycle` because
|
|
414
|
+
[Statlas files are permanent by default](https://bitbucket.org/atlassian/statlas/src/main/documentation/content/platform/statlas/files/upload.md).
|
|
415
|
+
Successful combined pipeline runs publish the automatic policy. Merging alone does not change the
|
|
416
|
+
live policy; standalone upload/promotion scripts do not publish it.
|
package/dist/cjs/atlas-cli.js
CHANGED
|
@@ -10,16 +10,31 @@ var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"))
|
|
|
10
10
|
var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
|
|
11
11
|
var _cli = require("./cli");
|
|
12
12
|
var _cliMetadata = require("./commands/cli-metadata");
|
|
13
|
+
var _getCommand = require("./commands/get-command");
|
|
14
|
+
var _createErrorEnvelope = require("./envelope/create-error-envelope");
|
|
15
|
+
var _getAtlasReleaseVersion = require("./get-atlas-release-version");
|
|
16
|
+
var _getAtlasVersionPolicy = require("./get-atlas-version-policy");
|
|
17
|
+
var _isAtlasReleaseOutdated = require("./is-atlas-release-outdated");
|
|
18
|
+
var _writeHumanError = require("./output/write-human-error");
|
|
19
|
+
var _writeJsonEnvelope = require("./output/write-json-envelope");
|
|
20
|
+
var _writer = require("./output/writer");
|
|
21
|
+
var _parseArgs2 = require("./parse-args");
|
|
13
22
|
/**
|
|
14
23
|
* Process entrypoint for the `atlas ads` distribution.
|
|
15
24
|
*
|
|
16
25
|
* Atlas forwards everything after `atlas ads` as process arguments. The shared CLI owns parsing,
|
|
17
|
-
* output, and its
|
|
18
|
-
* process.
|
|
26
|
+
* output, and its exit-code contract. This entrypoint enforces the Atlas release policy before
|
|
27
|
+
* command dispatch and maps the result onto the plugin process.
|
|
19
28
|
*/
|
|
20
29
|
var main = exports.main = /*#__PURE__*/function () {
|
|
21
30
|
var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
|
|
22
31
|
var argv,
|
|
32
|
+
_parseArgs,
|
|
33
|
+
command,
|
|
34
|
+
flags,
|
|
35
|
+
version,
|
|
36
|
+
policy,
|
|
37
|
+
message,
|
|
23
38
|
exitCode,
|
|
24
39
|
_error$stack,
|
|
25
40
|
_args = arguments,
|
|
@@ -29,32 +44,80 @@ var main = exports.main = /*#__PURE__*/function () {
|
|
|
29
44
|
case 0:
|
|
30
45
|
argv = _args.length > 0 && _args[0] !== undefined ? _args[0] : process.argv.slice(2);
|
|
31
46
|
_context.prev = 1;
|
|
32
|
-
|
|
47
|
+
_parseArgs = (0, _parseArgs2.parseArgs)(argv), command = _parseArgs.command, flags = _parseArgs.flags;
|
|
48
|
+
version = (0, _getAtlasReleaseVersion.getAtlasReleaseVersion)();
|
|
49
|
+
if (!(flags.version === true && version)) {
|
|
50
|
+
_context.next = 2;
|
|
51
|
+
break;
|
|
52
|
+
}
|
|
53
|
+
_writer.defaultWriter.out(version);
|
|
54
|
+
process.exitCode = 0;
|
|
55
|
+
return _context.abrupt("return");
|
|
56
|
+
case 2:
|
|
57
|
+
if (!(version && command && (0, _getCommand.getCommand)(command) && flags.help !== true && flags.version !== true)) {
|
|
58
|
+
_context.next = 5;
|
|
59
|
+
break;
|
|
60
|
+
}
|
|
61
|
+
_context.next = 3;
|
|
62
|
+
return (0, _getAtlasVersionPolicy.getAtlasVersionPolicy)().catch(function () {
|
|
63
|
+
return undefined;
|
|
64
|
+
});
|
|
65
|
+
case 3:
|
|
66
|
+
policy = _context.sent;
|
|
67
|
+
if (!(policy !== null && policy !== void 0 && policy.enabled && (0, _isAtlasReleaseOutdated.isAtlasReleaseOutdated)(version, policy.minimumVersion))) {
|
|
68
|
+
_context.next = 4;
|
|
69
|
+
break;
|
|
70
|
+
}
|
|
71
|
+
message = "ADS Atlas plugin ".concat(version, " is older than the minimum supported release ").concat(policy.minimumVersion, ". ") + 'Run `atlas plugin upgrade --name ads --channel stable`, then retry your command.';
|
|
72
|
+
if (flags.json === true) {
|
|
73
|
+
(0, _writeJsonEnvelope.writeJsonEnvelope)({
|
|
74
|
+
envelope: (0, _createErrorEnvelope.createErrorEnvelope)({
|
|
75
|
+
command: command,
|
|
76
|
+
code: 'UPGRADE_REQUIRED',
|
|
77
|
+
message: message
|
|
78
|
+
}),
|
|
79
|
+
writer: _writer.defaultWriter
|
|
80
|
+
});
|
|
81
|
+
} else {
|
|
82
|
+
(0, _writeHumanError.writeHumanError)({
|
|
83
|
+
message: message,
|
|
84
|
+
writer: _writer.defaultWriter
|
|
85
|
+
});
|
|
86
|
+
}
|
|
87
|
+
process.exitCode = 1;
|
|
88
|
+
return _context.abrupt("return");
|
|
89
|
+
case 4:
|
|
90
|
+
if (policy !== null && policy !== void 0 && policy.enabled && (0, _isAtlasReleaseOutdated.isAtlasReleaseOutdated)(version, policy.recommendedVersion)) {
|
|
91
|
+
// Diagnostics belong on stderr, leaving successful JSON/data output unchanged.
|
|
92
|
+
_writer.defaultWriter.err("Warning: ADS Atlas plugin ".concat(version, " is behind the latest stable release ").concat(policy.recommendedVersion, ". ") + 'Run `atlas plugin upgrade --name ads --channel stable` to update.');
|
|
93
|
+
}
|
|
94
|
+
case 5:
|
|
95
|
+
_context.next = 6;
|
|
33
96
|
return (0, _cli.run)(argv, undefined, {
|
|
34
97
|
invocation: _cliMetadata.CLI_ATLAS_INVOCATION
|
|
35
98
|
});
|
|
36
|
-
case
|
|
99
|
+
case 6:
|
|
37
100
|
exitCode = _context.sent;
|
|
38
101
|
process.exitCode = exitCode;
|
|
39
|
-
_context.next =
|
|
102
|
+
_context.next = 9;
|
|
40
103
|
break;
|
|
41
|
-
case
|
|
42
|
-
_context.prev =
|
|
104
|
+
case 7:
|
|
105
|
+
_context.prev = 7;
|
|
43
106
|
_t = _context["catch"](1);
|
|
44
107
|
if (!(typeof _t === 'number')) {
|
|
45
|
-
_context.next =
|
|
108
|
+
_context.next = 8;
|
|
46
109
|
break;
|
|
47
110
|
}
|
|
48
111
|
process.exitCode = _t;
|
|
49
112
|
return _context.abrupt("return");
|
|
50
|
-
case
|
|
113
|
+
case 8:
|
|
51
114
|
process.stderr.write("".concat(_t instanceof Error ? (_error$stack = _t.stack) !== null && _error$stack !== void 0 ? _error$stack : _t.message : String(_t), "\n"));
|
|
52
115
|
process.exitCode = 1;
|
|
53
|
-
case
|
|
116
|
+
case 9:
|
|
54
117
|
case "end":
|
|
55
118
|
return _context.stop();
|
|
56
119
|
}
|
|
57
|
-
}, _callee, null, [[1,
|
|
120
|
+
}, _callee, null, [[1, 7]]);
|
|
58
121
|
}));
|
|
59
122
|
return function main() {
|
|
60
123
|
return _ref.apply(this, arguments);
|
|
@@ -55,7 +55,7 @@ var getTextBlocks = function getTextBlocks(result) {
|
|
|
55
55
|
* Invoke an ADS MCP tool handler and unwrap its result into plain data.
|
|
56
56
|
*
|
|
57
57
|
* @param handler - The tool function (e.g. `searchComponentsTool`).
|
|
58
|
-
* @param args - The arguments object matching the tool's
|
|
58
|
+
* @param args - The arguments object matching the tool's input shape, or `undefined`
|
|
59
59
|
* for zero-argument tools such as `getAllComponentsTool`.
|
|
60
60
|
*/
|
|
61
61
|
var runTool = exports.runTool = /*#__PURE__*/function () {
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, "__esModule", {
|
|
4
|
+
value: true
|
|
5
|
+
});
|
|
6
|
+
exports.fetchAtlasVersionPolicy = void 0;
|
|
7
|
+
var _https = require("https");
|
|
8
|
+
var POLICY_URL = 'https://statlas.prod.atl-paas.net/atlas-cli-plugin-ads/version-policy.json';
|
|
9
|
+
var REQUEST_TIMEOUT_MS = 1500;
|
|
10
|
+
var MAX_POLICY_BYTES = 16 * 1024;
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* A bounded, unauthenticated read of the ADS-owned policy; failures leave the CLI usable.
|
|
14
|
+
*/
|
|
15
|
+
var fetchAtlasVersionPolicy = exports.fetchAtlasVersionPolicy = function fetchAtlasVersionPolicy() {
|
|
16
|
+
return new Promise(function (resolve) {
|
|
17
|
+
var request;
|
|
18
|
+
var deadline = setTimeout(function () {
|
|
19
|
+
var _request;
|
|
20
|
+
(_request = request) === null || _request === void 0 || _request.destroy();
|
|
21
|
+
resolve(undefined);
|
|
22
|
+
}, REQUEST_TIMEOUT_MS);
|
|
23
|
+
var finish = function finish(value) {
|
|
24
|
+
clearTimeout(deadline);
|
|
25
|
+
resolve(value);
|
|
26
|
+
};
|
|
27
|
+
try {
|
|
28
|
+
// Statlas explicitly bypasses its ten-minute proxy cache for Pragma requests.
|
|
29
|
+
request = (0, _https.get)(POLICY_URL, {
|
|
30
|
+
headers: {
|
|
31
|
+
Accept: 'application/json',
|
|
32
|
+
Pragma: 'no-cache'
|
|
33
|
+
}
|
|
34
|
+
}, function (response) {
|
|
35
|
+
if (response.statusCode !== 200) {
|
|
36
|
+
response.destroy();
|
|
37
|
+
finish();
|
|
38
|
+
return;
|
|
39
|
+
}
|
|
40
|
+
var body = '';
|
|
41
|
+
response.setEncoding('utf8');
|
|
42
|
+
response.on('data', function (chunk) {
|
|
43
|
+
body += chunk;
|
|
44
|
+
if (Buffer.byteLength(body) > MAX_POLICY_BYTES) {
|
|
45
|
+
var _request2;
|
|
46
|
+
(_request2 = request) === null || _request2 === void 0 || _request2.destroy();
|
|
47
|
+
finish();
|
|
48
|
+
}
|
|
49
|
+
});
|
|
50
|
+
response.on('error', function () {
|
|
51
|
+
return finish();
|
|
52
|
+
});
|
|
53
|
+
response.on('end', function () {
|
|
54
|
+
try {
|
|
55
|
+
finish(JSON.parse(body));
|
|
56
|
+
} catch (_unused) {
|
|
57
|
+
finish();
|
|
58
|
+
}
|
|
59
|
+
});
|
|
60
|
+
});
|
|
61
|
+
request.on('error', function () {
|
|
62
|
+
return finish();
|
|
63
|
+
});
|
|
64
|
+
} catch (_unused2) {
|
|
65
|
+
finish();
|
|
66
|
+
}
|
|
67
|
+
});
|
|
68
|
+
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, "__esModule", {
|
|
4
|
+
value: true
|
|
5
|
+
});
|
|
6
|
+
exports.getAtlasReleaseVersion = void 0;
|
|
7
|
+
var getAtlasReleaseVersion = exports.getAtlasReleaseVersion = function getAtlasReleaseVersion() {
|
|
8
|
+
return typeof __ADS_ATLAS_RELEASE_VERSION__ === 'string' && __ADS_ATLAS_RELEASE_VERSION__ !== '' ? __ADS_ATLAS_RELEASE_VERSION__ : undefined;
|
|
9
|
+
};
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
|
|
4
|
+
Object.defineProperty(exports, "__esModule", {
|
|
5
|
+
value: true
|
|
6
|
+
});
|
|
7
|
+
exports.getAtlasVersionPolicy = void 0;
|
|
8
|
+
var _regenerator = _interopRequireDefault(require("@babel/runtime/regenerator"));
|
|
9
|
+
var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
|
|
10
|
+
var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
|
|
11
|
+
var _typeof2 = _interopRequireDefault(require("@babel/runtime/helpers/typeof"));
|
|
12
|
+
var _promises = require("fs/promises");
|
|
13
|
+
var _os = require("os");
|
|
14
|
+
var _path = _interopRequireDefault(require("path"));
|
|
15
|
+
var _fileSystemCache = require("file-system-cache");
|
|
16
|
+
var _fetchAtlasVersionPolicy = require("./fetch-atlas-version-policy");
|
|
17
|
+
var _parseAtlasReleaseBuild = require("./parse-atlas-release-build");
|
|
18
|
+
function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
|
|
19
|
+
function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
|
|
20
|
+
var CACHE_TTL_SECONDS = 24 * 60 * 60;
|
|
21
|
+
var CACHE_KEY = 'version-policy';
|
|
22
|
+
var parsePolicy = function parsePolicy(value) {
|
|
23
|
+
if ((0, _typeof2.default)(value) !== 'object' || value === null || !('enabled' in value)) {
|
|
24
|
+
return undefined;
|
|
25
|
+
}
|
|
26
|
+
if (value.enabled === false) {
|
|
27
|
+
return {
|
|
28
|
+
enabled: false
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
var minimumVersion = 'minimumVersion' in value ? value.minimumVersion : undefined;
|
|
32
|
+
var recommendedVersion = 'recommendedVersion' in value ? value.recommendedVersion : undefined;
|
|
33
|
+
var minimumBuild = (0, _parseAtlasReleaseBuild.parseAtlasReleaseBuild)(minimumVersion);
|
|
34
|
+
var recommendedBuild = (0, _parseAtlasReleaseBuild.parseAtlasReleaseBuild)(recommendedVersion);
|
|
35
|
+
if (value.enabled === true && (minimumVersion !== undefined || recommendedVersion !== undefined) && (minimumVersion === undefined || minimumBuild !== undefined) && (recommendedVersion === undefined || recommendedBuild !== undefined) && (minimumBuild === undefined || recommendedBuild === undefined || minimumBuild <= recommendedBuild)) {
|
|
36
|
+
return _objectSpread(_objectSpread({
|
|
37
|
+
enabled: true
|
|
38
|
+
}, minimumVersion !== undefined ? {
|
|
39
|
+
minimumVersion: minimumVersion
|
|
40
|
+
} : {}), recommendedVersion !== undefined ? {
|
|
41
|
+
recommendedVersion: recommendedVersion
|
|
42
|
+
} : {});
|
|
43
|
+
}
|
|
44
|
+
return undefined;
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Share a 24-hour policy cache across Atlas invocations, including disabled and failed checks.
|
|
49
|
+
*/
|
|
50
|
+
var getAtlasVersionPolicy = exports.getAtlasVersionPolicy = /*#__PURE__*/function () {
|
|
51
|
+
var _ref = (0, _asyncToGenerator2.default)( /*#__PURE__*/_regenerator.default.mark(function _callee() {
|
|
52
|
+
var cacheDir, checkedAt, cache, cached, _policy, policy, _t, _t2, _t3, _t4;
|
|
53
|
+
return _regenerator.default.wrap(function (_context) {
|
|
54
|
+
while (1) switch (_context.prev = _context.next) {
|
|
55
|
+
case 0:
|
|
56
|
+
cacheDir = _path.default.join(process.env.ATLAS_CACHE || _path.default.join((0, _os.homedir)(), '.cache/atlassian/atlas'), 'ads'); // eslint-disable-next-line @repo/internal/react/disallow-unstable-values -- This is a Node CLI cache clock, not React render data.
|
|
57
|
+
checkedAt = Date.now();
|
|
58
|
+
_context.prev = 1;
|
|
59
|
+
cache = new _fileSystemCache.Cache({
|
|
60
|
+
basePath: cacheDir,
|
|
61
|
+
ttl: CACHE_TTL_SECONDS
|
|
62
|
+
});
|
|
63
|
+
_context.next = 2;
|
|
64
|
+
return cache.get(CACHE_KEY);
|
|
65
|
+
case 2:
|
|
66
|
+
cached = _context.sent;
|
|
67
|
+
if (!(typeof (cached === null || cached === void 0 ? void 0 : cached.checkedAt) === 'number' && checkedAt >= cached.checkedAt)) {
|
|
68
|
+
_context.next = 4;
|
|
69
|
+
break;
|
|
70
|
+
}
|
|
71
|
+
if (!(cached.policy === null)) {
|
|
72
|
+
_context.next = 3;
|
|
73
|
+
break;
|
|
74
|
+
}
|
|
75
|
+
return _context.abrupt("return", undefined);
|
|
76
|
+
case 3:
|
|
77
|
+
_policy = parsePolicy(cached.policy);
|
|
78
|
+
if (!_policy) {
|
|
79
|
+
_context.next = 4;
|
|
80
|
+
break;
|
|
81
|
+
}
|
|
82
|
+
return _context.abrupt("return", _policy);
|
|
83
|
+
case 4:
|
|
84
|
+
_context.next = 6;
|
|
85
|
+
break;
|
|
86
|
+
case 5:
|
|
87
|
+
_context.prev = 5;
|
|
88
|
+
_t = _context["catch"](1);
|
|
89
|
+
case 6:
|
|
90
|
+
_context.prev = 6;
|
|
91
|
+
_t2 = parsePolicy;
|
|
92
|
+
_context.next = 7;
|
|
93
|
+
return (0, _fetchAtlasVersionPolicy.fetchAtlasVersionPolicy)();
|
|
94
|
+
case 7:
|
|
95
|
+
policy = _t2(_context.sent);
|
|
96
|
+
_context.next = 9;
|
|
97
|
+
break;
|
|
98
|
+
case 8:
|
|
99
|
+
_context.prev = 8;
|
|
100
|
+
_t3 = _context["catch"](6);
|
|
101
|
+
case 9:
|
|
102
|
+
_context.prev = 9;
|
|
103
|
+
if (!cache) {
|
|
104
|
+
_context.next = 11;
|
|
105
|
+
break;
|
|
106
|
+
}
|
|
107
|
+
_context.next = 10;
|
|
108
|
+
return (0, _promises.mkdir)(cacheDir, {
|
|
109
|
+
recursive: true,
|
|
110
|
+
mode: 448
|
|
111
|
+
});
|
|
112
|
+
case 10:
|
|
113
|
+
_context.next = 11;
|
|
114
|
+
return cache.set(CACHE_KEY, {
|
|
115
|
+
checkedAt: checkedAt,
|
|
116
|
+
policy: policy !== null && policy !== void 0 ? policy : null
|
|
117
|
+
});
|
|
118
|
+
case 11:
|
|
119
|
+
_context.next = 13;
|
|
120
|
+
break;
|
|
121
|
+
case 12:
|
|
122
|
+
_context.prev = 12;
|
|
123
|
+
_t4 = _context["catch"](9);
|
|
124
|
+
case 13:
|
|
125
|
+
return _context.abrupt("return", policy);
|
|
126
|
+
case 14:
|
|
127
|
+
case "end":
|
|
128
|
+
return _context.stop();
|
|
129
|
+
}
|
|
130
|
+
}, _callee, null, [[1, 5], [6, 8], [9, 12]]);
|
|
131
|
+
}));
|
|
132
|
+
return function getAtlasVersionPolicy() {
|
|
133
|
+
return _ref.apply(this, arguments);
|
|
134
|
+
};
|
|
135
|
+
}();
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, "__esModule", {
|
|
4
|
+
value: true
|
|
5
|
+
});
|
|
6
|
+
exports.isAtlasReleaseOutdated = void 0;
|
|
7
|
+
var _parseAtlasReleaseBuild = require("./parse-atlas-release-build");
|
|
8
|
+
var isAtlasReleaseOutdated = exports.isAtlasReleaseOutdated = function isAtlasReleaseOutdated(installed, minimum) {
|
|
9
|
+
var installedBuild = (0, _parseAtlasReleaseBuild.parseAtlasReleaseBuild)(installed);
|
|
10
|
+
var minimumBuild = (0, _parseAtlasReleaseBuild.parseAtlasReleaseBuild)(minimum);
|
|
11
|
+
// Compare valid build numbers for either threshold; unknown versions remain usable.
|
|
12
|
+
return installedBuild !== undefined && minimumBuild !== undefined && installedBuild < minimumBuild;
|
|
13
|
+
};
|
|
@@ -38,8 +38,11 @@ var formatToken = exports.formatToken = function formatToken(data) {
|
|
|
38
38
|
if (token.exampleValue) {
|
|
39
39
|
sections.push('', "Example value: ".concat(token.exampleValue));
|
|
40
40
|
}
|
|
41
|
-
|
|
42
|
-
|
|
41
|
+
|
|
42
|
+
// Prefer the canonical per-token description over the broader category guidance.
|
|
43
|
+
var guidance = token.description || ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage ? oneLine(token.usageGuidelines.usage) : undefined);
|
|
44
|
+
if (guidance) {
|
|
45
|
+
sections.push('', 'Guidelines:', " ".concat(guidance));
|
|
43
46
|
}
|
|
44
47
|
if ((_token$usageGuideline2 = token.usageGuidelines) !== null && _token$usageGuideline2 !== void 0 && (_token$usageGuideline2 = _token$usageGuideline2.cssProperties) !== null && _token$usageGuideline2 !== void 0 && _token$usageGuideline2.length) {
|
|
45
48
|
sections.push.apply(sections, ['', 'CSS properties:'].concat((0, _toConsumableArray2.default)(token.usageGuidelines.cssProperties.map(function (item) {
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, "__esModule", {
|
|
4
|
+
value: true
|
|
5
|
+
});
|
|
6
|
+
exports.parseAtlasReleaseBuild = void 0;
|
|
7
|
+
/**
|
|
8
|
+
* ADS releases use <Bitbucket build number>-<8-character commit SHA>. The build number
|
|
9
|
+
* increases with each pipeline run; the SHA identifies the source but does not affect ordering.
|
|
10
|
+
*/
|
|
11
|
+
var parseAtlasReleaseBuild = exports.parseAtlasReleaseBuild = function parseAtlasReleaseBuild(version) {
|
|
12
|
+
if (typeof version !== 'string') {
|
|
13
|
+
return undefined;
|
|
14
|
+
}
|
|
15
|
+
var match = /^(\d+)-[a-f\d]{8}$/i.exec(version);
|
|
16
|
+
var build = match ? Number(match[1]) : NaN;
|
|
17
|
+
return Number.isSafeInteger(build) && build > 0 ? build : undefined;
|
|
18
|
+
};
|
package/dist/cjs/types.js
CHANGED
|
@@ -26,7 +26,7 @@ exports.ExitCode = void 0;
|
|
|
26
26
|
/**
|
|
27
27
|
* Any ADS MCP tool handler: takes an optional arguments object and resolves to a
|
|
28
28
|
* {@link ToolResult}. Kept intentionally loose (`unknown` args) because each tool has its
|
|
29
|
-
* own
|
|
29
|
+
* own input type and schema; the registry is responsible for building well-formed args.
|
|
30
30
|
*/
|
|
31
31
|
|
|
32
32
|
/**
|