@atlaskit/ads-cli 0.9.0 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +21 -0
- package/README.md +26 -10
- package/bin/ads-cli.js +9 -2
- package/dist/cjs/commands/init.js +79 -6
- package/dist/cjs/commands/update-agents-file.js +150 -0
- package/dist/cjs/output/format-component.js +23 -31
- package/dist/cjs/output/format-doc-object.js +2 -1
- package/dist/cjs/output/format-results.js +34 -45
- package/dist/es2019/commands/init.js +70 -2
- package/dist/es2019/commands/update-agents-file.js +139 -0
- package/dist/es2019/output/format-component.js +22 -31
- package/dist/es2019/output/format-doc-object.js +2 -1
- package/dist/es2019/output/format-results.js +27 -37
- package/dist/esm/commands/init.js +79 -6
- package/dist/esm/commands/update-agents-file.js +143 -0
- package/dist/esm/output/format-component.js +23 -30
- package/dist/esm/output/format-doc-object.js +2 -1
- package/dist/esm/output/format-results.js +34 -45
- package/dist/types/commands/update-agents-file.d.ts +22 -0
- package/dist/types/output/format-doc-object.d.ts +0 -8
- package/package.json +2 -1
|
@@ -13,6 +13,7 @@ import { writeHumanError } from '../output/write-human-error';
|
|
|
13
13
|
import { writeJsonEnvelope } from '../output/write-json-envelope';
|
|
14
14
|
import { ExitCode } from '../types';
|
|
15
15
|
import { CLI_ATLAS_INVOCATION } from './cli-metadata';
|
|
16
|
+
import { AGENTS_FILE_RELATIVE_PATH, updateAgentsFile } from './update-agents-file';
|
|
16
17
|
var SKILL_ENTRYPOINT = 'SKILL.md';
|
|
17
18
|
var SKILLS = [{
|
|
18
19
|
name: 'atlassian-design-system',
|
|
@@ -30,6 +31,8 @@ var SKILLS = [{
|
|
|
30
31
|
relativePath: '.agents/skills/a11y-foundation',
|
|
31
32
|
requiredFiles: [SKILL_ENTRYPOINT]
|
|
32
33
|
}];
|
|
34
|
+
var ADS_SKILL = SKILLS[0];
|
|
35
|
+
var SKILL_GET_STARTED_RELATIVE_PATH = "".concat(ADS_SKILL.relativePath, "/references/get-started.md");
|
|
33
36
|
var GIT_MARKER = '.git';
|
|
34
37
|
var SKILLS_INSTALLER_PACKAGE = '@atlassian/skills';
|
|
35
38
|
var SKILLS_INSTALLER_UNAVAILABLE_REASON = 'skills-installer-unavailable';
|
|
@@ -138,13 +141,33 @@ var validateInput = function validateInput(input) {
|
|
|
138
141
|
}
|
|
139
142
|
return undefined;
|
|
140
143
|
};
|
|
144
|
+
var writeAgentsFileResult = function writeAgentsFileResult(_ref3) {
|
|
145
|
+
var result = _ref3.result,
|
|
146
|
+
writer = _ref3.writer;
|
|
147
|
+
switch (result.status) {
|
|
148
|
+
case 'created':
|
|
149
|
+
writer.out("\u2713 Created ".concat(AGENTS_FILE_RELATIVE_PATH, " with ADS setup guidance"));
|
|
150
|
+
return;
|
|
151
|
+
case 'appended':
|
|
152
|
+
writer.out("\u2713 Appended ADS setup guidance to ".concat(AGENTS_FILE_RELATIVE_PATH));
|
|
153
|
+
return;
|
|
154
|
+
case 'updated':
|
|
155
|
+
writer.out("\u2713 Updated ADS setup guidance in ".concat(AGENTS_FILE_RELATIVE_PATH));
|
|
156
|
+
return;
|
|
157
|
+
case 'already-current':
|
|
158
|
+
writer.out("\u2713 ADS setup guidance already current in ".concat(AGENTS_FILE_RELATIVE_PATH));
|
|
159
|
+
return;
|
|
160
|
+
case 'not-written':
|
|
161
|
+
writer.out("\u2013 ".concat(AGENTS_FILE_RELATIVE_PATH, " not updated because the current directory is not in a Git repository"));
|
|
162
|
+
}
|
|
163
|
+
};
|
|
141
164
|
export var runInitCommand = /*#__PURE__*/function () {
|
|
142
|
-
var
|
|
143
|
-
var input, json, writer, invocation, cwd, usageError, projectRoot, skills, repositorySetupErrors, npxCommand, skillsInstallerUnavailable, skillHumanOutput, _loop, _i, _SKILLS, skillResultsByName, _iterator, _step, line, atlasCwd, atlasPluginStatus, _atlasCheck$error, atlasCheck, installResult, verification, data;
|
|
165
|
+
var _ref5 = _asyncToGenerator( /*#__PURE__*/_regeneratorRuntime.mark(function _callee(_ref4) {
|
|
166
|
+
var input, json, writer, invocation, cwd, usageError, projectRoot, skills, agentsMd, repositorySetupErrors, npxCommand, skillsInstallerUnavailable, skillHumanOutput, _loop, _i, _SKILLS, skillResultsByName, _iterator, _step, line, installedSkills, _adsSkillInstalled, atlasCwd, atlasPluginStatus, _atlasCheck$error, atlasCheck, installResult, verification, adsSkillInstalled, nextStep, data;
|
|
144
167
|
return _regeneratorRuntime.wrap(function (_context2) {
|
|
145
168
|
while (1) switch (_context2.prev = _context2.next) {
|
|
146
169
|
case 0:
|
|
147
|
-
input =
|
|
170
|
+
input = _ref4.input, json = _ref4.json, writer = _ref4.writer, invocation = _ref4.invocation, cwd = _ref4.cwd;
|
|
148
171
|
usageError = validateInput(input);
|
|
149
172
|
if (!usageError) {
|
|
150
173
|
_context2.next = 1;
|
|
@@ -167,6 +190,17 @@ export var runInitCommand = /*#__PURE__*/function () {
|
|
|
167
190
|
if (!json) {
|
|
168
191
|
writer.out('– Repository-local skills not installed because the current directory is not in a Git repository');
|
|
169
192
|
}
|
|
193
|
+
agentsMd = {
|
|
194
|
+
status: 'not-written',
|
|
195
|
+
path: AGENTS_FILE_RELATIVE_PATH,
|
|
196
|
+
reason: 'not-in-git-repository'
|
|
197
|
+
};
|
|
198
|
+
if (!json) {
|
|
199
|
+
writeAgentsFileResult({
|
|
200
|
+
result: agentsMd,
|
|
201
|
+
writer: writer
|
|
202
|
+
});
|
|
203
|
+
}
|
|
170
204
|
_context2.next = 7;
|
|
171
205
|
break;
|
|
172
206
|
case 2:
|
|
@@ -305,6 +339,36 @@ export var runInitCommand = /*#__PURE__*/function () {
|
|
|
305
339
|
writer.out(skillHumanOutput.length > 0 ? '– Remaining repository-local skills skipped because @atlassian/skills is unavailable; npx @atlaskit/ads-cli remains available' : '– Repository-local skills skipped because @atlassian/skills is unavailable; npx @atlaskit/ads-cli remains available');
|
|
306
340
|
}
|
|
307
341
|
}
|
|
342
|
+
installedSkills = skills.filter(function (skill) {
|
|
343
|
+
return skill.status !== 'not-installed';
|
|
344
|
+
});
|
|
345
|
+
_adsSkillInstalled = installedSkills.some(function (skill) {
|
|
346
|
+
return skill.name === ADS_SKILL.name;
|
|
347
|
+
});
|
|
348
|
+
if (skillsInstallerUnavailable || _adsSkillInstalled) {
|
|
349
|
+
try {
|
|
350
|
+
agentsMd = updateAgentsFile({
|
|
351
|
+
projectRoot: projectRoot,
|
|
352
|
+
guidance: _adsSkillInstalled ? {
|
|
353
|
+
mode: 'skills-installed',
|
|
354
|
+
skillEntrypoints: installedSkills.map(function (skill) {
|
|
355
|
+
return "".concat(skill.path, "/").concat(SKILL_ENTRYPOINT);
|
|
356
|
+
}),
|
|
357
|
+
getStartedPath: SKILL_GET_STARTED_RELATIVE_PATH
|
|
358
|
+
} : {
|
|
359
|
+
mode: 'public'
|
|
360
|
+
}
|
|
361
|
+
});
|
|
362
|
+
if (!json) {
|
|
363
|
+
writeAgentsFileResult({
|
|
364
|
+
result: agentsMd,
|
|
365
|
+
writer: writer
|
|
366
|
+
});
|
|
367
|
+
}
|
|
368
|
+
} catch (error) {
|
|
369
|
+
repositorySetupErrors.push(error instanceof Error ? error : new Error('Failed to set up the ADS repository guidance.'));
|
|
370
|
+
}
|
|
371
|
+
}
|
|
308
372
|
case 7:
|
|
309
373
|
atlasCwd = projectRoot !== null && projectRoot !== void 0 ? projectRoot : path.resolve(cwd);
|
|
310
374
|
if (!(invocation === CLI_ATLAS_INVOCATION)) {
|
|
@@ -383,18 +447,27 @@ export var runInitCommand = /*#__PURE__*/function () {
|
|
|
383
447
|
return error.message;
|
|
384
448
|
}).join('\n'));
|
|
385
449
|
case 14:
|
|
386
|
-
if (!(skills.length !== SKILLS.length)) {
|
|
450
|
+
if (!(skills.length !== SKILLS.length || !agentsMd)) {
|
|
387
451
|
_context2.next = 15;
|
|
388
452
|
break;
|
|
389
453
|
}
|
|
390
454
|
throw new Error('Failed to determine the ADS repository setup result.');
|
|
391
455
|
case 15:
|
|
456
|
+
adsSkillInstalled = skills.some(function (skill) {
|
|
457
|
+
return skill.name === ADS_SKILL.name && skill.status !== 'not-installed';
|
|
458
|
+
});
|
|
459
|
+
nextStep = projectRoot && adsSkillInstalled ? SKILL_GET_STARTED_RELATIVE_PATH : null;
|
|
460
|
+
if (!json && nextStep) {
|
|
461
|
+
writer.out("\u2192 Next: follow ".concat(nextStep, " to complete repository setup"));
|
|
462
|
+
}
|
|
392
463
|
data = {
|
|
393
464
|
projectRoot: projectRoot !== null && projectRoot !== void 0 ? projectRoot : null,
|
|
394
465
|
skills: skills,
|
|
466
|
+
agentsMd: agentsMd,
|
|
395
467
|
atlas: {
|
|
396
468
|
status: atlasPluginStatus
|
|
397
|
-
}
|
|
469
|
+
},
|
|
470
|
+
nextStep: nextStep
|
|
398
471
|
};
|
|
399
472
|
if (json) {
|
|
400
473
|
writeJsonEnvelope({
|
|
@@ -415,6 +488,6 @@ export var runInitCommand = /*#__PURE__*/function () {
|
|
|
415
488
|
}, _callee);
|
|
416
489
|
}));
|
|
417
490
|
return function runInitCommand(_x) {
|
|
418
|
-
return
|
|
491
|
+
return _ref5.apply(this, arguments);
|
|
419
492
|
};
|
|
420
493
|
}();
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
|
|
2
|
+
import { randomUUID } from 'node:crypto';
|
|
3
|
+
import { lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
4
|
+
import path from 'node:path';
|
|
5
|
+
export var ADS_INIT_START_MARKER = '<!-- ADS:INIT:START -->';
|
|
6
|
+
export var ADS_INIT_END_MARKER = '<!-- ADS:INIT:END -->';
|
|
7
|
+
export var AGENTS_FILE_RELATIVE_PATH = 'AGENTS.md';
|
|
8
|
+
var markerError = function markerError() {
|
|
9
|
+
return new Error("Cannot update ".concat(AGENTS_FILE_RELATIVE_PATH, " because the ").concat(ADS_INIT_START_MARKER, " and ").concat(ADS_INIT_END_MARKER, " markers are malformed or ambiguous. Repair or remove the markers, then run init again."));
|
|
10
|
+
};
|
|
11
|
+
var countOccurrences = function countOccurrences(content, value) {
|
|
12
|
+
return content.split(value).length - 1;
|
|
13
|
+
};
|
|
14
|
+
var isStandaloneMarker = function isStandaloneMarker(content, marker, index) {
|
|
15
|
+
var beforeIsLineBoundary = index === 0 || content[index - 1] === '\n';
|
|
16
|
+
var afterIndex = index + marker.length;
|
|
17
|
+
var afterIsLineBoundary = afterIndex === content.length || content[afterIndex] === '\n' || content[afterIndex] === '\r' && content[afterIndex + 1] === '\n';
|
|
18
|
+
return beforeIsLineBoundary && afterIsLineBoundary;
|
|
19
|
+
};
|
|
20
|
+
var detectLineEnding = function detectLineEnding(content) {
|
|
21
|
+
var _content$match$length, _content$match, _content$replace$matc, _content$replace$matc2;
|
|
22
|
+
var crlfCount = (_content$match$length = (_content$match = content.match(/\r\n/g)) === null || _content$match === void 0 ? void 0 : _content$match.length) !== null && _content$match$length !== void 0 ? _content$match$length : 0;
|
|
23
|
+
var lfOnlyCount = (_content$replace$matc = (_content$replace$matc2 = content.replace(/\r\n/g, '').match(/\n/g)) === null || _content$replace$matc2 === void 0 ? void 0 : _content$replace$matc2.length) !== null && _content$replace$matc !== void 0 ? _content$replace$matc : 0;
|
|
24
|
+
return crlfCount > lfOnlyCount ? '\r\n' : '\n';
|
|
25
|
+
};
|
|
26
|
+
var MCP_GUIDANCE = ['Use `atlas ads` first for structured ADS lookups. If Atlas is unavailable, use `npx @atlaskit/ads-cli` with the same trailing arguments.', '', '### Hosted ADS MCP fallback', '', 'Prefer the CLI first. Configure the hosted ADS MCP server only if this repository does not already configure `ads-mcp` or `atlassian-ads-mcp`. Merge the selected server into the existing configuration without replacing other servers, then reload the agent or IDE.', '', '**Cursor — `.cursor/mcp.json`:**', '', '```json', '{', ' "mcpServers": {', ' "ads-mcp": {', ' "url": "https://mcp.atlassian.com/v1/ads/public/mcp"', ' }', ' }', '}', '```', '', '**VS Code — `.vscode/mcp.json`:**', '', '```json', '{', ' "servers": {', ' "ads-mcp": {', ' "type": "http",', ' "url": "https://mcp.atlassian.com/v1/ads/public/mcp"', ' }', ' }', '}', '```', '', '**Codex — `.codex/config.toml`:**', '', '```toml', '[mcp_servers.atlassian-ads-mcp]', 'url = "https://mcp.atlassian.com/v1/ads/public/mcp"', '```', '', 'Do not add Rovo MCP configuration to the repository.'];
|
|
27
|
+
var renderManagedBlock = function renderManagedBlock(_ref) {
|
|
28
|
+
var lineEnding = _ref.lineEnding,
|
|
29
|
+
guidance = _ref.guidance;
|
|
30
|
+
var skillGuidance = guidance.mode === 'skills-installed' ? ['`init` installed repository-local guidance for setting up and using the Atlassian Design System.', '', 'For Atlassian frontend UI work—including component selection, tokens, icons, styling, accessibility, product content and ADS lint rules—follow:', ''].concat(_toConsumableArray(guidance.skillEntrypoints.map(function (entrypoint) {
|
|
31
|
+
return "- `".concat(entrypoint, "`");
|
|
32
|
+
})), ['', "Before starting frontend UI work, check and complete this repository's ADS setup by following:", '', "`".concat(guidance.getStartedPath, "`"), '', 'Apply only the setup that is missing, and preserve equivalent existing configuration.', '']) : ['`init` did not install repository-local skills. Use the public ADS CLI and optional MCP guidance below.', ''];
|
|
33
|
+
return [ADS_INIT_START_MARKER, '## Getting started with the Atlassian Design System', ''].concat(_toConsumableArray(skillGuidance), MCP_GUIDANCE, ['', "This is a temporary initialization section. It may be removed or rephrased once this repository's ADS setup has been completed.", ADS_INIT_END_MARKER]).join(lineEnding);
|
|
34
|
+
};
|
|
35
|
+
var readTargetStats = function readTargetStats(targetPath) {
|
|
36
|
+
try {
|
|
37
|
+
return lstatSync(targetPath);
|
|
38
|
+
} catch (error) {
|
|
39
|
+
if (error.code === 'ENOENT') {
|
|
40
|
+
return undefined;
|
|
41
|
+
}
|
|
42
|
+
throw error;
|
|
43
|
+
}
|
|
44
|
+
};
|
|
45
|
+
var atomicWriteFile = function atomicWriteFile(_ref2) {
|
|
46
|
+
var targetPath = _ref2.targetPath,
|
|
47
|
+
content = _ref2.content,
|
|
48
|
+
mode = _ref2.mode,
|
|
49
|
+
targetExists = _ref2.targetExists;
|
|
50
|
+
var temporaryPath = path.join(path.dirname(targetPath), ".".concat(path.basename(targetPath), ".").concat(process.pid, ".").concat(randomUUID(), ".tmp"));
|
|
51
|
+
var temporaryFileExists = false;
|
|
52
|
+
try {
|
|
53
|
+
writeFileSync(temporaryPath, content, {
|
|
54
|
+
encoding: 'utf8',
|
|
55
|
+
flag: 'wx',
|
|
56
|
+
mode: mode
|
|
57
|
+
});
|
|
58
|
+
temporaryFileExists = true;
|
|
59
|
+
try {
|
|
60
|
+
renameSync(temporaryPath, targetPath);
|
|
61
|
+
temporaryFileExists = false;
|
|
62
|
+
} catch (error) {
|
|
63
|
+
var code = error.code;
|
|
64
|
+
var canFallbackOnWindows = process.platform === 'win32' && targetExists && (code === 'EACCES' || code === 'EEXIST' || code === 'EPERM');
|
|
65
|
+
if (!canFallbackOnWindows) {
|
|
66
|
+
throw error;
|
|
67
|
+
}
|
|
68
|
+
writeFileSync(targetPath, content, {
|
|
69
|
+
encoding: 'utf8',
|
|
70
|
+
mode: mode
|
|
71
|
+
});
|
|
72
|
+
unlinkSync(temporaryPath);
|
|
73
|
+
temporaryFileExists = false;
|
|
74
|
+
}
|
|
75
|
+
} finally {
|
|
76
|
+
if (temporaryFileExists) {
|
|
77
|
+
try {
|
|
78
|
+
unlinkSync(temporaryPath);
|
|
79
|
+
} catch (_unused) {
|
|
80
|
+
// Preserve the original write failure if temporary cleanup also fails.
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
};
|
|
85
|
+
export var updateAgentsFile = function updateAgentsFile(_ref3) {
|
|
86
|
+
var _stats$mode;
|
|
87
|
+
var projectRoot = _ref3.projectRoot,
|
|
88
|
+
guidance = _ref3.guidance;
|
|
89
|
+
var targetPath = path.join(projectRoot, AGENTS_FILE_RELATIVE_PATH);
|
|
90
|
+
var stats = readTargetStats(targetPath);
|
|
91
|
+
if (stats !== null && stats !== void 0 && stats.isSymbolicLink()) {
|
|
92
|
+
throw new Error("Cannot update ".concat(AGENTS_FILE_RELATIVE_PATH, " because it is a symbolic link."));
|
|
93
|
+
}
|
|
94
|
+
if (stats && !stats.isFile()) {
|
|
95
|
+
throw new Error("Cannot update ".concat(AGENTS_FILE_RELATIVE_PATH, " because it is not a regular file."));
|
|
96
|
+
}
|
|
97
|
+
var existingContent = stats ? readFileSync(targetPath, 'utf8') : '';
|
|
98
|
+
var lineEnding = detectLineEnding(existingContent);
|
|
99
|
+
var managedBlock = renderManagedBlock({
|
|
100
|
+
lineEnding: lineEnding,
|
|
101
|
+
guidance: guidance
|
|
102
|
+
});
|
|
103
|
+
var startCount = countOccurrences(existingContent, ADS_INIT_START_MARKER);
|
|
104
|
+
var endCount = countOccurrences(existingContent, ADS_INIT_END_MARKER);
|
|
105
|
+
var nextContent;
|
|
106
|
+
var status;
|
|
107
|
+
if (!stats) {
|
|
108
|
+
nextContent = "".concat(managedBlock).concat(lineEnding);
|
|
109
|
+
status = 'created';
|
|
110
|
+
} else if (startCount === 0 && endCount === 0) {
|
|
111
|
+
var separator = existingContent.length === 0 ? '' : existingContent.endsWith("".concat(lineEnding).concat(lineEnding)) ? '' : existingContent.endsWith(lineEnding) ? lineEnding : "".concat(lineEnding).concat(lineEnding);
|
|
112
|
+
nextContent = "".concat(existingContent).concat(separator).concat(managedBlock).concat(lineEnding);
|
|
113
|
+
status = 'appended';
|
|
114
|
+
} else {
|
|
115
|
+
if (startCount !== 1 || endCount !== 1) {
|
|
116
|
+
throw markerError();
|
|
117
|
+
}
|
|
118
|
+
var startIndex = existingContent.indexOf(ADS_INIT_START_MARKER);
|
|
119
|
+
var endIndex = existingContent.indexOf(ADS_INIT_END_MARKER);
|
|
120
|
+
if (startIndex > endIndex || !isStandaloneMarker(existingContent, ADS_INIT_START_MARKER, startIndex) || !isStandaloneMarker(existingContent, ADS_INIT_END_MARKER, endIndex)) {
|
|
121
|
+
throw markerError();
|
|
122
|
+
}
|
|
123
|
+
var afterManagedBlock = endIndex + ADS_INIT_END_MARKER.length;
|
|
124
|
+
nextContent = "".concat(existingContent.slice(0, startIndex)).concat(managedBlock).concat(existingContent.slice(afterManagedBlock));
|
|
125
|
+
if (nextContent === existingContent) {
|
|
126
|
+
return {
|
|
127
|
+
status: 'already-current',
|
|
128
|
+
path: AGENTS_FILE_RELATIVE_PATH
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
status = 'updated';
|
|
132
|
+
}
|
|
133
|
+
atomicWriteFile({
|
|
134
|
+
targetPath: targetPath,
|
|
135
|
+
content: nextContent,
|
|
136
|
+
mode: (_stats$mode = stats === null || stats === void 0 ? void 0 : stats.mode) !== null && _stats$mode !== void 0 ? _stats$mode : 438,
|
|
137
|
+
targetExists: stats !== undefined
|
|
138
|
+
});
|
|
139
|
+
return {
|
|
140
|
+
status: status,
|
|
141
|
+
path: AGENTS_FILE_RELATIVE_PATH
|
|
142
|
+
};
|
|
143
|
+
};
|
|
@@ -17,36 +17,21 @@ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
|
|
|
17
17
|
* A component payload as returned by `searchComponentsTool` / `getAllComponentsTool`.
|
|
18
18
|
*/
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
* Collapse whitespace/newlines in a prop description so each prop stays on one readable line.
|
|
22
|
-
*/
|
|
23
|
-
var oneLine = function oneLine(text) {
|
|
24
|
-
return text.replace(/\s+/g, ' ').trim();
|
|
25
|
-
};
|
|
20
|
+
import { humanFormat } from '@atlaskit/cli-output/human-format';
|
|
26
21
|
|
|
27
22
|
/**
|
|
28
|
-
* Render the
|
|
29
|
-
*
|
|
23
|
+
* Render props through the shared terminal table used by Platform CLI. The shared formatter keeps
|
|
24
|
+
* names visually distinct, aligns columns, and bounds long generated type expressions.
|
|
30
25
|
*/
|
|
31
26
|
var formatProps = function formatProps(props) {
|
|
32
|
-
|
|
33
|
-
return ['Props: none'];
|
|
34
|
-
}
|
|
35
|
-
|
|
36
|
-
// Align the type column to the longest prop name for readability.
|
|
37
|
-
var longestName = props.reduce(function (max, prop) {
|
|
27
|
+
return humanFormat.propertyTable(props.map(function (prop) {
|
|
38
28
|
var _prop$name;
|
|
39
|
-
return
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
var header = " ".concat(name, " ").concat(type).trimEnd();
|
|
46
|
-
var description = prop.description ? " ".concat(oneLine(prop.description)) : null;
|
|
47
|
-
return description ? [header, description] : [header];
|
|
48
|
-
});
|
|
49
|
-
return ["Props (".concat(props.length, "):")].concat(_toConsumableArray(rows));
|
|
29
|
+
return {
|
|
30
|
+
name: (_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '(unknown)',
|
|
31
|
+
type: prop.type,
|
|
32
|
+
description: prop.description
|
|
33
|
+
};
|
|
34
|
+
}));
|
|
50
35
|
};
|
|
51
36
|
|
|
52
37
|
/**
|
|
@@ -59,7 +44,7 @@ var formatExamples = function formatExamples(examples) {
|
|
|
59
44
|
}
|
|
60
45
|
var blocks = examples.map(function (example, index) {
|
|
61
46
|
var code = typeof example === 'string' ? example : JSON.stringify(example, null, 2);
|
|
62
|
-
return ["Example ".concat(index + 1
|
|
47
|
+
return [humanFormat.section("Example ".concat(index + 1)), humanFormat.codeBlock(code)].join('\n');
|
|
63
48
|
});
|
|
64
49
|
return ["Examples (".concat(examples.length, "):"), ''].concat(_toConsumableArray(blocks));
|
|
65
50
|
};
|
|
@@ -69,14 +54,22 @@ var formatExamples = function formatExamples(examples) {
|
|
|
69
54
|
* data is not a recognisable component object, so the caller can fall back to generic rendering.
|
|
70
55
|
*/
|
|
71
56
|
export var formatComponent = function formatComponent(data) {
|
|
72
|
-
var _component$props, _component$examples, _component$designSour;
|
|
57
|
+
var _component$usageGuide, _component$props, _component$examples, _component$designSour;
|
|
73
58
|
// `component <name>` reuses component search with limit 1, so `data` is a one-element array.
|
|
74
59
|
var component = Array.isArray(data) ? data[0] : data;
|
|
75
60
|
if (!component || _typeof(component) !== 'object' || typeof component.name !== 'string') {
|
|
76
61
|
return null;
|
|
77
62
|
}
|
|
78
|
-
var header =
|
|
79
|
-
var
|
|
63
|
+
var header = humanFormat.heading(component.name);
|
|
64
|
+
var metadata = humanFormat.metadata([component.status, component.category, component.package]);
|
|
65
|
+
var sections = [header].concat(_toConsumableArray(metadata ? [metadata] : []));
|
|
66
|
+
if (component.description) sections.push('', component.description);
|
|
67
|
+
if ((_component$usageGuide = component.usageGuidelines) !== null && _component$usageGuide !== void 0 && _component$usageGuide.length) {
|
|
68
|
+
sections.push.apply(sections, ['', humanFormat.section('Use it well')].concat(_toConsumableArray(component.usageGuidelines.slice(0, 4).map(function (item) {
|
|
69
|
+
return " ".concat(humanFormat.success('•'), " ").concat(item);
|
|
70
|
+
}))));
|
|
71
|
+
}
|
|
72
|
+
sections.push.apply(sections, [''].concat(_toConsumableArray(formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : []))));
|
|
80
73
|
var examples = formatExamples((_component$examples = component.examples) !== null && _component$examples !== void 0 ? _component$examples : []);
|
|
81
74
|
if (examples.length > 0) {
|
|
82
75
|
sections.push.apply(sections, [''].concat(_toConsumableArray(examples)));
|
|
@@ -86,7 +79,7 @@ export var formatComponent = function formatComponent(data) {
|
|
|
86
79
|
// URL is actually present, so a `designSource` object without a `figmaUrl` doesn't print
|
|
87
80
|
// `Design: undefined`.
|
|
88
81
|
if ((_component$designSour = component.designSource) !== null && _component$designSour !== void 0 && _component$designSour.figmaUrl) {
|
|
89
|
-
sections.push('', "Design: ".concat(component.designSource.figmaUrl));
|
|
82
|
+
sections.push('', "".concat(humanFormat.section('Design:'), " ").concat(humanFormat.action(component.designSource.figmaUrl)));
|
|
90
83
|
}
|
|
91
84
|
return sections.join('\n');
|
|
92
85
|
};
|
|
@@ -9,6 +9,7 @@ import _typeof from "@babel/runtime/helpers/typeof";
|
|
|
9
9
|
* as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
|
|
10
10
|
* rather than raw JSON; `--json` still exposes the full structured payload.
|
|
11
11
|
*/
|
|
12
|
+
import { humanFormat } from '@atlaskit/cli-output/human-format';
|
|
12
13
|
|
|
13
14
|
/**
|
|
14
15
|
* Convert a camelCase / snake_case field key into a human "Title Case" heading,
|
|
@@ -46,7 +47,7 @@ var formatListItem = function formatListItem(item) {
|
|
|
46
47
|
var description = typeof record.description === 'string' ? [" ".concat(oneLine(record.description))] : [];
|
|
47
48
|
var labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
|
|
48
49
|
var codeBlocks = codeKeys.flatMap(function (key) {
|
|
49
|
-
return [].concat(_toConsumableArray(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [
|
|
50
|
+
return [].concat(_toConsumableArray(labelCodeBlocks ? [" ".concat(humanizeKey(key), ":")] : []), [humanFormat.codeBlock(record[key])]);
|
|
50
51
|
});
|
|
51
52
|
var additionalFields = Object.entries(record).flatMap(function (_ref) {
|
|
52
53
|
var _ref2 = _slicedToArray(_ref, 2),
|
|
@@ -10,6 +10,7 @@ import _toConsumableArray from "@babel/runtime/helpers/toConsumableArray";
|
|
|
10
10
|
* left to the caller's generic fallback.
|
|
11
11
|
*/
|
|
12
12
|
|
|
13
|
+
import { humanFormat } from '@atlaskit/cli-output/human-format';
|
|
13
14
|
import { CLI_BIN_NAME } from '../commands/cli-metadata';
|
|
14
15
|
import { compactResults } from './compact-results';
|
|
15
16
|
|
|
@@ -20,19 +21,6 @@ var pluralize = function pluralize(count, noun) {
|
|
|
20
21
|
return "".concat(count, " ").concat(noun).concat(count === 1 ? '' : 's');
|
|
21
22
|
};
|
|
22
23
|
|
|
23
|
-
/**
|
|
24
|
-
* Append a distribution-specific invocation to a compact row's follow-up command.
|
|
25
|
-
*
|
|
26
|
-
* Used for every `search` result, where the natural next step is to view that match in full.
|
|
27
|
-
* `--all` listings omit it because echoing every row's own name would just be noise.
|
|
28
|
-
*/
|
|
29
|
-
var withFollowUp = function withFollowUp(_ref) {
|
|
30
|
-
var line = _ref.line,
|
|
31
|
-
followUp = _ref.followUp,
|
|
32
|
-
invocation = _ref.invocation;
|
|
33
|
-
return followUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(followUp) : line;
|
|
34
|
-
};
|
|
35
|
-
|
|
36
24
|
/**
|
|
37
25
|
* Render one component as a compact line.
|
|
38
26
|
*
|
|
@@ -41,13 +29,13 @@ var withFollowUp = function withFollowUp(_ref) {
|
|
|
41
29
|
* context and a tag would just be noise.
|
|
42
30
|
*/
|
|
43
31
|
var formatComponentLine = function formatComponentLine(component, invocation) {
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
invocation:
|
|
32
|
+
return humanFormat.searchRow({
|
|
33
|
+
name: component.name,
|
|
34
|
+
package: component.package,
|
|
35
|
+
source: 'ads',
|
|
36
|
+
kind: 'component',
|
|
37
|
+
metadata: [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')],
|
|
38
|
+
followUp: component.followUp ? "".concat(invocation, " ").concat(component.followUp) : undefined
|
|
51
39
|
});
|
|
52
40
|
};
|
|
53
41
|
|
|
@@ -55,11 +43,12 @@ var formatComponentLine = function formatComponentLine(component, invocation) {
|
|
|
55
43
|
* Render one token as a compact `name = value` line.
|
|
56
44
|
*/
|
|
57
45
|
var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
46
|
+
return humanFormat.searchRow({
|
|
47
|
+
name: tokenResult.name,
|
|
48
|
+
source: 'ads',
|
|
49
|
+
kind: 'token',
|
|
50
|
+
metadata: tokenResult.exampleValue ? ["= ".concat(tokenResult.exampleValue)] : undefined,
|
|
51
|
+
followUp: tokenResult.followUp ? "".concat(invocation, " ").concat(tokenResult.followUp) : undefined
|
|
63
52
|
});
|
|
64
53
|
};
|
|
65
54
|
|
|
@@ -67,13 +56,13 @@ var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
|
|
|
67
56
|
* Render one icon as a compact line with its import package and short usage note.
|
|
68
57
|
*/
|
|
69
58
|
var formatIconLine = function formatIconLine(iconResult, invocation) {
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
invocation:
|
|
59
|
+
return humanFormat.searchRow({
|
|
60
|
+
name: iconResult.componentName,
|
|
61
|
+
package: iconResult.package,
|
|
62
|
+
source: 'ads',
|
|
63
|
+
kind: 'icon',
|
|
64
|
+
metadata: iconResult.usage ? [iconResult.usage] : undefined,
|
|
65
|
+
followUp: iconResult.followUp ? "".concat(invocation, " ").concat(iconResult.followUp) : undefined
|
|
77
66
|
});
|
|
78
67
|
};
|
|
79
68
|
|
|
@@ -81,12 +70,12 @@ var formatIconLine = function formatIconLine(iconResult, invocation) {
|
|
|
81
70
|
* Render one foundations-document match without dumping its full Markdown body.
|
|
82
71
|
*/
|
|
83
72
|
var formatDocLine = function formatDocLine(doc, invocation) {
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
invocation:
|
|
73
|
+
return humanFormat.searchRow({
|
|
74
|
+
name: doc.title,
|
|
75
|
+
source: 'ads',
|
|
76
|
+
kind: 'docs',
|
|
77
|
+
description: doc.summary,
|
|
78
|
+
followUp: doc.followUp ? "".concat(invocation, " ").concat(doc.followUp) : undefined
|
|
90
79
|
});
|
|
91
80
|
};
|
|
92
81
|
|
|
@@ -97,13 +86,13 @@ var formatDocLine = function formatDocLine(doc, invocation) {
|
|
|
97
86
|
* `showFollowUp` (default `false`) adds a `→ <invocation> <command> <name>` drill-in hint beneath
|
|
98
87
|
* each row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
|
|
99
88
|
*/
|
|
100
|
-
export var formatCompactResults = function formatCompactResults(
|
|
101
|
-
var kind =
|
|
102
|
-
data =
|
|
103
|
-
|
|
104
|
-
showFollowUp =
|
|
105
|
-
|
|
106
|
-
invocation =
|
|
89
|
+
export var formatCompactResults = function formatCompactResults(_ref) {
|
|
90
|
+
var kind = _ref.kind,
|
|
91
|
+
data = _ref.data,
|
|
92
|
+
_ref$showFollowUp = _ref.showFollowUp,
|
|
93
|
+
showFollowUp = _ref$showFollowUp === void 0 ? false : _ref$showFollowUp,
|
|
94
|
+
_ref$invocation = _ref.invocation,
|
|
95
|
+
invocation = _ref$invocation === void 0 ? CLI_BIN_NAME : _ref$invocation;
|
|
107
96
|
var compact = compactResults({
|
|
108
97
|
kind: kind,
|
|
109
98
|
data: data,
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
export declare const ADS_INIT_START_MARKER = "<!-- ADS:INIT:START -->";
|
|
2
|
+
export declare const ADS_INIT_END_MARKER = "<!-- ADS:INIT:END -->";
|
|
3
|
+
export declare const AGENTS_FILE_RELATIVE_PATH = "AGENTS.md";
|
|
4
|
+
export type AgentsFileResult = {
|
|
5
|
+
status: 'created' | 'appended' | 'updated' | 'already-current';
|
|
6
|
+
path: typeof AGENTS_FILE_RELATIVE_PATH;
|
|
7
|
+
} | {
|
|
8
|
+
status: 'not-written';
|
|
9
|
+
path: typeof AGENTS_FILE_RELATIVE_PATH;
|
|
10
|
+
reason: 'not-in-git-repository';
|
|
11
|
+
};
|
|
12
|
+
export type AgentsGuidance = {
|
|
13
|
+
mode: 'skills-installed';
|
|
14
|
+
skillEntrypoints: string[];
|
|
15
|
+
getStartedPath: string;
|
|
16
|
+
} | {
|
|
17
|
+
mode: 'public';
|
|
18
|
+
};
|
|
19
|
+
export declare const updateAgentsFile: ({ projectRoot, guidance, }: {
|
|
20
|
+
projectRoot: string;
|
|
21
|
+
guidance: AgentsGuidance;
|
|
22
|
+
}) => AgentsFileResult;
|
|
@@ -1,11 +1,3 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Human-readable renderer for a single "doc object" payload — the shape returned by the
|
|
3
|
-
* accessibility (`docs a11y`) and migration (`docs migration`) tools.
|
|
4
|
-
*
|
|
5
|
-
* These tools return a structured object (title, description, and several labelled lists such
|
|
6
|
-
* as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
|
|
7
|
-
* rather than raw JSON; `--json` still exposes the full structured payload.
|
|
8
|
-
*/
|
|
9
1
|
/**
|
|
10
2
|
* Render a doc-object payload as readable text. Handles both the full guide shape (a11y guidance,
|
|
11
3
|
* migration guide — keyed by `title`) and the topic-index shape the a11y tool returns when no
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atlaskit/ads-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
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",
|
|
@@ -32,6 +32,7 @@
|
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
34
|
"@atlaskit/ads-mcp": "^1.10.0",
|
|
35
|
+
"@atlaskit/cli-output": "^0.1.0",
|
|
35
36
|
"@babel/runtime": "^7.0.0",
|
|
36
37
|
"chalk": "^4.1.2"
|
|
37
38
|
},
|