@aidy-dev/documents 0.0.0-stage → 0.2.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/LICENSE ADDED
@@ -0,0 +1,18 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ Copyright 2026 Aidy Contributors
6
+
7
+ Licensed under the Apache License, Version 2.0 (the "License");
8
+ you may not use this file except in compliance with the License.
9
+ You may obtain a copy of the License at
10
+
11
+ http://www.apache.org/licenses/LICENSE-2.0
12
+
13
+ Unless required by applicable law or agreed to in writing, software
14
+ distributed under the License is distributed on an "AS IS" BASIS,
15
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16
+ See the License for the specific language governing permissions and
17
+ limitations under the License.
18
+
package/README.md CHANGED
@@ -1,3 +1,25 @@
1
- # Temporary Holding Version
1
+ # @aidy-dev/documents
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Pure generators over an aidy catalog (`Operation[]` from `@aidy-dev/spec/catalog`). aidy's runtime
4
+ serves them at `/skill.md` and `/llms.txt`; the `aidy` CLI writes them to files.
5
+
6
+ ```ts
7
+ import { readCatalog } from '@aidy-dev/spec/catalog';
8
+ import { renderLlmsTxt, renderReference, renderSkill } from '@aidy-dev/documents';
9
+
10
+ const operations = readCatalog(openapi);
11
+ renderSkill({ product: 'Acme Cloud', url: 'https://console.example.com', cli: { command: 'acme', package: '@acme/cli' }, guide, operations });
12
+ renderLlmsTxt({ product: 'Acme Cloud', url: 'https://console.example.com', summary: 'Cloud servers on demand.', operations });
13
+ renderReference({ operations });
14
+ ```
15
+
16
+ | Export | Output |
17
+ | --- | --- |
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
+ | `renderLlmsTxt` | `llms.txt` per [llmstxt.org](https://llmstxt.org): title, summary, docs, agent links, operations by group. |
20
+ | `renderReference` | Markdown reference of every operation: a table per group (request, effect, approval, surfaces) and each operation's input fields. |
21
+ | `operationGroup(op)` | The resource: first literal path segment after `/api` (and a `vN` segment), else the name's first word. |
22
+ | `cliCommand(op)` | The CLI command words, from `x-aidy.cli.command` (default: `name` with `_` → `-`). |
23
+ | `toolMeta(op)` | The MCP tool's `_meta.aidy`: `{ command, args, effect }`, which the `aidy` CLI reads to spell commands. |
24
+
25
+ License: Apache-2.0.
@@ -0,0 +1,81 @@
1
+ /**
2
+ * Documents generated from an aidy catalog: skill.md, llms.txt, the operation reference and
3
+ * CLI command names. Pure functions over `Operation[]`; core serves them and the CLI writes them.
4
+ */
5
+ import { Effect, Operation } from "@aidy-dev/spec/catalog";
6
+ /** The aidy CLI spelling of an MCP tool, carried in the tool's `_meta.aidy`. */
7
+ export interface ToolMeta {
8
+ /** Space-separated command words, e.g. `vm stop`. */
9
+ readonly command: string;
10
+ /** Input properties taken as positional arguments, in order. */
11
+ readonly args: readonly string[];
12
+ readonly effect: Effect;
13
+ }
14
+ /** The `_meta.aidy` of the MCP tool serving an operation. */
15
+ export declare function toolMeta(op: Operation): ToolMeta;
16
+ /** The CLI command words of an operation (`vm stop` → `['vm', 'stop']`). */
17
+ export declare function cliCommand(op: Operation): string[];
18
+ /**
19
+ * The resource an operation belongs to: the first literal path segment after `/api` (and a
20
+ * version segment such as `v1`), else the operation name's first word.
21
+ */
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
+ }
41
+ export interface SkillOptions {
42
+ /** Product name, e.g. `Acme Cloud`. */
43
+ readonly product: string;
44
+ /** The skill's `name`; default `skillName` of the product and `url`. */
45
+ readonly name?: string;
46
+ /** Public URL of the aidy instance; MCP is served at `${url}/mcp`. */
47
+ readonly url: string;
48
+ /** The product's CLI, a branded `aidy` (`tm`) or `aidy` itself. */
49
+ readonly cli?: CliOptions;
50
+ /** Hand-written Markdown placed before the generated sections. */
51
+ readonly guide?: string;
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[];
57
+ }
58
+ /** SKILL.md: frontmatter, the hand-written guide, then connection, safety and the operation index. */
59
+ export declare function renderSkill(options: SkillOptions): string;
60
+ export interface LlmsTxtOptions {
61
+ readonly product: string;
62
+ /** Public URL of the aidy instance. */
63
+ readonly url: string;
64
+ /** One-paragraph summary, the llms.txt blockquote. */
65
+ readonly summary: string;
66
+ readonly docs?: readonly {
67
+ readonly title: string;
68
+ readonly url: string;
69
+ }[];
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[];
74
+ }
75
+ /** llms.txt (https://llmstxt.org): title, summary, then link lists and the operation list. */
76
+ export declare function renderLlmsTxt(options: LlmsTxtOptions): string;
77
+ export interface ReferenceOptions {
78
+ readonly operations: readonly Operation[];
79
+ }
80
+ /** The operation reference in Markdown: a table per group, then each operation's input fields. */
81
+ export declare function renderReference(options: ReferenceOptions): string;
package/dist/index.js ADDED
@@ -0,0 +1,191 @@
1
+ // src/index.ts
2
+ /** The `_meta.aidy` of the MCP tool serving an operation. */
3
+ function toolMeta(op) {
4
+ return {
5
+ command: op.cli.command,
6
+ args: op.cli.args,
7
+ effect: op.effect
8
+ };
9
+ }
10
+ /** The CLI command words of an operation (`vm stop` → `['vm', 'stop']`). */
11
+ function cliCommand(op) {
12
+ return op.cli.command.split(" ");
13
+ }
14
+ /**
15
+ * The resource an operation belongs to: the first literal path segment after `/api` (and a
16
+ * version segment such as `v1`), else the operation name's first word.
17
+ */
18
+ function operationGroup(op) {
19
+ const segments = op.path.split("/").filter(Boolean);
20
+ if (segments[0] === "api") segments.shift();
21
+ if (segments[0] && /^v\d+$/.test(segments[0])) segments.shift();
22
+ const first = segments[0];
23
+ if (first && !first.startsWith("{")) return first;
24
+ return op.name.split("_")[0];
25
+ }
26
+ /** Operations an outside agent can reach: not a role, and on the `mcp` or `cli` surface. */
27
+ function reachable(operations) {
28
+ return operations.filter((op) => !op.role && (op.surfaces.includes("mcp") || op.surfaces.includes("cli")));
29
+ }
30
+ function grouped(operations) {
31
+ const groups = /* @__PURE__ */ new Map();
32
+ for (const op of operations) {
33
+ const group = operationGroup(op);
34
+ groups.set(group, [...groups.get(group) ?? [], op]);
35
+ }
36
+ return [...groups.entries()].sort(([a], [b]) => a.localeCompare(b));
37
+ }
38
+ function slug(text) {
39
+ return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
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
+ }
54
+ function trimUrl(url) {
55
+ return url.replace(/\/+$/, "");
56
+ }
57
+ function cliUsage(command, op) {
58
+ return [
59
+ command,
60
+ op.cli.command,
61
+ ...op.cli.args.map((arg) => `<${arg}>`)
62
+ ].join(" ");
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
+ }
77
+ /** SKILL.md: frontmatter, the hand-written guide, then connection, safety and the operation index. */
78
+ function renderSkill(options) {
79
+ const url = trimUrl(options.url);
80
+ const groups = options.operations ? grouped(reachable(options.operations)) : void 0;
81
+ const cli = options.cli?.command;
82
+ const via = cli ? `its MCP server or the \`${cli}\` CLI` : "its MCP server";
83
+ const areas = groups ? ` (${groups.map(([group]) => group).join(", ")})` : "";
84
+ const description = `Use ${options.product}${areas} through ${via}. Connect MCP at ${url}/mcp.`;
85
+ const out = [
86
+ "---",
87
+ `name: ${skillName({
88
+ ...options.name ? { name: options.name } : {},
89
+ product: options.product,
90
+ origin: url
91
+ })}`,
92
+ `description: ${JSON.stringify(description)}`,
93
+ "---",
94
+ "",
95
+ `# ${options.product}`,
96
+ ""
97
+ ];
98
+ const guide = options.guide ? guideBody(options.guide) : "";
99
+ if (guide) out.push(guide, "");
100
+ out.push("## Connect", "", `- MCP: \`${url}/mcp\` (Streamable HTTP, \`Authorization: Bearer <token>\`). Tools are named as in the index below.`);
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
+ }
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", "");
107
+ if (!groups) out.push(SIGNED_OUT, "");
108
+ for (const [group, ops] of groups ?? []) {
109
+ out.push(`### ${group}`, "");
110
+ for (const op of ops) {
111
+ const notes = [op.effect, ...op.surfaces.includes("mcp") ? [] : ["CLI only"]];
112
+ const usage = cli && op.surfaces.includes("cli") ? ` · \`${cliUsage(cli, op)}\`` : "";
113
+ out.push(`- \`${op.name}\` — ${op.title} (${notes.join(", ")})${usage}`);
114
+ }
115
+ out.push("");
116
+ }
117
+ return out.join("\n");
118
+ }
119
+ /** llms.txt (https://llmstxt.org): title, summary, then link lists and the operation list. */
120
+ function renderLlmsTxt(options) {
121
+ const url = trimUrl(options.url);
122
+ const out = [
123
+ `# ${options.product}`,
124
+ "",
125
+ `> ${options.summary.trim()}`,
126
+ ""
127
+ ];
128
+ if (options.docs && options.docs.length > 0) {
129
+ out.push("## Docs", "");
130
+ for (const doc of options.docs) out.push(`- [${doc.title}](${doc.url})`);
131
+ out.push("");
132
+ }
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 ?? []))) {
141
+ out.push(`## Operations: ${group}`, "");
142
+ for (const op of ops) out.push(`- \`${op.name}\` (${op.effect}): ${op.description}`);
143
+ out.push("");
144
+ }
145
+ return out.join("\n");
146
+ }
147
+ function cell(text) {
148
+ return text.replaceAll("|", "\\|").replaceAll("\n", " ");
149
+ }
150
+ function typeOf(schema) {
151
+ if (typeof schema !== "object" || schema === null) return "any";
152
+ const s = schema;
153
+ if (typeof s.$ref === "string") return s.$ref.replace("#/$defs/", "");
154
+ if (Array.isArray(s.enum)) return s.enum.map((value) => JSON.stringify(value)).join(" \\| ");
155
+ const variants = s.anyOf ?? s.oneOf;
156
+ if (Array.isArray(variants)) return variants.map(typeOf).join(" \\| ");
157
+ if (Array.isArray(s.type)) return s.type.join(" \\| ");
158
+ if (s.type === "array") return `${typeOf(s.items)}[]`;
159
+ return typeof s.type === "string" ? s.type : "any";
160
+ }
161
+ /** The operation reference in Markdown: a table per group, then each operation's input fields. */
162
+ function renderReference(options) {
163
+ const out = ["# Operation reference", ""];
164
+ for (const [group, ops] of grouped(options.operations)) {
165
+ out.push(`## ${group}`, "", "| Operation | Request | Effect | Approval | Surfaces |", "| --- | --- | --- | --- | --- |");
166
+ for (const op of ops) {
167
+ const surfaces = op.role ? `role: ${op.role}` : op.surfaces.join(", ") || "—";
168
+ out.push(`| \`${op.name}\` | \`${op.method} ${op.path}\` | ${op.effect} | ${op.approval} | ${surfaces} |`);
169
+ }
170
+ out.push("");
171
+ for (const op of ops) {
172
+ out.push(`### \`${op.name}\` — ${op.title}`, "", op.description, "");
173
+ const properties = op.input.properties ?? {};
174
+ const required = op.input.required ?? [];
175
+ const names = Object.keys(properties);
176
+ if (names.length === 0) {
177
+ out.push("No input.", "");
178
+ continue;
179
+ }
180
+ out.push("| Field | Type | In | Required | Description |", "| --- | --- | --- | --- | --- |");
181
+ for (const name of names) {
182
+ const schema = properties[name] ?? {};
183
+ const description = typeof schema.description === "string" ? schema.description : "";
184
+ out.push(`| \`${name}\` | ${typeOf(schema)} | ${op.bindings[name]} | ${required.includes(name) ? "yes" : ""} | ${cell(description)} |`);
185
+ }
186
+ out.push("");
187
+ }
188
+ }
189
+ return out.join("\n");
190
+ }
191
+ export { cliCommand, operationGroup, renderLlmsTxt, renderReference, renderSkill, skillName, toolMeta };
package/package.json CHANGED
@@ -1,6 +1,35 @@
1
1
  {
2
2
  "name": "@aidy-dev/documents",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.0",
4
+ "description": "aidy's generated documents: skill.md, llms.txt, the operation reference and CLI command names, from an aidy catalog.",
5
+ "license": "Apache-2.0",
6
+ "homepage": "https://aidy.lpythu.workers.dev",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/aidy-dev/aidy.git",
10
+ "directory": "packages/documents"
11
+ },
12
+ "type": "module",
13
+ "sideEffects": false,
14
+ "files": [
15
+ "dist"
16
+ ],
17
+ "exports": {
18
+ ".": {
19
+ "@aidy-dev/source": "./src/index.ts",
20
+ "default": "./dist/index.js"
21
+ },
22
+ "./package.json": "./package.json"
23
+ },
24
+ "publishConfig": {
25
+ "access": "public"
26
+ },
27
+ "dependencies": {
28
+ "@aidy-dev/spec": "0.2.0"
29
+ },
30
+ "scripts": {
31
+ "build": "tsdown",
32
+ "typecheck": "tsc -p .",
33
+ "test": "vitest run"
34
+ }
6
35
  }