@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.
Files changed (39) hide show
  1. package/CHANGELOG.md +27 -9
  2. package/README.md +115 -19
  3. package/dist/cjs/atlas-cli.js +74 -11
  4. package/dist/cjs/commands/run-tool.js +1 -1
  5. package/dist/cjs/fetch-atlas-version-policy.js +68 -0
  6. package/dist/cjs/get-atlas-release-version.js +9 -0
  7. package/dist/cjs/get-atlas-version-policy.js +135 -0
  8. package/dist/cjs/is-atlas-release-outdated.js +13 -0
  9. package/dist/cjs/output/format-token.js +5 -2
  10. package/dist/cjs/parse-atlas-release-build.js +18 -0
  11. package/dist/cjs/types.js +1 -1
  12. package/dist/es2019/atlas-cli.js +51 -2
  13. package/dist/es2019/commands/run-tool.js +1 -1
  14. package/dist/es2019/fetch-atlas-version-policy.js +56 -0
  15. package/dist/es2019/get-atlas-release-version.js +1 -0
  16. package/dist/es2019/get-atlas-version-policy.js +86 -0
  17. package/dist/es2019/is-atlas-release-outdated.js +7 -0
  18. package/dist/es2019/output/format-token.js +5 -2
  19. package/dist/es2019/parse-atlas-release-build.js +12 -0
  20. package/dist/es2019/types.js +1 -1
  21. package/dist/esm/atlas-cli.js +74 -11
  22. package/dist/esm/commands/run-tool.js +1 -1
  23. package/dist/esm/fetch-atlas-version-policy.js +62 -0
  24. package/dist/esm/get-atlas-release-version.js +3 -0
  25. package/dist/esm/get-atlas-version-policy.js +128 -0
  26. package/dist/esm/is-atlas-release-outdated.js +7 -0
  27. package/dist/esm/output/format-token.js +5 -2
  28. package/dist/esm/parse-atlas-release-build.js +12 -0
  29. package/dist/esm/types.js +1 -1
  30. package/dist/types/atlas-cli.d.ts +2 -2
  31. package/dist/types/commands/run-tool.d.ts +1 -1
  32. package/dist/types/envelope/types.d.ts +4 -4
  33. package/dist/types/fetch-atlas-version-policy.d.ts +4 -0
  34. package/dist/types/get-atlas-release-version.d.ts +1 -0
  35. package/dist/types/get-atlas-version-policy.d.ts +9 -0
  36. package/dist/types/is-atlas-release-outdated.d.ts +1 -0
  37. package/dist/types/parse-atlas-release-build.d.ts +5 -0
  38. package/dist/types/types.d.ts +1 -1
  39. 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 `usageGuidelines` and `usage`, and an icon `import`.
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 delegates directly to `run()`,
286
- so npm and Atlas share command parsing, output, and exit codes.
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
- Prepare an Atlas-shaped release locally:
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
- ```sh
302
- VERSION=local-$(git rev-parse --short HEAD) \
303
- afm workspace @atlaskit/ads-cli release:atlas:prepare
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
- This builds 5 variants under `build/releases/$VERSION`, creates each archive and checksum,
307
- smoke-tests the Linux AMD64 executable when running on Linux AMD64, and adds the release to the
308
- `alpha` channel in the working manifest.
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
- The `ads-cli-build-and-upload-to-statlas` custom pipeline runs the tests and typecheck, prepares the
311
- release, uploads all artifacts, then publishes the manifest. Run it from `master`.
404
+ ```sh
405
+ afm workspace @atlaskit/ads-cli release:atlas:policy --dry-run
406
+ ```
312
407
 
313
- After validating an alpha release, run the `ads-cli-promote-stable-version` custom pipeline from
314
- `master` with `VERSION_TO_PROMOTE` set to its exact version. Promotion updates the canonical remote
315
- manifest without rebuilding or uploading artifacts.
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 Statlas namespace authorization and Atlas plugin registry entry are one-time external
318
- prerequisites. Until the registry entry is available, use `atlas atlasdev exec` to exercise a
319
- packaged binary in the Atlas runtime. The AFM package scripts own the Node.js executable build; the
320
- generic `atlas atlasdev plugin build` command doesn't drive this package.
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.
@@ -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 stable exit-code contract; this entrypoint only maps that result onto the plugin
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
- _context.next = 2;
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 2:
99
+ case 6:
37
100
  exitCode = _context.sent;
38
101
  process.exitCode = exitCode;
39
- _context.next = 5;
102
+ _context.next = 9;
40
103
  break;
41
- case 3:
42
- _context.prev = 3;
104
+ case 7:
105
+ _context.prev = 7;
43
106
  _t = _context["catch"](1);
44
107
  if (!(typeof _t === 'number')) {
45
- _context.next = 4;
108
+ _context.next = 8;
46
109
  break;
47
110
  }
48
111
  process.exitCode = _t;
49
112
  return _context.abrupt("return");
50
- case 4:
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 5:
116
+ case 9:
54
117
  case "end":
55
118
  return _context.stop();
56
119
  }
57
- }, _callee, null, [[1, 3]]);
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 zod input schema, or `undefined`
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
- if ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage) {
42
- sections.push('', 'Guidelines:', " ".concat(oneLine(token.usageGuidelines.usage)));
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 zod input schema; the registry is responsible for building well-formed args.
29
+ * own input type and schema; the registry is responsible for building well-formed args.
30
30
  */
31
31
 
32
32
  /**