@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
|
@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
|
|
|
6
6
|
});
|
|
7
7
|
exports.formatCompactResults = void 0;
|
|
8
8
|
var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
|
|
9
|
+
var _humanFormat = require("@atlaskit/cli-output/human-format");
|
|
9
10
|
var _cliMetadata = require("../commands/cli-metadata");
|
|
10
11
|
var _compactResults = require("./compact-results");
|
|
11
12
|
/**
|
|
@@ -26,19 +27,6 @@ var pluralize = function pluralize(count, noun) {
|
|
|
26
27
|
return "".concat(count, " ").concat(noun).concat(count === 1 ? '' : 's');
|
|
27
28
|
};
|
|
28
29
|
|
|
29
|
-
/**
|
|
30
|
-
* Append a distribution-specific invocation to a compact row's follow-up command.
|
|
31
|
-
*
|
|
32
|
-
* Used for every `search` result, where the natural next step is to view that match in full.
|
|
33
|
-
* `--all` listings omit it because echoing every row's own name would just be noise.
|
|
34
|
-
*/
|
|
35
|
-
var withFollowUp = function withFollowUp(_ref) {
|
|
36
|
-
var line = _ref.line,
|
|
37
|
-
followUp = _ref.followUp,
|
|
38
|
-
invocation = _ref.invocation;
|
|
39
|
-
return followUp ? "".concat(line, "\n \u2192 ").concat(invocation, " ").concat(followUp) : line;
|
|
40
|
-
};
|
|
41
|
-
|
|
42
30
|
/**
|
|
43
31
|
* Render one component as a compact line.
|
|
44
32
|
*
|
|
@@ -47,13 +35,13 @@ var withFollowUp = function withFollowUp(_ref) {
|
|
|
47
35
|
* context and a tag would just be noise.
|
|
48
36
|
*/
|
|
49
37
|
var formatComponentLine = function formatComponentLine(component, invocation) {
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
invocation:
|
|
38
|
+
return _humanFormat.humanFormat.searchRow({
|
|
39
|
+
name: component.name,
|
|
40
|
+
package: component.package,
|
|
41
|
+
source: 'ads',
|
|
42
|
+
kind: 'component',
|
|
43
|
+
metadata: [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')],
|
|
44
|
+
followUp: component.followUp ? "".concat(invocation, " ").concat(component.followUp) : undefined
|
|
57
45
|
});
|
|
58
46
|
};
|
|
59
47
|
|
|
@@ -61,11 +49,12 @@ var formatComponentLine = function formatComponentLine(component, invocation) {
|
|
|
61
49
|
* Render one token as a compact `name = value` line.
|
|
62
50
|
*/
|
|
63
51
|
var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
52
|
+
return _humanFormat.humanFormat.searchRow({
|
|
53
|
+
name: tokenResult.name,
|
|
54
|
+
source: 'ads',
|
|
55
|
+
kind: 'token',
|
|
56
|
+
metadata: tokenResult.exampleValue ? ["= ".concat(tokenResult.exampleValue)] : undefined,
|
|
57
|
+
followUp: tokenResult.followUp ? "".concat(invocation, " ").concat(tokenResult.followUp) : undefined
|
|
69
58
|
});
|
|
70
59
|
};
|
|
71
60
|
|
|
@@ -73,13 +62,13 @@ var formatTokenLine = function formatTokenLine(tokenResult, invocation) {
|
|
|
73
62
|
* Render one icon as a compact line with its import package and short usage note.
|
|
74
63
|
*/
|
|
75
64
|
var formatIconLine = function formatIconLine(iconResult, invocation) {
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
invocation:
|
|
65
|
+
return _humanFormat.humanFormat.searchRow({
|
|
66
|
+
name: iconResult.componentName,
|
|
67
|
+
package: iconResult.package,
|
|
68
|
+
source: 'ads',
|
|
69
|
+
kind: 'icon',
|
|
70
|
+
metadata: iconResult.usage ? [iconResult.usage] : undefined,
|
|
71
|
+
followUp: iconResult.followUp ? "".concat(invocation, " ").concat(iconResult.followUp) : undefined
|
|
83
72
|
});
|
|
84
73
|
};
|
|
85
74
|
|
|
@@ -87,12 +76,12 @@ var formatIconLine = function formatIconLine(iconResult, invocation) {
|
|
|
87
76
|
* Render one foundations-document match without dumping its full Markdown body.
|
|
88
77
|
*/
|
|
89
78
|
var formatDocLine = function formatDocLine(doc, invocation) {
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
invocation:
|
|
79
|
+
return _humanFormat.humanFormat.searchRow({
|
|
80
|
+
name: doc.title,
|
|
81
|
+
source: 'ads',
|
|
82
|
+
kind: 'docs',
|
|
83
|
+
description: doc.summary,
|
|
84
|
+
followUp: doc.followUp ? "".concat(invocation, " ").concat(doc.followUp) : undefined
|
|
96
85
|
});
|
|
97
86
|
};
|
|
98
87
|
|
|
@@ -103,13 +92,13 @@ var formatDocLine = function formatDocLine(doc, invocation) {
|
|
|
103
92
|
* `showFollowUp` (default `false`) adds a `→ <invocation> <command> <name>` drill-in hint beneath
|
|
104
93
|
* each row. Search enables it for both grouped and `--type` output; `--all` listings leave it off.
|
|
105
94
|
*/
|
|
106
|
-
var formatCompactResults = exports.formatCompactResults = function formatCompactResults(
|
|
107
|
-
var kind =
|
|
108
|
-
data =
|
|
109
|
-
|
|
110
|
-
showFollowUp =
|
|
111
|
-
|
|
112
|
-
invocation =
|
|
95
|
+
var formatCompactResults = exports.formatCompactResults = function formatCompactResults(_ref) {
|
|
96
|
+
var kind = _ref.kind,
|
|
97
|
+
data = _ref.data,
|
|
98
|
+
_ref$showFollowUp = _ref.showFollowUp,
|
|
99
|
+
showFollowUp = _ref$showFollowUp === void 0 ? false : _ref$showFollowUp,
|
|
100
|
+
_ref$invocation = _ref.invocation,
|
|
101
|
+
invocation = _ref$invocation === void 0 ? _cliMetadata.CLI_BIN_NAME : _ref$invocation;
|
|
113
102
|
var compact = (0, _compactResults.compactResults)({
|
|
114
103
|
kind: kind,
|
|
115
104
|
data: data,
|
|
@@ -7,6 +7,7 @@ import { writeHumanError } from '../output/write-human-error';
|
|
|
7
7
|
import { writeJsonEnvelope } from '../output/write-json-envelope';
|
|
8
8
|
import { ExitCode } from '../types';
|
|
9
9
|
import { CLI_ATLAS_INVOCATION } from './cli-metadata';
|
|
10
|
+
import { AGENTS_FILE_RELATIVE_PATH, updateAgentsFile } from './update-agents-file';
|
|
10
11
|
const SKILL_ENTRYPOINT = 'SKILL.md';
|
|
11
12
|
const SKILLS = [{
|
|
12
13
|
name: 'atlassian-design-system',
|
|
@@ -24,6 +25,8 @@ const SKILLS = [{
|
|
|
24
25
|
relativePath: '.agents/skills/a11y-foundation',
|
|
25
26
|
requiredFiles: [SKILL_ENTRYPOINT]
|
|
26
27
|
}];
|
|
28
|
+
const ADS_SKILL = SKILLS[0];
|
|
29
|
+
const SKILL_GET_STARTED_RELATIVE_PATH = `${ADS_SKILL.relativePath}/references/get-started.md`;
|
|
27
30
|
const GIT_MARKER = '.git';
|
|
28
31
|
const SKILLS_INSTALLER_PACKAGE = '@atlassian/skills';
|
|
29
32
|
const SKILLS_INSTALLER_UNAVAILABLE_REASON = 'skills-installer-unavailable';
|
|
@@ -126,6 +129,27 @@ const validateInput = input => {
|
|
|
126
129
|
}
|
|
127
130
|
return undefined;
|
|
128
131
|
};
|
|
132
|
+
const writeAgentsFileResult = ({
|
|
133
|
+
result,
|
|
134
|
+
writer
|
|
135
|
+
}) => {
|
|
136
|
+
switch (result.status) {
|
|
137
|
+
case 'created':
|
|
138
|
+
writer.out(`✓ Created ${AGENTS_FILE_RELATIVE_PATH} with ADS setup guidance`);
|
|
139
|
+
return;
|
|
140
|
+
case 'appended':
|
|
141
|
+
writer.out(`✓ Appended ADS setup guidance to ${AGENTS_FILE_RELATIVE_PATH}`);
|
|
142
|
+
return;
|
|
143
|
+
case 'updated':
|
|
144
|
+
writer.out(`✓ Updated ADS setup guidance in ${AGENTS_FILE_RELATIVE_PATH}`);
|
|
145
|
+
return;
|
|
146
|
+
case 'already-current':
|
|
147
|
+
writer.out(`✓ ADS setup guidance already current in ${AGENTS_FILE_RELATIVE_PATH}`);
|
|
148
|
+
return;
|
|
149
|
+
case 'not-written':
|
|
150
|
+
writer.out(`– ${AGENTS_FILE_RELATIVE_PATH} not updated because the current directory is not in a Git repository`);
|
|
151
|
+
}
|
|
152
|
+
};
|
|
129
153
|
export const runInitCommand = async ({
|
|
130
154
|
input,
|
|
131
155
|
json,
|
|
@@ -143,12 +167,24 @@ export const runInitCommand = async ({
|
|
|
143
167
|
}
|
|
144
168
|
const projectRoot = findRepositoryRoot(cwd);
|
|
145
169
|
const skills = [];
|
|
170
|
+
let agentsMd;
|
|
146
171
|
const repositorySetupErrors = [];
|
|
147
172
|
if (!projectRoot) {
|
|
148
173
|
skills.push(...createNotInstalledSkillResults('not-in-git-repository'));
|
|
149
174
|
if (!json) {
|
|
150
175
|
writer.out('– Repository-local skills not installed because the current directory is not in a Git repository');
|
|
151
176
|
}
|
|
177
|
+
agentsMd = {
|
|
178
|
+
status: 'not-written',
|
|
179
|
+
path: AGENTS_FILE_RELATIVE_PATH,
|
|
180
|
+
reason: 'not-in-git-repository'
|
|
181
|
+
};
|
|
182
|
+
if (!json) {
|
|
183
|
+
writeAgentsFileResult({
|
|
184
|
+
result: agentsMd,
|
|
185
|
+
writer
|
|
186
|
+
});
|
|
187
|
+
}
|
|
152
188
|
} else {
|
|
153
189
|
const npxCommand = process.platform === 'win32' ? 'npx.cmd' : 'npx';
|
|
154
190
|
let skillsInstallerUnavailable = false;
|
|
@@ -224,6 +260,30 @@ export const runInitCommand = async ({
|
|
|
224
260
|
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');
|
|
225
261
|
}
|
|
226
262
|
}
|
|
263
|
+
const installedSkills = skills.filter(skill => skill.status !== 'not-installed');
|
|
264
|
+
const adsSkillInstalled = installedSkills.some(skill => skill.name === ADS_SKILL.name);
|
|
265
|
+
if (skillsInstallerUnavailable || adsSkillInstalled) {
|
|
266
|
+
try {
|
|
267
|
+
agentsMd = updateAgentsFile({
|
|
268
|
+
projectRoot,
|
|
269
|
+
guidance: adsSkillInstalled ? {
|
|
270
|
+
mode: 'skills-installed',
|
|
271
|
+
skillEntrypoints: installedSkills.map(skill => `${skill.path}/${SKILL_ENTRYPOINT}`),
|
|
272
|
+
getStartedPath: SKILL_GET_STARTED_RELATIVE_PATH
|
|
273
|
+
} : {
|
|
274
|
+
mode: 'public'
|
|
275
|
+
}
|
|
276
|
+
});
|
|
277
|
+
if (!json) {
|
|
278
|
+
writeAgentsFileResult({
|
|
279
|
+
result: agentsMd,
|
|
280
|
+
writer
|
|
281
|
+
});
|
|
282
|
+
}
|
|
283
|
+
} catch (error) {
|
|
284
|
+
repositorySetupErrors.push(error instanceof Error ? error : new Error('Failed to set up the ADS repository guidance.'));
|
|
285
|
+
}
|
|
286
|
+
}
|
|
227
287
|
}
|
|
228
288
|
const atlasCwd = projectRoot !== null && projectRoot !== void 0 ? projectRoot : path.resolve(cwd);
|
|
229
289
|
let atlasPluginStatus;
|
|
@@ -278,15 +338,23 @@ export const runInitCommand = async ({
|
|
|
278
338
|
if (repositorySetupErrors.length > 0) {
|
|
279
339
|
throw new Error(repositorySetupErrors.map(error => error.message).join('\n'));
|
|
280
340
|
}
|
|
281
|
-
|
|
341
|
+
// Keep the successful-path invariant explicit so future control-flow changes cannot return a partial result.
|
|
342
|
+
if (skills.length !== SKILLS.length || !agentsMd) {
|
|
282
343
|
throw new Error('Failed to determine the ADS repository setup result.');
|
|
283
344
|
}
|
|
345
|
+
const adsSkillInstalled = skills.some(skill => skill.name === ADS_SKILL.name && skill.status !== 'not-installed');
|
|
346
|
+
const nextStep = projectRoot && adsSkillInstalled ? SKILL_GET_STARTED_RELATIVE_PATH : null;
|
|
347
|
+
if (!json && nextStep) {
|
|
348
|
+
writer.out(`→ Next: follow ${nextStep} to complete repository setup`);
|
|
349
|
+
}
|
|
284
350
|
const data = {
|
|
285
351
|
projectRoot: projectRoot !== null && projectRoot !== void 0 ? projectRoot : null,
|
|
286
352
|
skills,
|
|
353
|
+
agentsMd,
|
|
287
354
|
atlas: {
|
|
288
355
|
status: atlasPluginStatus
|
|
289
|
-
}
|
|
356
|
+
},
|
|
357
|
+
nextStep
|
|
290
358
|
};
|
|
291
359
|
if (json) {
|
|
292
360
|
writeJsonEnvelope({
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
import { randomUUID } from 'node:crypto';
|
|
2
|
+
import { lstatSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
|
|
3
|
+
import path from 'node:path';
|
|
4
|
+
export const ADS_INIT_START_MARKER = '<!-- ADS:INIT:START -->';
|
|
5
|
+
export const ADS_INIT_END_MARKER = '<!-- ADS:INIT:END -->';
|
|
6
|
+
export const AGENTS_FILE_RELATIVE_PATH = 'AGENTS.md';
|
|
7
|
+
const markerError = () => new Error(`Cannot update ${AGENTS_FILE_RELATIVE_PATH} because the ${ADS_INIT_START_MARKER} and ${ADS_INIT_END_MARKER} markers are malformed or ambiguous. Repair or remove the markers, then run init again.`);
|
|
8
|
+
const countOccurrences = (content, value) => content.split(value).length - 1;
|
|
9
|
+
const isStandaloneMarker = (content, marker, index) => {
|
|
10
|
+
const beforeIsLineBoundary = index === 0 || content[index - 1] === '\n';
|
|
11
|
+
const afterIndex = index + marker.length;
|
|
12
|
+
const afterIsLineBoundary = afterIndex === content.length || content[afterIndex] === '\n' || content[afterIndex] === '\r' && content[afterIndex + 1] === '\n';
|
|
13
|
+
return beforeIsLineBoundary && afterIsLineBoundary;
|
|
14
|
+
};
|
|
15
|
+
const detectLineEnding = content => {
|
|
16
|
+
var _content$match$length, _content$match, _content$replace$matc, _content$replace$matc2;
|
|
17
|
+
const 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;
|
|
18
|
+
const 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;
|
|
19
|
+
return crlfCount > lfOnlyCount ? '\r\n' : '\n';
|
|
20
|
+
};
|
|
21
|
+
const 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.'];
|
|
22
|
+
const renderManagedBlock = ({
|
|
23
|
+
lineEnding,
|
|
24
|
+
guidance
|
|
25
|
+
}) => {
|
|
26
|
+
const 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:', '', ...guidance.skillEntrypoints.map(entrypoint => `- \`${entrypoint}\``), '', "Before starting frontend UI work, check and complete this repository's ADS setup by following:", '', `\`${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.', ''];
|
|
27
|
+
return [ADS_INIT_START_MARKER, '## Getting started with the Atlassian Design System', '', ...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);
|
|
28
|
+
};
|
|
29
|
+
const readTargetStats = targetPath => {
|
|
30
|
+
try {
|
|
31
|
+
return lstatSync(targetPath);
|
|
32
|
+
} catch (error) {
|
|
33
|
+
if (error.code === 'ENOENT') {
|
|
34
|
+
return undefined;
|
|
35
|
+
}
|
|
36
|
+
throw error;
|
|
37
|
+
}
|
|
38
|
+
};
|
|
39
|
+
const atomicWriteFile = ({
|
|
40
|
+
targetPath,
|
|
41
|
+
content,
|
|
42
|
+
mode,
|
|
43
|
+
targetExists
|
|
44
|
+
}) => {
|
|
45
|
+
const temporaryPath = path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`);
|
|
46
|
+
let temporaryFileExists = false;
|
|
47
|
+
try {
|
|
48
|
+
writeFileSync(temporaryPath, content, {
|
|
49
|
+
encoding: 'utf8',
|
|
50
|
+
flag: 'wx',
|
|
51
|
+
mode
|
|
52
|
+
});
|
|
53
|
+
temporaryFileExists = true;
|
|
54
|
+
try {
|
|
55
|
+
renameSync(temporaryPath, targetPath);
|
|
56
|
+
temporaryFileExists = false;
|
|
57
|
+
} catch (error) {
|
|
58
|
+
const code = error.code;
|
|
59
|
+
const canFallbackOnWindows = process.platform === 'win32' && targetExists && (code === 'EACCES' || code === 'EEXIST' || code === 'EPERM');
|
|
60
|
+
if (!canFallbackOnWindows) {
|
|
61
|
+
throw error;
|
|
62
|
+
}
|
|
63
|
+
writeFileSync(targetPath, content, {
|
|
64
|
+
encoding: 'utf8',
|
|
65
|
+
mode
|
|
66
|
+
});
|
|
67
|
+
unlinkSync(temporaryPath);
|
|
68
|
+
temporaryFileExists = false;
|
|
69
|
+
}
|
|
70
|
+
} finally {
|
|
71
|
+
if (temporaryFileExists) {
|
|
72
|
+
try {
|
|
73
|
+
unlinkSync(temporaryPath);
|
|
74
|
+
} catch {
|
|
75
|
+
// Preserve the original write failure if temporary cleanup also fails.
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
};
|
|
80
|
+
export const updateAgentsFile = ({
|
|
81
|
+
projectRoot,
|
|
82
|
+
guidance
|
|
83
|
+
}) => {
|
|
84
|
+
var _stats$mode;
|
|
85
|
+
const targetPath = path.join(projectRoot, AGENTS_FILE_RELATIVE_PATH);
|
|
86
|
+
const stats = readTargetStats(targetPath);
|
|
87
|
+
if (stats !== null && stats !== void 0 && stats.isSymbolicLink()) {
|
|
88
|
+
throw new Error(`Cannot update ${AGENTS_FILE_RELATIVE_PATH} because it is a symbolic link.`);
|
|
89
|
+
}
|
|
90
|
+
if (stats && !stats.isFile()) {
|
|
91
|
+
throw new Error(`Cannot update ${AGENTS_FILE_RELATIVE_PATH} because it is not a regular file.`);
|
|
92
|
+
}
|
|
93
|
+
const existingContent = stats ? readFileSync(targetPath, 'utf8') : '';
|
|
94
|
+
const lineEnding = detectLineEnding(existingContent);
|
|
95
|
+
const managedBlock = renderManagedBlock({
|
|
96
|
+
lineEnding,
|
|
97
|
+
guidance
|
|
98
|
+
});
|
|
99
|
+
const startCount = countOccurrences(existingContent, ADS_INIT_START_MARKER);
|
|
100
|
+
const endCount = countOccurrences(existingContent, ADS_INIT_END_MARKER);
|
|
101
|
+
let nextContent;
|
|
102
|
+
let status;
|
|
103
|
+
if (!stats) {
|
|
104
|
+
nextContent = `${managedBlock}${lineEnding}`;
|
|
105
|
+
status = 'created';
|
|
106
|
+
} else if (startCount === 0 && endCount === 0) {
|
|
107
|
+
const separator = existingContent.length === 0 ? '' : existingContent.endsWith(`${lineEnding}${lineEnding}`) ? '' : existingContent.endsWith(lineEnding) ? lineEnding : `${lineEnding}${lineEnding}`;
|
|
108
|
+
nextContent = `${existingContent}${separator}${managedBlock}${lineEnding}`;
|
|
109
|
+
status = 'appended';
|
|
110
|
+
} else {
|
|
111
|
+
if (startCount !== 1 || endCount !== 1) {
|
|
112
|
+
throw markerError();
|
|
113
|
+
}
|
|
114
|
+
const startIndex = existingContent.indexOf(ADS_INIT_START_MARKER);
|
|
115
|
+
const endIndex = existingContent.indexOf(ADS_INIT_END_MARKER);
|
|
116
|
+
if (startIndex > endIndex || !isStandaloneMarker(existingContent, ADS_INIT_START_MARKER, startIndex) || !isStandaloneMarker(existingContent, ADS_INIT_END_MARKER, endIndex)) {
|
|
117
|
+
throw markerError();
|
|
118
|
+
}
|
|
119
|
+
const afterManagedBlock = endIndex + ADS_INIT_END_MARKER.length;
|
|
120
|
+
nextContent = `${existingContent.slice(0, startIndex)}${managedBlock}${existingContent.slice(afterManagedBlock)}`;
|
|
121
|
+
if (nextContent === existingContent) {
|
|
122
|
+
return {
|
|
123
|
+
status: 'already-current',
|
|
124
|
+
path: AGENTS_FILE_RELATIVE_PATH
|
|
125
|
+
};
|
|
126
|
+
}
|
|
127
|
+
status = 'updated';
|
|
128
|
+
}
|
|
129
|
+
atomicWriteFile({
|
|
130
|
+
targetPath,
|
|
131
|
+
content: nextContent,
|
|
132
|
+
mode: (_stats$mode = stats === null || stats === void 0 ? void 0 : stats.mode) !== null && _stats$mode !== void 0 ? _stats$mode : 0o666,
|
|
133
|
+
targetExists: stats !== undefined
|
|
134
|
+
});
|
|
135
|
+
return {
|
|
136
|
+
status,
|
|
137
|
+
path: AGENTS_FILE_RELATIVE_PATH
|
|
138
|
+
};
|
|
139
|
+
};
|
|
@@ -15,35 +15,20 @@
|
|
|
15
15
|
* A component payload as returned by `searchComponentsTool` / `getAllComponentsTool`.
|
|
16
16
|
*/
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
* Collapse whitespace/newlines in a prop description so each prop stays on one readable line.
|
|
20
|
-
*/
|
|
21
|
-
const oneLine = text => text.replace(/\s+/g, ' ').trim();
|
|
18
|
+
import { humanFormat } from '@atlaskit/cli-output/human-format';
|
|
22
19
|
|
|
23
20
|
/**
|
|
24
|
-
* Render the
|
|
25
|
-
*
|
|
21
|
+
* Render props through the shared terminal table used by Platform CLI. The shared formatter keeps
|
|
22
|
+
* names visually distinct, aligns columns, and bounds long generated type expressions.
|
|
26
23
|
*/
|
|
27
|
-
const formatProps = props => {
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
return Math.max(max, ((_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '').length);
|
|
36
|
-
}, 0);
|
|
37
|
-
const rows = props.flatMap(prop => {
|
|
38
|
-
var _prop$name2;
|
|
39
|
-
const name = ((_prop$name2 = prop.name) !== null && _prop$name2 !== void 0 ? _prop$name2 : '(unknown)').padEnd(longestName);
|
|
40
|
-
const type = prop.type ? oneLine(prop.type) : '';
|
|
41
|
-
const header = ` ${name} ${type}`.trimEnd();
|
|
42
|
-
const description = prop.description ? ` ${oneLine(prop.description)}` : null;
|
|
43
|
-
return description ? [header, description] : [header];
|
|
44
|
-
});
|
|
45
|
-
return [`Props (${props.length}):`, ...rows];
|
|
46
|
-
};
|
|
24
|
+
const formatProps = props => humanFormat.propertyTable(props.map(prop => {
|
|
25
|
+
var _prop$name;
|
|
26
|
+
return {
|
|
27
|
+
name: (_prop$name = prop.name) !== null && _prop$name !== void 0 ? _prop$name : '(unknown)',
|
|
28
|
+
type: prop.type,
|
|
29
|
+
description: prop.description
|
|
30
|
+
};
|
|
31
|
+
}));
|
|
47
32
|
|
|
48
33
|
/**
|
|
49
34
|
* Render the examples section. Each example is a code snippet string; they are printed verbatim
|
|
@@ -55,7 +40,7 @@ const formatExamples = examples => {
|
|
|
55
40
|
}
|
|
56
41
|
const blocks = examples.map((example, index) => {
|
|
57
42
|
const code = typeof example === 'string' ? example : JSON.stringify(example, null, 2);
|
|
58
|
-
return [`Example ${index + 1}
|
|
43
|
+
return [humanFormat.section(`Example ${index + 1}`), humanFormat.codeBlock(code)].join('\n');
|
|
59
44
|
});
|
|
60
45
|
return [`Examples (${examples.length}):`, '', ...blocks];
|
|
61
46
|
};
|
|
@@ -65,14 +50,20 @@ const formatExamples = examples => {
|
|
|
65
50
|
* data is not a recognisable component object, so the caller can fall back to generic rendering.
|
|
66
51
|
*/
|
|
67
52
|
export const formatComponent = data => {
|
|
68
|
-
var _component$props, _component$examples, _component$designSour;
|
|
53
|
+
var _component$usageGuide, _component$props, _component$examples, _component$designSour;
|
|
69
54
|
// `component <name>` reuses component search with limit 1, so `data` is a one-element array.
|
|
70
55
|
const component = Array.isArray(data) ? data[0] : data;
|
|
71
56
|
if (!component || typeof component !== 'object' || typeof component.name !== 'string') {
|
|
72
57
|
return null;
|
|
73
58
|
}
|
|
74
|
-
const header =
|
|
75
|
-
const
|
|
59
|
+
const header = humanFormat.heading(component.name);
|
|
60
|
+
const metadata = humanFormat.metadata([component.status, component.category, component.package]);
|
|
61
|
+
const sections = [header, ...(metadata ? [metadata] : [])];
|
|
62
|
+
if (component.description) sections.push('', component.description);
|
|
63
|
+
if ((_component$usageGuide = component.usageGuidelines) !== null && _component$usageGuide !== void 0 && _component$usageGuide.length) {
|
|
64
|
+
sections.push('', humanFormat.section('Use it well'), ...component.usageGuidelines.slice(0, 4).map(item => ` ${humanFormat.success('•')} ${item}`));
|
|
65
|
+
}
|
|
66
|
+
sections.push('', ...formatProps((_component$props = component.props) !== null && _component$props !== void 0 ? _component$props : []));
|
|
76
67
|
const examples = formatExamples((_component$examples = component.examples) !== null && _component$examples !== void 0 ? _component$examples : []);
|
|
77
68
|
if (examples.length > 0) {
|
|
78
69
|
sections.push('', ...examples);
|
|
@@ -82,7 +73,7 @@ export const formatComponent = data => {
|
|
|
82
73
|
// URL is actually present, so a `designSource` object without a `figmaUrl` doesn't print
|
|
83
74
|
// `Design: undefined`.
|
|
84
75
|
if ((_component$designSour = component.designSource) !== null && _component$designSour !== void 0 && _component$designSour.figmaUrl) {
|
|
85
|
-
sections.push('',
|
|
76
|
+
sections.push('', `${humanFormat.section('Design:')} ${humanFormat.action(component.designSource.figmaUrl)}`);
|
|
86
77
|
}
|
|
87
78
|
return sections.join('\n');
|
|
88
79
|
};
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
* as `guidelines`, `bestPractices`, `nextSteps`). The default output prints this as readable text
|
|
7
7
|
* rather than raw JSON; `--json` still exposes the full structured payload.
|
|
8
8
|
*/
|
|
9
|
+
import { humanFormat } from '@atlaskit/cli-output/human-format';
|
|
9
10
|
|
|
10
11
|
/**
|
|
11
12
|
* Convert a camelCase / snake_case field key into a human "Title Case" heading,
|
|
@@ -34,7 +35,7 @@ const formatListItem = item => {
|
|
|
34
35
|
if (title && codeKeys.length > 0) {
|
|
35
36
|
const description = typeof record.description === 'string' ? [` ${oneLine(record.description)}`] : [];
|
|
36
37
|
const labelCodeBlocks = codeKeys.length > 1 || codeKeys[0] !== 'code';
|
|
37
|
-
const codeBlocks = codeKeys.flatMap(key => [...(labelCodeBlocks ? [` ${humanizeKey(key)}:`] : []),
|
|
38
|
+
const codeBlocks = codeKeys.flatMap(key => [...(labelCodeBlocks ? [` ${humanizeKey(key)}:`] : []), humanFormat.codeBlock(record[key])]);
|
|
38
39
|
const additionalFields = Object.entries(record).flatMap(([key, value]) => {
|
|
39
40
|
if (['title', 'description', ...codeKeys].includes(key) || value === null || value === undefined) {
|
|
40
41
|
return [];
|
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
* left to the caller's generic fallback.
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
|
+
import { humanFormat } from '@atlaskit/cli-output/human-format';
|
|
12
13
|
import { CLI_BIN_NAME } from '../commands/cli-metadata';
|
|
13
14
|
import { compactResults } from './compact-results';
|
|
14
15
|
|
|
@@ -17,18 +18,6 @@ import { compactResults } from './compact-results';
|
|
|
17
18
|
*/
|
|
18
19
|
const pluralize = (count, noun) => `${count} ${noun}${count === 1 ? '' : 's'}`;
|
|
19
20
|
|
|
20
|
-
/**
|
|
21
|
-
* Append a distribution-specific invocation to a compact row's follow-up command.
|
|
22
|
-
*
|
|
23
|
-
* Used for every `search` result, where the natural next step is to view that match in full.
|
|
24
|
-
* `--all` listings omit it because echoing every row's own name would just be noise.
|
|
25
|
-
*/
|
|
26
|
-
const withFollowUp = ({
|
|
27
|
-
line,
|
|
28
|
-
followUp,
|
|
29
|
-
invocation
|
|
30
|
-
}) => followUp ? `${line}\n → ${invocation} ${followUp}` : line;
|
|
31
|
-
|
|
32
21
|
/**
|
|
33
22
|
* Render one component as a compact line.
|
|
34
23
|
*
|
|
@@ -37,13 +26,13 @@ const withFollowUp = ({
|
|
|
37
26
|
* context and a tag would just be noise.
|
|
38
27
|
*/
|
|
39
28
|
const formatComponentLine = (component, invocation) => {
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
invocation
|
|
29
|
+
return humanFormat.searchRow({
|
|
30
|
+
name: component.name,
|
|
31
|
+
package: component.package,
|
|
32
|
+
source: 'ads',
|
|
33
|
+
kind: 'component',
|
|
34
|
+
metadata: [pluralize(component.propCount, 'prop'), pluralize(component.exampleCount, 'example')],
|
|
35
|
+
followUp: component.followUp ? `${invocation} ${component.followUp}` : undefined
|
|
47
36
|
});
|
|
48
37
|
};
|
|
49
38
|
|
|
@@ -51,11 +40,12 @@ const formatComponentLine = (component, invocation) => {
|
|
|
51
40
|
* Render one token as a compact `name = value` line.
|
|
52
41
|
*/
|
|
53
42
|
const formatTokenLine = (tokenResult, invocation) => {
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
43
|
+
return humanFormat.searchRow({
|
|
44
|
+
name: tokenResult.name,
|
|
45
|
+
source: 'ads',
|
|
46
|
+
kind: 'token',
|
|
47
|
+
metadata: tokenResult.exampleValue ? [`= ${tokenResult.exampleValue}`] : undefined,
|
|
48
|
+
followUp: tokenResult.followUp ? `${invocation} ${tokenResult.followUp}` : undefined
|
|
59
49
|
});
|
|
60
50
|
};
|
|
61
51
|
|
|
@@ -63,13 +53,13 @@ const formatTokenLine = (tokenResult, invocation) => {
|
|
|
63
53
|
* Render one icon as a compact line with its import package and short usage note.
|
|
64
54
|
*/
|
|
65
55
|
const formatIconLine = (iconResult, invocation) => {
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
invocation
|
|
56
|
+
return humanFormat.searchRow({
|
|
57
|
+
name: iconResult.componentName,
|
|
58
|
+
package: iconResult.package,
|
|
59
|
+
source: 'ads',
|
|
60
|
+
kind: 'icon',
|
|
61
|
+
metadata: iconResult.usage ? [iconResult.usage] : undefined,
|
|
62
|
+
followUp: iconResult.followUp ? `${invocation} ${iconResult.followUp}` : undefined
|
|
73
63
|
});
|
|
74
64
|
};
|
|
75
65
|
|
|
@@ -77,12 +67,12 @@ const formatIconLine = (iconResult, invocation) => {
|
|
|
77
67
|
* Render one foundations-document match without dumping its full Markdown body.
|
|
78
68
|
*/
|
|
79
69
|
const formatDocLine = (doc, invocation) => {
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
invocation
|
|
70
|
+
return humanFormat.searchRow({
|
|
71
|
+
name: doc.title,
|
|
72
|
+
source: 'ads',
|
|
73
|
+
kind: 'docs',
|
|
74
|
+
description: doc.summary,
|
|
75
|
+
followUp: doc.followUp ? `${invocation} ${doc.followUp}` : undefined
|
|
86
76
|
});
|
|
87
77
|
};
|
|
88
78
|
|