@reddb-io/red-skills 3.18.12 → 3.19.2

package/scripts/generate-gemini-manifests.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const REPO_URL = "https://github.com/reddb-io/red-skills";
+const AUTHOR = {
+  name: "reddb.io",
+  url: "https://github.com/reddb-io",
+};
+const CAPABILITIES = ["Interactive", "Read", "Write", "Shell"];
+const PREFERRED_SKILL_ROOT_ORDER = ["engineering", "knowledge", "productivity", "misc", "core"];
+
+function parseArgs(argv) {
+  const args = {
+    root: process.cwd(),
+    check: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--check") {
+      args.check = true;
+      continue;
+    }
+    if (arg === "--root") {
+      const next = argv[index + 1];
+      if (!next) throw new Error("--root requires a path");
+      args.root = next;
+      index += 1;
+      continue;
+    }
+    throw new Error(`unknown argument: ${arg}`);
+  }
+
+  return args;
+}
+
+function geminiText(input) {
+  return String(input ?? "")
+    .replace(/[`\u2018\u2019]/g, "")
+    .replace(/[\u201c\u201d]/g, '"')
+    .replace(/[\u2013\u2014]/g, "-")
+    .replace(/\u2026/g, "...")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function titleCaseName(name) {
+  return String(name)
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+    .join(" ");
+}
+
+function marketplaceDisplayName(name) {
+  if (name === "red-skills") return "RedSkills";
+  return titleCaseName(name);
+}
+
+function brandColorForPlugin(name) {
+  if (name === "brain") return "#2563EB";
+  return "#D92D20";
+}
+
+function pluginKeywords(name) {
+  const keywords = ["gemini-cli", "skills", "agents"];
+  if (name === "dev") return [...keywords, "github-issues", "tdd"];
+  return [...keywords, name];
+}
+
+function normalizeSkillEntry(entry) {
+  return String(entry).replace(/\/+$/, "");
+}
+
+function deriveGeminiSkillRoots(skills) {
+  if (typeof skills === "string") {
+    return skills.endsWith("/") ? skills : `${skills}/`;
+  }
+  if (!Array.isArray(skills)) return undefined;
+
+  const roots = new Set();
+  for (const skill of skills) {
+    const normalized = normalizeSkillEntry(skill);
+    const match = normalized.match(/^\.\/skills\/([^/]+)/);
+    if (match) roots.add(match[1]);
+  }
+
+  const orderedRoots = [...roots].sort((left, right) => {
+    const leftIndex = PREFERRED_SKILL_ROOT_ORDER.indexOf(left);
+    const rightIndex = PREFERRED_SKILL_ROOT_ORDER.indexOf(right);
+    if (leftIndex !== -1 || rightIndex !== -1) {
+      return (leftIndex === -1 ? Number.MAX_SAFE_INTEGER : leftIndex) - (rightIndex === -1 ? Number.MAX_SAFE_INTEGER : rightIndex);
+    }
+    return left.localeCompare(right);
+  });
+
+  return orderedRoots.map((root) => `./skills/${root}/`);
+}
+
+function defaultPromptForPlugin(name, skills) {
+  const skillEntries = Array.isArray(skills) ? skills : [];
+  const skillNames = skillEntries
+    .map((entry) => normalizeSkillEntry(entry).split("/").at(-1))
+    .filter(Boolean)
+    .slice(0, 4);
+
+  if (skillNames.length === 0) return [`Use RedSkills ${titleCaseName(name)} when this workspace needs it.`];
+  return skillNames.map((skill) => `Use $${skill} when this workspace needs it.`);
+}
+
+function maybeSet(target, key, value) {
+  if (value !== undefined) target[key] = value;
+}
+
+export function buildGeminiMarketplace(claudeMarketplace) {
+  return {
+    name: claudeMarketplace.name,
+    interface: {
+      displayName: marketplaceDisplayName(claudeMarketplace.name),
+    },
+    plugins: claudeMarketplace.plugins.map((plugin) => {
+      const geminiPlugin = {
+        name: plugin.name,
+        source: {
+          source: "local",
+          path: plugin.source,
+        },
+        policy: {
+          installation: plugin.name === "dev" ? "INSTALLED_BY_DEFAULT" : "AVAILABLE",
+          authentication: "ON_USE",
+        },
+      };
+      maybeSet(geminiPlugin, "dependencies", plugin.dependencies);
+      maybeSet(geminiPlugin, "description", geminiText(plugin.description));
+      geminiPlugin.category = "Developer Tools";
+      return geminiPlugin;
+    }),
+  };
+}
+
+export function buildGeminiPluginManifest(claudePlugin) {
+  const description = geminiText(claudePlugin.description);
+  const manifest = {
+    name: claudePlugin.name,
+    version: claudePlugin.version,
+    description,
+    author: AUTHOR,
+    homepage: REPO_URL,
+    repository: REPO_URL,
+    license: "Apache-2.0",
+  };
+
+  maybeSet(manifest, "dependencies", claudePlugin.dependencies);
+  manifest.keywords = pluginKeywords(claudePlugin.name);
+  maybeSet(manifest, "skills", deriveGeminiSkillRoots(claudePlugin.skills));
+  // Gemini CLI hooks are not Claude hook manifests with a renamed file. The
+  // native dev extension builder emits the supported hooks/hooks.json subset;
+  // this compatibility metadata must not advertise a fabricated sidecar.
+  maybeSet(manifest, "mcpServers", claudePlugin.mcpServers);
+  manifest.interface = {
+    displayName: `RedSkills ${titleCaseName(claudePlugin.name)}`,
+    shortDescription: description,
+    longDescription: description,
+    developerName: AUTHOR.name,
+    category: "Developer Tools",
+    capabilities: CAPABILITIES,
+    websiteURL: REPO_URL,
+    defaultPrompt: defaultPromptForPlugin(claudePlugin.name, claudePlugin.skills),
+    brandColor: brandColorForPlugin(claudePlugin.name),
+  };
+
+  return manifest;
+}
+
+function jsonBytes(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function writeGenerated(path, bytes, check, mismatches) {
+  if (!check) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, bytes);
+    return;
+  }
+
+  let current = "";
+  try {
+    current = await readFile(path, "utf8");
+  } catch {
+    current = "";
+  }
+
+  if (current !== bytes) {
+    mismatches.push({ path, bytes });
+  }
+}
+
+async function printDiffs(root, mismatches) {
+  const tempRoot = await mkdtemp(join(tmpdir(), "red-skills-gemini-manifest-diff-"));
+  try {
+    for (const mismatch of mismatches) {
+      const rel = relative(root, mismatch.path);
+      const expected = join(tempRoot, rel);
+      await mkdir(dirname(expected), { recursive: true });
+      await writeFile(expected, mismatch.bytes);
+      const diff = spawnSync("git", ["diff", "--no-index", "--", mismatch.path, expected], {
+        encoding: "utf8",
+      });
+      const output = `${diff.stdout}${diff.stderr}`.trim();
+      if (output) console.error(output);
+    }
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+export async function generateGeminiManifests({ root, check = false }) {
+  const mismatches = [];
+  const claudeMarketplacePath = join(root, ".claude-plugin/marketplace.json");
+  const geminiMarketplacePath = join(root, ".gemini-plugin/marketplace.json");
+  const claudeMarketplace = await readJson(claudeMarketplacePath);
+  await writeGenerated(geminiMarketplacePath, jsonBytes(buildGeminiMarketplace(claudeMarketplace)), check, mismatches);
+
+  for (const plugin of claudeMarketplace.plugins) {
+    const pluginRoot = join(root, plugin.source);
+    const claudePlugin = await readJson(join(pluginRoot, ".claude-plugin/plugin.json"));
+    await writeGenerated(
+      join(pluginRoot, ".gemini-plugin/plugin.json"),
+      jsonBytes(buildGeminiPluginManifest(claudePlugin)),
+      check,
+      mismatches,
+    );
+  }
+
+  if (check && mismatches.length > 0) {
+    await printDiffs(root, mismatches);
+    throw new Error(`Gemini manifests are stale; run node scripts/generate-gemini-manifests.mjs (${mismatches.length} file(s))`);
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  await generateGeminiManifests(args);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/scripts/generate-pi-manifests.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Generates Pi-package manifests for every RedSkills plugin from the canonical
+// Claude-side plugin tree, mirroring scripts/generate-codex-manifests.mjs.
+//
+// Pi packages are installed via `pi install <local-path>` and need a
+// package.json with a `pi-package` keyword plus a `pi.skills` array pointing at
+// the same skill buckets the Claude/Codex manifests expose. This script keeps
+// the per-plugin package.json files under `plugins/<name>/package.json` in
+// sync with the source-of-truth Claude manifests; run `pnpm pi:manifests` to
+// regenerate, `pnpm pi:manifests:check` to fail on drift.
+//
+// The generated package.json intentionally lives alongside the existing
+// .claude-plugin/plugin.json and .codex-plugin/plugin.json so a single source
+// tree continues to serve every host without forking the plugin definitions.
+// Skills exposed here are the same bucket paths the Codex manifest lists, so
+// a `pi install ./plugins/dev` install gives the agent every published dev
+// skill (engineering/knowledge/productivity/misc) without the in-progress
+// drafts.
+
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  jsonBytes,
+  normalizeSkillEntry,
+  normalizeText,
+  parseArgs,
+  printDiffs,
+  readJson,
+  writeGenerated,
+} from "./lib/manifest-core.mjs";
+
+const REPO_URL = "https://github.com/reddb-io/red-skills";
+const HOMEPAGE = "https://github.com/reddb-io/red-skills";
+const LICENSE = "Apache-2.0";
+const PREFERRED_SKILL_ROOT_ORDER = ["engineering", "knowledge", "productivity", "misc", "core"];
+const SCOPED_NAMESPACE = "@reddb-io";
+
+function deriveSkillRoots(skills) {
+  if (typeof skills === "string") {
+    return skills.startsWith("./skills/") || skills === "./skills/" ? skills : `./skills/${skills.replace(/^\.\//, "")}/`;
+  }
+  if (!Array.isArray(skills)) return [];
+
+  const roots = new Set();
+  for (const skill of skills) {
+    const normalized = normalizeSkillEntry(skill);
+    const match = normalized.match(/^\.\/skills\/([^/]+)/);
+    if (match) roots.add(match[1]);
+  }
+
+  const orderedRoots = [...roots].sort((left, right) => {
+    const leftIndex = PREFERRED_SKILL_ROOT_ORDER.indexOf(left);
+    const rightIndex = PREFERRED_SKILL_ROOT_ORDER.indexOf(right);
+    if (leftIndex !== -1 || rightIndex !== -1) {
+      return (leftIndex === -1 ? Number.MAX_SAFE_INTEGER : leftIndex) -
+        (rightIndex === -1 ? Number.MAX_SAFE_INTEGER : rightIndex);
+    }
+    return left.localeCompare(right);
+  });
+
+  // The Pi package manifest sits at plugins/<name>/package.json, so paths are
+  // rooted there and must include the shared `./skills/` prefix the Claude and
+  // Codex manifests also use. Pi auto-discovers SKILL.md files recursively
+  // beneath each listed directory.
+  return orderedRoots.map((root) => `./skills/${root}/`);
+}
+
+export function buildPiPackage(claudePlugin) {
+  const description = normalizeText(claudePlugin.description);
+  const packageName = `${SCOPED_NAMESPACE}/red-skills-${claudePlugin.name}`;
+  const skillRoots = deriveSkillRoots(claudePlugin.skills);
+  if (skillRoots.length === 0) {
+    throw new Error(
+      `${claudePlugin.name}: cannot derive skill buckets from Claude plugin manifest`,
+    );
+  }
+
+  const packageJson = {
+    name: packageName,
+    version: claudePlugin.version,
+    private: true,
+    description,
+    license: LICENSE,
+    homepage: HOMEPAGE,
+    repository: {
+      type: "git",
+      url: `${REPO_URL}.git`,
+    },
+    keywords: ["pi-package", "reddb-io", "red-skills", ...(claudePlugin.dependencies ?? []).map((dep) => `dep:${dep}`)],
+    pi: {
+      skills: skillRoots,
+    },
+  };
+
+  return packageJson;
+}
+
+export async function generatePiManifests({ root, check = false }) {
+  const mismatches = [];
+  const claudeMarketplacePath = join(root, ".claude-plugin/marketplace.json");
+  const claudeMarketplace = await readJson(claudeMarketplacePath);
+
+  for (const plugin of claudeMarketplace.plugins) {
+    const pluginRoot = join(root, plugin.source);
+    const claudePlugin = await readJson(join(pluginRoot, ".claude-plugin/plugin.json"));
+    const packageJson = buildPiPackage(claudePlugin);
+    await writeGenerated(
+      join(pluginRoot, "package.json"),
+      jsonBytes(packageJson),
+      check,
+      mismatches,
+    );
+  }
+
+  if (check && mismatches.length > 0) {
+    await printDiffs(root, mismatches, { tempLabel: "red-skills-pi-manifest-diff-" });
+    throw new Error(
+      `Pi manifests are stale; run node scripts/generate-pi-manifests.mjs (${mismatches.length} file(s))`,
+    );
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  await generatePiManifests(args);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/scripts/install-hermes-skills.mjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+
+import { cp, lstat, mkdir, readFile, readdir, readlink, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const NAMESPACE = "redskills-dev";
+const OWNED_STATE = "redskills-dev-owned.txt";
+const OWNED_HEADER = "redskills-hermes-owned-v1";
+const OWNED_ROOT = `skills/${NAMESPACE}`;
+
+function parseArgs(argv) {
+  const options = { action: "install", home: "", source: "" };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--install" || argument === "--verify" || argument === "--uninstall") {
+      options.action = argument.slice(2);
+      continue;
+    }
+    if (argument === "--home" || argument === "--source") {
+      const value = argv[index + 1];
+      if (!value) throw new Error(`${argument} requires a path`);
+      options[argument.slice(2)] = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`unknown argument: ${argument}`);
+  }
+  if (!options.home) throw new Error("--home requires a path");
+  if (options.action !== "uninstall" && !options.source) throw new Error("--source requires a path");
+  return options;
+}
+
+function inside(root, path) {
+  const rel = relative(root, path);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) && !isAbsolute(rel);
+}
+
+async function readDevSkills(sourceRoot) {
+  const pluginRoot = join(sourceRoot, "plugins", "dev");
+  const manifestPath = join(pluginRoot, ".claude-plugin", "plugin.json");
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch (error) {
+    throw new Error(`${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (manifest.name !== "dev") throw new Error(`${manifestPath}: name must be dev`);
+  if (!Array.isArray(manifest.skills) || manifest.skills.length === 0) {
+    throw new Error(`${manifestPath}: skills must be a non-empty array`);
+  }
+
+  const names = new Set();
+  const skills = [];
+  for (const declared of manifest.skills) {
+    if (typeof declared !== "string" || !declared.startsWith("./skills/")) {
+      throw new Error(`${manifestPath}: invalid skill path ${JSON.stringify(declared)}`);
+    }
+    const source = resolve(pluginRoot, declared);
+    if (!inside(pluginRoot, source)) throw new Error(`${manifestPath}: skill escapes plugin root: ${declared}`);
+    const name = basename(source);
+    if (names.has(name)) throw new Error(`${manifestPath}: duplicate flattened Hermes skill name: ${name}`);
+    names.add(name);
+    const skillFile = await lstat(join(source, "SKILL.md")).catch(() => undefined);
+    if (!skillFile?.isFile()) throw new Error(`${manifestPath}: declared skill is missing SKILL.md: ${declared}`);
+    skills.push({ name, source });
+  }
+  return skills.sort((left, right) => left.name.localeCompare(right.name, "en"));
+}
+
+async function describeTree(root, prefix = "") {
+  const result = [];
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const path = join(root, entry.name);
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    const metadata = await lstat(path);
+    if (metadata.isDirectory()) {
+      result.push([`${rel}/`, "directory"]);
+      result.push(...await describeTree(path, rel));
+    } else if (metadata.isSymbolicLink()) {
+      result.push([rel, `link:${await readlink(path)}`]);
+    } else if (metadata.isFile()) {
+      result.push([rel, `file:${metadata.mode & 0o777}:${await readFile(path, "base64")}`]);
+    } else {
+      throw new Error(`unsupported skill entry type: ${path}`);
+    }
+  }
+  return result.sort(([left], [right]) => left.localeCompare(right, "en"));
+}
+
+async function assertSkillCopy(source, target, name) {
+  const expected = await describeTree(source);
+  const actual = await describeTree(target).catch(() => undefined);
+  if (!actual || JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(`Hermes skill verification failed: ${name}`);
+  }
+}
+
+function capabilities(skillCount) {
+  return `# RedSkills dev capabilities for Hermes
+
+Capability | Status | Detail
+--- | --- | ---
+Skills | healthy | ${skillCount} complete skill directories are available from the user-global Hermes skills tree.
+Hooks | unsupported | Hermes has no RedSkills hook projection; no hook success is claimed.
+MCP | unsupported | Hermes has no RedSkills MCP projection; no MCP success is claimed.
+Agents | unsupported | Hermes has no RedSkills agent projection; no agent success is claimed.
+`;
+}
+
+function reportReadiness() {
+  process.stdout.write("Hermes readiness: skills=healthy\n");
+  process.stdout.write("Hermes limitation: hooks=unsupported\n");
+  process.stdout.write("Hermes limitation: mcp=unsupported\n");
+  process.stdout.write("Hermes limitation: agents=unsupported\n");
+}
+
+async function install(source, home) {
+  const sourceRoot = await realpath(resolve(source));
+  const skills = await readDevSkills(sourceRoot);
+  const target = join(home, OWNED_ROOT);
+  const staging = join(home, `.${NAMESPACE}.tmp-${process.pid}`);
+  await mkdir(home, { recursive: true });
+  await rm(staging, { recursive: true, force: true });
+  await mkdir(staging, { recursive: true });
+
+  try {
+    for (const skill of skills) {
+      const destination = join(staging, skill.name);
+      await cp(skill.source, destination, { recursive: true, force: true, verbatimSymlinks: true });
+      await assertSkillCopy(skill.source, destination, skill.name);
+    }
+    await writeFile(join(staging, "CAPABILITIES.md"), capabilities(skills.length));
+    await mkdir(join(target, ".."), { recursive: true });
+    await rm(target, { recursive: true, force: true });
+    await rename(staging, target);
+    await writeFile(join(home, OWNED_STATE), `${OWNED_HEADER}\n${OWNED_ROOT}\n`);
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+
+  await verify(sourceRoot, home);
+}
+
+async function verify(source, home) {
+  const skills = await readDevSkills(source);
+  const target = join(home, OWNED_ROOT);
+  const owned = await readFile(join(home, OWNED_STATE), "utf8");
+  if (owned !== `${OWNED_HEADER}\n${OWNED_ROOT}\n`) throw new Error("Hermes owned-state record is invalid");
+  for (const skill of skills) await assertSkillCopy(skill.source, join(target, skill.name), skill.name);
+  const capabilityReport = await readFile(join(target, "CAPABILITIES.md"), "utf8");
+  if (capabilityReport !== capabilities(skills.length)) throw new Error("Hermes capability report has drifted");
+  reportReadiness();
+}
+
+async function uninstall(home) {
+  const statePath = join(home, OWNED_STATE);
+  let state;
+  try {
+    state = await readFile(statePath, "utf8");
+  } catch (error) {
+    if (error && typeof error === "object" && error.code === "ENOENT") return;
+    throw error;
+  }
+  const lines = state.trimEnd().split("\n");
+  if (lines[0] !== OWNED_HEADER) throw new Error("refusing Hermes uninstall: owned-state header is invalid");
+  for (const owned of lines.slice(1)) {
+    if (owned !== OWNED_ROOT) throw new Error(`refusing Hermes uninstall: unexpected owned path ${JSON.stringify(owned)}`);
+    const target = resolve(home, owned);
+    if (!inside(resolve(home), target)) throw new Error("refusing Hermes uninstall: owned path escapes Hermes home");
+    await rm(target, { recursive: true, force: true });
+  }
+  await rm(statePath, { force: true });
+}
+
+export async function runHermesSkillsInstaller(options) {
+  const home = resolve(options.home);
+  if (options.action === "uninstall") return uninstall(home);
+  const source = await realpath(resolve(options.source));
+  if (options.action === "verify") return verify(source, home);
+  return install(source, home);
+}
+
+async function main() {
+  await runHermesSkillsInstaller(parseArgs(process.argv.slice(2)));
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}