@ai-plugin-marketplace/core 0.1.0

package/dist/targets/vercel/validate.js

@@ -0,0 +1,180 @@
+/**
+ * Per-target validators for the Vercel Skills CLI target.
+ *
+ * The Vercel target's primary authored artifact is `SKILL.md` — one file per
+ * skill directory under `plugins/<name>/skills/<skill-name>/SKILL.md`. This
+ * module validates:
+ *   1. YAML frontmatter presence and schema conformance.
+ *   2. Name/parent-directory consistency (the agentskills.io spec requires that
+ *      a skill's frontmatter `name` matches the name of its immediate parent
+ *      directory).
+ *   3. Body line-count recommendation (soft finding when body exceeds 500 lines).
+ *
+ * Cross-target concerns (envelope-adherence, name-consistency, mcp-key-sync,
+ * marketplace-registration, freshness) are out of scope for this module.
+ *
+ * @see docs/specs/architecture.md §10 (validation contract), §8.1 (Finding types)
+ * @see https://agentskills.io (agentskills.io spec — source of name/description constraints)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { vercelSkillFrontmatterSchema } from './schemas.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Soft-finding threshold for SKILL.md body length per agentskills.io recommendation. */
+const BODY_LINE_SOFT_LIMIT = 500;
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function hardFinding(pluginName, message, hint) {
+    const finding = {
+        severity: 'hard',
+        code: 'schema-invalid',
+        plugin: pluginName,
+        message,
+    };
+    if (hint !== undefined) {
+        finding.hint = hint;
+    }
+    return finding;
+}
+function softFinding(pluginName, code, message, hint) {
+    const finding = {
+        severity: 'soft',
+        code,
+        plugin: pluginName,
+        message,
+    };
+    if (hint !== undefined) {
+        finding.hint = hint;
+    }
+    return finding;
+}
+// ---------------------------------------------------------------------------
+// SKILL.md discovery — one level deep under `plugins/<name>/skills/`
+// ---------------------------------------------------------------------------
+/**
+ * Return absolute paths to every `SKILL.md` found exactly one directory deep
+ * under `skillsDir`. Does not recurse further (current template convention).
+ */
+function findSkillMds(skillsDir) {
+    if (!fs.existsSync(skillsDir))
+        return [];
+    const results = [];
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const candidate = path.join(skillsDir, entry.name, 'SKILL.md');
+        if (fs.existsSync(candidate)) {
+            results.push(candidate);
+        }
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Per-file SKILL.md validation
+// ---------------------------------------------------------------------------
+/**
+ * Validate a single `SKILL.md` file against the agentskills.io spec.
+ *
+ * Checks performed:
+ *  - Frontmatter block present (`---\n...\n---`).
+ *  - Frontmatter parses as YAML.
+ *  - Parsed frontmatter satisfies `vercelSkillFrontmatterSchema`.
+ *  - `name` in frontmatter equals the immediate parent directory name.
+ *  - Body line count does not exceed the soft limit of 500 lines.
+ */
+function validateSkillMd(skillPath, pluginName) {
+    const content = fs.readFileSync(skillPath, 'utf-8');
+    // Relative path from the plugin root is included in messages so the author
+    // can quickly locate the file (e.g. `skills/evaluate-skill/SKILL.md`).
+    const relPath = path.relative(path.join(path.dirname(skillPath), '..', '..'), skillPath);
+    // Derive the expected skill name from the parent directory.
+    const parentDir = path.basename(path.dirname(skillPath));
+    // ------------------------------------------------------------------
+    // 1. Frontmatter block
+    // ------------------------------------------------------------------
+    const fmMatch = /^---\r?\n([\s\S]*?)\r?\n---/m.exec(content);
+    if (fmMatch === null) {
+        return [
+            hardFinding(pluginName, `${relPath}: SKILL.md has no frontmatter block`, `add a YAML frontmatter block between --- markers at the top of ${relPath}`),
+        ];
+    }
+    // ------------------------------------------------------------------
+    // 2. YAML parse
+    // ------------------------------------------------------------------
+    const frontmatterYaml = fmMatch[1] ?? '';
+    let parsed;
+    try {
+        parsed = parseYaml(frontmatterYaml);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return [
+            hardFinding(pluginName, `${relPath}: frontmatter YAML parse error: ${msg}`, `fix the YAML syntax in the frontmatter of ${relPath}`),
+        ];
+    }
+    // ------------------------------------------------------------------
+    // 3. Schema validation
+    // ------------------------------------------------------------------
+    const schemaResult = vercelSkillFrontmatterSchema.safeParse(parsed);
+    if (!schemaResult.success) {
+        const issues = schemaResult.error.issues
+            .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+            .join('; ');
+        return [
+            hardFinding(pluginName, `${relPath}: frontmatter does not match schema — ${issues}`, `ensure ${relPath} frontmatter includes required fields (name, description) and meets agentskills.io constraints`),
+        ];
+    }
+    const frontmatter = schemaResult.data;
+    const findings = [];
+    // ------------------------------------------------------------------
+    // 4. Name/parent-directory consistency (hard)
+    //    Per agentskills.io: frontmatter `name` must equal the parent dir name.
+    // ------------------------------------------------------------------
+    if (frontmatter.name !== parentDir) {
+        findings.push({
+            severity: 'hard',
+            code: 'name-consistency',
+            plugin: pluginName,
+            message: `${relPath}: frontmatter name "${frontmatter.name}" does not match parent directory "${parentDir}"`,
+            hint: `rename the skill directory to "${frontmatter.name}" or update the name field to "${parentDir}"`,
+        });
+    }
+    // ------------------------------------------------------------------
+    // 5. Body line-count recommendation (soft)
+    //    The body is everything after the closing `---` of the frontmatter block.
+    // ------------------------------------------------------------------
+    const fmEnd = content.indexOf('---', content.indexOf('---') + 3);
+    if (fmEnd !== -1) {
+        const body = content.slice(fmEnd + 3).trimStart();
+        const bodyLines = body === '' ? 0 : body.split('\n').length;
+        if (bodyLines > BODY_LINE_SOFT_LIMIT) {
+            findings.push(softFinding(pluginName, 'schema-invalid', `${relPath}: body is ${bodyLines.toString()} lines (recommended max ${BODY_LINE_SOFT_LIMIT.toString()})`, `consider splitting the skill into smaller, focused skills`));
+        }
+    }
+    return findings;
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+/**
+ * Run Vercel-specific validators (SKILL.md shape and name consistency)
+ * against a plugin directory.
+ *
+ * `pluginDir` is the absolute path to a `plugins/<name>/` directory.
+ * All findings use `plugin: path.basename(pluginDir)`.
+ */
+export function validateVercelPlugin(pluginDir) {
+    const pluginName = path.basename(pluginDir);
+    const skillsDir = path.join(pluginDir, 'skills');
+    const skillPaths = findSkillMds(skillsDir);
+    const findings = [];
+    for (const skillPath of skillPaths) {
+        findings.push(...validateSkillMd(skillPath, pluginName));
+    }
+    return findings;
+}
+//# sourceMappingURL=validate.js.map

package/dist/targets/vercel/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../src/targets/vercel/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ai-plugin-marketplace/core",
+  "version": "0.1.0",
+  "description": "Core build pipeline, validation, and scaffolding for the AI plugin marketplace toolkit.",
+  "type": "module",
+  "author": "Mike North <michael.l.north@gmail.com>",
+  "main": "./dist/index.js",
+  "types": "./dist/core.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "yaml": "^2.7.0",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-plugin-marketplace/tools.git",
+    "directory": "packages/core"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build && api-extractor run --local",
+    "check": "nx run-many --targets=check:typecheck,check:lint-ts,check:api-report,test --projects=@ai-plugin-marketplace/core",
+    "check:typecheck": "tsc --build",
+    "check:lint-ts": "eslint src",
+    "check:api-report": "api-extractor run",
+    "fix:api-report": "api-extractor run --local",
+    "fix:lint-ts": "eslint src --fix",
+    "test": "vitest run",
+    "docs": "api-documenter markdown -i temp -o docs",
+    "clean": "rimraf dist *.tsbuildinfo temp"
+  }
+}