@lousy-agents/cli 2.6.1 → 2.7.1

package/README.md

@@ -6,7 +6,7 @@
 
 ## TL;DR
 
-A CLI tool that scaffolds projects with the structure AI coding assistants need to be effective. Run `npx @lousy-agents/cli init` to create a new project with testing, linting, and GitHub Copilot configuration. Run `npx @lousy-agents/cli copilot-setup` in existing projects to generate a workflow that gives Copilot your environment context.
+A CLI tool that scaffolds projects with the structure AI coding assistants need to be effective. Run `npx @lousy-agents/cli init` to create a new project with testing, linting, and GitHub Copilot configuration. Run `npx @lousy-agents/cli copilot-setup` in existing projects to generate a workflow that gives Copilot your environment context. Run `npx @lousy-agents/cli lint` to validate agent skill frontmatter.
 
 ---
 
@@ -59,6 +59,7 @@ AI coding assistants work best when given clear constraints. Without structure,
 
 - **[`init`](docs/init.md)** - Scaffold new projects with testing, linting, and Copilot configuration
 - **[`new`](docs/new.md)** - Create new resources like custom GitHub Copilot agents
+- **[`lint`](docs/lint.md)** - Validate agent skill frontmatter in SKILL.md files
 - **[`copilot-setup`](docs/copilot-setup.md)** - Generate GitHub Actions workflows for Copilot environment setup
 
 ### MCP Server
@@ -97,6 +98,7 @@ For detailed documentation on each command, see:
 
 - **[`init` command](docs/init.md)** - Scaffold new projects
 - **[`new` command](docs/new.md)** - Create new resources
+- **[`lint` command](docs/lint.md)** - Validate agent skill frontmatter
 - **[`copilot-setup` command](docs/copilot-setup.md)** - Generate Copilot workflows
 - **[MCP Server](docs/mcp-server.md)** - AI assistant integration
 
@@ -120,6 +122,12 @@ npx @lousy-agents/cli new --copilot-agent security
 npx @lousy-agents/cli copilot-setup
 ```
 
+**Lint agent skill frontmatter:**
+
+```bash
+npx @lousy-agents/cli lint
+```
+
 ## Roadmap
 
 | Feature | Status |
@@ -130,12 +138,15 @@ npx @lousy-agents/cli copilot-setup
 | Scaffolding for GraphQL APIs | Not Started |
 | Copilot setup package manager install steps | ✅ Complete |
 | Copilot agent and skill scaffolding | ✅ Complete |
+| Agent skill frontmatter linting | ✅ Complete |
 | MCP server package | ✅ Complete |
+| Claude Code web environment setup | ✅ Complete |
 
 ## Documentation
 
 - **[`init` Command](docs/init.md)** - Project scaffolding
 - **[`new` Command](docs/new.md)** - Create new resources
+- **[`lint` Command](docs/lint.md)** - Agent skill frontmatter validation
 - **[`copilot-setup` Command](docs/copilot-setup.md)** - Workflow generation
 - **[MCP Server](docs/mcp-server.md)** - AI assistant integration
 
@@ -145,5 +156,6 @@ The repository includes fully working reference implementations demonstrating th
 
 - **[ui/copilot-with-react](ui/copilot-with-react)** - Next.js + TypeScript webapp with pre-configured testing (Vitest), linting (Biome), GitHub Copilot instructions, and Dev Container configuration.
 - **[api/copilot-with-fastify](api/copilot-with-fastify)** - Fastify + TypeScript REST API with Kysely, PostgreSQL, Testcontainers integration testing, and Dev Container configuration.
+- **[cli/copilot-with-citty](cli/copilot-with-citty)** - Citty + TypeScript CLI with pre-configured testing (Vitest), linting (Biome), GitHub Copilot instructions, and Dev Container configuration.
 
-Launch a GitHub Codespace to instantly spin up either environment and experiment with spec-driven development.
+Launch a GitHub Codespace to instantly spin up any of these environments and experiment with spec-driven development.

package/api/copilot-with-fastify/vitest.integration.config.ts

@@ -9,10 +9,8 @@ export default defineConfig({
         testTimeout: 60000,
         hookTimeout: 60000,
         pool: "forks",
-        poolOptions: {
-            forks: {
-                singleFork: true,
-            },
+        forkOptions: {
+            singleFork: true,
         },
     },
 });

package/dist/index.js

@@ -14681,6 +14681,90 @@ async function watchConfig(options) {
 
 // EXTERNAL MODULE: ./node_modules/yaml/dist/index.js
 var dist = __webpack_require__(1198);
+;// CONCATENATED MODULE: ./src/gateways/skill-lint-gateway.ts
+/**
+ * Gateway for skill lint file system operations.
+ * Discovers skill files and parses YAML frontmatter.
+ */ 
+
+
+
+/**
+ * File system implementation of the skill lint gateway.
+ */ class FileSystemSkillLintGateway {
+    async discoverSkills(targetDir) {
+        const skillsDir = (0,external_node_path_.join)(targetDir, ".github", "skills");
+        if (!await file_system_utils_fileExists(skillsDir)) {
+            return [];
+        }
+        const entries = await (0,promises_.readdir)(skillsDir, {
+            withFileTypes: true
+        });
+        const skills = [];
+        for (const entry of entries){
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            if (entry.name.includes("..") || entry.name.includes("/") || entry.name.includes("\\")) {
+                continue;
+            }
+            const skillFilePath = (0,external_node_path_.join)(skillsDir, entry.name, "SKILL.md");
+            if (await file_system_utils_fileExists(skillFilePath)) {
+                skills.push({
+                    filePath: skillFilePath,
+                    skillName: entry.name
+                });
+            }
+        }
+        return skills;
+    }
+    async readSkillFileContent(filePath) {
+        return (0,promises_.readFile)(filePath, "utf-8");
+    }
+    parseFrontmatter(content) {
+        const lines = content.split("\n");
+        if (lines[0]?.trim() !== "---") {
+            return null;
+        }
+        let endIndex = -1;
+        for(let i = 1; i < lines.length; i++){
+            if (lines[i]?.trim() === "---") {
+                endIndex = i;
+                break;
+            }
+        }
+        if (endIndex === -1) {
+            return null;
+        }
+        const yamlContent = lines.slice(1, endIndex).join("\n");
+        let data;
+        try {
+            const parsed = (0,dist.parse)(yamlContent);
+            data = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        } catch  {
+            return null;
+        }
+        const fieldLines = new Map();
+        for(let i = 1; i < endIndex; i++){
+            // Match YAML top-level field names: non-whitespace start, any chars except colon, then colon+space
+            const match = lines[i]?.match(/^([^\s:][^:]*?):\s/);
+            if (match?.[1]) {
+                fieldLines.set(match[1], i + 1);
+            }
+        }
+        return {
+            data: data ?? {},
+            fieldLines,
+            frontmatterStartLine: 1
+        };
+    }
+}
+/**
+ * Creates and returns the default skill lint gateway.
+ */ function createSkillLintGateway() {
+    return new FileSystemSkillLintGateway();
+}
+
 ;// CONCATENATED MODULE: ./src/gateways/tool-discovery-gateway.ts
 /**
  * Gateway for discovering CLI tools and commands from GitHub Actions workflows
@@ -15137,6 +15221,7 @@ var dist = __webpack_require__(1198);
 
 
 
+
 ;// CONCATENATED MODULE: ./src/use-cases/candidate-builder.ts
 /**
  * Use case for building setup step candidates from environment detection.
@@ -30935,6 +31020,203 @@ const initCommand = defineCommand({
     }
 });
 
+;// CONCATENATED MODULE: ./src/use-cases/lint-skill-frontmatter.ts
+/**
+ * Use case for linting GitHub Copilot Agent Skill frontmatter.
+ * Validates required and recommended fields, name format, and directory naming.
+ */ 
+/**
+ * Zod schema for validating agent skill frontmatter.
+ * Based on the agentskills.io specification.
+ */ const AgentSkillFrontmatterSchema = schemas_object({
+    name: schemas_string().min(1, "Name is required").max(64, "Name must be 64 characters or fewer").regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Name must contain only lowercase letters, numbers, and hyphens. It cannot start/end with a hyphen or contain consecutive hyphens."),
+    description: schemas_string().min(1, "Description is required").max(1024, "Description must be 1024 characters or fewer").refine((s)=>s.trim().length > 0, {
+        message: "Description cannot be empty or whitespace-only"
+    }),
+    license: schemas_string().optional(),
+    compatibility: schemas_string().max(500, "Compatibility must be 500 characters or fewer").optional(),
+    metadata: record(schemas_string(), schemas_string()).optional(),
+    "allowed-tools": schemas_string().optional()
+});
+/**
+ * Recommended (optional) fields that produce warnings when missing.
+ */ const RECOMMENDED_FIELDS = [
+    "allowed-tools"
+];
+/**
+ * Use case for linting skill frontmatter across a repository.
+ */ class LintSkillFrontmatterUseCase {
+    gateway;
+    constructor(gateway){
+        this.gateway = gateway;
+    }
+    async execute(input) {
+        if (!input.targetDir) {
+            throw new Error("Target directory is required");
+        }
+        const skills = await this.gateway.discoverSkills(input.targetDir);
+        const results = [];
+        for (const skill of skills){
+            const content = await this.gateway.readSkillFileContent(skill.filePath);
+            const result = this.lintSkill(skill, content);
+            results.push(result);
+        }
+        const totalErrors = results.reduce((sum, r)=>sum + r.diagnostics.filter((d)=>d.severity === "error").length, 0);
+        const totalWarnings = results.reduce((sum, r)=>sum + r.diagnostics.filter((d)=>d.severity === "warning").length, 0);
+        return {
+            results,
+            totalSkills: skills.length,
+            totalErrors,
+            totalWarnings
+        };
+    }
+    lintSkill(skill, content) {
+        let parsed = null;
+        let diagnostics = [];
+        try {
+            parsed = this.gateway.parseFrontmatter(content);
+        } catch (error) {
+            const messagePrefix = "Invalid YAML frontmatter";
+            const errorMessage = error instanceof Error && error.message ? `${messagePrefix}: ${error.message}` : `${messagePrefix}.`;
+            diagnostics.push({
+                line: 1,
+                severity: "error",
+                message: errorMessage
+            });
+        }
+        if (!parsed) {
+            if (diagnostics.length === 0) {
+                const message = hasFrontmatterDelimiters(content) ? "Invalid YAML frontmatter. The content between --- delimiters could not be parsed as valid YAML." : "Missing YAML frontmatter. Skill files must begin with --- delimited YAML frontmatter.";
+                diagnostics.push({
+                    line: 1,
+                    severity: "error",
+                    message
+                });
+            }
+            return {
+                filePath: skill.filePath,
+                skillName: skill.skillName,
+                diagnostics,
+                valid: false
+            };
+        }
+        const frontmatterDiagnostics = this.validateFrontmatter(parsed, skill.skillName);
+        diagnostics = diagnostics.concat(frontmatterDiagnostics);
+        return {
+            filePath: skill.filePath,
+            skillName: skill.skillName,
+            diagnostics,
+            valid: diagnostics.every((d)=>d.severity !== "error")
+        };
+    }
+    validateFrontmatter(parsed, parentDirName) {
+        const diagnostics = [];
+        // Validate against Zod schema
+        const result = AgentSkillFrontmatterSchema.safeParse(parsed.data);
+        if (!result.success) {
+            for (const issue of result.error.issues){
+                const fieldName = issue.path[0]?.toString();
+                const line = fieldName ? parsed.fieldLines.get(fieldName) ?? parsed.frontmatterStartLine : parsed.frontmatterStartLine;
+                diagnostics.push({
+                    line,
+                    severity: "error",
+                    message: issue.message,
+                    field: fieldName
+                });
+            }
+        }
+        // Check name matches parent directory
+        if (result.success && result.data.name !== parentDirName) {
+            const nameLine = parsed.fieldLines.get("name") ?? parsed.frontmatterStartLine;
+            diagnostics.push({
+                line: nameLine,
+                severity: "error",
+                message: `Frontmatter name '${result.data.name}' must match parent directory name '${parentDirName}'`,
+                field: "name"
+            });
+        }
+        // Check recommended fields
+        for (const field of RECOMMENDED_FIELDS){
+            if (parsed.data[field] === undefined) {
+                diagnostics.push({
+                    line: parsed.frontmatterStartLine,
+                    severity: "warning",
+                    message: `Recommended field '${field}' is missing`,
+                    field
+                });
+            }
+        }
+        return diagnostics;
+    }
+}
+/**
+ * Checks whether content has opening and closing --- frontmatter delimiters.
+ */ function hasFrontmatterDelimiters(content) {
+    const lines = content.split("\n");
+    if (lines[0]?.trim() !== "---") {
+        return false;
+    }
+    for(let i = 1; i < lines.length; i++){
+        if (lines[i]?.trim() === "---") {
+            return true;
+        }
+    }
+    return false;
+}
+
+;// CONCATENATED MODULE: ./src/commands/lint.ts
+/**
+ * CLI command for linting agent skill frontmatter.
+ * Discovers skills, validates frontmatter, and reports diagnostics.
+ */ 
+
+
+
+/**
+ * The `lint` command for validating agent skill files.
+ */ const lintCommand = defineCommand({
+    meta: {
+        name: "lint",
+        description: "Lint agent skill frontmatter. Validates required and recommended fields in SKILL.md files."
+    },
+    run: async (context)=>{
+        const targetDir = typeof context.data?.targetDir === "string" ? context.data.targetDir : process.cwd();
+        const gateway = createSkillLintGateway();
+        const useCase = new LintSkillFrontmatterUseCase(gateway);
+        const output = await useCase.execute({
+            targetDir
+        });
+        if (output.totalSkills === 0) {
+            consola.info("No skills found in .github/skills/");
+            return;
+        }
+        consola.info(`Discovered ${output.totalSkills} skill(s)`);
+        for (const result of output.results){
+            if (result.diagnostics.length === 0) {
+                consola.success(`${result.filePath}: OK`);
+                continue;
+            }
+            for (const diagnostic of result.diagnostics){
+                const prefix = `${result.filePath}:${diagnostic.line}`;
+                const fieldInfo = diagnostic.field ? ` [${diagnostic.field}]` : "";
+                if (diagnostic.severity === "error") {
+                    consola.error(`${prefix}${fieldInfo}: ${diagnostic.message}`);
+                } else {
+                    consola.warn(`${prefix}${fieldInfo}: ${diagnostic.message}`);
+                }
+            }
+        }
+        if (output.totalErrors > 0) {
+            throw new Error(`Skill lint failed: ${output.totalErrors} error(s), ${output.totalWarnings} warning(s)`);
+        }
+        if (output.totalWarnings > 0) {
+            consola.warn(`Skill lint passed with ${output.totalWarnings} warning(s)`);
+        } else {
+            consola.success("All skills passed lint checks");
+        }
+    }
+});
+
 ;// CONCATENATED MODULE: ./src/entities/copilot-agent.ts
 /**
  * Core domain entity for GitHub Copilot custom agent files.
@@ -31054,7 +31336,9 @@ You are a ${normalizedName} agent specialized in {domain/responsibility}.
 ;// CONCATENATED MODULE: ./src/entities/skill.ts
 /**
  * Core domain entity for GitHub Copilot Agent Skills.
- * Handles name normalization and SKILL.md content generation.
+ * Handles name normalization, SKILL.md content generation, and lint types.
+ */ /**
+ * Severity levels for skill lint diagnostics.
  */ /**
  * Normalizes a skill name to lowercase with hyphens.
  * Handles spaces, mixed case, multiple spaces, and leading/trailing spaces.
@@ -31268,6 +31552,7 @@ const skillArgs = {
 
 
 
+
 const src_main = defineCommand({
     meta: {
         name: "lousy-agents",
@@ -31276,6 +31561,7 @@ const src_main = defineCommand({
     },
     subCommands: {
         init: initCommand,
+        lint: lintCommand,
         new: newCommand,
         "copilot-setup": copilotSetupCommand
     }