@terra-symposium/skills 0.1.0 → 0.1.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.
@@ -1,20 +1,28 @@
1
1
  #!/usr/bin/env node
2
+ /**
3
+ * packages/skills/bin/terra-skills.mjs
4
+ */
5
+
6
+ /*//////////////////////////////////////////////////
7
+ IMPORTS
8
+ //////////////////////////////////////////////////*/
9
+
2
10
  import console from 'node:console';
3
11
  import process from 'node:process';
4
12
  import { resolve } from 'node:path';
5
13
  import { prepareSkills, checkSkills } from '../src/index.mjs';
6
14
 
7
- const [command, rootArg] = process.argv.slice(2);
8
- if (!['prepare', 'check'].includes(command) || process.argv.length > 4) {
15
+ const [cmd, rootArg] = process.argv.slice(2);
16
+ if (!['prepare', 'check'].includes(cmd) || process.argv.length > 4) {
9
17
  console.error('Usage: terra-skills <prepare|check> [repository-root]');
10
18
  process.exitCode = 2;
11
19
  } else {
12
20
  try {
13
21
  const root = resolve(rootArg ?? process.cwd());
14
- const result = command === 'prepare' ? await prepareSkills(root) : await checkSkills(root);
15
- console.log(`${command}: ${result.skills} skills, ${result.files} files`);
16
- } catch (error) {
17
- console.error(error.message);
22
+ const result = cmd === 'prepare' ? await prepareSkills(root) : await checkSkills(root);
23
+ console.log(`${cmd}: ${result.skills} skills, ${result.files} files`);
24
+ } catch (err) {
25
+ console.error(err.message);
18
26
  process.exitCode = 1;
19
27
  }
20
28
  }
@@ -18,7 +18,7 @@ metadata:
18
18
  ---
19
19
  ```
20
20
 
21
- Keep links to detailed Markdown references and required assets relative to the skill page. Put those files beside the page; the compiler copies them into the generated skill folder. `metadata.related-files` names existing repository files that establish the workflow. Use `[]` when there is no such file. Keep the body readable as raw Markdown; generated skills must not depend on Docs-only rendering.
21
+ Keep links to detailed Markdown references and required assets relative to the skill page. Put them in sibling `references/`, `assets/`, `examples/`, `scripts/`, or `agents/` folders; the compiler copies those folders into the generated skill bundle. `metadata.related-files` names existing repository files that establish the workflow. Use `[]` when there is no such file. Keep the body readable as raw Markdown; generated skills must not depend on Docs-only rendering.
22
22
 
23
23
  Install `@terra-symposium/skills` as a development dependency, then run `terra-skills prepare` from the repository root. The command writes `.agents/skills/` for agent discovery. Run `terra-skills check` to compare that output with the Docs source without rewriting files. Preparation refuses to replace a hand-authored skill directory. Add `.agents/skills/` to Git ignore rules and rerun preparation after changing a skill page. Start a new agent session or refresh discovery after preparation.
24
24
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@terra-symposium/skills",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Compile Docs-authored agent skills for repository and plugin discovery.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
package/src/index.mjs CHANGED
@@ -1,3 +1,11 @@
1
+ /**
2
+ * packages/skills/src/index.mjs
3
+ */
4
+
5
+ /*//////////////////////////////////////////////////
6
+ IMPORTS
7
+ //////////////////////////////////////////////////*/
8
+
1
9
  import { Buffer } from 'node:buffer';
2
10
  import { readFile, readdir, mkdir, rm, writeFile, stat } from 'node:fs/promises';
3
11
  import { basename, dirname, extname, join, normalize, relative, resolve, sep } from 'node:path';
@@ -6,6 +14,11 @@ import { parse, stringify } from 'yaml';
6
14
  const marker = '.terra-skills-generated';
7
15
  const slug = /^[a-z][a-z0-9-]*$/;
8
16
 
17
+ /**
18
+ * Collect files recursively under a directory.
19
+ * @param root Directory to walk.
20
+ * @return Sorted file paths, or an empty list when the directory is missing.
21
+ */
9
22
  async function filesBelow(root) {
10
23
  const found = [];
11
24
  async function visit(dir) {
@@ -17,50 +30,68 @@ async function filesBelow(root) {
17
30
  }
18
31
  try {
19
32
  await visit(root);
20
- } catch (error) {
21
- if (error.code !== 'ENOENT') throw error;
33
+ } catch (err) {
34
+ if (err.code !== 'ENOENT') throw err;
22
35
  }
23
36
  return found.sort();
24
37
  }
25
38
 
26
- function splitFrontmatter(source, path) {
27
- const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(source);
39
+ /**
40
+ * Parse a marked Markdown page's YAML frontmatter.
41
+ * @param src Complete Markdown source.
42
+ * @param path Source path for diagnostics.
43
+ * @return Parsed metadata and Markdown body.
44
+ */
45
+ function splitFrontmatter(src, path) {
46
+ const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(src);
28
47
  if (!match) throw new Error(`Missing YAML frontmatter: ${path}`);
29
48
  let fields;
30
49
  try {
31
50
  fields = parse(match[1], { uniqueKeys: true });
32
- } catch (error) {
33
- throw new Error(`Invalid YAML frontmatter in ${path}: ${error.message}`, { cause: error });
51
+ } catch (err) {
52
+ throw new Error(`Invalid YAML frontmatter in ${path}: ${err.message}`, { cause: err });
34
53
  }
35
54
  if (!fields || typeof fields !== 'object' || Array.isArray(fields))
36
55
  throw new Error(`Invalid skill metadata: ${path}`);
37
- return { fields, body: source.slice(match[0].length) };
56
+ return { fields, body: src.slice(match[0].length) };
38
57
  }
39
58
 
40
- function validateLinks(contents, file, expected) {
59
+ /**
60
+ * Reject broken relative links in the portable skill bundle.
61
+ * @param contents Markdown content to inspect.
62
+ * @param file Generated relative path.
63
+ * @param expected Compiled file map.
64
+ * @return Nothing; throws when a link cannot resolve.
65
+ */
66
+ function validLinks(contents, file, expected) {
41
67
  const withoutFences = contents.replace(/```[\s\S]*?```/g, '');
42
68
  for (const match of withoutFences.matchAll(/!?\[[^\]]*\]\(([^)]+)\)/g)) {
43
69
  const target = match[1].split('#', 1)[0];
44
70
  if (!target || /^(?:[a-z][\w+.-]*:|\/)/i.test(target)) continue;
45
- const destination = normalize(join(dirname(file), decodeURIComponent(target)));
46
- if (destination === '..' || destination.startsWith(`..${sep}`))
71
+ const dest = normalize(join(dirname(file), decodeURIComponent(target)));
72
+ if (dest === '..' || dest.startsWith(`..${sep}`))
47
73
  throw new Error(`Skill link escapes generated skills: ${file} -> ${target}`);
48
- if (!expected.has(destination)) throw new Error(`Broken skill link: ${file} -> ${target}`);
74
+ if (!expected.has(dest)) throw new Error(`Broken skill link: ${file} -> ${target}`);
49
75
  }
50
76
  }
51
77
 
52
- /** Compile all marked Docs skill pages into a portable in-memory file map. */
78
+ /**
79
+ * Compile marked Docs skill pages into a portable file map.
80
+ * @param root Repository root.
81
+ * @return Number of skills and their generated file map.
82
+ */
53
83
  export async function compileSkills(root) {
54
84
  const repo = resolve(root);
55
- const docs = join(repo, 'docs');
56
- const pages = (await filesBelow(docs)).filter((file) => basename(file) === 'SKILL.md');
85
+ const pages = (await filesBelow(join(repo, 'docs'))).filter(
86
+ (file) => basename(file) === 'SKILL.md',
87
+ );
57
88
  const expected = new Map();
58
89
  const names = new Set();
59
90
  for (const page of pages) {
60
91
  const { fields, body } = splitFrontmatter(await readFile(page, 'utf8'), page);
61
92
  if (fields.skill !== true) continue;
62
- const { name, description } = fields;
63
- if (!slug.test(name ?? '') || typeof description !== 'string' || !description.trim()) {
93
+ const { name, description: desc } = fields;
94
+ if (!slug.test(name ?? '') || typeof desc !== 'string' || !desc.trim()) {
64
95
  throw new Error(`Skill needs a slug name and description: ${page}`);
65
96
  }
66
97
  if (names.has(name)) throw new Error(`Duplicate skill name: ${name}`);
@@ -83,10 +114,9 @@ export async function compileSkills(root) {
83
114
  for (const file of await filesBelow(dirname(page))) {
84
115
  if (file === page) continue;
85
116
  const local = relative(dirname(page), file);
86
- const first = local.split(sep)[0];
87
117
  if (
88
118
  !['agents', 'assets', 'examples', 'references', 'scripts', 'README.template.md'].includes(
89
- first,
119
+ local.split(sep)[0],
90
120
  )
91
121
  )
92
122
  continue;
@@ -94,12 +124,16 @@ export async function compileSkills(root) {
94
124
  }
95
125
  }
96
126
  for (const [file, content] of expected) {
97
- if (extname(file) === '.md') validateLinks(String(content), file, expected);
127
+ if (extname(file) === '.md') validLinks(String(content), file, expected);
98
128
  }
99
129
  return { skills: names.size, files: expected };
100
130
  }
101
131
 
102
- /** Write compiled skills to the repository discovery directory. */
132
+ /**
133
+ * Write compiled skills to the repository discovery directory.
134
+ * @param root Repository root.
135
+ * @return Number of written skills and files.
136
+ */
103
137
  export async function prepareSkills(root) {
104
138
  const repo = resolve(root);
105
139
  const out = join(repo, '.agents', 'skills');
@@ -108,8 +142,8 @@ export async function prepareSkills(root) {
108
142
  const entries = await readdir(out);
109
143
  if (entries.length && !entries.includes(marker))
110
144
  throw new Error(`Refusing to replace non-generated skills: ${out}`);
111
- } catch (error) {
112
- if (error.code !== 'ENOENT') throw error;
145
+ } catch (err) {
146
+ if (err.code !== 'ENOENT') throw err;
113
147
  }
114
148
  await rm(out, { recursive: true, force: true });
115
149
  await mkdir(out, { recursive: true });
@@ -122,7 +156,11 @@ export async function prepareSkills(root) {
122
156
  return { skills: compiled.skills, files: compiled.files.size };
123
157
  }
124
158
 
125
- /** Compare discovery files with Docs sources without changing the repository. */
159
+ /**
160
+ * Compare generated discovery files with Docs without changing the repository.
161
+ * @param root Repository root.
162
+ * @return Number of checked skills and files.
163
+ */
126
164
  export async function checkSkills(root) {
127
165
  const repo = resolve(root);
128
166
  const out = join(repo, '.agents', 'skills');
@@ -131,16 +169,16 @@ export async function checkSkills(root) {
131
169
  .map((file) => relative(out, file))
132
170
  .filter((file) => file !== marker);
133
171
  const expected = [...compiled.files.keys()];
134
- const differences = new Set([
172
+ const diffs = new Set([
135
173
  ...actual.filter((file) => !compiled.files.has(file)),
136
174
  ...expected.filter((file) => !actual.includes(file)),
137
175
  ]);
138
176
  for (const file of expected) {
139
177
  if (!actual.includes(file)) continue;
140
- const found = await readFile(join(out, file));
141
- if (!found.equals(Buffer.from(compiled.files.get(file)))) differences.add(file);
178
+ if (!(await readFile(join(out, file))).equals(Buffer.from(compiled.files.get(file))))
179
+ diffs.add(file);
142
180
  }
143
- if (differences.size)
144
- throw new Error(`Generated skills differ from Docs: ${[...differences].sort().join(', ')}`);
181
+ if (diffs.size)
182
+ throw new Error(`Generated skills differ from Docs: ${[...diffs].sort().join(', ')}`);
145
183
  return { skills: compiled.skills, files: compiled.files.size };
146
184
  }