@aidy-dev/documents 0.0.0-stage → 0.1.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' }, 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), safety rules, and the operation index grouped by resource. Role operations and operations without the `mcp` or `cli` surface are left out. |
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,56 @@
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
+ export interface SkillOptions {
24
+ /** Product name, e.g. `Acme Cloud`. The skill's `name` is its slug. */
25
+ readonly product: string;
26
+ /** Public URL of the aidy instance; MCP is served at `${url}/mcp`. */
27
+ readonly url: string;
28
+ /** The product's CLI, a branded `aidy` (`tm`) or `aidy` itself. */
29
+ readonly cli?: {
30
+ readonly command: string;
31
+ };
32
+ /** Hand-written Markdown placed before the generated sections. */
33
+ readonly guide?: string;
34
+ readonly operations: readonly Operation[];
35
+ }
36
+ /** SKILL.md: frontmatter, the hand-written guide, then connection, safety and the operation index. */
37
+ export declare function renderSkill(options: SkillOptions): string;
38
+ export interface LlmsTxtOptions {
39
+ readonly product: string;
40
+ /** Public URL of the aidy instance. */
41
+ readonly url: string;
42
+ /** One-paragraph summary, the llms.txt blockquote. */
43
+ readonly summary: string;
44
+ readonly docs?: readonly {
45
+ readonly title: string;
46
+ readonly url: string;
47
+ }[];
48
+ readonly operations: readonly Operation[];
49
+ }
50
+ /** llms.txt (https://llmstxt.org): title, summary, then link lists and the operation list. */
51
+ export declare function renderLlmsTxt(options: LlmsTxtOptions): string;
52
+ export interface ReferenceOptions {
53
+ readonly operations: readonly Operation[];
54
+ }
55
+ /** The operation reference in Markdown: a table per group, then each operation's input fields. */
56
+ export declare function renderReference(options: ReferenceOptions): string;
package/dist/index.js ADDED
@@ -0,0 +1,148 @@
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
+ function trimUrl(url) {
42
+ return url.replace(/\/+$/, "");
43
+ }
44
+ function cliUsage(command, op) {
45
+ return [
46
+ command,
47
+ op.cli.command,
48
+ ...op.cli.args.map((arg) => `<${arg}>`)
49
+ ].join(" ");
50
+ }
51
+ /** SKILL.md: frontmatter, the hand-written guide, then connection, safety and the operation index. */
52
+ function renderSkill(options) {
53
+ const url = trimUrl(options.url);
54
+ const groups = grouped(reachable(options.operations));
55
+ const cli = options.cli?.command;
56
+ 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.`;
58
+ const out = [
59
+ "---",
60
+ `name: ${slug(options.product)}`,
61
+ `description: ${JSON.stringify(description)}`,
62
+ "---",
63
+ "",
64
+ `# ${options.product}`,
65
+ ""
66
+ ];
67
+ if (options.guide?.trim()) out.push(options.guide.trim(), "");
68
+ 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.`);
70
+ 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) {
72
+ out.push(`### ${group}`, "");
73
+ for (const op of ops) {
74
+ const notes = [op.effect, ...op.surfaces.includes("mcp") ? [] : ["CLI only"]];
75
+ const usage = cli && op.surfaces.includes("cli") ? ` · \`${cliUsage(cli, op)}\`` : "";
76
+ out.push(`- \`${op.name}\` — ${op.title} (${notes.join(", ")})${usage}`);
77
+ }
78
+ out.push("");
79
+ }
80
+ return out.join("\n");
81
+ }
82
+ /** llms.txt (https://llmstxt.org): title, summary, then link lists and the operation list. */
83
+ function renderLlmsTxt(options) {
84
+ const url = trimUrl(options.url);
85
+ const out = [
86
+ `# ${options.product}`,
87
+ "",
88
+ `> ${options.summary.trim()}`,
89
+ ""
90
+ ];
91
+ if (options.docs && options.docs.length > 0) {
92
+ out.push("## Docs", "");
93
+ for (const doc of options.docs) out.push(`- [${doc.title}](${doc.url})`);
94
+ out.push("");
95
+ }
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))) {
98
+ out.push(`## Operations: ${group}`, "");
99
+ for (const op of ops) out.push(`- \`${op.name}\` (${op.effect}): ${op.description}`);
100
+ out.push("");
101
+ }
102
+ return out.join("\n");
103
+ }
104
+ function cell(text) {
105
+ return text.replaceAll("|", "\\|").replaceAll("\n", " ");
106
+ }
107
+ function typeOf(schema) {
108
+ if (typeof schema !== "object" || schema === null) return "any";
109
+ const s = schema;
110
+ if (typeof s.$ref === "string") return s.$ref.replace("#/$defs/", "");
111
+ if (Array.isArray(s.enum)) return s.enum.map((value) => JSON.stringify(value)).join(" \\| ");
112
+ const variants = s.anyOf ?? s.oneOf;
113
+ if (Array.isArray(variants)) return variants.map(typeOf).join(" \\| ");
114
+ if (Array.isArray(s.type)) return s.type.join(" \\| ");
115
+ if (s.type === "array") return `${typeOf(s.items)}[]`;
116
+ return typeof s.type === "string" ? s.type : "any";
117
+ }
118
+ /** The operation reference in Markdown: a table per group, then each operation's input fields. */
119
+ function renderReference(options) {
120
+ const out = ["# Operation reference", ""];
121
+ for (const [group, ops] of grouped(options.operations)) {
122
+ out.push(`## ${group}`, "", "| Operation | Request | Effect | Approval | Surfaces |", "| --- | --- | --- | --- | --- |");
123
+ for (const op of ops) {
124
+ const surfaces = op.role ? `role: ${op.role}` : op.surfaces.join(", ") || "—";
125
+ out.push(`| \`${op.name}\` | \`${op.method} ${op.path}\` | ${op.effect} | ${op.approval} | ${surfaces} |`);
126
+ }
127
+ out.push("");
128
+ for (const op of ops) {
129
+ out.push(`### \`${op.name}\` — ${op.title}`, "", op.description, "");
130
+ const properties = op.input.properties ?? {};
131
+ const required = op.input.required ?? [];
132
+ const names = Object.keys(properties);
133
+ if (names.length === 0) {
134
+ out.push("No input.", "");
135
+ continue;
136
+ }
137
+ out.push("| Field | Type | In | Required | Description |", "| --- | --- | --- | --- | --- |");
138
+ for (const name of names) {
139
+ const schema = properties[name] ?? {};
140
+ const description = typeof schema.description === "string" ? schema.description : "";
141
+ out.push(`| \`${name}\` | ${typeOf(schema)} | ${op.bindings[name]} | ${required.includes(name) ? "yes" : ""} | ${cell(description)} |`);
142
+ }
143
+ out.push("");
144
+ }
145
+ }
146
+ return out.join("\n");
147
+ }
148
+ export { cliCommand, operationGroup, renderLlmsTxt, renderReference, renderSkill, 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.1.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.1.0"
29
+ },
30
+ "scripts": {
31
+ "build": "tsdown",
32
+ "typecheck": "tsc -p .",
33
+ "test": "vitest run"
34
+ }
6
35
  }