@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
@@ -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
  });
@@ -38,7 +38,7 @@ const getTextBlocks = result => result.content.filter(item => item.type === 'tex
38
38
  * Invoke an ADS MCP tool handler and unwrap its result into plain data.
39
39
  *
40
40
  * @param handler - The tool function (e.g. `searchComponentsTool`).
41
- * @param args - The arguments object matching the tool's zod input schema, or `undefined`
41
+ * @param args - The arguments object matching the tool's input shape, or `undefined`
42
42
  * for zero-argument tools such as `getAllComponentsTool`.
43
43
  */
44
44
  export const runTool = async ({
@@ -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
+ };
@@ -27,8 +27,11 @@ export const formatToken = data => {
27
27
  if (token.exampleValue) {
28
28
  sections.push('', `Example value: ${token.exampleValue}`);
29
29
  }
30
- if ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage) {
31
- sections.push('', 'Guidelines:', ` ${oneLine(token.usageGuidelines.usage)}`);
30
+
31
+ // Prefer the canonical per-token description over the broader category guidance.
32
+ const guidance = token.description || ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage ? oneLine(token.usageGuidelines.usage) : undefined);
33
+ if (guidance) {
34
+ sections.push('', 'Guidelines:', ` ${guidance}`);
32
35
  }
33
36
  if ((_token$usageGuideline2 = token.usageGuidelines) !== null && _token$usageGuideline2 !== void 0 && (_token$usageGuideline3 = _token$usageGuideline2.cssProperties) !== null && _token$usageGuideline3 !== void 0 && _token$usageGuideline3.length) {
34
37
  sections.push('', 'CSS properties:', ...token.usageGuidelines.cssProperties.map(item => ` ${item}`));
@@ -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
+ };
@@ -20,7 +20,7 @@
20
20
  /**
21
21
  * Any ADS MCP tool handler: takes an optional arguments object and resolves to a
22
22
  * {@link ToolResult}. Kept intentionally loose (`unknown` args) because each tool has its
23
- * own zod input schema; the registry is responsible for building well-formed args.
23
+ * own input type and schema; the registry is responsible for building well-formed args.
24
24
  */
25
25
 
26
26
  /**
@@ -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);
@@ -48,7 +48,7 @@ var getTextBlocks = function getTextBlocks(result) {
48
48
  * Invoke an ADS MCP tool handler and unwrap its result into plain data.
49
49
  *
50
50
  * @param handler - The tool function (e.g. `searchComponentsTool`).
51
- * @param args - The arguments object matching the tool's zod input schema, or `undefined`
51
+ * @param args - The arguments object matching the tool's input shape, or `undefined`
52
52
  * for zero-argument tools such as `getAllComponentsTool`.
53
53
  */
54
54
  export var runTool = /*#__PURE__*/function () {
@@ -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
+ };
@@ -31,8 +31,11 @@ export var formatToken = function formatToken(data) {
31
31
  if (token.exampleValue) {
32
32
  sections.push('', "Example value: ".concat(token.exampleValue));
33
33
  }
34
- if ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage) {
35
- sections.push('', 'Guidelines:', " ".concat(oneLine(token.usageGuidelines.usage)));
34
+
35
+ // Prefer the canonical per-token description over the broader category guidance.
36
+ var guidance = token.description || ((_token$usageGuideline = token.usageGuidelines) !== null && _token$usageGuideline !== void 0 && _token$usageGuideline.usage ? oneLine(token.usageGuidelines.usage) : undefined);
37
+ if (guidance) {
38
+ sections.push('', 'Guidelines:', " ".concat(guidance));
36
39
  }
37
40
  if ((_token$usageGuideline2 = token.usageGuidelines) !== null && _token$usageGuideline2 !== void 0 && (_token$usageGuideline2 = _token$usageGuideline2.cssProperties) !== null && _token$usageGuideline2 !== void 0 && _token$usageGuideline2.length) {
38
41
  sections.push.apply(sections, ['', 'CSS properties:'].concat(_toConsumableArray(token.usageGuidelines.cssProperties.map(function (item) {
@@ -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
+ };
package/dist/esm/types.js CHANGED
@@ -20,7 +20,7 @@
20
20
  /**
21
21
  * Any ADS MCP tool handler: takes an optional arguments object and resolves to a
22
22
  * {@link ToolResult}. Kept intentionally loose (`unknown` args) because each tool has its
23
- * own zod input schema; the registry is responsible for building well-formed args.
23
+ * own input type and schema; the registry is responsible for building well-formed args.
24
24
  */
25
25
 
26
26
  /**
@@ -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>;