@aidy-dev/documents 0.1.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/dist/index.d.ts +31 -6
- package/dist/index.js +52 -9
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -8,14 +8,14 @@ import { readCatalog } from '@aidy-dev/spec/catalog';
|
|
|
8
8
|
import { renderLlmsTxt, renderReference, renderSkill } from '@aidy-dev/documents';
|
|
9
9
|
|
|
10
10
|
const operations = readCatalog(openapi);
|
|
11
|
-
renderSkill({ product: 'Acme Cloud', url: 'https://console.example.com', cli: { command: 'acme' }, guide, operations });
|
|
11
|
+
renderSkill({ product: 'Acme Cloud', url: 'https://console.example.com', cli: { command: 'acme', package: '@acme/cli' }, guide, operations });
|
|
12
12
|
renderLlmsTxt({ product: 'Acme Cloud', url: 'https://console.example.com', summary: 'Cloud servers on demand.', operations });
|
|
13
13
|
renderReference({ operations });
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
| Export | Output |
|
|
17
17
|
| --- | --- |
|
|
18
|
-
| `renderSkill` | `SKILL.md`: frontmatter (`name`, `description`), the hand-written guide, how to connect (MCP at `${url}/mcp`, the CLI when given), safety rules, and the operation index grouped by resource. Role operations and operations without the `mcp` or `cli` surface are left out. |
|
|
18
|
+
| `renderSkill` | `SKILL.md`: frontmatter (`name`, `description`), the hand-written guide, how to connect (MCP at `${url}/mcp`, the CLI when given, with an `npm i -g` line when its `package` is given), safety rules, and the operation index grouped by resource. Role operations and operations without the `mcp` or `cli` surface are left out. Without `operations` (a catalog only signed-in users see), it says signing in lists them. |
|
|
19
19
|
| `renderLlmsTxt` | `llms.txt` per [llmstxt.org](https://llmstxt.org): title, summary, docs, agent links, operations by group. |
|
|
20
20
|
| `renderReference` | Markdown reference of every operation: a table per group (request, effect, approval, surfaces) and each operation's input fields. |
|
|
21
21
|
| `operationGroup(op)` | The resource: first literal path segment after `/api` (and a `vN` segment), else the name's first word. |
|
package/dist/index.d.ts
CHANGED
|
@@ -20,18 +20,40 @@ export declare function cliCommand(op: Operation): string[];
|
|
|
20
20
|
* version segment such as `v1`), else the operation name's first word.
|
|
21
21
|
*/
|
|
22
22
|
export declare function operationGroup(op: Operation): string;
|
|
23
|
+
/**
|
|
24
|
+
* A skill `name`: lowercase letters, digits and hyphens, at most 64 characters, never empty.
|
|
25
|
+
* The given name, else the product's slug, else (a product named only in, say, Chinese) the
|
|
26
|
+
* first label of `origin`'s hostname.
|
|
27
|
+
*/
|
|
28
|
+
export declare function skillName(options: {
|
|
29
|
+
readonly name?: string;
|
|
30
|
+
readonly product: string;
|
|
31
|
+
readonly origin: string;
|
|
32
|
+
}): string;
|
|
33
|
+
/** A CLI the documents name, and how to install it. */
|
|
34
|
+
export interface CliOptions {
|
|
35
|
+
readonly command: string;
|
|
36
|
+
/** The npm package: the install line is `npm i -g <package>`. */
|
|
37
|
+
readonly package?: string;
|
|
38
|
+
/** A free-form install line, e.g. `curl -fsSL https://tm.example.com/install.sh | sh`; wins over `package`. */
|
|
39
|
+
readonly install?: string;
|
|
40
|
+
}
|
|
23
41
|
export interface SkillOptions {
|
|
24
|
-
/** Product name, e.g. `Acme Cloud`.
|
|
42
|
+
/** Product name, e.g. `Acme Cloud`. */
|
|
25
43
|
readonly product: string;
|
|
44
|
+
/** The skill's `name`; default `skillName` of the product and `url`. */
|
|
45
|
+
readonly name?: string;
|
|
26
46
|
/** Public URL of the aidy instance; MCP is served at `${url}/mcp`. */
|
|
27
47
|
readonly url: string;
|
|
28
48
|
/** The product's CLI, a branded `aidy` (`tm`) or `aidy` itself. */
|
|
29
|
-
readonly cli?:
|
|
30
|
-
readonly command: string;
|
|
31
|
-
};
|
|
49
|
+
readonly cli?: CliOptions;
|
|
32
50
|
/** Hand-written Markdown placed before the generated sections. */
|
|
33
51
|
readonly guide?: string;
|
|
34
|
-
|
|
52
|
+
/**
|
|
53
|
+
* The operations the reader may use. Absent when the host shows its catalog only to signed-in
|
|
54
|
+
* users: the document then says how to connect and that signing in shows the operations.
|
|
55
|
+
*/
|
|
56
|
+
readonly operations?: readonly Operation[];
|
|
35
57
|
}
|
|
36
58
|
/** SKILL.md: frontmatter, the hand-written guide, then connection, safety and the operation index. */
|
|
37
59
|
export declare function renderSkill(options: SkillOptions): string;
|
|
@@ -45,7 +67,10 @@ export interface LlmsTxtOptions {
|
|
|
45
67
|
readonly title: string;
|
|
46
68
|
readonly url: string;
|
|
47
69
|
}[];
|
|
48
|
-
|
|
70
|
+
/** The product's CLI, listed with the agent links. */
|
|
71
|
+
readonly cli?: CliOptions;
|
|
72
|
+
/** As in `SkillOptions`: absent for a catalog only signed-in users see. */
|
|
73
|
+
readonly operations?: readonly Operation[];
|
|
49
74
|
}
|
|
50
75
|
/** llms.txt (https://llmstxt.org): title, summary, then link lists and the operation list. */
|
|
51
76
|
export declare function renderLlmsTxt(options: LlmsTxtOptions): string;
|
package/dist/index.js
CHANGED
|
@@ -38,6 +38,19 @@ function grouped(operations) {
|
|
|
38
38
|
function slug(text) {
|
|
39
39
|
return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
|
|
40
40
|
}
|
|
41
|
+
const SKILL_NAME_LENGTH = 64;
|
|
42
|
+
/**
|
|
43
|
+
* A skill `name`: lowercase letters, digits and hyphens, at most 64 characters, never empty.
|
|
44
|
+
* The given name, else the product's slug, else (a product named only in, say, Chinese) the
|
|
45
|
+
* first label of `origin`'s hostname.
|
|
46
|
+
*/
|
|
47
|
+
function skillName(options) {
|
|
48
|
+
let host = "";
|
|
49
|
+
try {
|
|
50
|
+
host = new URL(options.origin).hostname.split(".")[0] ?? "";
|
|
51
|
+
} catch {}
|
|
52
|
+
return (slug(options.name ?? "") || slug(options.product) || slug(host) || "product").slice(0, SKILL_NAME_LENGTH).replace(/-+$/, "");
|
|
53
|
+
}
|
|
41
54
|
function trimUrl(url) {
|
|
42
55
|
return url.replace(/\/+$/, "");
|
|
43
56
|
}
|
|
@@ -48,27 +61,51 @@ function cliUsage(command, op) {
|
|
|
48
61
|
...op.cli.args.map((arg) => `<${arg}>`)
|
|
49
62
|
].join(" ");
|
|
50
63
|
}
|
|
64
|
+
/** The CLI's install line, if it has one. */
|
|
65
|
+
function installLine(cli) {
|
|
66
|
+
if (cli.install?.trim()) return cli.install.trim();
|
|
67
|
+
return cli.package ? `npm i -g ${cli.package}` : void 0;
|
|
68
|
+
}
|
|
69
|
+
const SIGNED_OUT = "The operations are listed for signed-in users: fetch this document with `Authorization: Bearer <token>`, or list the MCP tools once connected.";
|
|
70
|
+
/**
|
|
71
|
+
* A guide is often itself a skill file. Its own frontmatter and title would repeat the ones
|
|
72
|
+
* renderSkill writes, so they are dropped.
|
|
73
|
+
*/
|
|
74
|
+
function guideBody(guide) {
|
|
75
|
+
return guide.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trim().replace(/^#\s+[^\n]*\n?/, "").trim();
|
|
76
|
+
}
|
|
51
77
|
/** SKILL.md: frontmatter, the hand-written guide, then connection, safety and the operation index. */
|
|
52
78
|
function renderSkill(options) {
|
|
53
79
|
const url = trimUrl(options.url);
|
|
54
|
-
const groups = grouped(reachable(options.operations));
|
|
80
|
+
const groups = options.operations ? grouped(reachable(options.operations)) : void 0;
|
|
55
81
|
const cli = options.cli?.command;
|
|
56
82
|
const via = cli ? `its MCP server or the \`${cli}\` CLI` : "its MCP server";
|
|
57
|
-
const
|
|
83
|
+
const areas = groups ? ` (${groups.map(([group]) => group).join(", ")})` : "";
|
|
84
|
+
const description = `Use ${options.product}${areas} through ${via}. Connect MCP at ${url}/mcp.`;
|
|
58
85
|
const out = [
|
|
59
86
|
"---",
|
|
60
|
-
`name: ${
|
|
87
|
+
`name: ${skillName({
|
|
88
|
+
...options.name ? { name: options.name } : {},
|
|
89
|
+
product: options.product,
|
|
90
|
+
origin: url
|
|
91
|
+
})}`,
|
|
61
92
|
`description: ${JSON.stringify(description)}`,
|
|
62
93
|
"---",
|
|
63
94
|
"",
|
|
64
95
|
`# ${options.product}`,
|
|
65
96
|
""
|
|
66
97
|
];
|
|
67
|
-
|
|
98
|
+
const guide = options.guide ? guideBody(options.guide) : "";
|
|
99
|
+
if (guide) out.push(guide, "");
|
|
68
100
|
out.push("## Connect", "", `- MCP: \`${url}/mcp\` (Streamable HTTP, \`Authorization: Bearer <token>\`). Tools are named as in the index below.`);
|
|
69
|
-
if (cli)
|
|
101
|
+
if (cli) {
|
|
102
|
+
const install = options.cli && installLine(options.cli);
|
|
103
|
+
if (install) out.push(`- CLI install: \`${install}\``);
|
|
104
|
+
out.push(`- CLI: \`${cli} login ${url}\` once (reads the token from a prompt or \`--token-stdin\`), then \`${cli} tools\` lists the commands and \`${cli} <command> --help\` shows a command's flags. Output is JSON on stdout; exit codes: 0 ok, 1 tool error, 2 usage, 3 auth, 4 network.`);
|
|
105
|
+
}
|
|
70
106
|
out.push("", "## Safety", "", `- Never guess an id. Find it with \`search\`${cli ? ` (\`${cli} search <query>\`)` : ""} or a list operation first.`, "- Writes (effect create, update, delete or external) ask for confirmation. Confirm only what the user asked for; never confirm on the user's behalf.", "- Operations marked \"CLI only\" are not MCP tools.", "", "## Operations", "");
|
|
71
|
-
|
|
107
|
+
if (!groups) out.push(SIGNED_OUT, "");
|
|
108
|
+
for (const [group, ops] of groups ?? []) {
|
|
72
109
|
out.push(`### ${group}`, "");
|
|
73
110
|
for (const op of ops) {
|
|
74
111
|
const notes = [op.effect, ...op.surfaces.includes("mcp") ? [] : ["CLI only"]];
|
|
@@ -93,8 +130,14 @@ function renderLlmsTxt(options) {
|
|
|
93
130
|
for (const doc of options.docs) out.push(`- [${doc.title}](${doc.url})`);
|
|
94
131
|
out.push("");
|
|
95
132
|
}
|
|
96
|
-
out.push("## Agents", "", `- [Skill](${url}/skill.md): how an agent uses ${options.product}, with the operation index`, `- [MCP server](${url}/mcp): Streamable HTTP, bearer token; writes ask for confirmation
|
|
97
|
-
|
|
133
|
+
out.push("## Agents", "", `- [Skill](${url}/skill.md): how an agent uses ${options.product}, with the operation index`, `- [MCP server](${url}/mcp): Streamable HTTP, bearer token; writes ask for confirmation`);
|
|
134
|
+
if (options.cli) {
|
|
135
|
+
const install = installLine(options.cli);
|
|
136
|
+
out.push(`- CLI \`${options.cli.command}\`${install ? ` (install: \`${install}\`)` : ""}: \`${options.cli.command} login ${url}\`, then \`${options.cli.command} tools\``);
|
|
137
|
+
}
|
|
138
|
+
out.push("");
|
|
139
|
+
if (!options.operations) out.push("## Operations", "", SIGNED_OUT, "");
|
|
140
|
+
for (const [group, ops] of grouped(reachable(options.operations ?? []))) {
|
|
98
141
|
out.push(`## Operations: ${group}`, "");
|
|
99
142
|
for (const op of ops) out.push(`- \`${op.name}\` (${op.effect}): ${op.description}`);
|
|
100
143
|
out.push("");
|
|
@@ -145,4 +188,4 @@ function renderReference(options) {
|
|
|
145
188
|
}
|
|
146
189
|
return out.join("\n");
|
|
147
190
|
}
|
|
148
|
-
export { cliCommand, operationGroup, renderLlmsTxt, renderReference, renderSkill, toolMeta };
|
|
191
|
+
export { cliCommand, operationGroup, renderLlmsTxt, renderReference, renderSkill, skillName, toolMeta };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aidy-dev/documents",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "aidy's generated documents: skill.md, llms.txt, the operation reference and CLI command names, from an aidy catalog.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"homepage": "https://aidy.lpythu.workers.dev",
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"access": "public"
|
|
26
26
|
},
|
|
27
27
|
"dependencies": {
|
|
28
|
-
"@aidy-dev/spec": "0.1
|
|
28
|
+
"@aidy-dev/spec": "0.2.1"
|
|
29
29
|
},
|
|
30
30
|
"scripts": {
|
|
31
31
|
"build": "tsdown",
|