@open-agent-toolkit/cli 0.0.10

package/dist/validation/skills.js

@@ -0,0 +1,166 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getFrontmatterBlock } from '../commands/shared/frontmatter.js';
+async function isDirectory(path) {
+    try {
+        const s = await stat(path);
+        return s.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function frontmatterHasKey(frontmatter, key) {
+    const re = new RegExp(`^${key}:`, 'm');
+    return re.test(frontmatter);
+}
+function getFrontmatterScalar(frontmatter, key) {
+    const re = new RegExp(`^${key}:\\s*(.*)$`, 'm');
+    const match = frontmatter.match(re);
+    return match?.[1]?.trim() ?? null;
+}
+function isValidSemver(value) {
+    return /^\d+\.\d+\.\d+$/.test(value);
+}
+function hasProgressIndicatorsSection(content) {
+    return /^## Progress Indicators \(User-Facing\)\s*$/m.test(content);
+}
+function hasBannerSnippet(content) {
+    return (/OAT ▸/m.test(content) &&
+        /━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━/m.test(content));
+}
+function validateQuickStartSemantics(skillPath, content, findings) {
+    // Keep these checks intent-based rather than tied to one exact sentence so
+    // small wording edits in the skill do not create false validation failures.
+    const mentionsDiscovery = /`?discovery\.md`?/i.test(content);
+    const mentionsSessionContext = /(session context|current conversation|current session|existing context)/i.test(content);
+    const mentionsDiscoverySynthesis = /(synthesi(?:ze|s)|populate|draft|create)/i.test(content);
+    const mentionsEnoughExistingDetail = /(enough detail|sufficient detail|detail already exists|already available)/i.test(content);
+    if (!(mentionsDiscovery &&
+        mentionsSessionContext &&
+        mentionsDiscoverySynthesis &&
+        mentionsEnoughExistingDetail)) {
+        findings.push({
+            file: skillPath,
+            message: 'Quick-start must describe synthesizing discovery.md from session context when enough detail is already available',
+        });
+    }
+    if (!(mentionsDiscovery &&
+        /(backfill(?:s|ing)?|record|capture|reflect)/i.test(content) &&
+        /(discussion|q&a|questions|answers|decisions|options considered)/i.test(content) &&
+        /(before planning|before finalizing .*plan\.md|before writing .*plan\.md)/i.test(content))) {
+        findings.push({
+            file: skillPath,
+            message: 'Quick-start must describe backfilling discovery.md after startup Q&A before planning',
+        });
+    }
+    if (!(/(?:ask|only ask)/i.test(content) &&
+        /(minimum|minimum additional|minimum follow-up)/i.test(content) &&
+        /questions?/i.test(content) &&
+        /(remove blockers|resolve blockers|unblock planning)/i.test(content))) {
+        findings.push({
+            file: skillPath,
+            message: 'Quick-start must limit follow-up questions to the minimum needed to remove blockers',
+        });
+    }
+}
+export async function validateOatSkills(repoRoot) {
+    const skillsRoot = join(repoRoot, '.agents', 'skills');
+    const findings = [];
+    if (!(await isDirectory(skillsRoot))) {
+        throw new Error(`skills directory not found: ${skillsRoot}`);
+    }
+    const entries = await readdir(skillsRoot, { withFileTypes: true });
+    const oatSkillDirs = entries
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith('oat-'))
+        .map((entry) => entry.name)
+        .sort();
+    for (const dir of oatSkillDirs) {
+        const skillPath = join(skillsRoot, dir, 'SKILL.md');
+        let content;
+        try {
+            content = await readFile(skillPath, 'utf8');
+        }
+        catch {
+            findings.push({ file: skillPath, message: 'Missing SKILL.md' });
+            continue;
+        }
+        const fm = getFrontmatterBlock(content);
+        if (!fm) {
+            findings.push({
+                file: skillPath,
+                message: 'Missing frontmatter block (--- ... ---)',
+            });
+            continue;
+        }
+        for (const key of [
+            'name',
+            'description',
+            'disable-model-invocation',
+            'user-invocable',
+            'allowed-tools',
+        ]) {
+            if (!frontmatterHasKey(fm, key)) {
+                findings.push({
+                    file: skillPath,
+                    message: `Missing frontmatter key: ${key}`,
+                });
+            }
+        }
+        const frontmatterName = getFrontmatterScalar(fm, 'name');
+        if (frontmatterName && frontmatterName !== dir) {
+            findings.push({
+                file: skillPath,
+                message: `Frontmatter name must match directory name (expected: ${dir}, found: ${frontmatterName})`,
+            });
+        }
+        const frontmatterDescription = getFrontmatterScalar(fm, 'description');
+        if (frontmatterDescription) {
+            if (/^[>|]/.test(frontmatterDescription)) {
+                findings.push({
+                    file: skillPath,
+                    message: 'Frontmatter description must be a single-line scalar',
+                });
+            }
+            else {
+                if (!/^(Use|Run|Trigger) when\b/.test(frontmatterDescription)) {
+                    findings.push({
+                        file: skillPath,
+                        message: 'Frontmatter description must start with one of: "Use when", "Run when", "Trigger when"',
+                    });
+                }
+                if (frontmatterDescription.length > 500) {
+                    findings.push({
+                        file: skillPath,
+                        message: `Frontmatter description exceeds 500 characters (${frontmatterDescription.length})`,
+                    });
+                }
+            }
+        }
+        if (frontmatterHasKey(fm, 'version')) {
+            const version = getFrontmatterScalar(fm, 'version') ?? '';
+            if (!isValidSemver(version)) {
+                findings.push({
+                    file: skillPath,
+                    message: 'Frontmatter version must be valid semver (e.g., 1.0.0)',
+                });
+            }
+        }
+        if (!hasProgressIndicatorsSection(content)) {
+            findings.push({
+                file: skillPath,
+                message: 'Missing section heading: ## Progress Indicators (User-Facing)',
+            });
+        }
+        else if (!hasBannerSnippet(content)) {
+            findings.push({
+                file: skillPath,
+                message: 'Progress Indicators section missing banner snippet (separator lines + "OAT ▸ ...")',
+            });
+        }
+        if (dir === 'oat-project-quick-start') {
+            validateQuickStartSemantics(skillPath, content, findings);
+        }
+    }
+    return { validatedSkillCount: oatSkillDirs.length, findings };
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@open-agent-toolkit/cli",
+  "version": "0.0.10",
+  "private": false,
+  "description": "Open Agent Toolkit CLI",
+  "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
+  "bugs": {
+    "url": "https://github.com/voxmedia/open-agent-toolkit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voxmedia/open-agent-toolkit.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "oat": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "README.md"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bash scripts/bundle-assets.sh && tsc && tsc-alias",
+    "clean": "rm -rf dist",
+    "dev": "tsx watch src/index.ts",
+    "check": "oxlint . && oxfmt --check .",
+    "check:fix": "oxlint --fix . && oxfmt .",
+    "format": "oxfmt --check .",
+    "format:fix": "oxfmt .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@iarna/toml": "2.2.5",
+    "@inquirer/prompts": "^8.2.0",
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "ora": "^9.0.0",
+    "yaml": "2.8.2",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsc-alias": "^1.8.10",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22.17.0"
+  }
+}