@loom-skills/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -0,0 +1,1019 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command as Command9 } from "commander";
+
+// src/commands/install.ts
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { existsSync, mkdirSync, cpSync, writeFileSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+var installCommand = new Command("install").description("Install a skill package").argument("<package>", "Package name or path").option("-g, --global", "Install globally").option("-f, --force", "Force reinstall").action(async (packagePath, options) => {
+  const spinner = ora("Installing skill...").start();
+  try {
+    const targetDir = options.global ? join(process.env.HOME || "~", ".loom", "skills") : join(process.cwd(), ".loom", "skills");
+    if (!existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+    let sourcePath;
+    if (packagePath.startsWith("./") || packagePath.startsWith("/")) {
+      sourcePath = resolve(packagePath);
+    } else {
+      sourcePath = join(process.cwd(), "skills", packagePath.replace(/^@[^/]+\//, ""));
+    }
+    if (!existsSync(sourcePath)) {
+      throw new Error(`Package not found: ${packagePath}`);
+    }
+    const yamlPath = join(sourcePath, "SKILL.yaml");
+    if (!existsSync(yamlPath)) {
+      throw new Error(`No SKILL.yaml found in: ${sourcePath}`);
+    }
+    const yamlContent = readFileSync(yamlPath, "utf-8");
+    const nameMatch = yamlContent.match(/name:\s*"?([^"\n]+)"?/);
+    const versionMatch = yamlContent.match(/version:\s*"?([^"\n]+)"?/);
+    const skillName = nameMatch?.[1] || packagePath.split("/").pop() || "unknown";
+    const skillVersion = versionMatch?.[1] || "0.0.0";
+    const skillDir = join(targetDir, skillName.replace(/^@[^/]+\//, ""));
+    if (existsSync(skillDir) && !options.force) {
+      spinner.warn(`Skill already installed: ${skillName}`);
+      return;
+    }
+    cpSync(sourcePath, skillDir, { recursive: true });
+    const manifest = {
+      name: skillName,
+      version: skillVersion,
+      installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      source: sourcePath
+    };
+    writeFileSync(join(skillDir, ".loom-manifest.json"), JSON.stringify(manifest, null, 2));
+    spinner.succeed(chalk.green(`Installed ${skillName}@${skillVersion}`));
+    const providesMatch = yamlContent.match(/provides:\s*\n([\s\S]*?)(?=\nrequires:|\ncontext:|\ntags:|$)/);
+    if (providesMatch) {
+      console.log("\n" + chalk.bold("Capabilities:"));
+      const capLines = providesMatch[1].split("\n").filter((l) => l.includes("id:"));
+      for (const line of capLines) {
+        const capId = line.match(/id:\s*(\S+)/)?.[1];
+        if (capId) console.log(`  ${chalk.cyan(capId)}`);
+      }
+    }
+  } catch (error) {
+    spinner.fail(chalk.red(`Failed to install: ${error instanceof Error ? error.message : error}`));
+    process.exit(1);
+  }
+});
+
+// src/commands/list.ts
+import { Command as Command2 } from "commander";
+import chalk2 from "chalk";
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+var listCommand = new Command2("list").description("List installed skills").option("-g, --global", "List global skills").option("--json", "Output as JSON").action((options) => {
+  const skillsDir = options.global ? join2(process.env.HOME || "~", ".loom", "skills") : join2(process.cwd(), ".loom", "skills");
+  if (!existsSync2(skillsDir)) {
+    console.log(chalk2.yellow("No skills installed."));
+    return;
+  }
+  const skillDirs = readdirSync(skillsDir).filter(
+    (f) => existsSync2(join2(skillsDir, f, "SKILL.yaml"))
+  );
+  if (skillDirs.length === 0) {
+    console.log(chalk2.yellow("No skills installed."));
+    return;
+  }
+  if (options.json) {
+    const skills = skillDirs.map((dir) => {
+      const manifestPath = join2(skillsDir, dir, ".loom-manifest.json");
+      if (existsSync2(manifestPath)) {
+        return JSON.parse(readFileSync2(manifestPath, "utf-8"));
+      }
+      return { name: dir, version: "unknown" };
+    });
+    console.log(JSON.stringify(skills, null, 2));
+    return;
+  }
+  console.log(chalk2.bold("\nInstalled Skills:\n"));
+  for (const dir of skillDirs) {
+    const manifestPath = join2(skillsDir, dir, ".loom-manifest.json");
+    let name = dir;
+    let version = "unknown";
+    let installedAt = "";
+    if (existsSync2(manifestPath)) {
+      const manifest = JSON.parse(readFileSync2(manifestPath, "utf-8"));
+      name = manifest.name || dir;
+      version = manifest.version || "unknown";
+      installedAt = manifest.installedAt || "";
+    }
+    console.log(`${chalk2.green("\u2713")} ${chalk2.bold(name)}@${chalk2.cyan(version)}`);
+    if (installedAt) {
+      console.log(`  Installed: ${chalk2.gray(new Date(installedAt).toLocaleDateString())}`);
+    }
+    console.log();
+  }
+});
+
+// src/commands/compose.ts
+import { Command as Command3 } from "commander";
+import chalk3 from "chalk";
+import ora2 from "ora";
+import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+function resolveSkillPath(skillsDir, name) {
+  const shortName = name.replace(/^@[^/]+\//, "");
+  const flatPath = join3(skillsDir, shortName);
+  if (existsSync3(join3(flatPath, "SKILL.yaml"))) {
+    return flatPath;
+  }
+  const categories = existsSync3(skillsDir) ? readdirSync2(skillsDir).filter((f) => existsSync3(join3(skillsDir, f))) : [];
+  for (const category of categories) {
+    const candidate = join3(skillsDir, category, shortName);
+    if (existsSync3(join3(candidate, "SKILL.yaml"))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function parseSkillYaml(yamlPath) {
+  const content = readFileSync3(yamlPath, "utf-8");
+  const nameMatch = content.match(/name:\s*"?([^"\n]+)"?/);
+  const versionMatch = content.match(/version:\s*"?([^"\n]+)"?/);
+  const descMatch = content.match(/description:\s*"?([^"\n]+)"?/);
+  const provides = [];
+  const providesSection = content.match(/provides:\s*\n([\s\S]*?)(?=\nrequires:|\ncontext:|\ntags:|$)/);
+  if (providesSection) {
+    const capBlocks = providesSection[1].split(/(?=^\s*- id:)/m);
+    for (const block of capBlocks) {
+      const idMatch = block.match(/id:\s*(\S+)/);
+      const descMatch2 = block.match(/description:\s*"?([^"\n]+)"?/);
+      if (idMatch) {
+        provides.push({ id: idMatch[1], description: descMatch2?.[1] || "" });
+      }
+    }
+  }
+  const quality = [];
+  const qualitySection = content.match(/quality:\s*\n([\s\S]*?)(?=\nreferences:|\ntags:|$)/);
+  if (qualitySection) {
+    const gateBlocks = qualitySection[1].split(/(?=^\s*- id:)/m);
+    for (const block of gateBlocks) {
+      const idMatch = block.match(/id:\s*(\S+)/);
+      const descMatch2 = block.match(/description:\s*"?([^"\n]+)"?/);
+      const sevMatch = block.match(/severity:\s*(\S+)/);
+      if (idMatch) {
+        quality.push({
+          id: idMatch[1],
+          description: descMatch2?.[1] || "",
+          severity: sevMatch?.[1] || "warning"
+        });
+      }
+    }
+  }
+  return {
+    name: nameMatch?.[1] || "unknown",
+    version: versionMatch?.[1] || "0.0.0",
+    description: descMatch?.[1] || "",
+    provides,
+    quality
+  };
+}
+var composeCommand = new Command3("compose").description("Compose multiple skills into a workflow").argument("<skills...>", "Skills to compose").option("-o, --output <file>", "Output file").option("--dry-run", "Show composition without writing").action((skillNames, options) => {
+  const spinner = ora2("Composing skills...").start();
+  try {
+    const skills = [];
+    const skillsDir = join3(process.cwd(), "skills");
+    for (const name of skillNames) {
+      const skillPath = resolveSkillPath(skillsDir, name);
+      if (!skillPath) {
+        throw new Error(`Skill not found: ${name}`);
+      }
+      skills.push(parseSkillYaml(join3(skillPath, "SKILL.yaml")));
+    }
+    spinner.stop();
+    const allCapabilities = skills.flatMap((s) => s.provides);
+    const allQuality = skills.flatMap((s) => s.quality || []);
+    const lines = [
+      "# Loom Composed Workflow",
+      "",
+      `Generated: ${(/* @__PURE__ */ new Date()).toISOString()}`,
+      "",
+      "## Skills",
+      ""
+    ];
+    for (const skill of skills) {
+      lines.push(`- **${skill.name}**@${skill.version}: ${skill.description}`);
+    }
+    lines.push("", "## Capabilities", "");
+    for (const cap of allCapabilities) {
+      lines.push(`- **${cap.id}**: ${cap.description}`);
+    }
+    if (allQuality.length > 0) {
+      lines.push("", "## Quality Gates", "");
+      for (const gate of allQuality) {
+        lines.push(`- **${gate.id}**: ${gate.description} (${gate.severity})`);
+      }
+    }
+    const output = lines.join("\n");
+    if (options.dryRun) {
+      console.log(output);
+      return;
+    }
+    const outputFile = options.output || "loom-workflow.md";
+    writeFileSync2(outputFile, output);
+    console.log(chalk3.green(`Composed workflow written to ${outputFile}`));
+    console.log(`
+Skills: ${skills.length} | Capabilities: ${allCapabilities.length}`);
+  } catch (error) {
+    spinner.fail(chalk3.red(`Failed: ${error instanceof Error ? error.message : error}`));
+    process.exit(1);
+  }
+});
+
+// src/commands/test.ts
+import { Command as Command4 } from "commander";
+import chalk4 from "chalk";
+import { existsSync as existsSync4, readdirSync as readdirSync3, readFileSync as readFileSync4 } from "node:fs";
+import { join as join4, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+var require2 = createRequire(import.meta.url);
+function resolveVitestBin() {
+  const vitestPkgPath = require2.resolve("vitest/package.json");
+  const vitestPkg = JSON.parse(readFileSync4(vitestPkgPath, "utf-8"));
+  const binEntry = typeof vitestPkg.bin === "string" ? vitestPkg.bin : vitestPkg.bin?.vitest;
+  if (!binEntry) {
+    throw new Error("Could not resolve vitest executable");
+  }
+  return join4(dirname(vitestPkgPath), binEntry);
+}
+function runSkillTests(testDir, testFiles) {
+  const vitestBin = resolveVitestBin();
+  const result = spawnSync(
+    process.execPath,
+    [vitestBin, "run", ...testFiles, "--root", testDir, "--globals"],
+    { cwd: testDir, encoding: "utf-8" }
+  );
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  return { passed: result.status === 0, output };
+}
+var testCommand = new Command4("test").description("Run skill tests").argument("[skill]", "Skill to test").action((skillName) => {
+  try {
+    const skillsDir = join4(process.cwd(), "skills");
+    if (!existsSync4(skillsDir)) {
+      console.log(chalk4.red("No skills directory found"));
+      process.exit(1);
+    }
+    const skillDirs = [];
+    if (skillName) {
+      let skillPath = /^@[^/]+\//.test(skillName) ? join4(skillsDir, skillName.replace(/^@[^/]+\//, "")) : join4(skillsDir, skillName);
+      if (!existsSync4(skillPath)) {
+        const short = skillName.replace(/^@[^/]+\//, "");
+        const found = readdirSync3(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".")).map((d) => join4(skillsDir, d.name, short)).find((p) => existsSync4(join4(p, "SKILL.yaml")));
+        if (found) skillPath = found;
+      }
+      if (!existsSync4(skillPath)) {
+        throw new Error(`Skill not found: ${skillName}`);
+      }
+      skillDirs.push(skillPath);
+    } else {
+      const categories = readdirSync3(skillsDir).filter(
+        (f) => existsSync4(join4(skillsDir, f)) && !f.startsWith(".")
+      );
+      for (const category of categories) {
+        const categoryPath = join4(skillsDir, category);
+        if (!existsSync4(categoryPath)) continue;
+        const skills = readdirSync3(categoryPath).filter(
+          (f) => existsSync4(join4(categoryPath, f, "SKILL.yaml"))
+        );
+        for (const skill of skills) {
+          skillDirs.push(join4(categoryPath, skill));
+        }
+      }
+    }
+    if (skillDirs.length === 0) {
+      console.log(chalk4.yellow("No skills found to test"));
+      return;
+    }
+    console.log(chalk4.bold("Running tests...\n"));
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    for (const skillPath of skillDirs) {
+      const yamlPath = join4(skillPath, "SKILL.yaml");
+      const content = existsSync4(yamlPath) ? readFileSync4(yamlPath, "utf-8") : "";
+      const nameMatch = content.match(/name:\s*"?([^"\n]+)"?/);
+      const currentSkillName = nameMatch?.[1] || skillPath.split("/").pop() || "unknown";
+      const testDir = join4(skillPath, "tests");
+      if (!existsSync4(testDir)) {
+        console.log(chalk4.gray(`  ${currentSkillName}: no tests (skipped)`));
+        skipped++;
+        continue;
+      }
+      const testFiles = readdirSync3(testDir).filter((f) => f.endsWith(".test.ts") || f.endsWith(".test.js"));
+      if (testFiles.length === 0) {
+        console.log(chalk4.gray(`  ${currentSkillName}: no test files (skipped)`));
+        skipped++;
+        continue;
+      }
+      const { passed: skillPassed, output } = runSkillTests(testDir, testFiles);
+      if (skillPassed) {
+        console.log(chalk4.green(`  ${currentSkillName}: ${testFiles.length} test file(s) passed \u2713`));
+        passed++;
+      } else {
+        console.log(chalk4.red(`  ${currentSkillName}: tests failed \u2717`));
+        console.log(
+          output.split("\n").map((line) => `    ${line}`).join("\n")
+        );
+        failed++;
+      }
+    }
+    console.log("\n" + chalk4.bold("Summary:"));
+    console.log(`  ${chalk4.green(`Passed: ${passed}`)}`);
+    if (failed > 0) {
+      console.log(`  ${chalk4.red(`Failed: ${failed}`)}`);
+    }
+    if (skipped > 0) {
+      console.log(`  ${chalk4.yellow(`Skipped: ${skipped}`)}`);
+    }
+    if (failed > 0) {
+      process.exit(1);
+    }
+  } catch (error) {
+    console.log(chalk4.red(`Failed: ${error instanceof Error ? error.message : error}`));
+    process.exit(1);
+  }
+});
+
+// src/commands/validate.ts
+import { Command as Command5 } from "commander";
+import chalk5 from "chalk";
+import ora3 from "ora";
+import { existsSync as existsSync6, readdirSync as readdirSync5 } from "node:fs";
+import { join as join6 } from "node:path";
+
+// ../core/dist/loader.js
+import { readFileSync as readFileSync5, existsSync as existsSync5, readdirSync as readdirSync4, statSync } from "node:fs";
+import { join as join5, resolve as resolve2 } from "node:path";
+import { parse as parseYaml } from "yaml";
+var SkillLoader = class {
+  cache = /* @__PURE__ */ new Map();
+  /**
+   * Load a skill from a directory path
+   */
+  async load(skillPath) {
+    const canonical = resolve2(skillPath);
+    if (this.cache.has(canonical)) {
+      return this.cache.get(canonical);
+    }
+    if (!existsSync5(skillPath) || !statSync(skillPath).isDirectory()) {
+      throw new Error(`Skill directory not found: ${skillPath}`);
+    }
+    const yamlPath = join5(skillPath, "SKILL.yaml");
+    if (!existsSync5(yamlPath)) {
+      throw new Error(`SKILL.yaml not found in: ${skillPath}`);
+    }
+    const yamlContent = readFileSync5(yamlPath, "utf-8");
+    const definition = parseYaml(yamlContent);
+    this.validateDefinition(definition, skillPath);
+    const mdPath = join5(skillPath, "SKILL.md");
+    let content = "";
+    if (existsSync5(mdPath)) {
+      content = readFileSync5(mdPath, "utf-8");
+    }
+    const references = this.loadReferences(skillPath, definition.references || []);
+    const loaded = {
+      definition,
+      content,
+      references,
+      path: skillPath
+    };
+    this.cache.set(canonical, loaded);
+    return loaded;
+  }
+  /**
+   * Load a skill by package name (e.g., @loom-skills/tdd).
+   * The scope prefix is stripped generically so any scope works.
+   */
+  async loadByName(name, searchPaths = []) {
+    const skillDir = name.replace(/^@[^/]+\//, "");
+    for (const searchPath of searchPaths) {
+      const candidate = join5(searchPath, skillDir);
+      if (existsSync5(candidate)) {
+        return this.load(candidate);
+      }
+    }
+    const localCandidate = join5(process.cwd(), "skills", skillDir);
+    if (existsSync5(localCandidate)) {
+      return this.load(localCandidate);
+    }
+    throw new Error(`Skill not found: ${name}`);
+  }
+  /**
+   * Load all skills from a directory
+   */
+  async loadAll(skillsDir) {
+    const skills = [];
+    if (!existsSync5(skillsDir)) {
+      return skills;
+    }
+    const categories = readdirSync4(skillsDir).filter((f) => statSync(join5(skillsDir, f)).isDirectory());
+    for (const category of categories) {
+      const categoryPath = join5(skillsDir, category);
+      const skillDirs = readdirSync4(categoryPath).filter((f) => statSync(join5(categoryPath, f)).isDirectory());
+      for (const skillDir of skillDirs) {
+        const skillPath = join5(categoryPath, skillDir);
+        try {
+          const skill = await this.load(skillPath);
+          skills.push(skill);
+        } catch {
+        }
+      }
+    }
+    return skills;
+  }
+  /**
+   * Clear the load cache
+   */
+  clearCache() {
+    this.cache.clear();
+  }
+  // ==========================================================================
+  // Private Methods
+  // ==========================================================================
+  validateDefinition(def, path) {
+    if (!def.name) {
+      throw new Error(`Skill missing 'name' field: ${path}`);
+    }
+    if (!def.version) {
+      throw new Error(`Skill missing 'version' field: ${path}`);
+    }
+    if (!def.description) {
+      throw new Error(`Skill missing 'description' field: ${path}`);
+    }
+    if (!Array.isArray(def.provides)) {
+      throw new Error(`Skill missing 'provides' array: ${path}`);
+    }
+  }
+  loadReferences(skillPath, refs) {
+    const references = /* @__PURE__ */ new Map();
+    for (const ref of refs) {
+      const refPath = join5(skillPath, ref.path);
+      if (existsSync5(refPath)) {
+        const content = readFileSync5(refPath, "utf-8");
+        references.set(ref.path, content);
+      }
+    }
+    return references;
+  }
+};
+var defaultLoader = null;
+function getLoader() {
+  if (!defaultLoader) {
+    defaultLoader = new SkillLoader();
+  }
+  return defaultLoader;
+}
+async function loadSkill(path) {
+  return getLoader().load(path);
+}
+
+// ../core/dist/validator.js
+var CONTENT_GATE_HEADINGS = {
+  "has-overview": /^#{1,6}\s*overview\s*$/im,
+  "has-when-to-use": /^#{1,6}\s*when to use\s*$/im,
+  "has-workflow": /^#{1,6}\s*workflow\s*$/im
+};
+var AUTO_SATISFIED_GATES = /* @__PURE__ */ new Set([
+  "valid-schema",
+  "valid-name",
+  "valid-version",
+  "has-quality-gates"
+]);
+var Validator = class {
+  /**
+   * Validate a skill definition
+   */
+  validate(definition) {
+    const errors = [];
+    this.validateRequired(definition, errors);
+    this.validateFormats(definition, errors);
+    this.validateCapabilities(definition, errors);
+    this.validateQualityGates(definition, errors);
+    const validationErrors = errors.filter((e) => e.severity === "error");
+    const warnings = errors.filter((e) => e.severity === "warning");
+    return {
+      valid: validationErrors.length === 0,
+      errors: validationErrors,
+      warnings
+    };
+  }
+  /**
+   * Validate a loaded skill
+   */
+  validateLoaded(skill) {
+    const result = this.validate(skill.definition);
+    if (!skill.content) {
+      result.warnings.push({
+        field: "content",
+        message: "SKILL.md is empty or missing",
+        severity: "warning"
+      });
+    }
+    const unchecked = [];
+    for (const gate of skill.definition.quality ?? []) {
+      if (AUTO_SATISFIED_GATES.has(gate.id)) {
+        continue;
+      }
+      const headingPattern = CONTENT_GATE_HEADINGS[gate.id];
+      if (gate.type === "content" && headingPattern) {
+        if (!headingPattern.test(skill.content)) {
+          const entry = {
+            field: `quality.${gate.id}`,
+            message: `Quality gate '${gate.id}' failed: SKILL.md is missing a matching section (${gate.description})`,
+            severity: gate.severity
+          };
+          if (gate.severity === "error") {
+            result.errors.push(entry);
+            result.valid = false;
+          } else if (gate.severity === "warning") {
+            result.warnings.push(entry);
+          }
+        }
+        continue;
+      }
+      unchecked.push(gate.id);
+    }
+    result.unchecked = unchecked;
+    return result;
+  }
+  /**
+   * Validate skill name format
+   */
+  validateName(name) {
+    const nameRegex = /^(@[a-z0-9-]+\/)?[a-z0-9-]+$/;
+    return nameRegex.test(name);
+  }
+  /**
+   * Validate semver version
+   */
+  validateVersion(version) {
+    const semverRegex = /^\d+\.\d+\.\d+(-[a-z0-9.]+)?(\+[a-z0-9.]+)?$/;
+    return semverRegex.test(version);
+  }
+  // ==========================================================================
+  // Private Methods
+  // ==========================================================================
+  validateRequired(def, errors) {
+    if (!def.name) {
+      errors.push({
+        field: "name",
+        message: "Skill name is required",
+        severity: "error"
+      });
+    } else if (!this.validateName(def.name)) {
+      errors.push({
+        field: "name",
+        message: `Invalid skill name format: ${def.name}`,
+        severity: "error"
+      });
+    }
+    if (!def.version) {
+      errors.push({
+        field: "version",
+        message: "Skill version is required",
+        severity: "error"
+      });
+    } else if (!this.validateVersion(def.version)) {
+      errors.push({
+        field: "version",
+        message: `Invalid semver version: ${def.version}`,
+        severity: "error"
+      });
+    }
+    if (!def.description) {
+      errors.push({
+        field: "description",
+        message: "Skill description is required",
+        severity: "error"
+      });
+    }
+    if (!Array.isArray(def.provides) || def.provides.length === 0) {
+      errors.push({
+        field: "provides",
+        message: "At least one capability must be provided",
+        severity: "error"
+      });
+    }
+  }
+  validateFormats(def, errors) {
+    if (def.version && !this.validateVersion(def.version)) {
+      errors.push({
+        field: "version",
+        message: `Version must be valid semver: ${def.version}`,
+        severity: "error"
+      });
+    }
+    if (def.authors) {
+      for (const author of def.authors) {
+        if (author.email && !this.validateEmail(author.email)) {
+          errors.push({
+            field: "authors.email",
+            message: `Invalid email format: ${author.email}`,
+            severity: "warning"
+          });
+        }
+      }
+    }
+    if (def.invocation !== void 0 && !["user", "model", "either"].includes(def.invocation)) {
+      errors.push({
+        field: "invocation",
+        message: `Invalid invocation mode: ${def.invocation} (expected user, model, or either)`,
+        severity: "error"
+      });
+    }
+  }
+  validateCapabilities(def, errors) {
+    const capIds = /* @__PURE__ */ new Set();
+    for (const cap of def.provides) {
+      if (capIds.has(cap.id)) {
+        errors.push({
+          field: "provides",
+          message: `Duplicate capability ID: ${cap.id}`,
+          severity: "error"
+        });
+      }
+      capIds.add(cap.id);
+      if (!/^[a-z0-9-]+$/.test(cap.id)) {
+        errors.push({
+          field: "provides.id",
+          message: `Invalid capability ID format: ${cap.id}`,
+          severity: "error"
+        });
+      }
+      if (cap.input) {
+        for (const param of cap.input) {
+          this.validateParameter(param, `provides.${cap.id}.input`, errors);
+        }
+      }
+      if (cap.output) {
+        for (const param of cap.output) {
+          this.validateParameter(param, `provides.${cap.id}.output`, errors);
+        }
+      }
+    }
+  }
+  validateParameter(param, path, errors) {
+    if (!param.name) {
+      errors.push({
+        field: `${path}.name`,
+        message: "Parameter name is required",
+        severity: "error"
+      });
+    }
+    const validTypes = [
+      "string",
+      "number",
+      "boolean",
+      "file",
+      "file[]",
+      "object",
+      "array",
+      "enum"
+    ];
+    if (param.type && !validTypes.includes(param.type)) {
+      errors.push({
+        field: `${path}.type`,
+        message: `Invalid parameter type: ${param.type}`,
+        severity: "error"
+      });
+    }
+  }
+  validateQualityGates(def, errors) {
+    if (!def.quality)
+      return;
+    const gateIds = /* @__PURE__ */ new Set();
+    for (const gate of def.quality) {
+      if (gateIds.has(gate.id)) {
+        errors.push({
+          field: "quality",
+          message: `Duplicate quality gate ID: ${gate.id}`,
+          severity: "error"
+        });
+      }
+      gateIds.add(gate.id);
+      if (!/^[a-z0-9-]+$/.test(gate.id)) {
+        errors.push({
+          field: "quality.id",
+          message: `Invalid quality gate ID format: ${gate.id}`,
+          severity: "error"
+        });
+      }
+      const validTypes = ["structural", "behavioral", "content", "performance"];
+      if (!validTypes.includes(gate.type)) {
+        errors.push({
+          field: "quality.type",
+          message: `Invalid quality gate type: ${gate.type}`,
+          severity: "error"
+        });
+      }
+      const validSeverities = ["error", "warning", "info"];
+      if (!validSeverities.includes(gate.severity)) {
+        errors.push({
+          field: "quality.severity",
+          message: `Invalid quality gate severity: ${gate.severity}`,
+          severity: "error"
+        });
+      }
+    }
+  }
+  validateEmail(email) {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+  }
+};
+var defaultValidator = null;
+function getValidator() {
+  if (!defaultValidator) {
+    defaultValidator = new Validator();
+  }
+  return defaultValidator;
+}
+
+// src/commands/validate.ts
+var validateCommand = new Command5("validate").description("Validate skill definitions").argument("[skill]", "Skill to validate").option("--strict", "Treat warnings as errors").action(async (skillName, options = {}) => {
+  const spinner = ora3("Validating skills...").start();
+  try {
+    const skillsDir = join6(process.cwd(), "skills");
+    if (!existsSync6(skillsDir)) {
+      spinner.fail(chalk5.red("No skills directory found"));
+      process.exit(1);
+    }
+    const skillDirs = [];
+    if (skillName) {
+      let skillPath = /^@[^/]+\//.test(skillName) ? join6(skillsDir, skillName.replace(/^@[^/]+\//, "")) : join6(skillsDir, skillName);
+      if (!existsSync6(skillPath)) {
+        const short = skillName.replace(/^@[^/]+\//, "");
+        const found = readdirSync5(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith(".")).map((d) => join6(skillsDir, d.name, short)).find((p) => existsSync6(join6(p, "SKILL.yaml")));
+        if (found) skillPath = found;
+      }
+      if (!existsSync6(skillPath)) {
+        throw new Error(`Skill not found: ${skillName}`);
+      }
+      skillDirs.push(skillPath);
+    } else {
+      const categories = readdirSync5(skillsDir).filter(
+        (f) => existsSync6(join6(skillsDir, f)) && !f.startsWith(".")
+      );
+      for (const category of categories) {
+        const categoryPath = join6(skillsDir, category);
+        if (!existsSync6(categoryPath)) continue;
+        const skills = readdirSync5(categoryPath).filter(
+          (f) => existsSync6(join6(categoryPath, f, "SKILL.yaml"))
+        );
+        for (const skill of skills) {
+          skillDirs.push(join6(categoryPath, skill));
+        }
+      }
+    }
+    if (skillDirs.length === 0) {
+      spinner.warn(chalk5.yellow("No skills found to validate"));
+      return;
+    }
+    spinner.stop();
+    const validator = getValidator();
+    let valid = 0;
+    let invalid = 0;
+    for (const skillPath of skillDirs) {
+      const label = skillPath.split("/").pop() || "unknown";
+      try {
+        const skill = await loadSkill(skillPath);
+        const result = validator.validateLoaded(skill);
+        const name = `${skill.definition.name}@${skill.definition.version}`;
+        const failsStrict = options.strict && result.warnings.length > 0;
+        if (result.valid && !failsStrict) {
+          console.log(chalk5.green(`  ${name}: valid`));
+          valid++;
+        } else {
+          console.log(chalk5.red(`  ${name}: invalid`));
+          invalid++;
+        }
+        for (const error of result.errors) {
+          console.log(chalk5.red(`    \u2717 ${error.field}: ${error.message}`));
+        }
+        for (const warning of result.warnings) {
+          console.log(chalk5.yellow(`    \u26A0 ${warning.field}: ${warning.message}`));
+        }
+        if (result.unchecked && result.unchecked.length > 0) {
+          console.log(
+            chalk5.gray(
+              `    \u2139 requires manual verification: ${result.unchecked.join(", ")}`
+            )
+          );
+        }
+      } catch (error) {
+        console.log(chalk5.red(`  ${label}: invalid`));
+        console.log(
+          chalk5.red(`    \u2717 ${error instanceof Error ? error.message : error}`)
+        );
+        invalid++;
+      }
+    }
+    console.log("\n" + chalk5.bold("Summary:"));
+    console.log(`  ${chalk5.green(`Valid: ${valid}`)}`);
+    if (invalid > 0) {
+      console.log(`  ${chalk5.red(`Invalid: ${invalid}`)}`);
+    }
+    if (invalid > 0) process.exit(1);
+  } catch (error) {
+    spinner.fail(chalk5.red(`Failed: ${error instanceof Error ? error.message : error}`));
+    process.exit(1);
+  }
+});
+
+// src/commands/init.ts
+import { Command as Command6 } from "commander";
+import chalk6 from "chalk";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join7 } from "node:path";
+var initCommand = new Command6("init").description("Initialize a new skill package").argument("<name>", "Skill name (e.g., my-skill)").option("-c, --category <category>", "Skill category", "engineering").action((name, options = {}) => {
+  const category = options.category || "engineering";
+  const skillDir = join7(process.cwd(), "skills", category, name);
+  mkdirSync2(join7(skillDir, "references"), { recursive: true });
+  mkdirSync2(join7(skillDir, "tests"), { recursive: true });
+  const yaml = `name: "${name}"
+version: "0.1.0"
+description: "TODO: Describe what this skill does"
+license: "MIT"
+authors:
+  - name: "Your Name"
+
+provides:
+  - id: "${name.replace(/-/g, "_")}"
+    description: "TODO: Describe the capability"
+    input:
+      - name: "target"
+        type: "string"
+        required: true
+    output:
+      - name: "result"
+        type: "object"
+
+context:
+  - type: "language"
+    values: ["typescript", "javascript"]
+    required: true
+
+quality:
+  - id: "has-overview"
+    type: "content"
+    description: "Skill has overview section"
+    severity: "warning"
+
+tags: []
+category: "${category}"
+difficulty: "intermediate"
+`;
+  writeFileSync3(join7(skillDir, "SKILL.yaml"), yaml);
+  const md = `# ${name}
+
+## Overview
+
+TODO: Describe what this skill does and when to use it.
+
+## When to Use
+
+- TODO: Add triggering conditions
+
+## Workflow
+
+### Step 1: TODO
+
+[Instructions]
+
+## Quality Gates
+
+- **has-overview**: Skill has overview section
+`;
+  writeFileSync3(join7(skillDir, "SKILL.md"), md);
+  writeFileSync3(join7(skillDir, "references", ".gitkeep"), "");
+  writeFileSync3(
+    join7(skillDir, "tests", `${name}.test.ts`),
+    `// Tests for ${name}
+describe('${name}', () => {
+  it('should load successfully', () => {
+    // TODO: Add test
+    expect(true).toBe(true);
+  });
+});
+`
+  );
+  console.log(chalk6.green(`Created skill: ${name}`));
+  console.log(`
+Location: ${skillDir}`);
+  console.log("\nFiles created:");
+  console.log(`  ${chalk6.cyan("SKILL.yaml")} - Skill definition`);
+  console.log(`  ${chalk6.cyan("SKILL.md")} - Skill instructions`);
+  console.log(`  ${chalk6.cyan("references/")} - Reference files`);
+  console.log(`  ${chalk6.cyan("tests/")} - Test files`);
+  console.log("\nNext steps:");
+  console.log("  1. Edit SKILL.yaml with your skill definition");
+  console.log("  2. Write SKILL.md with your skill instructions");
+  console.log("  3. Run `loom validate` to check for issues");
+});
+
+// src/commands/search.ts
+import { Command as Command7 } from "commander";
+import chalk7 from "chalk";
+import ora4 from "ora";
+var searchCommand = new Command7("search").description("Search for skills").argument("<query>", "Search query").action((query) => {
+  const spinner = ora4("Searching...").start();
+  try {
+    spinner.stop();
+    console.log(chalk7.bold(`
+Search results for "${query}":
+`));
+    const results = [
+      { name: "@loom-skills/tdd", description: "Test-driven development", category: "engineering" },
+      { name: "@loom-skills/review", description: "Code review", category: "engineering" },
+      { name: "@loom-skills/debug", description: "Debugging workflow", category: "engineering" }
+    ];
+    const filtered = results.filter(
+      (r) => r.name.toLowerCase().includes(query.toLowerCase()) || r.description.toLowerCase().includes(query.toLowerCase())
+    );
+    if (filtered.length === 0) {
+      console.log(chalk7.yellow("No results found."));
+      return;
+    }
+    for (const result of filtered) {
+      console.log(`${chalk7.bold(result.name)}`);
+      console.log(`  ${chalk7.gray(result.description)}`);
+      console.log(`  Category: ${chalk7.cyan(result.category)}`);
+      console.log();
+    }
+    console.log(chalk7.gray(`Found ${filtered.length} results`));
+  } catch (error) {
+    spinner.fail(chalk7.red(`Failed: ${error instanceof Error ? error.message : error}`));
+    process.exit(1);
+  }
+});
+
+// src/commands/publish.ts
+import { Command as Command8 } from "commander";
+import chalk8 from "chalk";
+import ora5 from "ora";
+import { existsSync as existsSync7, readFileSync as readFileSync6 } from "node:fs";
+import { join as join8 } from "node:path";
+var publishCommand = new Command8("publish").description("Publish a skill to the registry").argument("[path]", "Path to skill directory", ".").option("--dry-run", "Preview publish without uploading").action((skillPath, options = {}) => {
+  const spinner = ora5("Preparing to publish...").start();
+  try {
+    const resolvedPath = skillPath === "." ? process.cwd() : skillPath;
+    const yamlPath = join8(resolvedPath, "SKILL.yaml");
+    if (!existsSync7(yamlPath)) {
+      throw new Error(`No SKILL.yaml found in: ${resolvedPath}`);
+    }
+    const content = readFileSync6(yamlPath, "utf-8");
+    const nameMatch = content.match(/name:\s*"?([^"\n]+)"?/);
+    const versionMatch = content.match(/version:\s*"?([^"\n]+)"?/);
+    const descMatch = content.match(/description:\s*"?([^"\n]+)"?/);
+    const name = nameMatch?.[1] || "unknown";
+    const version = versionMatch?.[1] || "0.0.0";
+    const description = descMatch?.[1] || "";
+    const errors = [];
+    if (!nameMatch) errors.push("Missing name");
+    if (!versionMatch) errors.push("Missing version");
+    if (!descMatch) errors.push("Missing description");
+    if (!content.includes("provides:")) errors.push("Missing provides section");
+    if (errors.length > 0) {
+      spinner.fail(chalk8.red("Validation failed:"));
+      for (const error of errors) {
+        console.log(chalk8.red(`  \u2717 ${error}`));
+      }
+      process.exit(1);
+    }
+    spinner.stop();
+    console.log(chalk8.bold("\nPublish Preview:\n"));
+    console.log(`  ${chalk8.bold("Name:")} ${name}`);
+    console.log(`  ${chalk8.bold("Version:")} ${version}`);
+    console.log(`  ${chalk8.bold("Description:")} ${description}`);
+    if (options.dryRun) {
+      console.log("\n" + chalk8.gray("Dry run - no files uploaded"));
+      return;
+    }
+    console.log("\n" + chalk8.green("Publish functionality coming soon!"));
+    console.log(chalk8.gray("This would upload to the Loom registry."));
+  } catch (error) {
+    spinner.fail(chalk8.red(`Failed: ${error instanceof Error ? error.message : error}`));
+    process.exit(1);
+  }
+});
+
+// src/index.ts
+var program = new Command9();
+program.name("loom").description("Skills woven together \u2014 A skill operating system for AI coding agents").version("0.1.0");
+program.addCommand(installCommand);
+program.addCommand(listCommand);
+program.addCommand(composeCommand);
+program.addCommand(testCommand);
+program.addCommand(validateCommand);
+program.addCommand(initCommand);
+program.addCommand(searchCommand);
+program.addCommand(publishCommand);
+program.parse();

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@loom-skills/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Command-line interface for Loom skill system",
+  "homepage": "https://github.com/hemantho-r/loom",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hemantho-r/loom.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/hemantho-r/loom/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "loom": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.0",
+    "vitest": "^1.6.0",
+    "yaml": "^2.4.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0",
+    "esbuild": "^0.21.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/index.js --external:commander --external:chalk --external:ora --external:vitest --external:yaml && chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.