@atlaskit/ads-cli 0.8.2 → 0.10.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 +18 -0
- package/README.md +38 -0
- package/dist/cjs/cli.js +49 -20
- package/dist/cjs/commands/definitions.js +12 -0
- package/dist/cjs/commands/init.js +500 -0
- package/dist/cjs/commands/update-agents-file.js +150 -0
- package/dist/es2019/cli.js +20 -0
- package/dist/es2019/commands/definitions.js +10 -0
- package/dist/es2019/commands/init.js +371 -0
- package/dist/es2019/commands/update-agents-file.js +139 -0
- package/dist/esm/cli.js +46 -17
- package/dist/esm/commands/definitions.js +12 -0
- package/dist/esm/commands/init.js +493 -0
- package/dist/esm/commands/update-agents-file.js +143 -0
- package/dist/types/commands/init.d.ts +10 -0
- package/dist/types/commands/types.d.ts +10 -1
- package/dist/types/commands/update-agents-file.d.ts +22 -0
- package/package.json +2 -2
|
@@ -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
|
+
};
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { Writer } from '../output/writer';
|
|
2
|
+
import { type ExitCodeValue } from '../types';
|
|
3
|
+
import type { CommandInput } from './types';
|
|
4
|
+
export declare const runInitCommand: ({ input, json, writer, invocation, cwd, }: {
|
|
5
|
+
input: CommandInput;
|
|
6
|
+
json: boolean;
|
|
7
|
+
writer: Writer;
|
|
8
|
+
invocation: string;
|
|
9
|
+
cwd: string;
|
|
10
|
+
}) => Promise<ExitCodeValue>;
|
|
@@ -124,7 +124,7 @@ export type RenderContext = {
|
|
|
124
124
|
/**
|
|
125
125
|
* A single CLI command definition.
|
|
126
126
|
*/
|
|
127
|
-
|
|
127
|
+
type CommandDefinitionBase = {
|
|
128
128
|
/**
|
|
129
129
|
* The command name as typed on the CLI, e.g. `search`.
|
|
130
130
|
*/
|
|
@@ -187,9 +187,18 @@ export type CommandDefinition = {
|
|
|
187
187
|
data: unknown;
|
|
188
188
|
input: CommandInput;
|
|
189
189
|
}) => unknown;
|
|
190
|
+
};
|
|
191
|
+
export type QueryCommandDefinition = CommandDefinitionBase & {
|
|
192
|
+
action?: never;
|
|
190
193
|
/**
|
|
191
194
|
* Resolve which ADS MCP tool to run and with what arguments. Returning `{ error }` means
|
|
192
195
|
* the input was invalid (a usage error); the CLI surfaces the message.
|
|
193
196
|
*/
|
|
194
197
|
resolve: (input: CommandInput) => ResolveResult;
|
|
195
198
|
};
|
|
199
|
+
export type ActionCommandDefinition = CommandDefinitionBase & {
|
|
200
|
+
action: 'init';
|
|
201
|
+
resolve?: never;
|
|
202
|
+
};
|
|
203
|
+
export type CommandDefinition = QueryCommandDefinition | ActionCommandDefinition;
|
|
204
|
+
export {};
|
|
@@ -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;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@atlaskit/ads-cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.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",
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
"release:atlas:promote": "bash scripts/atlas/promote-stable.sh"
|
|
32
32
|
},
|
|
33
33
|
"dependencies": {
|
|
34
|
-
"@atlaskit/ads-mcp": "^1.
|
|
34
|
+
"@atlaskit/ads-mcp": "^1.10.0",
|
|
35
35
|
"@babel/runtime": "^7.0.0",
|
|
36
36
|
"chalk": "^4.1.2"
|
|
37
37
|
},
|