@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 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`. The skill's `name` is its slug. */
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
- readonly operations: readonly Operation[];
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
- readonly operations: readonly Operation[];
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 description = `Use ${options.product} (${groups.map(([group]) => group).join(", ")}) through ${via}. Connect MCP at ${url}/mcp.`;
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: ${slug(options.product)}`,
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
- if (options.guide?.trim()) out.push(options.guide.trim(), "");
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) 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.`);
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
- for (const [group, ops] of groups) {
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
- for (const [group, ops] of grouped(reachable(options.operations))) {
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.0",
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.0"
28
+ "@aidy-dev/spec": "0.2.1"
29
29
  },
30
30
  "scripts": {
31
31
  "build": "tsdown",