unoverse 0.1.206 → 0.1.207

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "unoverse",
3
- "version": "0.1.206",
3
+ "version": "0.1.207",
4
4
  "description": "The Unoverse front door — create a Studio project, a universe, or a client app, and launch Studio.",
5
5
  "license": "SEE LICENSE IN README.md",
6
6
  "type": "module",
@@ -0,0 +1,198 @@
1
+ /**
2
+ * The prompts linter: Agent skills and prompt blocks, as a LIBRARY. Rules in, findings out.
3
+ *
4
+ * A FOURTH SIBLING of ../design/, ../nodes/ and ../objects/ (2026-09-18). Until it existed
5
+ * nothing read a SKILL.md or a block before publish, and the run-time loaders drop a file
6
+ * they cannot parse with one console line and `null`. So a skill whose description held a
7
+ * bare colon (YAML reads `a: b: c` as a nested key) was published, installed, and absent
8
+ * from every list, and the first place anyone met the failure was an empty Studio screen.
9
+ * The author is the only person who can fix it, so the author is who this tells, at the
10
+ * line.
11
+ *
12
+ * What it holds a skill to is the same discoverability contract nodes are held to
13
+ * (https://docs.unoverse.ai/nodes/node-discoverability): a `whenToUse` that exists and
14
+ * carries selection signal, because a skill is found by ranking that text and nothing else.
15
+ *
16
+ * Callers: `unoverse lint` and `POST /publish` through items/publish lintForPublish; CI.
17
+ * Prints nothing, exits nothing, throws nothing for a lint failure.
18
+ *
19
+ * `options.overlay` maps an absolute path to text that STANDS IN for what is on disk, so an
20
+ * editor can lint what the developer has typed before it is saved.
21
+ */
22
+ import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
23
+ import { join, resolve, relative, basename } from "node:path";
24
+ import { createRequire } from "node:module";
25
+ import { problems, reset, report } from "../context.mjs";
26
+
27
+ const require_ = createRequire(import.meta.url);
28
+ let YAML;
29
+ try {
30
+ YAML = require_("yaml");
31
+ } catch {
32
+ throw new Error("the prompts linter needs yaml (npm install -D yaml)");
33
+ }
34
+
35
+ const DISCOVERABILITY = "https://docs.unoverse.ai/nodes/node-discoverability";
36
+ const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
37
+
38
+ const isDir = (p) => existsSync(p) && statSync(p).isDirectory();
39
+ const isRecord = (x) => !!x && typeof x === "object" && !Array.isArray(x);
40
+
41
+ /**
42
+ * Split a markdown file into frontmatter and body the way the run-time loaders do
43
+ * (gray-matter: a `---` line first, a `---` line closing). Returns
44
+ * `{ data, body, error, line }`: `data` is null when there is no block or it does not parse,
45
+ * and `line` is where in the FILE the parser stopped, so the finding lands on it.
46
+ */
47
+ export function splitFrontmatter(text) {
48
+ const lines = text.split(/\r?\n/);
49
+ if (lines[0]?.trim() !== "---") return { data: null, body: text, error: "no frontmatter block: the file must open with a --- line", line: 1 };
50
+ const close = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
51
+ if (close < 0) return { data: null, body: "", error: "the frontmatter never closes: no second --- line", line: 1 };
52
+ const yamlText = lines.slice(1, close).join("\n");
53
+ const body = lines.slice(close + 1).join("\n");
54
+ try {
55
+ const data = YAML.parse(yamlText) ?? {};
56
+ if (!isRecord(data)) return { data: null, body, error: "the frontmatter is not a mapping of key: value lines", line: 2 };
57
+ return { data, body, error: null, line: 0 };
58
+ } catch (e) {
59
+ const at = e?.linePos?.[0]?.line ?? e?.linePos?.line;
60
+ const line = typeof at === "number" ? at + 1 : 2; // +1: the opening --- is line 1
61
+ return { data: null, body, error: e.message.split("\n")[0], line };
62
+ }
63
+ }
64
+
65
+ /**
66
+ * A YAML error most authors will hit once: a plain value with `: ` inside it. The parser's
67
+ * own sentence is right and unhelpful ("nested mappings are not allowed"); this one says
68
+ * what to do.
69
+ */
70
+ function yamlHint(error, yamlLine) {
71
+ if (/nested mapping|implicit map keys|mapping pair|key node is missed/i.test(error) && /:\s/.test(yamlLine.replace(/^[^:]*:\s*/, "")))
72
+ return `${error}. A value holding a colon followed by a space must be quoted: description: "One thing: another"`;
73
+ return error;
74
+ }
75
+
76
+ function lintSkillFile(file, text, folderName, at) {
77
+ const { data, body, error, line } = splitFrontmatter(text);
78
+ if (!data) {
79
+ const src = text.split(/\r?\n/)[line - 1] ?? "";
80
+ report("error", at, `skill ${folderName}: ${yamlHint(error, src)}. The loaders skip a file they cannot parse, so this skill would not exist`, line);
81
+ return;
82
+ }
83
+ const name = typeof data.name === "string" ? data.name.trim() : "";
84
+ if (!name) report("error", at, `skill ${folderName}: name is missing; a SKILL.md without one does not load`);
85
+ else if (!KEBAB.test(name)) report("error", at, `skill ${folderName}: name "${name}" must be kebab-case: lowercase letters, digits and hyphens`);
86
+ else if (name !== folderName) report("error", at, `skill ${folderName}: name "${name}" differs from its folder; the folder is the lookup name and the two must agree`);
87
+
88
+ const description = typeof data.description === "string" ? data.description.trim() : "";
89
+ if (!description) report("error", at, `skill ${folderName}: description is missing; a SKILL.md without one does not load`);
90
+ else if (/\n/.test(description)) report("error", at, `skill ${folderName}: description must be one line; it is the listing subtitle`);
91
+ else if (description.length > 200) report("warn", at, `skill ${folderName}: description is ${description.length} characters; the listing subtitle reads best under 160`);
92
+
93
+ const w = typeof data.whenToUse === "string" ? data.whenToUse.trim() : "";
94
+ if (!w) report("error", at, `skill ${folderName}: whenToUse is missing. A skill is found by ranking this text; without it the skill cannot be discovered (${DISCOVERABILITY})`);
95
+ else {
96
+ if (description && w.toLowerCase() === description.toLowerCase()) report("error", at, `skill ${folderName}: whenToUse merely repeats description. It carries zero selection signal (${DISCOVERABILITY})`);
97
+ if (/^use this (skill|when)/i.test(w)) report("warn", at, `skill ${folderName}: whenToUse opens by restating itself. Lead with the OUTCOME in the user's own words (${DISCOVERABILITY})`);
98
+ if (/^(this is an?|a powerful|a comprehensive|an? (skill|guide) (for|that))/i.test(w)) report("warn", at, `skill ${folderName}: whenToUse opens with a label or marketing. Outcome first; it sinks the ranking (${DISCOVERABILITY})`);
99
+ }
100
+
101
+ if (data.triggers !== undefined && !(Array.isArray(data.triggers) && data.triggers.every((t) => typeof t === "string")))
102
+ report("error", at, `skill ${folderName}: triggers must be a list of phrases`);
103
+ if (data.title !== undefined && typeof data.title !== "string") report("error", at, `skill ${folderName}: title must be text`);
104
+ if (!data.title) report("hint", at, `skill ${folderName}: no title; the name "${name || folderName}" is what a person will see`);
105
+
106
+ if (!body.trim()) report("error", at, `skill ${folderName}: the body is empty; frontmatter alone is not a skill`);
107
+ }
108
+
109
+ function lintBlockFile(file, text, at) {
110
+ const id = basename(file, ".md");
111
+ const { data, body, error, line } = splitFrontmatter(text);
112
+ if (!data) {
113
+ const src = text.split(/\r?\n/)[line - 1] ?? "";
114
+ report("error", at, `block ${id}: ${yamlHint(error, src)}. The loaders skip a file they cannot parse, so this block would not exist`, line);
115
+ return;
116
+ }
117
+ if (!KEBAB.test(id)) report("error", at, `block ${id}: the filename must be kebab-case; it becomes the block's {{prompt.<camelCase>}} reference`);
118
+ if (typeof data.name !== "string" || !data.name.trim()) report("error", at, `block ${id}: name is missing`);
119
+ if (typeof data.description !== "string" || !data.description.trim()) report("error", at, `block ${id}: description is missing; it says what the block contributes to a prompt`);
120
+ if (data.tags !== undefined && !(Array.isArray(data.tags) && data.tags.every((t) => typeof t === "string"))) report("error", at, `block ${id}: tags must be a list of words`);
121
+ if (!body.trim()) report("error", at, `block ${id}: the body is empty`);
122
+ else if (/\{\{\s*prompt\./.test(body)) report("error", at, `block ${id}: references another block with {{prompt.…}}. A block stands alone; a node composes blocks, a block never does`);
123
+ }
124
+
125
+ /**
126
+ * Lint every skill and prompt block under `designRoot`: the marketplace tier and every org's.
127
+ * Returns `{ problems, skillCount, blockCount, designRoot }`.
128
+ */
129
+ export function lintPrompts(designRoot, options = {}) {
130
+ const ROOT = resolve(designRoot);
131
+ reset(ROOT, "");
132
+ const overlay = {};
133
+ for (const [k, v] of Object.entries(options.overlay ?? {})) overlay[resolve(k)] = v;
134
+ const readText = (f) => (overlay[resolve(f)] === undefined ? readFileSync(f, "utf8") : overlay[resolve(f)]);
135
+ const present = (f) => existsSync(f) || overlay[resolve(f)] !== undefined;
136
+ const rel = (f) => (relative(process.cwd(), f).startsWith("..") ? f : relative(process.cwd(), f));
137
+
138
+ if (!isDir(ROOT)) {
139
+ report("error", ROOT, "no design/ folder here");
140
+ return { problems: [...problems], skillCount: 0, blockCount: 0, designRoot: ROOT };
141
+ }
142
+
143
+ // ── the tiers: the marketplace, every flat org folder, and the legacy orgs/ container ──
144
+ const tiers = [];
145
+ const marketplace = join(ROOT, "marketplace");
146
+ if (isDir(marketplace)) tiers.push({ org: undefined, dir: marketplace });
147
+ const orgDirs = (base) => readdirSync(base).filter((e) => !e.startsWith(".") && !e.startsWith("_") && e !== "marketplace" && e !== "orgs" && isDir(join(base, e)));
148
+ for (const e of orgDirs(ROOT)) tiers.push({ org: e, dir: join(ROOT, e) });
149
+ if (isDir(join(ROOT, "orgs"))) for (const e of orgDirs(join(ROOT, "orgs"))) tiers.push({ org: e, dir: join(ROOT, "orgs", e) });
150
+
151
+ let skillCount = 0;
152
+ let blockCount = 0;
153
+ for (const tier of tiers) {
154
+ const skills = join(tier.dir, "skills");
155
+ if (isDir(skills)) {
156
+ for (const e of readdirSync(skills, { withFileTypes: true })) {
157
+ if (e.name.startsWith(".")) continue;
158
+ const p = join(skills, e.name);
159
+ if (!e.isDirectory()) {
160
+ if (e.name.endsWith(".md")) report("warn", rel(p), `a skill is a folder holding SKILL.md, not a loose file; ${e.name} is not read`);
161
+ continue;
162
+ }
163
+ const file = join(p, "SKILL.md");
164
+ if (!present(file)) {
165
+ report("error", rel(file), `skill ${e.name}: the folder has no SKILL.md, so it is not a skill`);
166
+ continue;
167
+ }
168
+ skillCount++;
169
+ lintSkillFile(file, readText(file), e.name, rel(file));
170
+ }
171
+ }
172
+ const blocks = join(tier.dir, "blocks");
173
+ if (isDir(blocks)) {
174
+ const walk = (dir) => {
175
+ for (const e of readdirSync(dir, { withFileTypes: true })) {
176
+ if (e.name.startsWith(".")) continue;
177
+ const p = join(dir, e.name);
178
+ if (e.isDirectory()) walk(p);
179
+ else if (e.name.endsWith(".md")) {
180
+ if (dir === blocks) report("warn", rel(p), `a block lives in a category folder (blocks/<category>/<name>.md); ${e.name} sits at the root and has no category`);
181
+ blockCount++;
182
+ lintBlockFile(p, readText(p), rel(p));
183
+ }
184
+ }
185
+ };
186
+ walk(blocks);
187
+ }
188
+ }
189
+
190
+ const rank = { error: 0, warn: 1, hint: 2 };
191
+ const sorted = [...problems].sort((a, b) => rank[a.level] - rank[b.level] || a.file.localeCompare(b.file));
192
+ return { problems: sorted, skillCount, blockCount, designRoot: ROOT };
193
+ }
194
+
195
+ /** True when anything would fail a build. Warnings and hints inform, errors stop. */
196
+ export function hasErrors(result) {
197
+ return result.problems.some((p) => p.level === "error");
198
+ }