@atlaskit/ads-cli 0.11.1 → 0.12.1

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 CHANGED
@@ -1,5 +1,27 @@
1
1
  # @atlaskit/ads-cli
2
2
 
3
+ ## 0.12.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [`537770ebfc5a1`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/537770ebfc5a1) -
8
+ Automatically patch release ADS CLI when ADS MCP changes, keeping the bundled Atlas CLI content
9
+ current and including content updates missed by earlier releases.
10
+
11
+ ## 0.12.0
12
+
13
+ ### Minor Changes
14
+
15
+ - [`ba02fecea90d9`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/ba02fecea90d9) -
16
+ Add an Atlas-only minimum supported release gate controlled by an ADS Statlas policy, with checks
17
+ cached for 24 hours using file-system-cache and UPGRADE_REQUIRED errors. Policy lookup failures
18
+ leave commands usable, including unexpected initialization errors.
19
+
20
+ Warn at one to six stable releases behind and require an upgrade at seven or more behind. One
21
+ pipeline runs manually or daily without input variables, releasing and promoting only when the ADS
22
+ CLI package version changes. It automatically calculates the policy from stable release history,
23
+ even when release is skipped. With fewer than eight stable releases, the policy only warns.
24
+
3
25
  ## 0.11.1
4
26
 
5
27
  ### Patch Changes
@@ -77,15 +99,9 @@
77
99
  {
78
100
  "name": "Avatar",
79
101
  "package": "@atlaskit/avatar",
80
- "props": [
81
- /* ... */
82
- ],
83
- "examples": [
84
- /* ... */
85
- ],
86
- "designSource": {
87
- /* ... */
88
- },
102
+ "props": [/* ... */],
103
+ "examples": [/* ... */],
104
+ "designSource": {/* ... */},
89
105
  }
90
106
  ```
91
107
 
package/README.md CHANGED
@@ -284,8 +284,8 @@ The `--json` envelope is shared unchanged by the npm and Atlas distributions.
284
284
 
285
285
  ## Atlas CLI distribution
286
286
 
287
- The same command surface is available as `atlas ads`. Its entrypoint delegates directly to `run()`,
288
- 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.
289
289
 
290
290
  Build the self-contained JavaScript bundle from the `platform/` directory:
291
291
 
@@ -298,25 +298,119 @@ The `.atlas-plugin` descriptor declares the `ads` plugin and the `atlas-cli-plug
298
298
  namespace. Every upload fetches `manifest.toml` from Statlas before adding a release, so the remote
299
299
  manifest history remains canonical.
300
300
 
301
- 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.
302
339
 
303
- ```sh
304
- VERSION=local-$(git rev-parse --short HEAD) \
305
- 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
+ }
306
358
  ```
307
359
 
308
- This builds 5 variants under `build/releases/$VERSION`, creates each archive and checksum,
309
- smoke-tests the Linux AMD64 executable when running on Linux AMD64, and adds the release to the
310
- `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/`:
311
403
 
312
- The `ads-cli-build-and-upload-to-statlas` custom pipeline runs the tests and typecheck, prepares the
313
- 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
+ ```
314
407
 
315
- After validating an alpha release, run the `ads-cli-promote-stable-version` custom pipeline from
316
- `master` with `VERSION_TO_PROMOTE` set to its exact version. Promotion updates the canonical remote
317
- 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.
318
412
 
319
- The Statlas namespace authorization and Atlas plugin registry entry are one-time external
320
- prerequisites. Until the registry entry is available, use `atlas atlasdev exec` to exercise a
321
- packaged binary in the Atlas runtime. The AFM package scripts own the Node.js executable build; the
322
- 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);
@@ -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
+ };
@@ -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
+ };
@@ -1,16 +1,65 @@
1
1
  #!/usr/bin/env node
2
2
  import { run } from './cli';
3
3
  import { CLI_ATLAS_INVOCATION } from './commands/cli-metadata';
4
+ import { getCommand } from './commands/get-command';
5
+ import { createErrorEnvelope } from './envelope/create-error-envelope';
6
+ import { getAtlasReleaseVersion } from './get-atlas-release-version';
7
+ import { getAtlasVersionPolicy } from './get-atlas-version-policy';
8
+ import { isAtlasReleaseOutdated } from './is-atlas-release-outdated';
9
+ import { writeHumanError } from './output/write-human-error';
10
+ import { writeJsonEnvelope } from './output/write-json-envelope';
11
+ import { defaultWriter } from './output/writer';
12
+ import { parseArgs } from './parse-args';
4
13
 
5
14
  /**
6
15
  * Process entrypoint for the `atlas ads` distribution.
7
16
  *
8
17
  * Atlas forwards everything after `atlas ads` as process arguments. The shared CLI owns parsing,
9
- * output, and its stable exit-code contract; this entrypoint only maps that result onto the plugin
10
- * process.
18
+ * output, and its exit-code contract. This entrypoint enforces the Atlas release policy before
19
+ * command dispatch and maps the result onto the plugin process.
11
20
  */
12
21
  export const main = async (argv = process.argv.slice(2)) => {
13
22
  try {
23
+ const {
24
+ command,
25
+ flags
26
+ } = parseArgs(argv);
27
+ const version = getAtlasReleaseVersion();
28
+ if (flags.version === true && version) {
29
+ defaultWriter.out(version);
30
+ process.exitCode = 0;
31
+ return;
32
+ }
33
+ // Match `run()`'s flag semantics exactly: only a bare `--help`/`--version` short-circuits
34
+ // there, so only those may skip the policy check here.
35
+ if (version && command && getCommand(command) && flags.help !== true && flags.version !== true) {
36
+ // Policy checks are best-effort: even unexpected setup failures must leave ADS usable.
37
+ const policy = await getAtlasVersionPolicy().catch(() => undefined);
38
+ if (policy !== null && policy !== void 0 && policy.enabled && isAtlasReleaseOutdated(version, policy.minimumVersion)) {
39
+ const message = `ADS Atlas plugin ${version} is older than the minimum supported release ${policy.minimumVersion}. ` + 'Run `atlas plugin upgrade --name ads --channel stable`, then retry your command.';
40
+ if (flags.json === true) {
41
+ writeJsonEnvelope({
42
+ envelope: createErrorEnvelope({
43
+ command,
44
+ code: 'UPGRADE_REQUIRED',
45
+ message
46
+ }),
47
+ writer: defaultWriter
48
+ });
49
+ } else {
50
+ writeHumanError({
51
+ message,
52
+ writer: defaultWriter
53
+ });
54
+ }
55
+ process.exitCode = 1;
56
+ return;
57
+ }
58
+ if (policy !== null && policy !== void 0 && policy.enabled && isAtlasReleaseOutdated(version, policy.recommendedVersion)) {
59
+ // Diagnostics belong on stderr, leaving successful JSON/data output unchanged.
60
+ defaultWriter.err(`Warning: ADS Atlas plugin ${version} is behind the latest stable release ${policy.recommendedVersion}. ` + 'Run `atlas plugin upgrade --name ads --channel stable` to update.');
61
+ }
62
+ }
14
63
  const exitCode = await run(argv, undefined, {
15
64
  invocation: CLI_ATLAS_INVOCATION
16
65
  });
@@ -0,0 +1,56 @@
1
+ import { get } from 'https';
2
+ const POLICY_URL = 'https://statlas.prod.atl-paas.net/atlas-cli-plugin-ads/version-policy.json';
3
+ const REQUEST_TIMEOUT_MS = 1500;
4
+ const MAX_POLICY_BYTES = 16 * 1024;
5
+
6
+ /**
7
+ * A bounded, unauthenticated read of the ADS-owned policy; failures leave the CLI usable.
8
+ */
9
+ export const fetchAtlasVersionPolicy = () => new Promise(resolve => {
10
+ let request;
11
+ const deadline = setTimeout(() => {
12
+ var _request;
13
+ (_request = request) === null || _request === void 0 ? void 0 : _request.destroy();
14
+ resolve(undefined);
15
+ }, REQUEST_TIMEOUT_MS);
16
+ const finish = value => {
17
+ clearTimeout(deadline);
18
+ resolve(value);
19
+ };
20
+ try {
21
+ // Statlas explicitly bypasses its ten-minute proxy cache for Pragma requests.
22
+ request = get(POLICY_URL, {
23
+ headers: {
24
+ Accept: 'application/json',
25
+ Pragma: 'no-cache'
26
+ }
27
+ }, response => {
28
+ if (response.statusCode !== 200) {
29
+ response.destroy();
30
+ finish();
31
+ return;
32
+ }
33
+ let body = '';
34
+ response.setEncoding('utf8');
35
+ response.on('data', chunk => {
36
+ body += chunk;
37
+ if (Buffer.byteLength(body) > MAX_POLICY_BYTES) {
38
+ var _request2;
39
+ (_request2 = request) === null || _request2 === void 0 ? void 0 : _request2.destroy();
40
+ finish();
41
+ }
42
+ });
43
+ response.on('error', () => finish());
44
+ response.on('end', () => {
45
+ try {
46
+ finish(JSON.parse(body));
47
+ } catch {
48
+ finish();
49
+ }
50
+ });
51
+ });
52
+ request.on('error', () => finish());
53
+ } catch {
54
+ finish();
55
+ }
56
+ });
@@ -0,0 +1 @@
1
+ export const getAtlasReleaseVersion = () => typeof __ADS_ATLAS_RELEASE_VERSION__ === 'string' && __ADS_ATLAS_RELEASE_VERSION__ !== '' ? __ADS_ATLAS_RELEASE_VERSION__ : undefined;
@@ -0,0 +1,86 @@
1
+ import { mkdir } from 'fs/promises';
2
+ import { homedir } from 'os';
3
+ import path from 'path';
4
+ import { Cache } from 'file-system-cache';
5
+ import { fetchAtlasVersionPolicy } from './fetch-atlas-version-policy';
6
+ import { parseAtlasReleaseBuild } from './parse-atlas-release-build';
7
+ const CACHE_TTL_SECONDS = 24 * 60 * 60;
8
+ const CACHE_KEY = 'version-policy';
9
+ const parsePolicy = value => {
10
+ if (typeof value !== 'object' || value === null || !('enabled' in value)) {
11
+ return undefined;
12
+ }
13
+ if (value.enabled === false) {
14
+ return {
15
+ enabled: false
16
+ };
17
+ }
18
+ const minimumVersion = 'minimumVersion' in value ? value.minimumVersion : undefined;
19
+ const recommendedVersion = 'recommendedVersion' in value ? value.recommendedVersion : undefined;
20
+ const minimumBuild = parseAtlasReleaseBuild(minimumVersion);
21
+ const recommendedBuild = parseAtlasReleaseBuild(recommendedVersion);
22
+ if (value.enabled === true && (minimumVersion !== undefined || recommendedVersion !== undefined) && (minimumVersion === undefined || minimumBuild !== undefined) && (recommendedVersion === undefined || recommendedBuild !== undefined) && (minimumBuild === undefined || recommendedBuild === undefined || minimumBuild <= recommendedBuild)) {
23
+ return {
24
+ enabled: true,
25
+ ...(minimumVersion !== undefined ? {
26
+ minimumVersion: minimumVersion
27
+ } : {}),
28
+ ...(recommendedVersion !== undefined ? {
29
+ recommendedVersion: recommendedVersion
30
+ } : {})
31
+ };
32
+ }
33
+ return undefined;
34
+ };
35
+
36
+ /**
37
+ * Share a 24-hour policy cache across Atlas invocations, including disabled and failed checks.
38
+ */
39
+ export const getAtlasVersionPolicy = async () => {
40
+ const cacheDir = path.join(process.env.ATLAS_CACHE || path.join(homedir(), '.cache/atlassian/atlas'), 'ads');
41
+ // eslint-disable-next-line @repo/internal/react/disallow-unstable-values -- This is a Node CLI cache clock, not React render data.
42
+ const checkedAt = Date.now();
43
+ let cache;
44
+ try {
45
+ cache = new Cache({
46
+ basePath: cacheDir,
47
+ ttl: CACHE_TTL_SECONDS
48
+ });
49
+ const cached = await cache.get(CACHE_KEY);
50
+ // The library handles expiry; reject future-dated entries if the machine's clock moves back.
51
+ if (typeof (cached === null || cached === void 0 ? void 0 : cached.checkedAt) === 'number' && checkedAt >= cached.checkedAt) {
52
+ if (cached.policy === null) {
53
+ return undefined;
54
+ }
55
+ const policy = parsePolicy(cached.policy);
56
+ if (policy) {
57
+ return policy;
58
+ }
59
+ }
60
+ } catch {
61
+ // Unreadable or partial concurrent writes are cache misses, so try a fresh check.
62
+ }
63
+ let policy;
64
+ try {
65
+ policy = parsePolicy(await fetchAtlasVersionPolicy());
66
+ } catch {
67
+ // Match devenv's fail-open behavior when remote configuration is unavailable.
68
+ }
69
+ try {
70
+ if (cache) {
71
+ var _policy;
72
+ // Owner-only access to the directory (chmod 700) protects the library-managed files.
73
+ await mkdir(cacheDir, {
74
+ recursive: true,
75
+ mode: 0o700
76
+ });
77
+ await cache.set(CACHE_KEY, {
78
+ checkedAt,
79
+ policy: (_policy = policy) !== null && _policy !== void 0 ? _policy : null
80
+ });
81
+ }
82
+ } catch {
83
+ // The policy still works when a machine's cache is read-only.
84
+ }
85
+ return policy;
86
+ };
@@ -0,0 +1,7 @@
1
+ import { parseAtlasReleaseBuild } from './parse-atlas-release-build';
2
+ export const isAtlasReleaseOutdated = (installed, minimum) => {
3
+ const installedBuild = parseAtlasReleaseBuild(installed);
4
+ const minimumBuild = parseAtlasReleaseBuild(minimum);
5
+ // Compare valid build numbers for either threshold; unknown versions remain usable.
6
+ return installedBuild !== undefined && minimumBuild !== undefined && installedBuild < minimumBuild;
7
+ };
@@ -0,0 +1,12 @@
1
+ /**
2
+ * ADS releases use <Bitbucket build number>-<8-character commit SHA>. The build number
3
+ * increases with each pipeline run; the SHA identifies the source but does not affect ordering.
4
+ */
5
+ export const parseAtlasReleaseBuild = version => {
6
+ if (typeof version !== 'string') {
7
+ return undefined;
8
+ }
9
+ const match = /^(\d+)-[a-f\d]{8}$/i.exec(version);
10
+ const build = match ? Number(match[1]) : NaN;
11
+ return Number.isSafeInteger(build) && build > 0 ? build : undefined;
12
+ };
@@ -3,17 +3,32 @@ import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
3
3
  import _regeneratorRuntime from "@babel/runtime/regenerator";
4
4
  import { run } from './cli';
5
5
  import { CLI_ATLAS_INVOCATION } from './commands/cli-metadata';
6
+ import { getCommand } from './commands/get-command';
7
+ import { createErrorEnvelope } from './envelope/create-error-envelope';
8
+ import { getAtlasReleaseVersion } from './get-atlas-release-version';
9
+ import { getAtlasVersionPolicy } from './get-atlas-version-policy';
10
+ import { isAtlasReleaseOutdated } from './is-atlas-release-outdated';
11
+ import { writeHumanError } from './output/write-human-error';
12
+ import { writeJsonEnvelope } from './output/write-json-envelope';
13
+ import { defaultWriter } from './output/writer';
14
+ import { parseArgs } from './parse-args';
6
15
 
7
16
  /**
8
17
  * Process entrypoint for the `atlas ads` distribution.
9
18
  *
10
19
  * Atlas forwards everything after `atlas ads` as process arguments. The shared CLI owns parsing,
11
- * output, and its stable exit-code contract; this entrypoint only maps that result onto the plugin
12
- * process.
20
+ * output, and its exit-code contract. This entrypoint enforces the Atlas release policy before
21
+ * command dispatch and maps the result onto the plugin process.
13
22
  */
14
23
  export var main = /*#__PURE__*/function () {
15
24
  var _ref = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee() {
16
25
  var argv,
26
+ _parseArgs,
27
+ command,
28
+ flags,
29
+ version,
30
+ policy,
31
+ message,
17
32
  exitCode,
18
33
  _error$stack,
19
34
  _args = arguments,
@@ -23,32 +38,80 @@ export var main = /*#__PURE__*/function () {
23
38
  case 0:
24
39
  argv = _args.length > 0 && _args[0] !== undefined ? _args[0] : process.argv.slice(2);
25
40
  _context.prev = 1;
26
- _context.next = 2;
41
+ _parseArgs = parseArgs(argv), command = _parseArgs.command, flags = _parseArgs.flags;
42
+ version = getAtlasReleaseVersion();
43
+ if (!(flags.version === true && version)) {
44
+ _context.next = 2;
45
+ break;
46
+ }
47
+ defaultWriter.out(version);
48
+ process.exitCode = 0;
49
+ return _context.abrupt("return");
50
+ case 2:
51
+ if (!(version && command && getCommand(command) && flags.help !== true && flags.version !== true)) {
52
+ _context.next = 5;
53
+ break;
54
+ }
55
+ _context.next = 3;
56
+ return getAtlasVersionPolicy().catch(function () {
57
+ return undefined;
58
+ });
59
+ case 3:
60
+ policy = _context.sent;
61
+ if (!(policy !== null && policy !== void 0 && policy.enabled && isAtlasReleaseOutdated(version, policy.minimumVersion))) {
62
+ _context.next = 4;
63
+ break;
64
+ }
65
+ 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.';
66
+ if (flags.json === true) {
67
+ writeJsonEnvelope({
68
+ envelope: createErrorEnvelope({
69
+ command: command,
70
+ code: 'UPGRADE_REQUIRED',
71
+ message: message
72
+ }),
73
+ writer: defaultWriter
74
+ });
75
+ } else {
76
+ writeHumanError({
77
+ message: message,
78
+ writer: defaultWriter
79
+ });
80
+ }
81
+ process.exitCode = 1;
82
+ return _context.abrupt("return");
83
+ case 4:
84
+ if (policy !== null && policy !== void 0 && policy.enabled && isAtlasReleaseOutdated(version, policy.recommendedVersion)) {
85
+ // Diagnostics belong on stderr, leaving successful JSON/data output unchanged.
86
+ 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.');
87
+ }
88
+ case 5:
89
+ _context.next = 6;
27
90
  return run(argv, undefined, {
28
91
  invocation: CLI_ATLAS_INVOCATION
29
92
  });
30
- case 2:
93
+ case 6:
31
94
  exitCode = _context.sent;
32
95
  process.exitCode = exitCode;
33
- _context.next = 5;
96
+ _context.next = 9;
34
97
  break;
35
- case 3:
36
- _context.prev = 3;
98
+ case 7:
99
+ _context.prev = 7;
37
100
  _t = _context["catch"](1);
38
101
  if (!(typeof _t === 'number')) {
39
- _context.next = 4;
102
+ _context.next = 8;
40
103
  break;
41
104
  }
42
105
  process.exitCode = _t;
43
106
  return _context.abrupt("return");
44
- case 4:
107
+ case 8:
45
108
  process.stderr.write("".concat(_t instanceof Error ? (_error$stack = _t.stack) !== null && _error$stack !== void 0 ? _error$stack : _t.message : String(_t), "\n"));
46
109
  process.exitCode = 1;
47
- case 5:
110
+ case 9:
48
111
  case "end":
49
112
  return _context.stop();
50
113
  }
51
- }, _callee, null, [[1, 3]]);
114
+ }, _callee, null, [[1, 7]]);
52
115
  }));
53
116
  return function main() {
54
117
  return _ref.apply(this, arguments);
@@ -0,0 +1,62 @@
1
+ import { get } from 'https';
2
+ var POLICY_URL = 'https://statlas.prod.atl-paas.net/atlas-cli-plugin-ads/version-policy.json';
3
+ var REQUEST_TIMEOUT_MS = 1500;
4
+ var MAX_POLICY_BYTES = 16 * 1024;
5
+
6
+ /**
7
+ * A bounded, unauthenticated read of the ADS-owned policy; failures leave the CLI usable.
8
+ */
9
+ export var fetchAtlasVersionPolicy = function fetchAtlasVersionPolicy() {
10
+ return new Promise(function (resolve) {
11
+ var request;
12
+ var deadline = setTimeout(function () {
13
+ var _request;
14
+ (_request = request) === null || _request === void 0 || _request.destroy();
15
+ resolve(undefined);
16
+ }, REQUEST_TIMEOUT_MS);
17
+ var finish = function finish(value) {
18
+ clearTimeout(deadline);
19
+ resolve(value);
20
+ };
21
+ try {
22
+ // Statlas explicitly bypasses its ten-minute proxy cache for Pragma requests.
23
+ request = get(POLICY_URL, {
24
+ headers: {
25
+ Accept: 'application/json',
26
+ Pragma: 'no-cache'
27
+ }
28
+ }, function (response) {
29
+ if (response.statusCode !== 200) {
30
+ response.destroy();
31
+ finish();
32
+ return;
33
+ }
34
+ var body = '';
35
+ response.setEncoding('utf8');
36
+ response.on('data', function (chunk) {
37
+ body += chunk;
38
+ if (Buffer.byteLength(body) > MAX_POLICY_BYTES) {
39
+ var _request2;
40
+ (_request2 = request) === null || _request2 === void 0 || _request2.destroy();
41
+ finish();
42
+ }
43
+ });
44
+ response.on('error', function () {
45
+ return finish();
46
+ });
47
+ response.on('end', function () {
48
+ try {
49
+ finish(JSON.parse(body));
50
+ } catch (_unused) {
51
+ finish();
52
+ }
53
+ });
54
+ });
55
+ request.on('error', function () {
56
+ return finish();
57
+ });
58
+ } catch (_unused2) {
59
+ finish();
60
+ }
61
+ });
62
+ };
@@ -0,0 +1,3 @@
1
+ export var getAtlasReleaseVersion = function getAtlasReleaseVersion() {
2
+ return typeof __ADS_ATLAS_RELEASE_VERSION__ === 'string' && __ADS_ATLAS_RELEASE_VERSION__ !== '' ? __ADS_ATLAS_RELEASE_VERSION__ : undefined;
3
+ };
@@ -0,0 +1,128 @@
1
+ import _asyncToGenerator from "@babel/runtime/helpers/asyncToGenerator";
2
+ import _defineProperty from "@babel/runtime/helpers/defineProperty";
3
+ import _typeof from "@babel/runtime/helpers/typeof";
4
+ import _regeneratorRuntime from "@babel/runtime/regenerator";
5
+ 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; }
6
+ 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) { _defineProperty(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; }
7
+ import { mkdir } from 'fs/promises';
8
+ import { homedir } from 'os';
9
+ import path from 'path';
10
+ import { Cache } from 'file-system-cache';
11
+ import { fetchAtlasVersionPolicy } from './fetch-atlas-version-policy';
12
+ import { parseAtlasReleaseBuild } from './parse-atlas-release-build';
13
+ var CACHE_TTL_SECONDS = 24 * 60 * 60;
14
+ var CACHE_KEY = 'version-policy';
15
+ var parsePolicy = function parsePolicy(value) {
16
+ if (_typeof(value) !== 'object' || value === null || !('enabled' in value)) {
17
+ return undefined;
18
+ }
19
+ if (value.enabled === false) {
20
+ return {
21
+ enabled: false
22
+ };
23
+ }
24
+ var minimumVersion = 'minimumVersion' in value ? value.minimumVersion : undefined;
25
+ var recommendedVersion = 'recommendedVersion' in value ? value.recommendedVersion : undefined;
26
+ var minimumBuild = parseAtlasReleaseBuild(minimumVersion);
27
+ var recommendedBuild = parseAtlasReleaseBuild(recommendedVersion);
28
+ if (value.enabled === true && (minimumVersion !== undefined || recommendedVersion !== undefined) && (minimumVersion === undefined || minimumBuild !== undefined) && (recommendedVersion === undefined || recommendedBuild !== undefined) && (minimumBuild === undefined || recommendedBuild === undefined || minimumBuild <= recommendedBuild)) {
29
+ return _objectSpread(_objectSpread({
30
+ enabled: true
31
+ }, minimumVersion !== undefined ? {
32
+ minimumVersion: minimumVersion
33
+ } : {}), recommendedVersion !== undefined ? {
34
+ recommendedVersion: recommendedVersion
35
+ } : {});
36
+ }
37
+ return undefined;
38
+ };
39
+
40
+ /**
41
+ * Share a 24-hour policy cache across Atlas invocations, including disabled and failed checks.
42
+ */
43
+ export var getAtlasVersionPolicy = /*#__PURE__*/function () {
44
+ var _ref = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee() {
45
+ var cacheDir, checkedAt, cache, cached, _policy, policy, _t, _t2, _t3, _t4;
46
+ return _regeneratorRuntime.wrap(function (_context) {
47
+ while (1) switch (_context.prev = _context.next) {
48
+ case 0:
49
+ cacheDir = path.join(process.env.ATLAS_CACHE || path.join(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.
50
+ checkedAt = Date.now();
51
+ _context.prev = 1;
52
+ cache = new Cache({
53
+ basePath: cacheDir,
54
+ ttl: CACHE_TTL_SECONDS
55
+ });
56
+ _context.next = 2;
57
+ return cache.get(CACHE_KEY);
58
+ case 2:
59
+ cached = _context.sent;
60
+ if (!(typeof (cached === null || cached === void 0 ? void 0 : cached.checkedAt) === 'number' && checkedAt >= cached.checkedAt)) {
61
+ _context.next = 4;
62
+ break;
63
+ }
64
+ if (!(cached.policy === null)) {
65
+ _context.next = 3;
66
+ break;
67
+ }
68
+ return _context.abrupt("return", undefined);
69
+ case 3:
70
+ _policy = parsePolicy(cached.policy);
71
+ if (!_policy) {
72
+ _context.next = 4;
73
+ break;
74
+ }
75
+ return _context.abrupt("return", _policy);
76
+ case 4:
77
+ _context.next = 6;
78
+ break;
79
+ case 5:
80
+ _context.prev = 5;
81
+ _t = _context["catch"](1);
82
+ case 6:
83
+ _context.prev = 6;
84
+ _t2 = parsePolicy;
85
+ _context.next = 7;
86
+ return fetchAtlasVersionPolicy();
87
+ case 7:
88
+ policy = _t2(_context.sent);
89
+ _context.next = 9;
90
+ break;
91
+ case 8:
92
+ _context.prev = 8;
93
+ _t3 = _context["catch"](6);
94
+ case 9:
95
+ _context.prev = 9;
96
+ if (!cache) {
97
+ _context.next = 11;
98
+ break;
99
+ }
100
+ _context.next = 10;
101
+ return mkdir(cacheDir, {
102
+ recursive: true,
103
+ mode: 448
104
+ });
105
+ case 10:
106
+ _context.next = 11;
107
+ return cache.set(CACHE_KEY, {
108
+ checkedAt: checkedAt,
109
+ policy: policy !== null && policy !== void 0 ? policy : null
110
+ });
111
+ case 11:
112
+ _context.next = 13;
113
+ break;
114
+ case 12:
115
+ _context.prev = 12;
116
+ _t4 = _context["catch"](9);
117
+ case 13:
118
+ return _context.abrupt("return", policy);
119
+ case 14:
120
+ case "end":
121
+ return _context.stop();
122
+ }
123
+ }, _callee, null, [[1, 5], [6, 8], [9, 12]]);
124
+ }));
125
+ return function getAtlasVersionPolicy() {
126
+ return _ref.apply(this, arguments);
127
+ };
128
+ }();
@@ -0,0 +1,7 @@
1
+ import { parseAtlasReleaseBuild } from './parse-atlas-release-build';
2
+ export var isAtlasReleaseOutdated = function isAtlasReleaseOutdated(installed, minimum) {
3
+ var installedBuild = parseAtlasReleaseBuild(installed);
4
+ var minimumBuild = parseAtlasReleaseBuild(minimum);
5
+ // Compare valid build numbers for either threshold; unknown versions remain usable.
6
+ return installedBuild !== undefined && minimumBuild !== undefined && installedBuild < minimumBuild;
7
+ };
@@ -0,0 +1,12 @@
1
+ /**
2
+ * ADS releases use <Bitbucket build number>-<8-character commit SHA>. The build number
3
+ * increases with each pipeline run; the SHA identifies the source but does not affect ordering.
4
+ */
5
+ export var parseAtlasReleaseBuild = function parseAtlasReleaseBuild(version) {
6
+ if (typeof version !== 'string') {
7
+ return undefined;
8
+ }
9
+ var match = /^(\d+)-[a-f\d]{8}$/i.exec(version);
10
+ var build = match ? Number(match[1]) : NaN;
11
+ return Number.isSafeInteger(build) && build > 0 ? build : undefined;
12
+ };
@@ -3,7 +3,7 @@
3
3
  * Process entrypoint for the `atlas ads` distribution.
4
4
  *
5
5
  * Atlas forwards everything after `atlas ads` as process arguments. The shared CLI owns parsing,
6
- * output, and its stable exit-code contract; this entrypoint only maps that result onto the plugin
7
- * process.
6
+ * output, and its exit-code contract. This entrypoint enforces the Atlas release policy before
7
+ * command dispatch and maps the result onto the plugin process.
8
8
  */
9
9
  export declare const main: (argv?: string[]) => Promise<void>;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Types for the stable JSON envelope emitted when the CLI is run with `--json`.
3
3
  *
4
- * Agents (and a future `atlas ads` plugin) consume this shape, so it must stay stable and
4
+ * Agents and the `atlas ads` plugin consume this shape, so it must stay stable and
5
5
  * self-describing. Every envelope carries a `type` discriminator (`ads-cli/<command>` for
6
6
  * success, `ads-cli/error` for failures) so consumers can branch without re-parsing.
7
7
  */
@@ -42,10 +42,10 @@ export type SuccessEnvelope<Data = unknown> = {
42
42
  /**
43
43
  * Machine-readable error codes used inside {@link ErrorEnvelope}.
44
44
  *
45
- * These mirror the process exit codes but are surfaced as strings so JSON consumers do not
46
- * depend on numeric codes.
45
+ * These identify failure types without relying on numeric process exit codes. Different error
46
+ * codes can share an exit code, such as RUNTIME_ERROR and UPGRADE_REQUIRED both exiting with 1.
47
47
  */
48
- export type EnvelopeErrorCode = 'USAGE_ERROR' | 'NOT_FOUND' | 'RUNTIME_ERROR';
48
+ export type EnvelopeErrorCode = 'USAGE_ERROR' | 'NOT_FOUND' | 'RUNTIME_ERROR' | 'UPGRADE_REQUIRED';
49
49
  /**
50
50
  * Failure envelope. Emitted (with `--json`) when a command cannot complete.
51
51
  */
@@ -0,0 +1,4 @@
1
+ /**
2
+ * A bounded, unauthenticated read of the ADS-owned policy; failures leave the CLI usable.
3
+ */
4
+ export declare const fetchAtlasVersionPolicy: () => Promise<unknown>;
@@ -0,0 +1 @@
1
+ export declare const getAtlasReleaseVersion: () => string | undefined;
@@ -0,0 +1,9 @@
1
+ export type AtlasVersionPolicy = {
2
+ enabled: boolean;
3
+ minimumVersion?: string;
4
+ recommendedVersion?: string;
5
+ };
6
+ /**
7
+ * Share a 24-hour policy cache across Atlas invocations, including disabled and failed checks.
8
+ */
9
+ export declare const getAtlasVersionPolicy: () => Promise<AtlasVersionPolicy | undefined>;
@@ -0,0 +1 @@
1
+ export declare const isAtlasReleaseOutdated: (installed: string | undefined, minimum: string | undefined) => boolean;
@@ -0,0 +1,5 @@
1
+ /**
2
+ * ADS releases use <Bitbucket build number>-<8-character commit SHA>. The build number
3
+ * increases with each pipeline run; the SHA identifies the source but does not affect ordering.
4
+ */
5
+ export declare const parseAtlasReleaseBuild: (version: unknown) => number | undefined;
package/index.js CHANGED
@@ -1,3 +1,4 @@
1
+ /* oxlint-disable eslint-core-js/global-require -- Existing file-level ESLint disable uses original core rule IDs; Oxlint JS plugins report namespaced IDs. */
1
2
  /**
2
3
  * Custom `main` entrypoint that switches between source (in the monorepo) and the
3
4
  * built `dist/cjs` output (when published to npm), mirroring the sibling
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/ads-cli",
3
- "version": "0.11.1",
3
+ "version": "0.12.1",
4
4
  "description": "An npx-runnable command-line tool to query Atlassian Design System (ADS) structured content — components, tokens, icons, and guidelines — from the terminal.",
5
5
  "author": "Atlassian Pty Ltd",
6
6
  "license": "Apache-2.0",
@@ -18,26 +18,31 @@
18
18
  "bin": "./bin/ads-cli.js",
19
19
  "scripts": {
20
20
  "start": "./bin/ads-cli.js",
21
- "build:atlas": "esbuild src/atlas-cli.tsx --bundle --outfile=build/atlas/ads-cli.js --format=cjs --platform=node --target=node18",
21
+ "build:atlas": "run-ts scripts/atlas/build-atlas.tsx",
22
22
  "package:atlas:darwin-amd64": "pkg --public --public-packages '*' --compress GZip --target node18-macos-x64 --output build/atlas/ads-darwin-amd64 build/atlas/ads-cli.js",
23
23
  "package:atlas:darwin-arm64": "pkg --public --public-packages '*' --compress GZip --target node18-macos-arm64 --output build/atlas/ads-darwin-arm64 build/atlas/ads-cli.js",
24
24
  "package:atlas:linux-amd64": "pkg --public --public-packages '*' --compress GZip --target node18-linux-x64 --output build/atlas/ads-linux-amd64 build/atlas/ads-cli.js",
25
25
  "package:atlas:linux-arm64": "pkg --public --public-packages '*' --compress GZip --target node18-linux-arm64 --output build/atlas/ads-linux-arm64 build/atlas/ads-cli.js",
26
26
  "package:atlas:windows-amd64": "pkg --public --public-packages '*' --compress GZip --target node18-win-x64 --output build/atlas/ads-windows-amd64.exe build/atlas/ads-cli.js",
27
27
  "package:atlas": "afm run build:atlas && afm run package:atlas:darwin-amd64 && afm run package:atlas:darwin-arm64 && afm run package:atlas:linux-amd64 && afm run package:atlas:linux-arm64 && afm run package:atlas:windows-amd64",
28
- "release:atlas:fetch-manifest": "bash scripts/atlas/fetch-manifest.sh",
29
- "release:atlas:prepare": "bash scripts/atlas/prepare-release.sh",
30
- "release:atlas:upload": "bash scripts/atlas/upload-release.sh",
31
- "release:atlas:promote": "bash scripts/atlas/promote-stable.sh"
28
+ "release:atlas:fetch-manifest": "run-ts scripts/atlas/fetch-manifest.tsx",
29
+ "release:atlas:prepare": "run-ts scripts/atlas/prepare-release.tsx",
30
+ "release:atlas:upload": "run-ts scripts/atlas/upload-release.tsx",
31
+ "release:atlas:promote": "run-ts scripts/atlas/promote-stable.tsx",
32
+ "release:atlas": "run-ts scripts/atlas/release-and-promote.tsx",
33
+ "release:atlas:policy": "run-ts scripts/atlas/publish-version-policy.tsx"
32
34
  },
33
35
  "dependencies": {
34
- "@atlaskit/ads-mcp": "^1.11.0",
36
+ "@atlaskit/ads-mcp": "1.12.16",
35
37
  "@atlaskit/cli-output": "^0.1.0",
36
38
  "@babel/runtime": "^7.0.0",
37
- "chalk": "^4.1.2"
39
+ "chalk": "^4.1.2",
40
+ "file-system-cache": "^2.4.4"
38
41
  },
39
42
  "devDependencies": {
43
+ "@atlaskit/docs": "^12.3.0",
40
44
  "@atlassian/ts-loader": "^0.1.0",
45
+ "@iarna/toml": "^2.2.5",
41
46
  "esbuild": "^0.15.18",
42
47
  "pkg": "5.8.1"
43
48
  }